feedc0de/wolfssl
1
0
Fork 0
forked from wolfSSL/wolfssl
Code Pull Requests Activity

IoT-SAFE: minor fixes + doxygen for new API calls

Browse Source
This commit is contained in:
Daniele Lacamera
2021-12-07 14:05:06 +01:00
parent 9e73c324a4
commit 1cb8b34fba
3 changed files with 230 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
doc/dox_comments/header_files/iotsafe.h
View File

@ -25,6 +25,10 @@ WOLFSSL_API int wolfSSL_CTX_iotsafe_enable(WOLFSSL_CTX *ctx);
/*!
\ingroup IoTSafe
\brief This function connects the IoT-Safe TLS callbacks to the given SSL session.
\brief 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, \ref wolfSSL_iotsafe_on_ex "wolfSSL_iotsafe_on_ex()"
should be used instead.
\param ssl pointer to the WOLFSSL object where the callbacks will be enabled
\param privkey_id id of the iot-safe applet slot containing the private key for the host
@ -48,15 +52,72 @@ WOLFSSL_API int wolfSSL_CTX_iotsafe_enable(WOLFSSL_CTX *ctx);
if (!ssl)
return NULL;
// Enable IoT-Safe and associate key slots
ret = wolfSSL_CTX_iotsafe_on(ssl, PRIVKEY_ID, ECDH_KEYPAIR_ID, PEER_PUBKEY_ID, PEER_CERT_ID);
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);
}
\endcode
\sa wolfSSL_iotsafe_on_ex
\sa wolfSSL_CTX_iotsafe_enable
*/
WOLFSSL_API int wolfSSL_iotsafe_on(WOLFSSL *ssl, byte privkey_id,
byte ecdh_keypair_slot, byte peer_pubkey_slot, byte peer_cert_slot);
/*!
\ingroup IoTSafe
\brief This function connects the IoT-Safe TLS callbacks to the given SSL session.
This is equivalent to \ref wolfSSL_iotsafe_on "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".
\param ssl pointer to the WOLFSSL object where the callbacks will be enabled
\param privkey_id pointer to the id of the iot-safe applet slot containing the private key for the host
\param ecdh_keypair_slot pointer to the id of the iot-safe applet slot to store the ECDH keypair
\param peer_pubkey_slot pointer to the of id the iot-safe applet slot to store the other endpoint's public key for ECDH
\param peer_cert_slot pointer to the id of the iot-safe applet slot to store the other endpoint's public key for verification
\param id_size size of each slot ID
\return 0 upon success
\return NOT_COMPILED_IN if HAVE_PK_CALLBACKS is disabled
\return BAD_FUNC_ARG if the ssl pointer is invalid
_Example_
\code
// 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);
}
\endcode
\sa wolfSSL_iotsafe_on
\sa wolfSSL_CTX_iotsafe_enable
*/
WOLFSSL_API 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);
/*!
\ingroup IoTSafe
\brief Associates a read callback for the AT+CSIM commands. This input function is
@ -120,14 +181,14 @@ WOLFSSL_API int wolfIoTSafe_GetRandom(unsigned char* out, word32 sz);
/*!
\ingroup IoTSafe
\brief Import a certificate stored in a file on IoT-Safe applet, and
store it locally in memory.
store it locally in memory. Works with one-byte file ID field.
\param id The file id in the IoT-Safe applet where the certificate is stored
\param output the buffer where the certificate will be imported
\param sz the maximum size available in the buffer output
\return the length of the certificate imported
\return < 0 in case of failure
_Example_
\code
#define CRT_CLIENT_FILE_ID 0x03
@ -139,7 +200,7 @@ WOLFSSL_API int wolfIoTSafe_GetRandom(unsigned char* out, word32 sz);
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) {
@ -153,6 +214,47 @@ WOLFSSL_API int wolfIoTSafe_GetRandom(unsigned char* out, word32 sz);
WOLFSSL_API int wolfIoTSafe_GetCert(uint8_t id, unsigned char *output, unsigned long sz);
/*!
\ingroup IoTSafe
\brief Import a certificate stored in a file on IoT-Safe applet, and
store it locally in memory. Equivalent to \ref wolfIoTSafe_GetCert "wolfIoTSafe_GetCert",
except that it can be invoked with a file ID of two or more bytes.
\param id Pointer to the file id in the IoT-Safe applet where the certificate is stored
\param id_sz Size of the file id in bytes
\param output the buffer where the certificate will be imported
\param sz the maximum size available in the buffer output
\return the length of the certificate imported
\return < 0 in case of failure
_Example_
\code
#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");
\endcode
*/
WOLFSSL_API int wolfIoTSafe_GetCert_ex(uint8_t *id, uint16_t id_sz, unsigned char *output, unsigned long sz);
/*!
\ingroup IoTSafe
@ -163,7 +265,7 @@ WOLFSSL_API int wolfIoTSafe_GetCert(uint8_t id, unsigned char *output, unsigned
\param id The key id in the IoT-Safe applet where the public key is stored
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_export_public
\sa wc_iotsafe_ecc_export_private
@ -178,13 +280,33 @@ WOLFSSL_API int wc_iotsafe_ecc_import_public(ecc_key *key, byte key_id);
\param id The key id in the IoT-Safe applet where the public key will be stored
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_import_public_ex
\sa wc_iotsafe_ecc_export_private
*/
WOLFSSL_API int wc_iotsafe_ecc_export_public(ecc_key *key, byte key_id);
/*!
\ingroup IoTSafe
\brief Export an ECC 256-bit public key, from ecc_key object to a writable public-key slot into the IoT-Safe applet.
Equivalent to \ref wc_iotsafe_ecc_import_public "wc_iotsafe_ecc_import_public",
except that it can be invoked with a key ID of two or more bytes.
\param key the ecc_key object containing the key to be exported
\param id The pointer to the key id in the IoT-Safe applet where the public key will be stored
\param id_size The key id size
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_import_public
\sa wc_iotsafe_ecc_export_private
*/
WOLFSSL_API int wc_iotsafe_ecc_export_public(ecc_key *key, byte key_id);
WOLFSSL_API int wc_iotsafe_ecc_import_public_ex(ecc_key *key, byte *key_id, word16 id_size);
/*!
\ingroup IoTSafe
@ -193,14 +315,35 @@ WOLFSSL_API int wc_iotsafe_ecc_export_public(ecc_key *key, byte key_id);
\param id The key id in the IoT-Safe applet where the private key will be stored
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_export_private_ex
\sa wc_iotsafe_ecc_import_public
\sa wc_iotsafe_ecc_export_public
*/
WOLFSSL_API int wc_iotsafe_ecc_export_private(ecc_key *key, byte key_id);
/*!
\ingroup IoTSafe
\brief Export an ECC 256-bit key, from ecc_key object to a writable private-key slot into the IoT-Safe applet.
Equivalent to \ref wc_iotsafe_ecc_export_private "wc_iotsafe_ecc_export_private",
except that it can be invoked with a key ID of two or more bytes.
\param key the ecc_key object containing the key to be exported
\param id The pointer to the key id in the IoT-Safe applet where the private key will be stored
\param id_size The key id size
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_export_private
\sa wc_iotsafe_ecc_import_public
\sa wc_iotsafe_ecc_export_public
*/
WOLFSSL_API int wc_iotsafe_ecc_export_private_ex(ecc_key *key, byte *key_id, word16 id_size);
/*!
\ingroup IoTSafe
\brief Sign a pre-computed 256-bit HASH, using a private key previously stored, or pre-provisioned,
@ -214,13 +357,37 @@ WOLFSSL_API int wc_iotsafe_ecc_export_private(ecc_key *key, byte key_id);
written to out upon successfully generating a message signature
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_sign_hash_ex
\sa wc_iotsafe_ecc_verify_hash
\sa wc_iotsafe_ecc_gen_k
*/
WOLFSSL_API int wc_iotsafe_ecc_sign_hash(byte *in, word32 inlen, byte *out, word32 *outlen, byte key_id);
/*!
\ingroup IoTSafe
\brief Sign a pre-computed 256-bit HASH, using a private key previously stored, or pre-provisioned,
in the IoT-Safe applet. Equivalent to \ref wc_iotsafe_ecc_sign_hash "wc_iotsafe_ecc_sign_hash",
except that it can be invoked with a key ID of two or more bytes.
\param in pointer to the buffer containing the message hash to sign
\param inlen length of the message hash to sign
\param out buffer in which to store the generated signature
\param outlen max length of the output buffer. Will store the bytes
\param 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
\param id_size The key id size
\return 0 upon success
\return < 0 in case of failure
\sa wc_iotsafe_ecc_sign_hash
\sa wc_iotsafe_ecc_verify_hash
\sa wc_iotsafe_ecc_gen_k
*/
WOLFSSL_API int wc_iotsafe_ecc_sign_hash_ex(byte *in, word32 inlen, byte *out, word32 *outlen, byte *key_id, word16 id_size);
/*!
\ingroup IoTSafe
\brief Verify an ECC signature against a pre-computed 256-bit HASH, using a public key previously stored, or pre-provisioned,
@ -236,12 +403,38 @@ WOLFSSL_API int wc_iotsafe_ecc_sign_hash(byte *in, word32 inlen, byte *out, word
\param res Result of signature, 1==valid, 0==invalid
\param key_id The id of the slot where the public ECC key is stored in the IoT-Safe applet
\sa wc_iotsafe_ecc_verify_hash_ex
\sa wc_iotsafe_ecc_sign_hash
\sa wc_iotsafe_ecc_gen_k
*/
WOLFSSL_API int wc_iotsafe_ecc_verify_hash(byte *sig, word32 siglen, byte *hash, word32 hashlen, int *res, byte key_id);
/*!
\ingroup IoTSafe
\brief Verify an ECC signature against a pre-computed 256-bit 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 \ref wc_iotsafe_ecc_verify_hash "wc_iotsafe_ecc_verify_hash",
except that it can be invoked with a key ID of two or more bytes.
\return 0 upon success (even if the signature is not valid)
\return < 0 in case of failure.
\param sig buffer containing the signature to verify
\param hash The hash (message digest) that was signed
\param hashlen The length of the hash (octets)
\param res Result of signature, 1==valid, 0==invalid
\param key_id The id of the slot where the public ECC key is stored in the IoT-Safe applet
\param id_size The key id size
\sa wc_iotsafe_ecc_verify_hash
\sa wc_iotsafe_ecc_sign_hash
\sa wc_iotsafe_ecc_gen_k
*/
WOLFSSL_API int wc_iotsafe_ecc_verify_hash_ex(byte *sig, word32 siglen, byte *hash, word32 hashlen, int *res, byte *key_id, word16 id_size);
/*!
\ingroup IoTSafe
\brief Generate an ECC 256-bit keypair and store it in a (writable) slot into the IoT-Safe applet.
@ -249,8 +442,24 @@ WOLFSSL_API int wc_iotsafe_ecc_verify_hash(byte *sig, word32 siglen, byte *hash,
\return 0 upon success
\return < 0 in case of failure.
\sa wc_iotsafe_ecc_gen_k_ex
\sa wc_iotsafe_ecc_sign_hash
\sa wc_iotsafe_ecc_verify_hash
*/
WOLFSSL_API int wc_iotsafe_ecc_gen_k(byte key_id);
/*!
\ingroup IoTSafe
\brief Generate an ECC 256-bit keypair and store it in a (writable) slot into the IoT-Safe applet.
Equivalent to \ref wc_iotsafe_ecc_gen_k "wc_iotsafe_ecc_gen_k",
except that it can be invoked with a key ID of two or more bytes.
\param key_id The id of the slot where the ECC key pair is stored in the IoT-Safe applet.
\param id_size The key id size
\return 0 upon success
\return < 0 in case of failure.
\sa wc_iotsafe_ecc_gen_k
\sa wc_iotsafe_ecc_sign_hash_ex
\sa wc_iotsafe_ecc_verify_hash_ex
*/
WOLFSSL_API int wc_iotsafe_ecc_gen_k(byte key_id);

