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 #include "callbacks.h"
29 
59 /*******************************************************************************
60  * Definitions
61  ******************************************************************************/
62 
64 #define CSEC_STATUS_BUSY (0x1U)
65 
66 #define CSEC_STATUS_SECURE_BOOT (0x2U)
67 
69 #define CSEC_STATUS_BOOT_INIT (0x4U)
70 
73 #define CSEC_STATUS_BOOT_FINISHED (0x8U)
74 
76 #define CSEC_STATUS_BOOT_OK (0x10U)
77 
78 #define CSEC_STATUS_RND_INIT (0x20U)
79 
80 #define CSEC_STATUS_EXT_DEBUGGER (0x40U)
81 
83 #define CSEC_STATUS_INT_DEBUGGER (0x80U)
84 
92 typedef uint8_t csec_status_t;
93 
100 typedef enum {
115  CSEC_RAM_KEY = 0xFU,
116  CSEC_KEY_11 = 0x14U,
123 } csec_key_id_t;
124 
130 typedef enum {
153 } csec_cmd_t;
154 
160 typedef enum {
164 
170 typedef enum {
176 
186 typedef struct {
189  const uint8_t *inputBuff;
190  uint8_t *outputBuff;
191  uint32_t index;
192  uint32_t fullSize;
193  uint32_t partSize;
196  const uint8_t *iv;
198  uint32_t msgLen;
199  bool *verifStatus;
200  bool macWritten;
201  const uint8_t *mac;
202  uint32_t macLen;
205 } csec_state_t;
206 
207 
208 /*******************************************************************************
209  * API
210  ******************************************************************************/
211 
212 #if defined(__cplusplus)
213 extern "C" {
214 #endif
215 
223 void CSEC_DRV_Init(csec_state_t *state);
224 
229 void CSEC_DRV_Deinit(void);
230 
248  const uint8_t *plainText, uint32_t length, uint8_t *cipherText,
249  uint32_t timeout);
250 
267 status_t CSEC_DRV_DecryptECB(csec_key_id_t keyId, const uint8_t *cipherText,
268  uint32_t length, uint8_t *plainText, uint32_t timeout);
269 
289  const uint8_t *plainText, uint32_t length,
290  const uint8_t *iv, uint8_t *cipherText, uint32_t timeout);
291 
309 status_t CSEC_DRV_DecryptCBC(csec_key_id_t keyId, const uint8_t *cipherText,
310  uint32_t length, const uint8_t* iv, uint8_t *plainText, uint32_t timeout);
311 
326 status_t CSEC_DRV_GenerateMAC(csec_key_id_t keyId, const uint8_t *msg,
327  uint32_t msgLen, uint8_t *cmac, uint32_t timeout);
328 
347  const uint8_t *msg, uint32_t msgLen, uint8_t *cmac);
348 
366 status_t CSEC_DRV_VerifyMAC(csec_key_id_t keyId, const uint8_t *msg,
367  uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus,
368  uint32_t timeout);
369 
390 status_t CSEC_DRV_VerifyMACAddrMode(csec_key_id_t keyId, const uint8_t *msg,
391  uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus);
392 
413 status_t CSEC_DRV_LoadKey(csec_key_id_t keyId, const uint8_t *m1,
414  const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5);
415 
428 status_t CSEC_DRV_LoadPlainKey(const uint8_t *plainKey);
429 
443 status_t CSEC_DRV_ExportRAMKey(uint8_t *m1, uint8_t *m2,
444  uint8_t *m3, uint8_t *m4, uint8_t *m5);
445 
455 
469 status_t CSEC_DRV_ExtendSeed(const uint8_t *entropy);
470 
483 status_t CSEC_DRV_GenerateRND(uint8_t *rnd);
484 
494 
505 
518 status_t CSEC_DRV_BootDefine(uint32_t bootSize, csec_boot_flavor_t bootFlavor);
519 
530 {
531  return (FTFC->FCSESTAT);
532 }
533 
549 status_t CSEC_DRV_GetID(const uint8_t *challenge, uint8_t *uid,
550  uint8_t *sreg, uint8_t *mac);
551 
564 status_t CSEC_DRV_DbgChal(uint8_t *challenge);
565 
577 status_t CSEC_DRV_DbgAuth(const uint8_t *authorization);
578 
596 status_t CSEC_DRV_MPCompress(const uint8_t *msg, uint16_t msgLen,
597  uint8_t *mpCompress, uint32_t timeout);
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 *plainText,
659  uint32_t length,
660  const uint8_t* iv,
661  uint8_t *cipherText);
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(security_callback_t callbackFunc, void *callbackParam);
751 
755 void CSEC_DRV_CancelCommand(void);
756 
757 #if defined(__cplusplus)
758 }
759 #endif
760 
763 #endif /* CSEC_DRV_H */
764 /*******************************************************************************
765  * EOF
766  ******************************************************************************/
status_t CSEC_DRV_LoadPlainKey(const uint8_t *plainKey)
Updates the RAM key memory slot with a 128-bit plaintext.
Definition: csec_driver.c:657
status_t CSEC_DRV_GetAsyncCmdStatus(void)
Checks the status of the execution of an asynchronous command.
Definition: csec_driver.c:1388
bool cmdInProgress
Definition: csec_driver.h:187
security_callback_t callback
Definition: csec_driver.h:203
void CSEC_DRV_InstallCallback(security_callback_t callbackFunc, void *callbackParam)
Installs a callback function which will be invoked when an asynchronous command finishes its executio...
Definition: csec_driver.c:1763
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:968
Internal driver state information.
Definition: csec_driver.h:186
status_t CSEC_DRV_DecryptCBC(csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, const uint8_t *iv, uint8_t *plainText, uint32_t timeout)
Performs the AES-128 decryption in CBC mode.
Definition: csec_driver.c:330
void CSEC_DRV_Init(csec_state_t *state)
Initializes the internal state of the driver and enables the FTFC interrupt.
Definition: csec_driver.c:134
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:1060
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:1348
csec_key_id_t
Specify the KeyID to be used to implement the requested cryptographic operation.
Definition: csec_driver.h:100
csec_key_id_t keyId
Definition: csec_driver.h:194
status_t CSEC_DRV_BootOK(void)
Marks a successful boot verification during later stages of the boot process.
Definition: csec_driver.c:895
status_t CSEC_DRV_EncryptCBCAsync(csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, const uint8_t *iv, uint8_t *cipherText)
Asynchronously performs the AES-128 encryption in CBC mode.
Definition: csec_driver.c:1245
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, uint32_t timeout)
Verifies the MAC of a given message using CMAC with AES-128.
Definition: csec_driver.c:487
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:550
status_t CSEC_DRV_InitRNG(void)
Initializes the seed and derives a key for the PRNG.
Definition: csec_driver.c:746
static csec_status_t CSEC_DRV_GetStatus(void)
Returns the content of the status register.
Definition: csec_driver.h:529
const uint8_t * iv
Definition: csec_driver.h:196
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:92
status_t CSEC_DRV_ExtendSeed(const uint8_t *entropy)
Extends the seed of the PRNG.
Definition: csec_driver.c:783
status_t CSEC_DRV_EncryptECB(csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, uint8_t *cipherText, uint32_t timeout)
Performs the AES-128 encryption in ECB mode.
Definition: csec_driver.c:169
status_t CSEC_DRV_BootFailure(void)
Signals a failure detected during later stages of the boot process.
Definition: csec_driver.c:861
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:1213
bool * verifStatus
Definition: csec_driver.h:199
csec_cmd_t cmd
Definition: csec_driver.h:188
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:1181
uint32_t partSize
Definition: csec_driver.h:193
status_t CSEC_DRV_DecryptECB(csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, uint8_t *plainText, uint32_t timeout)
Performs the AES-128 decryption in ECB mode.
Definition: csec_driver.c:222
uint32_t msgLen
Definition: csec_driver.h:198
uint8_t * outputBuff
Definition: csec_driver.h:190
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 CSEC_DRV_EncryptCBC(csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, const uint8_t *iv, uint8_t *cipherText, uint32_t timeout)
Performs the AES-128 encryption in CBC mode.
Definition: csec_driver.c:274
#define FTFC
Definition: S32K118.h:3641
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:442
void CSEC_DRV_Deinit(void)
Clears the internal state of the driver and disables the FTFC interrupt.
Definition: csec_driver.c:154
status_t errCode
Definition: csec_driver.h:195
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:603
uint32_t macLen
Definition: csec_driver.h:202
uint32_t index
Definition: csec_driver.h:191
status_t CSEC_DRV_MPCompress(const uint8_t *msg, uint16_t msgLen, uint8_t *mpCompress, uint32_t timeout)
Compresses the given messages by accessing the Miyaguchi-Prenell compression feature with in the CSEc...
Definition: csec_driver.c:1097
void CSEC_DRV_CancelCommand(void)
Cancels a previously launched asynchronous command.
Definition: csec_driver.c:1778
csec_boot_flavor_t
Specifies the boot type for the BOOT_DEFINE command.
Definition: csec_driver.h:170
const uint8_t * mac
Definition: csec_driver.h:201
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:1280
csec_call_sequence_t
Specifies if the information is the first or a following function call.
Definition: csec_driver.h:160
csec_cmd_t
CSEc commands which follow the same values as the SHE command definition.
Definition: csec_driver.h:130
csec_call_sequence_t seq
Definition: csec_driver.h:197
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:694
status_t CSEC_DRV_GenerateRND(uint8_t *rnd)
Generates a vector of 128 random bits.
Definition: csec_driver.c:821
uint32_t fullSize
Definition: csec_driver.h:192
status_t CSEC_DRV_GenerateMAC(csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac, uint32_t timeout)
Calculates the MAC of a given message using CMAC with AES-128.
Definition: csec_driver.c:386
const uint8_t * inputBuff
Definition: csec_driver.h:189
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:1020
void * callbackParam
Definition: csec_driver.h:204
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:929
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:1315