Line data    Source code

       1            1 : /*
       2              :  * Copyright (c) 2022 Intel Corporation.
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief Crypto Hash APIs
      10              :  *
      11              :  * This file contains the Crypto Abstraction layer APIs.
      12              :  */
      13              : #ifndef ZEPHYR_INCLUDE_CRYPTO_HASH_H_
      14              : #define ZEPHYR_INCLUDE_CRYPTO_HASH_H_
      15              : 
      16              : 
      17              : /**
      18              :  * @addtogroup crypto_hash
      19              :  * @{
      20              :  */
      21              : 
      22              : 
      23              : /**
      24              :  * Hash algorithm
      25              :  */
      26            0 : enum hash_algo {
      27              :         CRYPTO_HASH_ALGO_SHA224 = 1,
      28              :         CRYPTO_HASH_ALGO_SHA256 = 2,
      29              :         CRYPTO_HASH_ALGO_SHA384 = 3,
      30              :         CRYPTO_HASH_ALGO_SHA512 = 4,
      31              : };
      32              : 
      33              : /* Forward declarations */
      34              : struct hash_ctx;
      35              : struct hash_pkt;
      36              : 
      37              : 
      38            0 : typedef int (*hash_op_t)(struct hash_ctx *ctx, struct hash_pkt *pkt,
      39              :                          bool finish);
      40              : 
      41              : /**
      42              :  * Structure encoding session parameters.
      43              :  *
      44              :  * Refer to comments for individual fields to know the contract
      45              :  * in terms of who fills what and when w.r.t begin_session() call.
      46              :  */
      47            1 : struct hash_ctx {
      48              :         /** The device driver instance this crypto context relates to. Will be
      49              :          * populated by the begin_session() API.
      50              :          */
      51            1 :         const struct device *device;
      52              : 
      53              :         /** If the driver supports multiple simultaneously crypto sessions, this
      54              :          * will identify the specific driver state this crypto session relates
      55              :          * to. Since dynamic memory allocation is not possible, it is
      56              :          * suggested that at build time drivers allocate space for the
      57              :          * max simultaneous sessions they intend to support. To be populated
      58              :          * by the driver on return from begin_session().
      59              :          */
      60            1 :         void *drv_sessn_state;
      61              : 
      62              :         /**
      63              :          * Hash handler set up when the session begins.
      64              :          */
      65            1 :         hash_op_t hash_hndlr;
      66              : 
      67              :         /**
      68              :          * If it has started a multipart hash operation.
      69              :          */
      70            1 :         bool started;
      71              : 
      72              :         /** How certain fields are to be interpreted for this session.
      73              :          * (A bitmask of CAP_* below.)
      74              :          * To be populated by the app before calling hash_begin_session().
      75              :          * An app can obtain the capability flags supported by a hw/driver
      76              :          * by calling crypto_query_hwcaps().
      77              :          */
      78            1 :         uint16_t flags;
      79              : };
      80              : 
      81              : /**
      82              :  * Structure encoding IO parameters of a hash
      83              :  * operation.
      84              :  *
      85              :  * The fields which has not been explicitly called out has to
      86              :  * be filled up by the app before calling hash_compute().
      87              :  */
      88            1 : struct hash_pkt {
      89              : 
      90              :         /** Start address of input buffer */
      91            1 :         uint8_t *in_buf;
      92              : 
      93              :         /** Bytes to be operated upon */
      94            1 :         size_t  in_len;
      95              : 
      96              :         /**
      97              :          * Start of the output buffer, to be allocated by
      98              :          * the application. Can be NULL for in-place ops. To be populated
      99              :          * with contents by the driver on return from op / async callback.
     100              :          */
     101            1 :         uint8_t *out_buf;
     102              : 
     103              :         /**
     104              :          * Context this packet relates to. This can be useful to get the
     105              :          * session details, especially for async ops.
     106              :          */
     107            1 :         struct hash_ctx *ctx;
     108              : };
     109              : 
     110              : /* Prototype for the application function to be invoked by the crypto driver
     111              :  * on completion of an async request. The app may get the session context
     112              :  * via the pkt->ctx field.
     113              :  */
     114            0 : typedef void (*hash_completion_cb)(struct hash_pkt *completed, int status);
     115              : 
     116              : 
     117              : /**
     118              :  * @}
     119              :  */
     120              : #endif /* ZEPHYR_INCLUDE_CRYPTO_HASH_H_ */