Skip to content

iotsafe.h

Functions

Name
int wolfSSL_CTX_iotsafe_enable(WOLFSSL_CTX * ctx)
This function enables the IoT-Safe support on the given context.
int wolfSSL_iotsafe_on(WOLFSSL * ssl, byte privkey_id, byte ecdh_keypair_slot, byte peer_pubkey_slot, byte peer_cert_slot)
This function connects the IoT-Safe TLS callbacks to the given SSL session.
int wolfSSL_iotsafe_on_ex(WOLFSSL * ssl, byte * privkey_id, byte * ecdh_keypair_slot, byte * peer_pubkey_slot, byte * peer_cert_slot, word16 id_size)
This function connects the IoT_Safe TLS callbacks to the given SSL session. This is equivalent to wolfSSL_iotsafe_on except that the IDs for the IoT-SAFE slots can be passed by reference, and the length of the ID fields can be specified via the parameter "id_size".
void wolfIoTSafe_SetCSIM_read_cb(wolfSSL_IOTSafe_CSIM_read_cb rf)
Associates a read callback for the AT+CSIM commands. This input function is usually associated to a read event of a UART channel communicating with the modem. The read callback associated is global and changes for all the contexts that use IoT-safe support at the same time.
void wolfIoTSafe_SetCSIM_write_cb(wolfSSL_IOTSafe_CSIM_write_cb wf)
Associates a write callback for the AT+CSIM commands. This output function is usually associated to a write event on a UART channel communicating with the modem. The write callback associated is global and changes for all the contexts that use IoT-safe support at the same time.
int wolfIoTSafe_GetRandom(unsigned char * out, word32 sz)
Generate a random buffer of given size, using the IoT-Safe function GetRandom. This function is automatically used by the wolfCrypt RNG object.
int wolfIoTSafe_GetCert(uint8_t id, unsigned char * output, unsigned long sz)
Import a certificate stored in a file on IoT-Safe applet, and store it locally in memory. Works with one-byte file ID field.
int wolfIoTSafe_GetCert_ex(uint8_t * id, uint16_t id_sz, unsigned char * output, unsigned long sz)
Import a certificate stored in a file on IoT_Safe applet, and store it locally in memory. Equivalent to wolfIoTSafe_GetCert, except that it can be invoked with a file ID of two or more bytes.
int wc_iotsafe_ecc_import_public(ecc_key * key, byte key_id)
Import an ECC 256-bit public key, stored in the IoT-Safe applet, into an ecc_key object.
int wc_iotsafe_ecc_export_public(ecc_key * key, byte key_id)
Export an ECC 256-bit public key, from ecc_key object to a writable public-key slot into the IoT-Safe applet.
int wc_iotsafe_ecc_import_public_ex(ecc_key * key, byte * key_id, word16 id_size)
Export an ECC 256_bit public key, from ecc_key object to a writable public_key slot into the IoT_Safe applet. Equivalent to wc_iotsafe_ecc_import_public, except that it can be invoked with a key ID of two or more bytes.
int wc_iotsafe_ecc_export_private(ecc_key * key, byte key_id)
Export an ECC 256-bit key, from ecc_key object to a writable private-key slot into the IoT-Safe applet.
int wc_iotsafe_ecc_export_private_ex(ecc_key * key, byte * key_id, word16 id_size)
Export an ECC 256_bit key, from ecc_key object to a writable private_key slot into the IoT_Safe applet. Equivalent to wc_iotsafe_ecc_export_private, except that it can be invoked with a key ID of two or more bytes.
int wc_iotsafe_ecc_sign_hash(byte * in, word32 inlen, byte * out, word32 * outlen, byte key_id)
Sign a pre-computed HASH, using a private key previously stored, or pre-provisioned, in the IoT-Safe applet.
int wc_iotsafe_ecc_sign_hash_ex(byte * in, word32 inlen, byte * out, word32 * outlen, byte * key_id, word16 id_size)
Sign a pre_computed HASH, using a private key previously stored, or pre_provisioned, in the IoT_Safe applet. Equivalent to wc_iotsafe_ecc_sign_hash, except that it can be invoked with a key ID of two or more bytes.
int wc_iotsafe_ecc_verify_hash(byte * sig, word32 siglen, byte * hash, word32 hashlen, int * res, byte key_id)
Verify an ECC signature against a pre-computed HASH, using a public key previously stored, or pre-provisioned, in the IoT-Safe applet. Result is written to res. 1 is valid, 0 is invalid. Note: Do not use the return value to test for valid. Only use res.
int wc_iotsafe_ecc_verify_hash_ex(byte * sig, word32 siglen, byte * hash, word32 hashlen, int * res, byte * key_id, word16 id_size)
Verify an ECC signature against a pre_computed HASH, using a public key previously stored, or pre_provisioned, in the IoT_Safe applet. Result is written to res. 1 is valid, 0 is invalid. Note: Do not use the return value to test for valid. Only use res. Equivalent to wc_iotsafe_ecc_verify_hash, except that it can be invoked with a key ID of two or more bytes.
int wc_iotsafe_ecc_gen_k(byte key_id)
Generate an ECC 256_bit keypair and store it in a (writable) slot into the IoT-Safe applet.