22
wolfcrypt/src/port/iotsafe/iotsafe.c
View File

@ -1420,17 +1420,17 @@ int wolfSSL_iotsafe_on_ex(WOLFSSL *ssl, byte *privkey_id,
#if defined(HAVE_PK_CALLBACKS)
int ret;
IOTSAFE iotsafe;
if (id_size == 1) {
iotsafe.privkey_id = *privkey_id;
iotsafe.ecdh_keypair_slot = *ecdh_keypair_slot;
iotsafe.peer_pubkey_slot = *peer_pubkey_slot;
iotsafe.peer_cert_slot = *peer_cert_slot;
} else if (id_size == 2) {
XMEMCPY(&iotsafe.privkey_id, privkey_id, id_size);
XMEMCPY(&iotsafe.ecdh_keypair_slot, ecdh_keypair_slot, id_size);
XMEMCPY(&iotsafe.peer_pubkey_slot, peer_pubkey_slot, id_size);
XMEMCPY(&iotsafe.peer_cert_slot, peer_cert_slot, id_size);
}
#ifdef TWO_BYTES_ID_DEMO
iotsafe.privkey_id = *privkey_id;
iotsafe.ecdh_keypair_slot = *ecdh_keypair_slot;
iotsafe.peer_pubkey_slot = *peer_pubkey_slot;
iotsafe.peer_cert_slot = *peer_cert_slot;
#else
XMEMCPY(&iotsafe.privkey_id, privkey_id, id_size);
XMEMCPY(&iotsafe.ecdh_keypair_slot, ecdh_keypair_slot, id_size);
XMEMCPY(&iotsafe.peer_pubkey_slot, peer_pubkey_slot, id_size);
XMEMCPY(&iotsafe.peer_cert_slot, peer_cert_slot, id_size);
#endif
iotsafe.enabled = 1;
ret = wolfSSL_set_iotsafe_ctx(ssl, &iotsafe);
if (ret == 0) {

1
wolfssl/wolfcrypt/port/iotsafe/iotsafe.h
View File

@ -46,6 +46,7 @@ WOLFSSL_API void wolfIoTSafe_SetCSIM_write_cb(wolfSSL_IOTSafe_CSIM_write_cb wf);
WOLFSSL_API int wolfIoTSafe_GetRandom(unsigned char* out, word32 sz);
WOLFSSL_API int wolfIoTSafe_GetCert(uint8_t id, unsigned char *output, unsigned long sz);
WOLFSSL_API int wolfIoTSafe_GetCert_ex(uint8_t *id, uint16_t id_sz, unsigned char *output, unsigned long sz);
#ifdef HAVE_ECC
#include <wolfssl/wolfcrypt/ecc.h>