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_ */