Functions Documentation

function wolfSSL_CTX_iotsafe_enable

int wolfSSL_CTX_iotsafe_enable(
    WOLFSSL_CTX * ctx
)

This function enables the IoT-Safe support on the given context.

Parameters:

  • ctx pointer to the WOLFSSL_CTX object on which the IoT-safe support must be enabled

See:

Return:

  • 0 on success
  • WC_HW_E on hardware error

Example

WOLFSSL_CTX *ctx;
ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
if (!ctx)
    return NULL;
wolfSSL_CTX_iotsafe_enable(ctx);

function wolfSSL_iotsafe_on

int wolfSSL_iotsafe_on(
    WOLFSSL * ssl,
    byte privkey_id,
    byte ecdh_keypair_slot,
    byte peer_pubkey_slot,
    byte peer_cert_slot
)

This function connects the IoT-Safe TLS callbacks to the given SSL session.

Parameters:

  • ssl pointer to the WOLFSSL object where the callbacks will be enabled
  • privkey_id id of the iot-safe applet slot containing the private key for the host
  • ecdh_keypair_slot id of the iot-safe applet slot to store the ECDH keypair
  • peer_pubkey_slot id of the iot-safe applet slot to store the other endpoint's public key for ECDH
  • peer_cert_slot id of the iot-safe applet slot to store the other endpoint's public key for verification

See:

Return:

  • 0 upon success
  • NOT_COMPILED_IN if HAVE_PK_CALLBACKS is disabled
  • BAD_FUNC_ARG if the ssl pointer is invalid

This should be called to connect a SSL session to IoT-Safe applet when the ID of the slots are one-byte long. If IoT-SAFE slots have an ID of two or more bytes, wolfSSL_iotsafe_on_ex() should be used instead.

Example

// Define key ids for IoT-Safe
#define PRIVKEY_ID 0x02
#define ECDH_KEYPAIR_ID 0x03
#define PEER_PUBKEY_ID 0x04
#define PEER_CERT_ID 0x05
// Create new ssl session
WOLFSSL *ssl;
ssl = wolfSSL_new(ctx);
if (!ssl)
    return NULL;
// Enable IoT-Safe and associate key slots
ret = wolfSSL_CTX_iotsafe_enable(ctx);
if (ret == 0) {
    ret = wolfSSL_iotsafe_on(ssl, PRIVKEY_ID, ECDH_KEYPAIR_ID, PEER_PUBKEY_ID, PEER_CERT_ID);
}

function wolfSSL_iotsafe_on_ex

