1 /* USER CODE BEGIN Header */
2 /**
3   ******************************************************************************
4   * @file    pka_manager.h
5   * @author  GPM WBL Application Team
6   * @brief   This file contains all the functions prototypes for the PKA Manager.
7   ******************************************************************************
8   * @attention
9   *
10   * Copyright (c) 2024 STMicroelectronics.
11   * All rights reserved.
12   *
13   * This software is licensed under terms that can be found in the LICENSE file
14   * in the root directory of this software component.
15   * If no LICENSE file comes with this software, it is provided AS-IS.
16   *
17   ******************************************************************************
18   */
19 /* USER CODE END Header */
20 
21 /* Define to prevent recursive inclusion -------------------------------------*/
22 #ifndef PKAMGR_H
23 #define PKAMGR_H
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /* Includes ------------------------------------------------------------------*/
30 #include "stdint.h"
31 
32 /** @addtogroup PKA_Manager_Peripheral  PKA Manager
33  * @{
34  */
35 
36 /** @defgroup PKA_Manager_Exported_Types Exported Types
37  * @{
38  */
39 /* Enumerated values used to report the PKA result status after a process */
40 typedef enum
41 {
42   PKAMGR_SUCCESS     =  0,
43   PKAMGR_ERROR       = -1,
44   PKAMGR_ERR_BUSY    = -2,
45   PKAMGR_ERR_PARAM   = -3,
46   PKAMGR_ERR_PROCESS = -4
47 } PKAMGR_ResultStatus;
48 /**
49  * @}
50  */
51 
52 /** @defgroup PKA_Manager_Public_Variables Public Variables
53 * @{
54 */
55 static const uint32_t PKAStartPoint[16] = { 0xd898c296U, 0xf4a13945U, 0x2deb33a0U, 0x77037d81U,
56                                        0x63a440f2U, 0xf8bce6e5U, 0xe12c4247U, 0x6b17d1f2U,
57                                        0x37bf51f5U, 0xcbb64068U, 0x6b315eceU, 0x2bce3357U,
58                                        0x7c0f9e16U, 0x8ee7eb4aU, 0xfe1a7f9bU, 0x4fe342e2U};
59 
60 /**
61 * @}
62 */
63 
64 /** @defgroup PKA_Manager_Exported_Functions        Exported Functions
65  * @{
66  */
67 
68 /**
69   * @brief  PKA Callback pointer definition
70   *
71   * @param  errorCode - indicates the status of the PKA operation just completed.
72   *
73   * @param  args - reference to a copy of the output/result of the PKA operation.
74   *         It may be either:
75   *         a) an array of 3x32 octets long, containing the Local Public Key, in case of P256 Public Key generation,
76   *            formatted as follows:
77   *            | Secret Key  | Public Key X-coord | Public Key Y-coord |
78   *            | (32 octets) | (32 octets)        | (32 octets)        |
79   *         b) an array of 32 octets long, containing the DHKey-check result, in case of DHKey check operation,
80   *            formatted as follows:
81   *            | DHKey check |
82   *            | (32 octets) |
83   *            | N.A.        | DHKey check        | N.A.               |
84   *            | (32 octets) | (32 octets)        | (32 octets)        |
85   *         The PKA processing output/result is reported as a linear array of octets,
86   *         without any indication of the data length.
87   *         The caller of the PKA operations shall read/decode the result, including the data length,
88   *         based on the last operation requested.
89   *
90   *
91   * @note 1 - ERROR_PARAMETERS should not be reported to the callback,
92   *           assuming that the input parameters (passed for DHKey computation)
93   *           are checked when calling HW_PKA_StartP256DHkeyGeneration.
94   *
95   * @note 2 This model is based on a unique and generic callback function, that reports the PKA output/result
96   *         without enforcing a specific function argument typing (preferred option).
97   *         Otherwise, 2 specific function callbacks may be defined, each one with specific function arguments
98   *         depending on the specific operation requested.
99   */
100 typedef void (*PKAMGR_funcCB)(PKAMGR_ResultStatus errorCode, void *args);  /*!< Pointer to a PKA callback function */
101 
102 PKAMGR_ResultStatus PKAMGR_Init(void);
103 
104 PKAMGR_ResultStatus PKAMGR_Deinit(void);
105 
106 PKAMGR_ResultStatus PKAMGR_SleepCheck(void);
107 
108 uint8_t PKAMGR_PowerSaveLevelCheck(uint8_t x);
109 
110 PKAMGR_ResultStatus PKAMGR_Lock(void);
111 
112 PKAMGR_ResultStatus PKAMGR_Unlock(void);
113 
114 void PKAMGR_IRQCallback(void);
115 
116 /**
117  * @name   PKAMGR_StartP256PublicKeyGeneration.
118  *
119  * @brief  Function used to request the generation of a new ECC Public Key.
120  *
121  * @param[in] privateKey The private key used to generate the public key.
122  *
123  * @param   funcCB - callback function that BLEPS Library makes available to BLEPLAT HAL,
124  *          that is called when the PKA operation requested has been completed (either successfully or not).
125  *
126  * @return Status of the PKA peripheral w.r.t. the requested operation
127  *         - SUCCESS in case the PKA peripheral is available and ready to execute the operation.
128  *         - ERROR_BUSY in case the PKA peripheral is BUSY with another operation that could
129  *         have been requested by the BLEPS Library or by the End-User Application.
130  *
131  * @note   Called by BLEPS Library function: <c>hci_le_read_local_p256_publicKey<\c>.
132  *
133  */
134 PKAMGR_ResultStatus PKAMGR_StartP256PublicKeyGeneration(const uint32_t *privateKey, PKAMGR_funcCB funcCB);
135 
136 /**
137  * @name    pka_manager_Start_ECDH_P256_DHKey_Generation
138  *
139  * @brief   Function which configures the PKA to perform the computation of DHKey check value.
140  *
141  * @param   secretKey - the Secret Key of the Local device (LE format).
142  * @param   publicKey - the Public Key of the peer remote device for which the DHKey will be computed (LE format).
143  * @param   funcCB - callback function that BLEPS Library makes available to BLEPLAT HAL,
144  *          that is called when the PKA operation requested has been completed (either successfully or not).
145  *
146  * @return  Status of the preliminary checks performed on input parameters and PKA peripheral status
147  *          made beofre to configure the PKA for DHKey computation.
148  *         - SUCCESS in case the PKA peripheral is available and ready to execute the operation
149  *           and the input parameters are correct!
150  *         - ERROR_BUSY in case the PKA peripheral is BUSY with another operation that could
151  *           have been requested by the BLEPS Library or by the End-User Application.
152  *         - ERROR_PARAMETERS in case the input parameters are invalid; either the Secret key or the
153  *           remote P256 public key may be wrong (when the peer remote public key is not a valid ECC point)
154  *
155  */
156 PKAMGR_ResultStatus HW_PKA_StartP256DHkeyGeneration(const uint32_t *secretKey,
157                                                     const uint32_t *publicKey,
158                                                     PKAMGR_funcCB funcCB);
159 
160 /**
161  * @}
162  */
163 
164 /**
165  * @}
166  */
167 
168 #ifdef __cplusplus
169 }
170 #endif
171 
172 #endif /* PKAMGR_H */
173