S32 SDK
csec_driver.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016 NXP
4  * All rights reserved.
5  *
6  * THIS SOFTWARE IS PROVIDED BY NXP "AS IS" AND ANY EXPRESSED OR
7  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
8  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
9  * IN NO EVENT SHALL NXP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
10  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
11  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
12  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
13  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
14  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
15  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
16  * THE POSSIBILITY OF SUCH DAMAGE.
17  */
18 
19 #ifndef CSEC_DRV_H
20 #define CSEC_DRV_H
21 
22 #include <stdint.h>
23 #include <stdbool.h>
24 #include <stdlib.h>
25 #include "device_registers.h"
26 #include "interrupt_manager.h"
27 #include "status.h"
28 
58 /*******************************************************************************
59  * Definitions
60  ******************************************************************************/
61 
63 #define CSEC_STATUS_BUSY (0x1U)
64 
65 #define CSEC_STATUS_SECURE_BOOT (0x2U)
66 
68 #define CSEC_STATUS_BOOT_INIT (0x4U)
69 
72 #define CSEC_STATUS_BOOT_FINISHED (0x8U)
73 
75 #define CSEC_STATUS_BOOT_OK (0x10U)
76 
77 #define CSEC_STATUS_RND_INIT (0x20U)
78 
79 #define CSEC_STATUS_EXT_DEBUGGER (0x40U)
80 
82 #define CSEC_STATUS_INT_DEBUGGER (0x80U)
83 
91 typedef uint8_t csec_status_t;
92 
99 typedef enum {
114  CSEC_RAM_KEY = 0xFU,
115  CSEC_KEY_11 = 0x14U,
126 } csec_key_id_t;
127 
133 typedef enum {
156 } csec_cmd_t;
157 
163 typedef enum {
167 
173 typedef enum {
179 
185 typedef void (*csec_callback_t)(csec_cmd_t completedCmd, void *callbackParam);
186 
196 typedef struct {
199  const uint8_t *inputBuff;
200  uint8_t *outputBuff;
201  uint32_t index;
202  uint32_t fullSize;
203  uint32_t partSize;
206  const uint8_t *iv;
208  uint32_t msgLen;
209  bool *verifStatus;
210  bool macWritten;
211  const uint8_t *mac;
212  uint32_t macLen;
215 } csec_state_t;
216 
217 
218 /*******************************************************************************
219  * API
220  ******************************************************************************/
221 
222 #if defined(__cplusplus)
223 extern "C" {
224 #endif
225 
233 void CSEC_DRV_Init(csec_state_t *state);
234 
239 void CSEC_DRV_Deinit(void);
240 
257  const uint8_t *plainText, uint32_t length, uint8_t *cipherText);
258 
274 status_t CSEC_DRV_DecryptECB(csec_key_id_t keyId, const uint8_t *cipherText,
275  uint32_t length, uint8_t *plainText);
276 
294  const uint8_t *plainText, uint32_t length,
295  const uint8_t *iv, uint8_t *cipherText);
296 
313 status_t CSEC_DRV_DecryptCBC(csec_key_id_t keyId, const uint8_t *cipherText,
314  uint16_t length, const uint8_t* iv, uint8_t *plainText);
315 
329 status_t CSEC_DRV_GenerateMAC(csec_key_id_t keyId, const uint8_t *msg,
330  uint32_t msgLen, uint8_t *cmac);
331 
350  const uint8_t *msg, uint32_t msgLen, uint8_t *cmac);
351 
368 status_t CSEC_DRV_VerifyMAC(csec_key_id_t keyId, const uint8_t *msg,
369  uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus);
370 
391 status_t CSEC_DRV_VerifyMACAddrMode(csec_key_id_t keyId, const uint8_t *msg,
392  uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus);
393 
414 status_t CSEC_DRV_LoadKey(csec_key_id_t keyId, const uint8_t *m1,
415  const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5);
416 
429 status_t CSEC_DRV_LoadPlainKey(const uint8_t *plainKey);
430 
444 status_t CSEC_DRV_ExportRAMKey(uint8_t *m1, uint8_t *m2,
445  uint8_t *m3, uint8_t *m4, uint8_t *m5);
446 
456 
470 status_t CSEC_DRV_ExtendSeed(const uint8_t *entropy);
471 
484 status_t CSEC_DRV_GenerateRND(uint8_t *rnd);
485 
495 
506 
519 status_t CSEC_DRV_BootDefine(uint32_t bootSize, csec_boot_flavor_t bootFlavor);
520 
531 {
532  return (FTFC->FCSESTAT);
533 }
534 
550 status_t CSEC_DRV_GetID(const uint8_t *challenge, uint8_t *uid,
551  uint8_t *sreg, uint8_t *mac);
552 
565 status_t CSEC_DRV_DbgChal(uint8_t *challenge);
566 
578 status_t CSEC_DRV_DbgAuth(const uint8_t *authorization);
579 
596 status_t CSEC_DRV_MPCompress(const uint8_t *msg, uint16_t msgLen,
597  uint8_t *mpCompress);
598 
616  const uint8_t *plainText,
617  uint32_t length,
618  uint8_t *cipherText);
619 
637  const uint8_t *cipherText,
638  uint32_t length,
639  uint8_t *plainText);
658  const uint8_t *cipherText,
659  uint16_t length,
660  const uint8_t* iv,
661  uint8_t *plainText);
662 
681  const uint8_t *cipherText,
682  uint32_t length,
683  const uint8_t* iv,
684  uint8_t *plainText);
685 
703  const uint8_t *msg,
704  uint32_t msgLen,
705  uint8_t *cmac);
706 
727  const uint8_t *msg,
728  uint32_t msgLen,
729  const uint8_t *mac,
730  uint16_t macLen,
731  bool *verifStatus);
732 
742 
750 void CSEC_DRV_InstallCallback(csec_callback_t callbackFunc, void *callbackParam);
751 
752 #if defined(__cplusplus)
753 }
754 #endif
755 
758 #endif /* CSEC_DRV_H */
759 /*******************************************************************************
760  * EOF
761  ******************************************************************************/
status_t CSEC_DRV_LoadPlainKey(const uint8_t *plainKey)
Updates the RAM key memory slot with a 128-bit plaintext.
Definition: csec_driver.c:555
status_t CSEC_DRV_GetAsyncCmdStatus(void)
Checks the status of the execution of an asynchronous command.
Definition: csec_driver.c:1226
bool cmdInProgress
Definition: csec_driver.h:197
status_t CSEC_DRV_GetID(const uint8_t *challenge, uint8_t *uid, uint8_t *sreg, uint8_t *mac)
Returns the identity (UID) and the value of the status register protected by a MAC over a challenge a...
Definition: csec_driver.c:854
Internal driver state information.
Definition: csec_driver.h:196
void CSEC_DRV_Init(csec_state_t *state)
Initializes the internal state of the driver and enables the FTFC interrupt.
Definition: csec_driver.c:133
status_t CSEC_DRV_DbgAuth(const uint8_t *authorization)
Erases all keys (actual and outdated) stored in NVM Memory if the authorization is confirmed by CSEc...
Definition: csec_driver.c:944
status_t CSEC_DRV_VerifyMACAsync(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
Asynchronously verifies the MAC of a given message using CMAC with AES-128.
Definition: csec_driver.c:1191
csec_key_id_t
Specify the KeyID to be used to implement the requested cryptographic operation.
Definition: csec_driver.h:99
csec_key_id_t keyId
Definition: csec_driver.h:204
status_t CSEC_DRV_BootOK(void)
Marks a successful boot verification during later stages of the boot process.
Definition: csec_driver.c:785
status_t CSEC_DRV_MPCompress(const uint8_t *msg, uint16_t msgLen, uint8_t *mpCompress)
Compresses the given messages by accessing the Miyaguchi-Prenell compression feature with in the CSEc...
Definition: csec_driver.c:980
status_t CSEC_DRV_VerifyMACAddrMode(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
Verifies the MAC of a given message (located in Flash) using CMAC with AES-128.
Definition: csec_driver.c:450
status_t CSEC_DRV_InitRNG(void)
Initializes the seed and derives a key for the PRNG.
Definition: csec_driver.c:642
static csec_status_t CSEC_DRV_GetStatus(void)
Returns the content of the status register.
Definition: csec_driver.h:530
const uint8_t * iv
Definition: csec_driver.h:206
uint8_t csec_status_t
Represents the status of the CSEc module. Provides one bit for each status code as per SHE specificat...
Definition: csec_driver.h:91
status_t CSEC_DRV_ExtendSeed(const uint8_t *entropy)
Extends the seed of the PRNG.
Definition: csec_driver.c:677
status_t CSEC_DRV_BootFailure(void)
Signals a failure detected during later stages of the boot process.
Definition: csec_driver.c:753
status_t CSEC_DRV_DecryptECBAsync(csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, uint8_t *plainText)
Asynchronously performs the AES-128 decryption in ECB mode.
Definition: csec_driver.c:1074
csec_callback_t callback
Definition: csec_driver.h:213
bool * verifStatus
Definition: csec_driver.h:209
csec_cmd_t cmd
Definition: csec_driver.h:198
status_t CSEC_DRV_EncryptECBAsync(csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, uint8_t *cipherText)
Asynchronously performs the AES-128 encryption in ECB mode.
Definition: csec_driver.c:1046
uint32_t partSize
Definition: csec_driver.h:203
uint32_t msgLen
Definition: csec_driver.h:208
void CSEC_DRV_InstallCallback(csec_callback_t callbackFunc, void *callbackParam)
Installs a callback function which will be invoked when an asynchronous command finishes its executio...
Definition: csec_driver.c:1599
uint8_t * outputBuff
Definition: csec_driver.h:200
status_t
Status return codes. Common error codes will be a unified enumeration (C enum) that will contain all ...
Definition: status.h:44
status_t CSEC_DRV_DecryptCBC(csec_key_id_t keyId, const uint8_t *cipherText, uint16_t length, const uint8_t *iv, uint8_t *plainText)
Performs the AES-128 decryption in CBC mode.
Definition: csec_driver.c:279
status_t CSEC_DRV_DecryptECB(csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, uint8_t *plainText)
Performs the AES-128 decryption in ECB mode.
Definition: csec_driver.c:203
status_t CSEC_DRV_EncryptCBC(csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, const uint8_t *iv, uint8_t *cipherText)
Performs the AES-128 encryption in CBC mode.
Definition: csec_driver.c:239
#define FTFC
Definition: S32K142.h:3712
status_t CSEC_DRV_GenerateMACAddrMode(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac)
Calculates the MAC of a given message (located in Flash) using CMAC with AES-128. ...
Definition: csec_driver.c:359
void CSEC_DRV_Deinit(void)
Clears the internal state of the driver and disables the FTFC interrupt.
Definition: csec_driver.c:151
status_t errCode
Definition: csec_driver.h:205
status_t CSEC_DRV_LoadKey(csec_key_id_t keyId, const uint8_t *m1, const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5)
Updates an internal key per the SHE specification.
Definition: csec_driver.c:502
uint32_t macLen
Definition: csec_driver.h:212
status_t CSEC_DRV_EncryptECB(csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, uint8_t *cipherText)
Performs the AES-128 encryption in ECB mode.
Definition: csec_driver.c:166
uint32_t index
Definition: csec_driver.h:201
csec_boot_flavor_t
Specifies the boot type for the BOOT_DEFINE command.
Definition: csec_driver.h:173
const uint8_t * mac
Definition: csec_driver.h:211
status_t CSEC_DRV_DecryptCBCAsync(csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, const uint8_t *iv, uint8_t *plainText)
Asynchronously performs the AES-128 decryption in CBC mode.
Definition: csec_driver.c:1132
csec_call_sequence_t
Specifies if the information is the first or a following function call.
Definition: csec_driver.h:163
csec_cmd_t
CSEc commands which follow the same values as the SHE command definition.
Definition: csec_driver.h:133
csec_call_sequence_t seq
Definition: csec_driver.h:207
status_t CSEC_DRV_ExportRAMKey(uint8_t *m1, uint8_t *m2, uint8_t *m3, uint8_t *m4, uint8_t *m5)
Exports the RAM_KEY into a format protected by SECRET_KEY.
Definition: csec_driver.c:591
status_t CSEC_DRV_GenerateRND(uint8_t *rnd)
Generates a vector of 128 random bits.
Definition: csec_driver.c:714
status_t CSEC_DRV_EncryptCBCAsync(csec_key_id_t keyId, const uint8_t *cipherText, uint16_t length, const uint8_t *iv, uint8_t *plainText)
Asynchronously performs the AES-128 encryption in CBC mode.
Definition: csec_driver.c:1102
uint32_t fullSize
Definition: csec_driver.h:202
const uint8_t * inputBuff
Definition: csec_driver.h:199
status_t CSEC_DRV_DbgChal(uint8_t *challenge)
Obtains a random number which the user shall use along with the MASTER_ECU_KEY and UID to return an a...
Definition: csec_driver.c:905
void(* csec_callback_t)(csec_cmd_t completedCmd, void *callbackParam)
CSEc asynchronous command complete callback function type.
Definition: csec_driver.h:185
void * callbackParam
Definition: csec_driver.h:214
status_t CSEC_DRV_GenerateMAC(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac)
Calculates the MAC of a given message using CMAC with AES-128.
Definition: csec_driver.c:319
status_t CSEC_DRV_VerifyMAC(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
Verifies the MAC of a given message using CMAC with AES-128.
Definition: csec_driver.c:403
status_t CSEC_DRV_BootDefine(uint32_t bootSize, csec_boot_flavor_t bootFlavor)
Implements an extension of the SHE standard to define both the user boot size and boot method...
Definition: csec_driver.c:817
status_t CSEC_DRV_GenerateMACAsync(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac)
Asynchronously calculates the MAC of a given message using CMAC with AES-128.
Definition: csec_driver.c:1162