int wolfSSL_iotsafe_on_ex(
    WOLFSSL * ssl,
    byte * privkey_id,
    byte * ecdh_keypair_slot,
    byte * peer_pubkey_slot,
    byte * peer_cert_slot,
    word16 id_size
)

This function connects the IoT-Safe TLS callbacks to the given SSL session. This is equivalent to wolfSSL_iotsafe_on except that the IDs for the IoT-SAFE slots can be passed by reference, and the length of the ID fields can be specified via the parameter "id_size".

Parameters:

  • ssl pointer to the WOLFSSL object where the callbacks will be enabled
  • privkey_id pointer to the id of the iot-safe applet slot containing the private key for the host
  • ecdh_keypair_slot pointer to the id of the iot-safe applet slot to store the ECDH keypair
  • peer_pubkey_slot pointer to the of id the iot-safe applet slot to store the other endpoint's public key for ECDH
  • peer_cert_slot pointer to the id of the iot-safe applet slot to store the other endpoint's public key for verification
  • id_size size of each slot ID

See:

Return:

  • 0 upon success
  • NOT_COMPILED_IN if HAVE_PK_CALLBACKS is disabled
  • BAD_FUNC_ARG if the ssl pointer is invalid

Example

// Define key ids for IoT-Safe (16 bit, little endian)
#define PRIVKEY_ID 0x0201
#define ECDH_KEYPAIR_ID 0x0301
#define PEER_PUBKEY_ID 0x0401
#define PEER_CERT_ID 0x0501
#define ID_SIZE (sizeof(word16))

word16 privkey = PRIVKEY_ID,
         ecdh_keypair = ECDH_KEYPAIR_ID,
         peer_pubkey = PEER_PUBKEY_ID,
         peer_cert = PEER_CERT_ID;



// Create new ssl session
WOLFSSL *ssl;
ssl = wolfSSL_new(ctx);
if (!ssl)
    return NULL;
// Enable IoT-Safe and associate key slots
ret = wolfSSL_CTX_iotsafe_enable(ctx);
if (ret == 0) {
    ret = wolfSSL_CTX_iotsafe_on_ex(ssl, &privkey, &ecdh_keypair, &peer_pubkey, &peer_cert, ID_SIZE);
}

function wolfIoTSafe_SetCSIM_read_cb

void wolfIoTSafe_SetCSIM_read_cb(
    wolfSSL_IOTSafe_CSIM_read_cb rf
)

Associates a read callback for the AT+CSIM commands. This input function is usually associated to a read event of a UART channel communicating with the modem. The read callback associated is global and changes for all the contexts that use IoT-safe support at the same time.

Parameters:

  • rf Read callback associated to a UART read event. The callback function takes two arguments (buf, len) and return the number of characters read, up to len. When a newline is encountered, the callback should return the number of characters received so far, including the newline character.

See: wolfIoTSafe_SetCSIM_write_cb

Example

// USART read function, defined elsewhere
int usart_read(char *buf, int len);

wolfIoTSafe_SetCSIM_read_cb(usart_read);

function wolfIoTSafe_SetCSIM_write_cb

void wolfIoTSafe_SetCSIM_write_cb(
    wolfSSL_IOTSafe_CSIM_write_cb wf
)

Associates a write callback for the AT+CSIM commands. This output function is usually associated to a write event on a UART channel communicating with the modem. The write callback associated is global and changes for all the contexts that use IoT-safe support at the same time.

Parameters:

  • rf Write callback associated to a UART write event. The callback function takes two arguments (buf, len) and return the number of characters written, up to len.

See: wolfIoTSafe_SetCSIM_read_cb

Example

// USART write function, defined elsewhere
int usart_write(const char *buf, int len);
wolfIoTSafe_SetCSIM_write_cb(usart_write);

function wolfIoTSafe_GetRandom

int wolfIoTSafe_GetRandom(
    unsigned char * out,
    word32 sz
)

Generate a random buffer of given size, using the IoT-Safe function GetRandom. This function is automatically used by the wolfCrypt RNG object.

