security_pal.h
Go to the documentation of this file.
1 /*
2  * Copyright 2017 NXP
3  * All rights reserved.
4  *
5  * THIS SOFTWARE IS PROVIDED BY NXP "AS IS" AND ANY EXPRESSED OR
6  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
7  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
8  * IN NO EVENT SHALL NXP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
9  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
10  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
11  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
12  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
13  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
14  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
15  * THE POSSIBILITY OF SUCH DAMAGE.
16  */
17 
18 #ifndef SECURITY_PAL_H_
19 #define SECURITY_PAL_H_
20 
30 #include "security_pal_cfg.h"
31 #include "security_pal_mapping.h"
32 #include "status.h"
33 #include "callbacks.h"
34 
44 /*******************************************************************************
45  * Definitions
46  ******************************************************************************/
47 
52 typedef enum
53 {
56 
61 typedef enum
62 {
77 #if (defined(SECURITY_OVER_HSM))
78  SECURITY_RAM_KEY = 0xEU,
79 #elif (defined(SECURITY_OVER_CSEC))
80  SECURITY_RAM_KEY = 0xFU,
81 #endif
82  SECURITY_KEY_11 = 0x14U,
89 #if (defined(SECURITY_OVER_HSM))
90  SECURITY_KEY_18,
91  SECURITY_KEY_19,
92  SECURITY_KEY_20
93 #endif
95 
100 typedef enum
101 {
107 
112 typedef enum {
113 #if (defined(SECURITY_OVER_HSM))
114  SECURITY_CMD_NONE = 0U,
115 #endif
128 #if (defined(SECURITY_OVER_CSEC))
129  SECURITY_CMD_RESERVED_1,
130 #elif (defined(SECURITY_OVER_HSM))
131  SECURITY_CMD_SECURE_BOOT,
132 #endif
136 #if (defined(SECURITY_OVER_CSEC))
137  SECURITY_CMD_BOOT_DEFINE,
138 #elif (defined(SECURITY_OVER_HSM))
139  SECURITY_CMD_BOOT_CANCEL,
140 #endif
143 #if (defined(SECURITY_OVER_CSEC))
144  SECURITY_CMD_RESERVED_2,
145  SECURITY_CMD_RESERVED_3,
146  SECURITY_CMD_MP_COMPRESS
147 #elif (defined(SECURITY_OVER_HSM))
148  SECURITY_CMD_TRNG_RND,
149  SECURITY_CMD_GET_VER,
150  SECURITY_CMD_CHANGE_TRNG_CLK_SOURCE
151 #endif
153 
158 typedef struct
159 {
163 
164 /*******************************************************************************
165  * API
166  ******************************************************************************/
167 
168 #if defined(__cplusplus)
169 extern "C" {
170 #endif
171 
182 
192 
211  security_key_id_t keyId,
212  const uint8_t *plainText,
213  uint32_t msgLen,
214  uint8_t *cipherText,
215  uint32_t timeout);
216 
235  security_key_id_t keyId,
236  const uint8_t *cipherText,
237  uint32_t msgLen,
238  uint8_t *plainText,
239  uint32_t timeout);
240 
260  security_key_id_t keyId,
261  const uint8_t *plainText,
262  uint32_t msgLen,
263  const uint8_t *iv,
264  uint8_t *cipherText,
265  uint32_t timeout);
266 
286  security_key_id_t keyId,
287  const uint8_t *cipherText,
288  uint32_t msgLen,
289  const uint8_t* iv,
290  uint8_t *plainText,
291  uint32_t timeout);
292 
312  security_key_id_t keyId,
313  const uint8_t *msg,
314  uint64_t msgLen,
315  uint8_t *cmac,
316  uint32_t timeout);
317 
339  security_key_id_t keyId,
340  const uint8_t *msg,
341  uint64_t msgLen,
342  const uint8_t *mac,
343  uint16_t macLen,
344  bool *verifStatus,
345  uint32_t timeout);
346 
372  security_key_id_t keyId,
373  const uint8_t *m1,
374  const uint8_t *m2,
375  const uint8_t *m3,
376  uint8_t *m4,
377  uint8_t *m5,
378  uint32_t timeout);
379 
393  const uint8_t *plainKey,
394  uint32_t timeout);
395 
413  uint8_t *m1,
414  uint8_t *m2,
415  uint8_t *m3,
416  uint8_t *m4,
417  uint8_t *m5,
418  uint32_t timeout);
419 
436  const uint8_t *entropy,
437  uint32_t timeout);
438 
450  uint32_t timeout);
451 
466  uint8_t *rnd,
467  uint32_t timeout);
468 
488  const uint8_t *challenge,
489  uint8_t *uid,
490  uint8_t *sreg,
491  uint8_t *mac,
492  uint32_t timeout);
493 
509  uint32_t bootImageSize,
510  const uint8_t *bootImagePtr,
511  uint32_t timeout);
512 
524  uint32_t timeout);
525 
538  uint32_t timeout);
539 
556  uint32_t bootSize,
557  security_boot_flavor_t bootFlavor,
558  uint32_t timeout);
559 
575  uint8_t *challenge,
576  uint32_t timeout);
577 
592  const uint8_t *authorization,
593  uint32_t timeout);
594 
615  const uint8_t *msg,
616  uint32_t msgLen,
617  uint8_t *mpCompress,
618  uint32_t timeout);
619 
635  uint8_t *trnd,
636  uint32_t timeout);
637 
647 
658 
678  security_key_id_t keyId,
679  const uint8_t *plainText,
680  uint32_t msgLen,
681  uint8_t *cipherText);
682 
702  security_key_id_t keyId,
703  const uint8_t *cipherText,
704  uint32_t msgLen,
705  uint8_t *plainText);
706 
727  security_key_id_t keyId,
728  const uint8_t *plainText,
729  uint32_t msgLen,
730  const uint8_t *iv,
731  uint8_t *cipherText);
732 
753  security_key_id_t keyId,
754  const uint8_t *cipherText,
755  uint32_t msgLen,
756  const uint8_t* iv,
757  uint8_t *plainText);
758 
777  security_key_id_t keyId,
778  const uint8_t *msg,
779  uint64_t msgLen,
780  uint8_t *cmac);
781 
806  security_key_id_t keyId,
807  const uint8_t *msg,
808  uint64_t msgLen,
809  const uint8_t *mac,
810  uint16_t macLen,
811  bool *verifStatus);
812 
813 #if defined(__cplusplus)
814 }
815 #endif
816 
818 #endif /* SECURITY_PAL_H_ */
819 
820 /*******************************************************************************
821  * EOF
822  ******************************************************************************/
status_t SECURITY_CancelCommand(security_instance_t instance)
Cancel Command.
Definition: security_pal.c:874
status_t SECURITY_LoadKey(security_instance_t instance, security_key_id_t keyId, const uint8_t *m1, const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5, uint32_t timeout)
Load Key.
Definition: security_pal.c:438
status_t SECURITY_ExtendSeed(security_instance_t instance, const uint8_t *entropy, uint32_t timeout)
Initialize Random Number Generator.
Definition: security_pal.c:528
Define user configuration Implements : security_user_config_t_Class.
Definition: security_pal.h:158
status_t SECURITY_DecryptEcb(security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, uint8_t *plainText)
Decrypt ECB.
Definition: security_pal.c:953
status_t SECURITY_GenerateMacBlocking(security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, uint8_t *cmac, uint32_t timeout)
MAC Generation.
Definition: security_pal.c:372
status_t SECURITY_GenerateMac(security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, uint8_t *cmac)
Generate MAC.
status_t SECURITY_EncryptCbc(security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, const uint8_t *iv, uint8_t *cipherText)
Encrypt CBC.
Definition: security_pal.c:982
status_t SECURITY_DbgChal(security_instance_t instance, uint8_t *challenge, uint32_t timeout)
Debug Challenge.
Definition: security_pal.c:758
status_t SECURITY_BootFailure(security_instance_t instance, uint32_t timeout)
Boot Failure.
Definition: security_pal.c:671
security_boot_flavor_t
Defines the security boot flavor Implements : security_boot_flavor_t_Class.
Definition: security_pal.h:100
status_t SECURITY_EncryptEcb(security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, uint8_t *cipherText)
Encrypt ECB.
Definition: security_pal.c:924
status_t SECURITY_DecryptCbc(security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, const uint8_t *iv, uint8_t *plainText)
Decrypt CBC.
status_t SECURITY_DecryptEcbBlocking(security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, uint8_t *plainText, uint32_t timeout)
ECB Decryption.
Definition: security_pal.c:281
status_t
Status return codes. Common error codes will be a unified enumeration (C enum) that will contain all ...
Definition: status.h:44
void(* security_callback_t)(uint32_t completedCmd, void *callbackParam)
Callback for security modules.
Definition: callbacks.h:168
status_t SECURITY_ExportRamKey(security_instance_t instance, uint8_t *m1, uint8_t *m2, uint8_t *m3, uint8_t *m4, uint8_t *m5, uint32_t timeout)
Export RAM key.
Definition: security_pal.c:497
status_t SECURITY_Deinit(security_instance_t instance)
De-initializes the SECURITY module.
Definition: security_pal.c:212
status_t SECURITY_EncryptCbcBlocking(security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, const uint8_t *iv, uint8_t *cipherText, uint32_t timeout)
CBC Decryption.
Definition: security_pal.c:311
status_t SECURITY_LoadPlainKey(security_instance_t instance, const uint8_t *plainKey, uint32_t timeout)
Load Plain Key.
Definition: security_pal.c:470
status_t SECURITY_VerifyMacBlocking(security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus, uint32_t timeout)
MAC Verification.
Definition: security_pal.c:404
security_callback_t callback
Definition: security_pal.h:160
security_key_id_t
Defines the security keys Implements : security_key_id_t_Class.
Definition: security_pal.h:61
security_cmd_t
Defines the security command Implements : security_cmd_t_Class.
Definition: security_pal.h:112
status_t SECURITY_VerifyMac(security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
Verify MAC.
status_t SECURITY_SecureBoot(security_instance_t instance, uint32_t bootImageSize, const uint8_t *bootImagePtr, uint32_t timeout)
Secure boot.
Definition: security_pal.c:640
status_t SECURITY_MPCompress(security_instance_t instance, const uint8_t *msg, uint32_t msgLen, uint8_t *mpCompress, uint32_t timeout)
Miyaguchi-Prenell Compression.
Definition: security_pal.c:815
status_t SECURITY_Init(security_instance_t instance, const security_user_config_t *config)
Initializes the SECURITY module.
Definition: security_pal.c:156
status_t SECURITY_GenerateTrnd(security_instance_t instance, uint8_t *trnd, uint32_t timeout)
Generate True Random Number.
Definition: security_pal.c:846
status_t SECURITY_BootDefine(security_instance_t instance, uint32_t bootSize, security_boot_flavor_t bootFlavor, uint32_t timeout)
Boot Define.
Definition: security_pal.c:725
status_t SECURITY_EncryptEcbBlocking(security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, uint8_t *cipherText, uint32_t timeout)
ECB Encryption.
Definition: security_pal.c:251
status_t SECURITY_DecryptCbcBlocking(security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, const uint8_t *iv, uint8_t *plainText, uint32_t timeout)
CBC Decryption.
Definition: security_pal.c:342
status_t SECURITY_GenerateRnd(security_instance_t instance, uint8_t *rnd, uint32_t timeout)
Generate RND.
Definition: security_pal.c:581
status_t SECURITY_GetAsyncCmdStatus(security_instance_t instance)
Get asynchronous command status.
Definition: security_pal.c:899
status_t SECURITY_DbgAuth(security_instance_t instance, const uint8_t *authorization, uint32_t timeout)
Debug Authentification.
Definition: security_pal.c:786
security_instance_t
Define instances for SECURITY PAL Implements : security_instance_t_Class.
Definition: security_pal.h:52
status_t SECURITY_BootOk(security_instance_t instance, uint32_t timeout)
Boot Ok.
Definition: security_pal.c:698
status_t SECURITY_GetId(security_instance_t instance, const uint8_t *challenge, uint8_t *uid, uint8_t *sreg, uint8_t *mac, uint32_t timeout)
Get ID.
Definition: security_pal.c:609
status_t SECURITY_InitRng(security_instance_t instance, uint32_t timeout)
Initialize Random Number Generator.
Definition: security_pal.c:555