SEcube
SEcube Open Source Library - Host
Data Structures | Macros | Typedefs | Functions
L1.h File Reference

This file contains L1 functions and structures. More...

#include "L0.h"
#include "se3c1def.h"

Go to the source code of this file.

Data Structures

struct  se3_session_
 SEcube Communication session structure. More...
 
struct  se3_key_
 SEcube Key structure. More...
 
struct  se3_algo_
 SEcube Algorithm structure. More...
 

Macros

#define SE3_REQ_CHALLENGE_SIZE   (96+16)
 
#define SE3_REQ_CHALLENGE_IV_OFFSET   (0)
 
#define SE3_REQ_CHALLENGE_TOKEN_OFFSET   (16)
 
#define SE3_REQ_CHALLENGE_CC_OFFSET   (32)
 
#define SE3_REQ_CHALLENGE_CC2_OFFSET   (64)
 
#define SE3_REQ_CHALLENGE_ACCESS_OFFSET   (96)
 
#define SE3_RESP_CHALLENGE_SC_OFFSET   (32)
 
#define SE3_RESP_LOGIN_TOKEN_OFFSET   (32)
 

Typedefs

typedef struct se3_session_ se3_session
 SEcube Communication session structure.
 
typedef struct se3_key_ se3_key
 SEcube Key structure.
 
typedef struct se3_algo_ se3_algo
 SEcube Algorithm structure.
 

Functions

uint16_t L1_login (se3_session *s, se3_device *dev, const uint8_t *pin, uint16_t access)
 This function is used to let a user/admin login on the device. More...
 
uint16_t L1_set_admin_PIN (se3_session *s, uint8_t *pin)
 This function is used to change the current admin pin. More...
 
uint16_t L1_set_user_PIN (se3_session *s, uint8_t *pin)
 This function is used to change the current user pin. More...
 
uint16_t L1_logout (se3_session *s)
 This function is used to logout from the device. More...
 
uint16_t L1_key_list (se3_session *s, uint16_t skip, uint16_t max_keys, se3_key *key_array, uint16_t *count)
 This function is used get the list of the already of the already available keys on the device. More...
 
uint16_t L1_key_edit (se3_session *s, uint16_t op, se3_key *k)
 This function is used to edit the keys data on the device. More...
 
bool L1_find_key (se3_session *s, uint32_t key_id)
 Check if a Key is present or not. More...
 
uint16_t L1_crypto_init (se3_session *s, uint16_t algorithm, uint16_t mode, uint32_t key_id, uint32_t *sess_id)
 Initialise a crypto session. More...
 
uint16_t L1_crypto_update (se3_session *s, uint32_t sess_id, uint16_t flags, uint16_t data1_len, uint8_t *data1, uint16_t data2_len, uint8_t *data2, uint16_t *dataout_len, uint8_t *data_out)
 Update a crypto session. More...
 
uint16_t L1_crypto_set_time (se3_session *s, uint32_t devtime)
 Set time for a crypto session. More...
 
uint16_t L1_encrypt (se3_session *s, uint16_t algorithm, uint16_t mode, uint32_t key_id, size_t datain_len, int8_t *data_in, size_t *dataout_len, uint8_t *data_out)
 This function is used to encrypt a buffer of data given the algorithm, the encryption mode, the buffer size, and where to store the encrypted data. More...
 
uint16_t L1_decrypt (se3_session *s, uint16_t algorithm, uint16_t mode, uint32_t key_id, size_t datain_len, int8_t *data_in, size_t *dataout_len, uint8_t *data_out)
 This function is used to decrypt a buffer of data given the algorithm, the decryption mode, the buffer size, and where to store the decrypted data. More...
 
uint16_t L1_digest (se3_session *s, uint16_t algorithm, size_t datain_len, int8_t *data_in, size_t *dataout_len, uint8_t *data_out)
 This function is used to sign a buffer of data given the algorithm, the amount of data to sign and where to store them. More...
 
uint16_t L1_get_algorithms (se3_session *s, uint16_t skip, uint16_t max_algorithms, se3_algo *algorithms_array, uint16_t *count)
 This function is used to retrieve a list from the device of available algorithms. More...
 

Detailed Description

This file contains L1 functions and structures.

Function Documentation

uint16_t L1_crypto_init ( se3_session s,
uint16_t  algorithm,
uint16_t  mode,
uint32_t  key_id,
uint32_t *  sess_id 
)

Initialise a crypto session.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]algorithmWhich algorithm to use, see AlgorithmAvail
[in]modeThis parameter strictly depends on the which algorithm is chosen
[in]key_idWhich key ID to use for encryption
[in]sess_idSession ID
Returns
Error code or SE3_OK
uint16_t L1_crypto_set_time ( se3_session s,
uint32_t  devtime 
)

Set time for a crypto session.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]devtimeTime to be set
Returns
Error code or SE3_OK
uint16_t L1_crypto_update ( se3_session s,
uint32_t  sess_id,
uint16_t  flags,
uint16_t  data1_len,
uint8_t *  data1,
uint16_t  data2_len,
uint8_t *  data2,
uint16_t *  dataout_len,
uint8_t *  data_out 
)