Parameters:

  • out the buffer where the random sequence of bytes is stored.
  • sz the size of the random sequence to generate, in bytes

Return: 0 upon success

function wolfIoTSafe_GetCert

int wolfIoTSafe_GetCert(
    uint8_t id,
    unsigned char * output,
    unsigned long sz
)

Import a certificate stored in a file on IoT-Safe applet, and store it locally in memory. Works with one-byte file ID field.

Parameters:

  • id The file id in the IoT-Safe applet where the certificate is stored
  • output the buffer where the certificate will be imported
  • sz the maximum size available in the buffer output

Return:

  • the length of the certificate imported
  • < 0 in case of failure

Example

#define CRT_CLIENT_FILE_ID 0x03
unsigned char cert_buffer[2048];
// Get the certificate into the buffer
cert_buffer_size = wolfIoTSafe_GetCert(CRT_CLIENT_FILE_ID, cert_buffer, 2048);
if (cert_buffer_size < 1) {
    printf("Bad cli cert\n");
    return -1;
}
printf("Loaded Client certificate from IoT-Safe, size = %lu\n", cert_buffer_size);

// Use the certificate buffer as identity for the TLS client context
if (wolfSSL_CTX_use_certificate_buffer(cli_ctx, cert_buffer,
            cert_buffer_size, SSL_FILETYPE_ASN1) != SSL_SUCCESS) {
    printf("Cannot load client cert\n");
    return -1;
}
printf("Client certificate successfully imported.\n");

function wolfIoTSafe_GetCert_ex

int wolfIoTSafe_GetCert_ex(
    uint8_t * id,
    uint16_t id_sz,
    unsigned char * output,
    unsigned long sz
)

Import a certificate stored in a file on IoT-Safe applet, and store it locally in memory. Equivalent to wolfIoTSafe_GetCert, except that it can be invoked with a file ID of two or more bytes.

Parameters:

  • id Pointer to the file id in the IoT-Safe applet where the certificate is stored
  • id_sz Size of the file id in bytes
  • output the buffer where the certificate will be imported
  • sz the maximum size available in the buffer output

Return:

  • the length of the certificate imported
  • < 0 in case of failure

Example

#define CRT_CLIENT_FILE_ID 0x0302
#define ID_SIZE (sizeof(word16))
unsigned char cert_buffer[2048];
word16 client_file_id = CRT_CLIENT_FILE_ID;



// Get the certificate into the buffer
cert_buffer_size = wolfIoTSafe_GetCert_ex(&client_file_id, ID_SIZE, cert_buffer, 2048);
if (cert_buffer_size < 1) {
    printf("Bad cli cert\n");
    return -1;
}
printf("Loaded Client certificate from IoT-Safe, size = %lu\n", cert_buffer_size);

// Use the certificate buffer as identity for the TLS client context
if (wolfSSL_CTX_use_certificate_buffer(cli_ctx, cert_buffer,
            cert_buffer_size, SSL_FILETYPE_ASN1) != SSL_SUCCESS) {
    printf("Cannot load client cert\n");
    return -1;
}
printf("Client certificate successfully imported.\n");

function wc_iotsafe_ecc_import_public

int wc_iotsafe_ecc_import_public(
    ecc_key * key,
    byte key_id
)

Import an ECC 256-bit public key, stored in the IoT-Safe applet, into an ecc_key object.

Parameters:

  • key the ecc_key object that will contain the key imported from the IoT-Safe applet
  • id The key id in the IoT-Safe applet where the public key is stored

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_export_public

int wc_iotsafe_ecc_export_public(
    ecc_key * key,
    byte key_id
)

Export an ECC 256-bit public key, from ecc_key object to a writable public-key slot into the IoT-Safe applet.

Parameters:

  • key the ecc_key object containing the key to be exported
  • id The key id in the IoT-Safe applet where the public key will be stored

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_import_public_ex

