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 "csec_hal.h"
27 #include "interrupt_manager.h"
28 
38 /*******************************************************************************
39  * Definitions
40  ******************************************************************************/
41 
47 typedef enum {
53 
59 typedef void (*csec_callback_t)(csec_cmd_t completedCmd, void *callbackParam);
60 
70 typedef struct {
73  const uint8_t *inputBuff;
74  uint8_t *outputBuff;
75  uint32_t index;
76  uint32_t fullSize;
77  uint32_t partSize;
80  const uint8_t *iv;
82  uint32_t msgLen;
83  bool *verifStatus;
84  bool macWritten;
85  const uint8_t *mac;
86  uint32_t macLen;
88  void *callbackParam;
89 } csec_state_t;
90 
91 
92 /*******************************************************************************
93  * API
94  ******************************************************************************/
95 
96 #if defined(__cplusplus)
97 extern "C" {
98 #endif
99 
107 void CSEC_DRV_Init(csec_state_t *state);
108 
113 void CSEC_DRV_Deinit(void);
114 
131  const uint8_t *plainText, uint32_t length, uint8_t *cipherText);
132 
148 status_t CSEC_DRV_DecryptECB(csec_key_id_t keyId, const uint8_t *cipherText,
149  uint32_t length, uint8_t *plainText);
150 
168  const uint8_t *plainText, uint32_t length,
169  const uint8_t *iv, uint8_t *cipherText);
170 
187 status_t CSEC_DRV_DecryptCBC(csec_key_id_t keyId, const uint8_t *cipherText,
188  uint16_t length, const uint8_t* iv, uint8_t *plainText);
189 
203 status_t CSEC_DRV_GenerateMAC(csec_key_id_t keyId, const uint8_t *msg,
204  uint32_t msgLen, uint8_t *cmac);
205 
224  const uint8_t *msg, uint32_t msgLen, uint8_t *cmac);
225 
242 status_t CSEC_DRV_VerifyMAC(csec_key_id_t keyId, const uint8_t *msg,
243  uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus);
244 
265 status_t CSEC_DRV_VerifyMACAddrMode(csec_key_id_t keyId, const uint8_t *msg,
266  uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus);
267 
288 status_t CSEC_DRV_LoadKey(csec_key_id_t keyId, const uint8_t *m1,
289  const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5);
290 
303 status_t CSEC_DRV_LoadPlainKey(const uint8_t *plainKey);
304 
318 status_t CSEC_DRV_ExportRAMKey(uint8_t *m1, uint8_t *m2,
319  uint8_t *m3, uint8_t *m4, uint8_t *m5);
320 
330 
344 status_t CSEC_DRV_ExtendSeed(const uint8_t *entropy);
345 
358 status_t CSEC_DRV_GenerateRND(uint8_t *rnd);
359 
369 
380 
393 status_t CSEC_DRV_BootDefine(uint32_t bootSize, csec_boot_flavor_t bootFlavor);
394 
405 {
406  return CSEC_HAL_ReadStatus();
407 }
408 
424 status_t CSEC_DRV_GetID(const uint8_t *challenge, uint8_t *uid,
425  uint8_t *sreg, uint8_t *mac);
426 
439 status_t CSEC_DRV_DbgChal(uint8_t *challenge);
440 
452 status_t CSEC_DRV_DbgAuth(const uint8_t *authorization);
453 
470 status_t CSEC_DRV_MPCompress(const uint8_t *msg, uint16_t msgLen,
471  uint8_t *mpCompress);
472 
490  const uint8_t *plainText,
491  uint32_t length,
492  uint8_t *cipherText);
493 
511  const uint8_t *cipherText,
512  uint32_t length,
513  uint8_t *plainText);
532  const uint8_t *cipherText,
533  uint16_t length,
534  const uint8_t* iv,
535  uint8_t *plainText);
536 
555  const uint8_t *cipherText,
556  uint32_t length,
557  const uint8_t* iv,
558  uint8_t *plainText);
559 
577  const uint8_t *msg,
578  uint32_t msgLen,
579  uint8_t *cmac);
580 
601  const uint8_t *msg,
602  uint32_t msgLen,
603  const uint8_t *mac,
604  uint16_t macLen,
605  bool *verifStatus);
606 
616 
624 void CSEC_DRV_InstallCallback(csec_callback_t callbackFunc, void *callbackParam);
625 
626 #if defined(__cplusplus)
627 }
628 #endif
629 
632 #endif /* CSEC_DRV_H */
633 /*******************************************************************************
634  * EOF
635  ******************************************************************************/
status_t CSEC_DRV_LoadPlainKey(const uint8_t *plainKey)
Updates the RAM key memory slot with a 128-bit plaintext.
Definition: csec_driver.c:554
status_t CSEC_DRV_GetAsyncCmdStatus(void)
Checks the status of the execution of an asynchronous command.
Definition: csec_driver.c:1225
bool cmdInProgress
Definition: csec_driver.h:71
bool macWritten
Definition: csec_driver.h:84
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:853
Internal driver state information.
Definition: csec_driver.h:70
void CSEC_DRV_Init(csec_state_t *state)
Initializes the internal state of the driver and enables the FTFC interrupt.
Definition: csec_driver.c:132
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:943
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:1190
csec_key_id_t keyId
Definition: csec_driver.h:78
status_t CSEC_DRV_BootOK(void)
Marks a successful boot verification during later stages of the boot process.
Definition: csec_driver.c:784
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:979
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:449
status_t CSEC_DRV_InitRNG(void)
Initializes the seed and derives a key for the PRNG.
Definition: csec_driver.c:641
static csec_status_t CSEC_DRV_GetStatus(void)
Returns the content of the status register.
Definition: csec_driver.h:404
const uint8_t * iv
Definition: csec_driver.h:80
status_t CSEC_DRV_ExtendSeed(const uint8_t *entropy)
Extends the seed of the PRNG.
Definition: csec_driver.c:676
status_t CSEC_DRV_BootFailure(void)
Signals a failure detected during later stages of the boot process.
Definition: csec_driver.c:752
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:1073
csec_callback_t callback
Definition: csec_driver.h:87
bool * verifStatus
Definition: csec_driver.h:83
static csec_status_t CSEC_HAL_ReadStatus(void)
Reads the status of the CSEc module.
Definition: csec_hal.h:411
csec_cmd_t cmd
Definition: csec_driver.h:72
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:1045
uint32_t partSize
Definition: csec_driver.h:77
csec_cmd_t
CSEc commands which follow the same values as the SHE command definition.
Definition: csec_hal.h:108
uint32_t msgLen
Definition: csec_driver.h:82
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:1598
uint8_t * outputBuff
Definition: csec_driver.h:74
status_t
Status return codes. Common error codes will be a unified enumeration (C enum) that will contain all ...
Definition: status.h:31
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:278
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:202
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:238
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:358
void CSEC_DRV_Deinit(void)
Clears the internal state of the driver and disables the FTFC interrupt.
Definition: csec_driver.c:150
status_t errCode
Definition: csec_driver.h:79
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_hal.h:101
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:501
uint32_t macLen
Definition: csec_driver.h:86
csec_call_sequence_t
Specifies if the information is the first or a following function call.
Definition: csec_hal.h:185
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:165
uint32_t index
Definition: csec_driver.h:75
csec_boot_flavor_t
Specifies the boot type for the BOOT_DEFINE command.
Definition: csec_driver.h:47
const uint8_t * mac
Definition: csec_driver.h:85
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:1131
csec_call_sequence_t seq
Definition: csec_driver.h:81
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:590
status_t CSEC_DRV_GenerateRND(uint8_t *rnd)
Generates a vector of 128 random bits.
Definition: csec_driver.c:713
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:1101
uint32_t fullSize
Definition: csec_driver.h:76
const uint8_t * inputBuff
Definition: csec_driver.h:73
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:904
void(* csec_callback_t)(csec_cmd_t completedCmd, void *callbackParam)
CSEc asynchronous command complete callback function type.
Definition: csec_driver.h:59
void * callbackParam
Definition: csec_driver.h:88
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:318
csec_key_id_t
Specify the KeyID to be used to implement the requested cryptographic operation.
Definition: csec_hal.h:139
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:402
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:816
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:1161