Update a crypto session.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]sess_idSession ID
[in]flagsParameter_Description
[in]data1_lenHow long is the buffer you want to encrypt
[in]data1Pointer to input buffer 1
[in]data2_lenLength of input buffer 1
[in]data2Pointer to input buffer 2
[out]dataout_lenLength of input buffer 1
[out]data_outPointer to the output buffer
Returns
Error code or SE3_OK
uint16_t L1_decrypt ( se3_session s,
uint16_t  algorithm,
uint16_t  mode,
uint32_t  key_id,
size_t  datain_len,
int8_t *  data_in,
size_t *  dataout_len,
uint8_t *  data_out 
)

This function is used to decrypt a buffer of data given the algorithm, the decryption mode, the buffer size, and where to store the decrypted data.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]algorithmWhich algorithm to use, see AlgorithmAvail
[in]modeThis parameter strictly depends on the which algorithm is chosen
[in]key_idWhich key ID to use for decryption
[in]datain_lenHow long is the buffer you want to decrypt
[in]data_inPointer to the buffer
[out]dataout_lenHow many data were actually decrypted
[out]data_outPointer to a pre-allocated buffer where to store the clear text
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
uint16_t L1_digest ( se3_session s,
uint16_t  algorithm,
size_t  datain_len,
int8_t *  data_in,
size_t *  dataout_len,
uint8_t *  data_out 
)

This function is used to sign a buffer of data given the algorithm, the amount of data to sign and where to store them.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]algorithmWhich algorithm to use, see AlgorithmAvail
[in]datain_lenHow long is the buffer you want to sign
[in]data_inPointer to the buffer
[out]dataout_lenHow many data were actually signed (can be NULL)
[out]data_outPointer to a pre-allocated buffer where to store the digest
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
uint16_t L1_encrypt ( se3_session s,
uint16_t  algorithm,
uint16_t  mode,
uint32_t  key_id,
size_t  datain_len,
int8_t *  data_in,
size_t *  dataout_len,
uint8_t *  data_out 
)

This function is used to encrypt a buffer of data given the algorithm, the encryption mode, the buffer size, and where to store the encrypted data.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]algorithmWhich algorithm to use, see AlgorithmAvail
[in]modeThis parameter strictly depends on the which algorithm is chosen
[in]key_idWhich key ID to use for encryption
[in]datain_lenHow long is the buffer you want to encrypt
[in]data_inPointer to the buffer
[out]dataout_lenHow many data were actually encrypted
[out]data_outPointer to a pre-allocated buffer where to store the cipher text
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
bool L1_find_key ( se3_session s,
uint32_t  key_id 
)

Check if a Key is present or not.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]key_idID of key to be found
Returns
true if key is found, false otherwise
uint16_t L1_get_algorithms ( se3_session s,
uint16_t  skip,
uint16_t  max_algorithms,
se3_algo algorithms_array,
uint16_t *  count 
)

This function is used to retrieve a list from the device of available algorithms.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]skipHow many algorithms you want to skip from the beginning of the device list
[in]max_algorithmsHow many algorithms you want to retrieve from the device
[out]algorithms_arrayPointer to the already allocated array where to store the algorithms
[in]countEffective number of retrieved keys
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
uint16_t L1_key_edit ( se3_session s,
uint16_t  op,
se3_key k 
)

This function is used to edit the keys data on the device.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]opsee KeyOpEdit
[in]kKey value you want to add/update/delete
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
uint16_t L1_key_list ( se3_session s,
uint16_t  skip,
uint16_t  max_keys,
se3_key key_array,
uint16_t *  count 
)

This function is used get the list of the already of the already available keys on the device.

Parameters
[in]sPointer to current se3_session, you must be logged in
[in]skipHow many keys you want to skip from the beginning of the list
[in]max_keysHow many keys you want to retrieve from the device
[out]key_arrayPointer to the already allocated array where to store the keys
[out]countEffective number of retrieved keys
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
uint16_t L1_login ( se3_session s,
se3_device dev,
const uint8_t *  pin,
uint16_t  access 
)

This function is used to let a user/admin login on the device.

Parameters
[out]sPointer to an already allocated se3_session object where to store current logged in session
[in]devDevice you want to login to
[in]pinPassword to login
[in]accesssee AccessLogin
Returns
It returns SE3_OK on success, otherwise see se3c1def.h

Before issueing any command to the device, you need to login. Some operations are allowed only to the admin user. After a flash erase, the admin pin and the user pin are both a sequence of 32 0s, please use L1_set_admin_PIN or L1_set_user_PIN to change them.

uint16_t L1_logout ( se3_session s)

This function is used to logout from the device.

Parameters
[in]sCurrent session you want to end
Returns
It returns SE3_OK on success, otherwise see se3c1def.h

After issueing this function, you will be forbidden to perform any command on the device. This can also be used to free the allocated resources, such as cryptographic sessions, with just one call.

uint16_t L1_set_admin_PIN ( se3_session s,
uint8_t *  pin 
)

This function is used to change the current admin pin.

Parameters
[in]sPointer to current se3_session, you must be logged in as admin to issue this command
[in]pinNew pin to be set
Returns
It returns SE3_OK on success, otherwise see se3c1def.h
uint16_t L1_set_user_PIN ( se3_session s,
uint8_t *  pin 
)

This function is used to change the current user pin.

Parameters
[in]sPointer to current se3_session, you must be logged in as admin to issue this command
[in]pinNew pin to be set
Returns
It returns SE3_OK on success, otherwise see se3c1def.h