int wc_iotsafe_ecc_import_public_ex(
    ecc_key * key,
    byte * key_id,
    word16 id_size
)

Export an ECC 256-bit public key, from ecc_key object to a writable public-key slot into the IoT-Safe applet. Equivalent to wc_iotsafe_ecc_import_public, except that it can be invoked with a key ID of two or more bytes.

Parameters:

  • key the ecc_key object containing the key to be exported
  • id The pointer to the key id in the IoT-Safe applet where the public key will be stored
  • id_size The key id size

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_export_private

int wc_iotsafe_ecc_export_private(
    ecc_key * key,
    byte key_id
)

Export an ECC 256-bit key, from ecc_key object to a writable private-key slot into the IoT-Safe applet.

Parameters:

  • key the ecc_key object containing the key to be exported
  • id The key id in the IoT-Safe applet where the private key will be stored

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_export_private_ex

int wc_iotsafe_ecc_export_private_ex(
    ecc_key * key,
    byte * key_id,
    word16 id_size
)

Export an ECC 256-bit key, from ecc_key object to a writable private-key slot into the IoT-Safe applet. Equivalent to wc_iotsafe_ecc_export_private, except that it can be invoked with a key ID of two or more bytes.

Parameters:

  • key the ecc_key object containing the key to be exported
  • id The pointer to the key id in the IoT-Safe applet where the private key will be stored
  • id_size The key id size

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_sign_hash

int wc_iotsafe_ecc_sign_hash(
    byte * in,
    word32 inlen,
    byte * out,
    word32 * outlen,
    byte key_id
)

Sign a pre-computed HASH, using a private key previously stored, or pre-provisioned, in the IoT-Safe applet.

Parameters:

  • in pointer to the buffer containing the message hash to sign
  • inlen length of the message hash to sign
  • out buffer in which to store the generated signature
  • outlen max length of the output buffer. Will store the bytes
  • id key id in the IoT-Safe applet for the slot containing the private key to sign the payload written to out upon successfully generating a message signature

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_sign_hash_ex

int wc_iotsafe_ecc_sign_hash_ex(
    byte * in,
    word32 inlen,
    byte * out,
    word32 * outlen,
    byte * key_id,
    word16 id_size
)

Sign a pre-computed HASH, using a private key previously stored, or pre-provisioned, in the IoT-Safe applet. Equivalent to wc_iotsafe_ecc_sign_hash, except that it can be invoked with a key ID of two or more bytes.

Parameters:

  • in pointer to the buffer containing the message hash to sign
  • inlen length of the message hash to sign
  • out buffer in which to store the generated signature
  • outlen max length of the output buffer. Will store the bytes
  • id pointer to a key id in the IoT-Safe applet for the slot containing the private key to sign the payload written to out upon successfully generating a message signature
  • id_size The key id size

See:

Return:

  • 0 upon success
  • < 0 in case of failure

function wc_iotsafe_ecc_verify_hash

int wc_iotsafe_ecc_verify_hash(
    byte * sig,
    word32 siglen,
    byte * hash,
    word32 hashlen,
    int * res,
    byte key_id
)

Verify an ECC signature against a pre-computed HASH, using a public key previously stored, or pre-provisioned, in the IoT-Safe applet. Result is written to res. 1 is valid, 0 is invalid. Note: Do not use the return value to test for valid. Only use res.

Parameters:

  • sig buffer containing the signature to verify
  • hash The hash (message digest) that was signed
  • hashlen The length of the hash (octets)
  • res Result of signature, 1==valid, 0==invalid
  • key_id The id of the slot where the public ECC key is stored in the IoT-Safe applet

See:

Return:

  • 0 upon success (even if the signature is not valid)
  • < 0 in case of failure.

function wc_iotsafe_ecc_verify_hash_ex

int wc_iotsafe_ecc_verify_hash_ex(
    byte * sig,
    word32 siglen,
    byte * hash,
    word32 hashlen,
    int * res,
    byte * key_id,
    word16 id_size
)

Verify an ECC signature against a pre-computed HASH, using a public key previously stored, or pre-provisioned, in the IoT-Safe applet. Result is written to res. 1 is valid, 0 is invalid. Note: Do not use the return value to test for valid. Only use res. Equivalent to wc_iotsafe_ecc_verify_hash, except that it can be invoked with a key ID of two or more bytes.

Parameters:

  • sig buffer containing the signature to verify
  • hash The hash (message digest) that was signed
  • hashlen The length of the hash (octets)
  • res Result of signature, 1==valid, 0==invalid
  • key_id The id of the slot where the public ECC key is stored in the IoT-Safe applet
  • id_size The key id size

See:

Return:

  • 0 upon success (even if the signature is not valid)
  • < 0 in case of failure.

function wc_iotsafe_ecc_gen_k

int wc_iotsafe_ecc_gen_k(
    byte key_id
)

Generate an ECC 256-bit keypair and store it in a (writable) slot into the IoT-Safe applet.

Parameters:

  • key_id The id of the slot where the ECC key pair is stored in the IoT-Safe applet.
  • key_id The id of the slot where the ECC key pair is stored in the IoT-Safe applet.
  • id_size The key id size

See:

Return:

  • 0 upon success
  • < 0 in case of failure.
  • 0 upon success
  • < 0 in case of failure.

Generate an ECC 256-bit keypair and store it in a (writable) slot into the IoT-Safe applet. Equivalent to wc_iotsafe_ecc_gen_k, except that it can be invoked with a key ID of two or more bytes.

Source code


int wolfSSL_CTX_iotsafe_enable(WOLFSSL_CTX *ctx);


int wolfSSL_iotsafe_on(WOLFSSL *ssl, byte privkey_id,
       byte ecdh_keypair_slot, byte peer_pubkey_slot, byte peer_cert_slot);


int wolfSSL_iotsafe_on_ex(WOLFSSL *ssl, byte *privkey_id,
       byte *ecdh_keypair_slot, byte *peer_pubkey_slot, byte *peer_cert_slot, word16 id_size);


void wolfIoTSafe_SetCSIM_read_cb(wolfSSL_IOTSafe_CSIM_read_cb rf);

void wolfIoTSafe_SetCSIM_write_cb(wolfSSL_IOTSafe_CSIM_write_cb wf);



int wolfIoTSafe_GetRandom(unsigned char* out, word32 sz);


int wolfIoTSafe_GetCert(uint8_t id, unsigned char *output, unsigned long sz);


int wolfIoTSafe_GetCert_ex(uint8_t *id, uint16_t id_sz, unsigned char *output, unsigned long sz);

int wc_iotsafe_ecc_import_public(ecc_key *key, byte key_id);

int wc_iotsafe_ecc_export_public(ecc_key *key, byte key_id);


int wc_iotsafe_ecc_import_public_ex(ecc_key *key, byte *key_id, word16 id_size);

int wc_iotsafe_ecc_export_private(ecc_key *key, byte key_id);

int wc_iotsafe_ecc_export_private_ex(ecc_key *key, byte *key_id, word16 id_size);

int wc_iotsafe_ecc_sign_hash(byte *in, word32 inlen, byte *out, word32 *outlen, byte key_id);

int wc_iotsafe_ecc_sign_hash_ex(byte *in, word32 inlen, byte *out, word32 *outlen, byte *key_id, word16 id_size);

int wc_iotsafe_ecc_verify_hash(byte *sig, word32 siglen, byte *hash, word32 hashlen, int *res, byte key_id);

int wc_iotsafe_ecc_verify_hash_ex(byte *sig, word32 siglen, byte *hash, word32 hashlen, int *res, byte *key_id, word16 id_size);

int wc_iotsafe_ecc_gen_k(byte key_id);

int wc_iotsafe_ecc_gen_k(byte key_id);

Updated on 2024-03-19 at 01:20:40 +0000