From 77d9410aa00f4dcc3ac0bccc30abdfa583cb6714 Mon Sep 17 00:00:00 2001 From: David Garske Date: Fri, 26 Dec 2025 08:00:20 -0800 Subject: [PATCH] Add missing API documentation for Doxygen: This PR adds Doxygen documentation for native wolfSSL API functions that were previously undocumented. It includes documentation notes for APIs gated on specific preprocessor macros: - WOLF_PRIVATE_KEY_ID: _Id and _Label init helpers (wc_AesInit_Id, wc_AesInit_Label, wc_ecc_init_id, wc_ecc_init_label, wc_InitRsaKey_Id, wc_InitRsaKey_Label) require this for PKCS11 support - WC_NO_CONSTRUCTORS: New/Delete constructor functions (wc_AesNew/Delete, wc_curve25519_new/delete, wc_ed25519_new/delete, wc_NewRsaKey/DeleteRsaKey) are only available when this is not defined. WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined. - WOLFSSL_PUBLIC_ASN: ASN functions marked with WOLFSSL_ASN_API include notes indicating they are not public by default - WOLFSSL_DUAL_ALG_CERTS: wc_GeneratePreTBS and wc_MakeSigWithBitStr for Post-Quantum dual algorithm certificate signing The New/Delete functions are documented as being exposed to support allocation of structures using dynamic memory to provide better ABI compatibility. --- doc/dox_comments/header_files/aes.h | 1693 +++++++++++++++++ doc/dox_comments/header_files/arc4.h | 54 + doc/dox_comments/header_files/ascon.h | 105 + doc/dox_comments/header_files/asn.h | 239 +++ doc/dox_comments/header_files/asn_public.h | 1553 ++++++++++++++- doc/dox_comments/header_files/chacha.h | 41 + .../header_files/chacha20_poly1305.h | 270 +++ doc/dox_comments/header_files/cmac.h | 79 + doc/dox_comments/header_files/coding.h | 40 + doc/dox_comments/header_files/compress.h | 128 ++ doc/dox_comments/header_files/cryptocb.h | 71 + doc/dox_comments/header_files/curve25519.h | 323 ++++ doc/dox_comments/header_files/curve448.h | 34 + doc/dox_comments/header_files/des3.h | 121 ++ doc/dox_comments/header_files/dh.h | 680 ++++++- doc/dox_comments/header_files/dsa.h | 295 +++ doc/dox_comments/header_files/ecc.h | 1241 ++++++++++++ doc/dox_comments/header_files/ed25519.h | 215 +++ doc/dox_comments/header_files/iotsafe.h | 39 +- doc/dox_comments/header_files/pkcs7.h | 1326 +++++++++++++ doc/dox_comments/header_files/poly1305.h | 68 + doc/dox_comments/header_files/psa.h | 62 + doc/dox_comments/header_files/pwdbased.h | 170 ++ doc/dox_comments/header_files/quic.h | 36 + doc/dox_comments/header_files/random.h | 320 ++++ doc/dox_comments/header_files/rsa.h | 591 ++++++ doc/dox_comments/header_files/sha.h | 121 ++ doc/dox_comments/header_files/sha256.h | 345 +++- doc/dox_comments/header_files/sha512.h | 824 ++++++++ doc/dox_comments/header_files/signature.h | 203 ++ doc/dox_comments/header_files/srp.h | 43 + doc/dox_comments/header_files/types.h | 298 +++ doc/dox_comments/header_files/wc_encrypt.h | 121 ++ doc/dox_comments/header_files/wc_port.h | 693 +++++++ doc/dox_comments/header_files/wolfio.h | 798 ++++++++ 35 files changed, 13226 insertions(+), 14 deletions(-) diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index 281029854..4c65257cd 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -1974,3 +1974,1696 @@ int wc_AesCtsDecryptUpdate(Aes* aes, byte* out, word32* outSz, \sa wc_AesCtsEncryptFinal */ int wc_AesCtsDecryptFinal(Aes* aes, byte* out, word32* outSz); + + +/*! + \ingroup AES + \brief This function encrypts data using AES CFB-1 mode (1-bit + feedback). It processes data one bit at a time, making it suitable + for bit-oriented applications. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store encrypted data + \param in pointer to the input buffer containing data to encrypt + (packed to left, e.g., 101 is 0x90) + \param sz size of input in bits + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + byte plaintext[1] = { 0x90 }; // bits 101 + byte ciphertext[1]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + int ret = wc_AesCfb1Encrypt(&aes, ciphertext, plaintext, 3); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCfb1Decrypt + \sa wc_AesCfb8Encrypt +*/ +int wc_AesCfb1Encrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function encrypts data using AES CFB-8 mode (8-bit + feedback). It processes data one byte at a time, making it suitable + for byte-oriented stream encryption. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store encrypted data + \param in pointer to the input buffer containing data to encrypt + \param sz size of input in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + byte plaintext[10] = { }; // data to encrypt + byte ciphertext[10]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + int ret = wc_AesCfb8Encrypt(&aes, ciphertext, plaintext, 10); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCfb8Decrypt + \sa wc_AesCfb1Encrypt +*/ +int wc_AesCfb8Encrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function decrypts data using AES CFB-1 mode (1-bit + feedback). It processes data one bit at a time, making it suitable + for bit-oriented applications. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store decrypted data + \param in pointer to the input buffer containing data to decrypt + \param sz size of input in bits + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + byte ciphertext[1] = { }; // encrypted bits + byte plaintext[1]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + int ret = wc_AesCfb1Decrypt(&aes, plaintext, ciphertext, 3); + if (ret != 0) { + // decryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCfb1Encrypt + \sa wc_AesCfb8Decrypt +*/ +int wc_AesCfb1Decrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function decrypts data using AES CFB-8 mode (8-bit + feedback). It processes data one byte at a time, making it suitable + for byte-oriented stream decryption. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store decrypted data + \param in pointer to the input buffer containing data to decrypt + \param sz size of input in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + byte ciphertext[10] = { }; // encrypted data + byte plaintext[10]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + int ret = wc_AesCfb8Decrypt(&aes, plaintext, ciphertext, 10); + if (ret != 0) { + // decryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCfb8Encrypt + \sa wc_AesCfb1Decrypt +*/ +int wc_AesCfb8Decrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function encrypts data using AES OFB mode (Output + Feedback). OFB mode turns a block cipher into a stream cipher by + encrypting the IV and XORing with plaintext. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store encrypted data + \param in pointer to the input buffer containing data to encrypt + \param sz size of input in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + byte plaintext[100] = { }; // data to encrypt + byte ciphertext[100]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + int ret = wc_AesOfbEncrypt(&aes, ciphertext, plaintext, 100); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesOfbDecrypt + \sa wc_AesSetKey +*/ +int wc_AesOfbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function decrypts data using AES OFB mode (Output + Feedback). In OFB mode, encryption and decryption are the same + operation. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store decrypted data + \param in pointer to the input buffer containing data to decrypt + \param sz size of input in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + byte ciphertext[100] = { }; // encrypted data + byte plaintext[100]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + int ret = wc_AesOfbDecrypt(&aes, plaintext, ciphertext, 100); + if (ret != 0) { + // decryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesOfbEncrypt + \sa wc_AesSetKey +*/ +int wc_AesOfbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function encrypts data using AES ECB mode (Electronic + Codebook). Warning: ECB mode is not recommended for most use cases + as it does not provide semantic security. Each block is encrypted + independently. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store encrypted data + \param in pointer to the input buffer containing data to encrypt + \param sz size of input in bytes (must be multiple of AES_BLOCK_SIZE) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte plaintext[32] = { }; // data to encrypt + byte ciphertext[32]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, NULL, AES_ENCRYPTION); + int ret = wc_AesEcbEncrypt(&aes, ciphertext, plaintext, 32); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesEcbDecrypt + \sa wc_AesSetKey +*/ +int wc_AesEcbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function decrypts data using AES ECB mode (Electronic + Codebook). Warning: ECB mode is not recommended for most use cases + as it does not provide semantic security. Each block is decrypted + independently. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL. + \return Other negative values on error. + + \param aes pointer to the AES structure containing the key + \param out pointer to the output buffer to store decrypted data + \param in pointer to the input buffer containing data to decrypt + \param sz size of input in bytes (must be multiple of AES_BLOCK_SIZE) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte ciphertext[32] = { }; // encrypted data + byte plaintext[32]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, NULL, AES_DECRYPTION); + int ret = wc_AesEcbDecrypt(&aes, plaintext, ciphertext, 32); + if (ret != 0) { + // decryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesEcbEncrypt + \sa wc_AesSetKey +*/ +int wc_AesEcbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz); + +/*! + \ingroup AES + \brief This function sets the key and IV for AES CTR mode. It + initializes the AES structure for counter mode encryption or + decryption. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, key, or iv is NULL, or if key length + is invalid. + + \param aes pointer to the AES structure to initialize + \param key pointer to the key buffer (16, 24, or 32 bytes) + \param len length of the key in bytes + \param iv pointer to the initialization vector (16 bytes) + \param dir cipher direction (always use AES_ENCRYPTION for CTR mode) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[16] = { }; // initialization vector + + wc_AesInit(&aes, NULL, INVALID_DEVID); + int ret = wc_AesCtrSetKey(&aes, key, 16, iv, AES_ENCRYPTION); + if (ret != 0) { + // failed to set key + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCtrEncrypt + \sa wc_AesSetKey +*/ +int wc_AesCtrSetKey(Aes* aes, const byte* key, word32 len, const byte* iv, + int dir); + +/*! + \ingroup AES + \brief This function sets the key for AES GCM with an extended key + update parameter. It allows for key updates in certain hardware + implementations. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or key is NULL, or if key length is invalid. + + \param aes pointer to the AES structure to initialize + \param key pointer to the key buffer (16, 24, or 32 bytes) + \param len length of the key in bytes + \param kup key update parameter for hardware implementations + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + + wc_AesInit(&aes, NULL, INVALID_DEVID); + int ret = wc_AesGcmSetKey_ex(&aes, key, 16, 0); + if (ret != 0) { + // failed to set key + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmSetKey + \sa wc_AesGcmInit +*/ +int wc_AesGcmSetKey_ex(Aes* aes, const byte* key, word32 len, word32 kup); + +/*! + \ingroup AES + \brief This function initializes an AES GCM cipher with key and IV. + It can be called with NULL key to only set the IV, or with NULL IV + to only set the key. + + \return 0 On success. + \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid. + \return MEMORY_E If dynamic memory allocation fails. + + \param aes pointer to the AES structure to initialize + \param key pointer to the key buffer, or NULL to skip key setting + \param len length of the key in bytes + \param iv pointer to the IV/nonce buffer, or NULL to skip IV setting + \param ivSz length of the IV/nonce in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // 96-bit nonce + + wc_AesInit(&aes, NULL, INVALID_DEVID); + int ret = wc_AesGcmInit(&aes, key, 16, iv, 12); + if (ret != 0) { + // failed to initialize + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmSetKey + \sa wc_AesGcmEncrypt +*/ +int wc_AesGcmInit(Aes* aes, const byte* key, word32 len, const byte* iv, + word32 ivSz); + +/*! + \ingroup AES + \brief This function initializes an AES GCM cipher for encryption. + It is a convenience wrapper around wc_AesGcmInit for encryption + operations. + + \return 0 On success. + \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid. + + \param aes pointer to the AES structure to initialize + \param key pointer to the key buffer, or NULL to skip key setting + \param len length of the key in bytes + \param iv pointer to the IV/nonce buffer, or NULL to skip IV setting + \param ivSz length of the IV/nonce in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // 96-bit nonce + + wc_AesInit(&aes, NULL, INVALID_DEVID); + int ret = wc_AesGcmEncryptInit(&aes, key, 16, iv, 12); + if (ret != 0) { + // failed to initialize + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmInit + \sa wc_AesGcmEncryptUpdate +*/ +int wc_AesGcmEncryptInit(Aes* aes, const byte* key, word32 len, + const byte* iv, word32 ivSz); + +/*! + \ingroup AES + \brief This function initializes an AES GCM cipher for encryption and + outputs the IV. This is useful when part of the IV is generated + internally. Must call wc_AesGcmSetIV() before this function to set + the fixed part of the IV. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, ivOut is NULL, or if ivOutSz doesn't + match the cached nonce size. + + \param aes pointer to the AES structure to initialize + \param key pointer to the key buffer, or NULL to skip key setting + \param len length of the key in bytes + \param ivOut pointer to buffer to receive the complete IV + \param ivOutSz length of the IV output buffer in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte ivFixed[4] = { }; // fixed part of IV + byte ivOut[12]; + WC_RNG rng; + + wc_InitRng(&rng); + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng); + int ret = wc_AesGcmEncryptInit_ex(&aes, key, 16, ivOut, 12); + if (ret != 0) { + // failed to initialize + } + wc_AesFree(&aes); + wc_FreeRng(&rng); + \endcode + + \sa wc_AesGcmSetIV + \sa wc_AesGcmEncryptUpdate +*/ +int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len, + byte* ivOut, word32 ivOutSz); + +/*! + \ingroup AES + \brief This function performs an update step of AES GCM encryption. + It processes plaintext and/or additional authentication data (AAD) + in a streaming fashion. + + \return 0 On success. + \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid. + + \param aes pointer to the AES structure + \param out pointer to buffer to store ciphertext (can be NULL if sz=0) + \param in pointer to plaintext to encrypt (can be NULL if sz=0) + \param sz length of plaintext in bytes + \param authIn pointer to additional authentication data (can be NULL) + \param authInSz length of AAD in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // nonce + byte plaintext[100] = { }; // data + byte ciphertext[100]; + byte aad[20] = { }; // additional data + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmEncryptInit(&aes, key, 16, iv, 12); + int ret = wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100, + aad, 20); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmEncryptInit + \sa wc_AesGcmEncryptFinal +*/ +int wc_AesGcmEncryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz, + const byte* authIn, word32 authInSz); + +/*! + \ingroup AES + \brief This function finalizes AES GCM encryption and generates the + authentication tag. This must be called after all data has been + processed with wc_AesGcmEncryptUpdate. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or authTag is NULL, or if authTagSz is + invalid. + + \param aes pointer to the AES structure + \param authTag pointer to buffer to store the authentication tag + \param authTagSz length of the authentication tag in bytes (typically + 12 or 16) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // nonce + byte plaintext[100] = { }; // data + byte ciphertext[100]; + byte authTag[16]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmEncryptInit(&aes, key, 16, iv, 12); + wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100, NULL, 0); + int ret = wc_AesGcmEncryptFinal(&aes, authTag, 16); + if (ret != 0) { + // failed to generate tag + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmEncryptUpdate + \sa wc_AesGcmDecryptFinal +*/ +int wc_AesGcmEncryptFinal(Aes* aes, byte* authTag, word32 authTagSz); + +/*! + \ingroup AES + \brief This function initializes an AES GCM cipher for decryption. + It is a convenience wrapper around wc_AesGcmInit for decryption + operations. + + \return 0 On success. + \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid. + + \param aes pointer to the AES structure to initialize + \param key pointer to the key buffer, or NULL to skip key setting + \param len length of the key in bytes + \param iv pointer to the IV/nonce buffer, or NULL to skip IV setting + \param ivSz length of the IV/nonce in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // 96-bit nonce + + wc_AesInit(&aes, NULL, INVALID_DEVID); + int ret = wc_AesGcmDecryptInit(&aes, key, 16, iv, 12); + if (ret != 0) { + // failed to initialize + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmInit + \sa wc_AesGcmDecryptUpdate +*/ +int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len, + const byte* iv, word32 ivSz); + +/*! + \ingroup AES + \brief This function performs an update step of AES GCM decryption. + It processes ciphertext and/or additional authentication data (AAD) + in a streaming fashion. + + \return 0 On success. + \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid. + + \param aes pointer to the AES structure + \param out pointer to buffer to store plaintext (can be NULL if sz=0) + \param in pointer to ciphertext to decrypt (can be NULL if sz=0) + \param sz length of ciphertext in bytes + \param authIn pointer to additional authentication data (can be NULL) + \param authInSz length of AAD in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // nonce + byte ciphertext[100] = { }; // encrypted data + byte plaintext[100]; + byte aad[20] = { }; // additional data + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmDecryptInit(&aes, key, 16, iv, 12); + int ret = wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100, + aad, 20); + if (ret != 0) { + // decryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmDecryptInit + \sa wc_AesGcmDecryptFinal +*/ +int wc_AesGcmDecryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz, + const byte* authIn, word32 authInSz); + +/*! + \ingroup AES + \brief This function finalizes AES GCM decryption and verifies the + authentication tag. This must be called after all data has been + processed with wc_AesGcmDecryptUpdate. + + \return 0 On success. + \return AES_GCM_AUTH_E If authentication tag verification fails. + \return BAD_FUNC_ARG If aes or authTag is NULL, or if authTagSz is + invalid. + + \param aes pointer to the AES structure + \param authTag pointer to the authentication tag to verify + \param authTagSz length of the authentication tag in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // nonce + byte ciphertext[100] = { }; // encrypted data + byte plaintext[100]; + byte authTag[16] = { }; // received tag + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmDecryptInit(&aes, key, 16, iv, 12); + wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100, NULL, 0); + int ret = wc_AesGcmDecryptFinal(&aes, authTag, 16); + if (ret != 0) { + // authentication failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmDecryptUpdate + \sa wc_AesGcmEncryptFinal +*/ +int wc_AesGcmDecryptFinal(Aes* aes, const byte* authTag, word32 authTagSz); + +/*! + \ingroup AES + \brief This function sets an external IV for AES GCM. This allows + using an IV that was generated externally or received from another + source. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or iv is NULL, or if ivSz is invalid. + + \param aes pointer to the AES structure + \param iv pointer to the IV/nonce buffer + \param ivSz length of the IV/nonce in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // external nonce + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmSetKey(&aes, key, 16); + int ret = wc_AesGcmSetExtIV(&aes, iv, 12); + if (ret != 0) { + // failed to set IV + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesGcmSetIV + \sa wc_AesGcmInit +*/ +int wc_AesGcmSetExtIV(Aes* aes, const byte* iv, word32 ivSz); + +/*! + \ingroup AES + \brief This function sets the IV for AES GCM with optional random + generation. It can generate part of the IV using an RNG, which is + useful for ensuring IV uniqueness. + + \return 0 On success. + \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid. + \return Other negative values on RNG or other errors. + + \param aes pointer to the AES structure + \param ivSz total length of the IV/nonce in bytes + \param ivFixed pointer to the fixed part of the IV (can be NULL) + \param ivFixedSz length of the fixed part in bytes + \param rng pointer to initialized RNG for generating random part + (can be NULL if ivFixedSz equals ivSz) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte ivFixed[4] = { }; // fixed part + WC_RNG rng; + + wc_InitRng(&rng); + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmSetKey(&aes, key, 16); + int ret = wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng); + if (ret != 0) { + // failed to set IV + } + wc_AesFree(&aes); + wc_FreeRng(&rng); + \endcode + + \sa wc_AesGcmSetExtIV + \sa wc_AesGcmEncryptInit_ex +*/ +int wc_AesGcmSetIV(Aes* aes, word32 ivSz, const byte* ivFixed, + word32 ivFixedSz, WC_RNG* rng); + +/*! + \ingroup AES + \brief This function performs AES GCM encryption with extended + parameters, including IV output. This is a one-shot encryption + function that outputs the generated IV. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param aes pointer to the AES structure + \param out pointer to buffer to store ciphertext + \param in pointer to plaintext to encrypt + \param sz length of plaintext in bytes + \param ivOut pointer to buffer to receive the IV + \param ivOutSz length of the IV output buffer in bytes + \param authTag pointer to buffer to store authentication tag + \param authTagSz length of authentication tag in bytes + \param authIn pointer to additional authentication data + \param authInSz length of AAD in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte ivFixed[4] = { }; // fixed part + byte ivOut[12]; + byte plaintext[100] = { }; // data + byte ciphertext[100]; + byte authTag[16]; + WC_RNG rng; + + wc_InitRng(&rng); + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesGcmSetKey(&aes, key, 16); + wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng); + int ret = wc_AesGcmEncrypt_ex(&aes, ciphertext, plaintext, 100, + ivOut, 12, authTag, 16, NULL, 0); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + wc_FreeRng(&rng); + \endcode + + \sa wc_AesGcmEncrypt + \sa wc_AesGcmSetIV +*/ +int wc_AesGcmEncrypt_ex(Aes* aes, byte* out, const byte* in, word32 sz, + byte* ivOut, word32 ivOutSz, byte* authTag, + word32 authTagSz, const byte* authIn, + word32 authInSz); + +/*! + \ingroup AES + \brief This function performs GMAC (Galois Message Authentication Code) + generation. GMAC is essentially AES-GCM with no plaintext, used for + authentication only. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param key pointer to the key buffer + \param keySz length of the key in bytes (16, 24, or 32) + \param iv pointer to the IV/nonce buffer + \param ivSz length of the IV/nonce in bytes + \param authIn pointer to data to authenticate + \param authInSz length of data to authenticate in bytes + \param authTag pointer to buffer to store authentication tag + \param authTagSz length of authentication tag in bytes + \param rng pointer to initialized RNG (can be NULL if IV is complete) + + _Example_ + \code + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // nonce + byte data[100] = { }; // data to authenticate + byte authTag[16]; + + int ret = wc_Gmac(key, 16, iv, 12, data, 100, authTag, 16, NULL); + if (ret != 0) { + // GMAC generation failed + } + \endcode + + \sa wc_GmacVerify + \sa wc_AesGcmEncrypt +*/ +int wc_Gmac(const byte* key, word32 keySz, byte* iv, word32 ivSz, + const byte* authIn, word32 authInSz, byte* authTag, + word32 authTagSz, WC_RNG* rng); + +/*! + \ingroup AES + \brief This function verifies a GMAC (Galois Message Authentication + Code). It computes the GMAC and compares it with the provided tag. + + \return 0 On successful verification. + \return AES_GCM_AUTH_E If authentication tag verification fails. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param key pointer to the key buffer + \param keySz length of the key in bytes (16, 24, or 32) + \param iv pointer to the IV/nonce buffer + \param ivSz length of the IV/nonce in bytes + \param authIn pointer to data to authenticate + \param authInSz length of data to authenticate in bytes + \param authTag pointer to the authentication tag to verify + \param authTagSz length of authentication tag in bytes + + _Example_ + \code + byte key[16] = { }; // 128-bit key + byte iv[12] = { }; // nonce + byte data[100] = { }; // data to authenticate + byte authTag[16] = { }; // received tag + + int ret = wc_GmacVerify(key, 16, iv, 12, data, 100, authTag, 16); + if (ret != 0) { + // GMAC verification failed + } + \endcode + + \sa wc_Gmac + \sa wc_AesGcmDecrypt +*/ +int wc_GmacVerify(const byte* key, word32 keySz, const byte* iv, + word32 ivSz, const byte* authIn, word32 authInSz, + const byte* authTag, word32 authTagSz); + +/*! + \ingroup AES + \brief This function sets the nonce for AES CCM mode. The nonce must + be set before encryption or decryption operations. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or nonce is NULL, or if nonceSz is invalid. + + \param aes pointer to the AES structure + \param nonce pointer to the nonce buffer + \param nonceSz length of the nonce in bytes (7-13 bytes for CCM) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte nonce[12] = { }; // nonce + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesCcmSetKey(&aes, key, 16); + int ret = wc_AesCcmSetNonce(&aes, nonce, 12); + if (ret != 0) { + // failed to set nonce + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCcmEncrypt + \sa wc_AesCcmSetKey +*/ +int wc_AesCcmSetNonce(Aes* aes, const byte* nonce, word32 nonceSz); + +/*! + \ingroup AES + \brief This function performs AES CCM encryption with extended + parameters, including nonce output. This is useful when part of the + nonce is generated internally. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param aes pointer to the AES structure + \param out pointer to buffer to store ciphertext + \param in pointer to plaintext to encrypt + \param sz length of plaintext in bytes + \param ivOut pointer to buffer to receive the nonce + \param ivOutSz length of the nonce output buffer in bytes + \param authTag pointer to buffer to store authentication tag + \param authTagSz length of authentication tag in bytes + \param authIn pointer to additional authentication data + \param authInSz length of AAD in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + byte nonce[12]; + byte plaintext[100] = { }; // data + byte ciphertext[100]; + byte authTag[16]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesCcmSetKey(&aes, key, 16); + int ret = wc_AesCcmEncrypt_ex(&aes, ciphertext, plaintext, 100, + nonce, 12, authTag, 16, NULL, 0); + if (ret != 0) { + // encryption failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesCcmEncrypt + \sa wc_AesCcmSetNonce +*/ +int wc_AesCcmEncrypt_ex(Aes* aes, byte* out, const byte* in, word32 sz, + byte* ivOut, word32 ivOutSz, byte* authTag, + word32 authTagSz, const byte* authIn, + word32 authInSz); + +/*! + \ingroup AES + \brief This function wraps a key using AES Key Wrap algorithm + (RFC 3394). This is commonly used to securely transport + cryptographic keys. + + \return Length of wrapped key in bytes on success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param key pointer to the key-encryption key + \param keySz length of the key-encryption key in bytes + \param in pointer to the key to wrap + \param inSz length of the key to wrap in bytes + \param out pointer to buffer to store wrapped key + \param outSz size of output buffer in bytes + \param iv pointer to IV (typically NULL to use default) + + _Example_ + \code + byte kek[16] = { }; // key-encryption key + byte keyToWrap[16] = { }; // key to wrap + byte wrappedKey[24]; + + int wrappedLen = wc_AesKeyWrap(kek, 16, keyToWrap, 16, wrappedKey, + 24, NULL); + if (wrappedLen <= 0) { + // key wrap failed + } + \endcode + + \sa wc_AesKeyUnWrap + \sa wc_AesKeyWrap_ex +*/ +int wc_AesKeyWrap(const byte* key, word32 keySz, const byte* in, + word32 inSz, byte* out, word32 outSz, const byte* iv); + +/*! + \ingroup AES + \brief This function wraps a key using AES Key Wrap algorithm with + an initialized AES structure. This allows reusing the same AES + structure for multiple wrap operations. + + \return Length of wrapped key in bytes on success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param aes pointer to initialized AES structure + \param in pointer to the key to wrap + \param inSz length of the key to wrap in bytes + \param out pointer to buffer to store wrapped key + \param outSz size of output buffer in bytes + \param iv pointer to IV (typically NULL to use default) + + _Example_ + \code + Aes aes; + byte kek[16] = { }; // key-encryption key + byte keyToWrap[16] = { }; // key to wrap + byte wrappedKey[24]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, kek, 16, NULL, AES_ENCRYPTION); + int wrappedLen = wc_AesKeyWrap_ex(&aes, keyToWrap, 16, wrappedKey, + 24, NULL); + if (wrappedLen <= 0) { + // key wrap failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesKeyWrap + \sa wc_AesKeyUnWrap_ex +*/ +int wc_AesKeyWrap_ex(Aes *aes, const byte* in, word32 inSz, byte* out, + word32 outSz, const byte* iv); + +/*! + \ingroup AES + \brief This function unwraps a key using AES Key Unwrap algorithm + (RFC 3394). This is used to securely receive cryptographic keys + that were wrapped. + + \return Length of unwrapped key in bytes on success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param key pointer to the key-encryption key + \param keySz length of the key-encryption key in bytes + \param in pointer to the wrapped key + \param inSz length of the wrapped key in bytes + \param out pointer to buffer to store unwrapped key + \param outSz size of output buffer in bytes + \param iv pointer to IV (typically NULL to use default) + + _Example_ + \code + byte kek[16] = { }; // key-encryption key + byte wrappedKey[24] = { }; // wrapped key + byte unwrappedKey[16]; + + int unwrappedLen = wc_AesKeyUnWrap(kek, 16, wrappedKey, 24, + unwrappedKey, 16, NULL); + if (unwrappedLen <= 0) { + // key unwrap failed + } + \endcode + + \sa wc_AesKeyWrap + \sa wc_AesKeyUnWrap_ex +*/ +int wc_AesKeyUnWrap(const byte* key, word32 keySz, const byte* in, + word32 inSz, byte* out, word32 outSz, const byte* iv); + +/*! + \ingroup AES + \brief This function unwraps a key using AES Key Unwrap algorithm + with an initialized AES structure. This allows reusing the same AES + structure for multiple unwrap operations. + + \return Length of unwrapped key in bytes on success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param aes pointer to initialized AES structure + \param in pointer to the wrapped key + \param inSz length of the wrapped key in bytes + \param out pointer to buffer to store unwrapped key + \param outSz size of output buffer in bytes + \param iv pointer to IV (typically NULL to use default) + + _Example_ + \code + Aes aes; + byte kek[16] = { }; // key-encryption key + byte wrappedKey[24] = { }; // wrapped key + byte unwrappedKey[16]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, kek, 16, NULL, AES_ENCRYPTION); + int unwrappedLen = wc_AesKeyUnWrap_ex(&aes, wrappedKey, 24, + unwrappedKey, 16, NULL); + if (unwrappedLen <= 0) { + // key unwrap failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesKeyUnWrap + \sa wc_AesKeyWrap_ex +*/ +int wc_AesKeyUnWrap_ex(Aes *aes, const byte* in, word32 inSz, byte* out, + word32 outSz, const byte* iv); + +/*! + \ingroup AES + \brief This function encrypts multiple consecutive sectors using AES XTS + mode. It processes multiple sectors in sequence, automatically + incrementing the sector number for each sector. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL, or if sectorSz is 0, + or if sz is less than AES_BLOCK_SIZE. + \return Other negative values on error. + + \param aes pointer to the XtsAes structure + \param out pointer to buffer to store encrypted data + \param in pointer to plaintext data to encrypt + \param sz total length of data in bytes + \param sector starting sector number for the tweak + \param sectorSz size of each sector in bytes + + _Example_ + \code + XtsAes aes; + byte key[32] = { }; // 256-bit key + byte plaintext[1024] = { }; // data + byte ciphertext[1024]; + + wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID); + int ret = wc_AesXtsEncryptConsecutiveSectors(&aes, ciphertext, + plaintext, 1024, 0, 512); + if (ret != 0) { + // encryption failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsDecryptConsecutiveSectors + \sa wc_AesXtsEncryptSector +*/ +int wc_AesXtsEncryptConsecutiveSectors(XtsAes* aes, byte* out, + const byte* in, word32 sz, + word64 sector, word32 sectorSz); + +/*! + \ingroup AES + \brief This function decrypts multiple consecutive sectors using AES XTS + mode. It processes multiple sectors in sequence, automatically + incrementing the sector number for each sector. + + \return 0 On success. + \return BAD_FUNC_ARG If aes, out, or in is NULL, or if sectorSz is 0, + or if sz is less than AES_BLOCK_SIZE. + \return Other negative values on error. + + \param aes pointer to the XtsAes structure + \param out pointer to buffer to store decrypted data + \param in pointer to ciphertext data to decrypt + \param sz total length of data in bytes + \param sector starting sector number for the tweak + \param sectorSz size of each sector in bytes + + _Example_ + \code + XtsAes aes; + byte key[32] = { }; // 256-bit key + byte ciphertext[1024] = { }; // encrypted data + byte plaintext[1024]; + + wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID); + int ret = wc_AesXtsDecryptConsecutiveSectors(&aes, plaintext, + ciphertext, 1024, 0, 512); + if (ret != 0) { + // decryption failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncryptConsecutiveSectors + \sa wc_AesXtsDecryptSector +*/ +int wc_AesXtsDecryptConsecutiveSectors(XtsAes* aes, byte* out, + const byte* in, word32 sz, + word64 sector, word32 sectorSz); + +/*! + \ingroup AES + \brief This function initializes streaming AES XTS encryption. It sets + up the context for processing data in multiple update calls. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + + \param aes pointer to the XtsAes structure + \param i pointer to the tweak/IV buffer + \param iSz length of the tweak/IV in bytes + \param stream pointer to XtsAesStreamData structure for streaming state + + _Example_ + \code + XtsAes aes; + struct XtsAesStreamData stream; + byte key[32] = { }; // 256-bit key + byte tweak[16] = { }; // tweak value + + wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID); + int ret = wc_AesXtsEncryptInit(&aes, tweak, 16, &stream); + if (ret != 0) { + // initialization failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncryptUpdate + \sa wc_AesXtsEncryptFinal +*/ +int wc_AesXtsEncryptInit(XtsAes* aes, const byte* i, word32 iSz, + struct XtsAesStreamData *stream); + +/*! + \ingroup AES + \brief This function initializes streaming AES XTS decryption. It sets + up the context for processing data in multiple update calls. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + + \param aes pointer to the XtsAes structure + \param i pointer to the tweak/IV buffer + \param iSz length of the tweak/IV in bytes + \param stream pointer to XtsAesStreamData structure for streaming state + + _Example_ + \code + XtsAes aes; + struct XtsAesStreamData stream; + byte key[32] = { }; // 256-bit key + byte tweak[16] = { }; // tweak value + + wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID); + int ret = wc_AesXtsDecryptInit(&aes, tweak, 16, &stream); + if (ret != 0) { + // initialization failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsDecryptUpdate + \sa wc_AesXtsDecryptFinal +*/ +int wc_AesXtsDecryptInit(XtsAes* aes, const byte* i, word32 iSz, + struct XtsAesStreamData *stream); + +/*! + \ingroup AES + \brief This function performs an update step of streaming AES XTS + encryption. It processes a chunk of data and can be called multiple + times. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + + \param aes pointer to the XtsAes structure + \param out pointer to buffer to store encrypted data + \param in pointer to plaintext data to encrypt + \param sz length of data in bytes + \param stream pointer to XtsAesStreamData structure for streaming state + + _Example_ + \code + XtsAes aes; + struct XtsAesStreamData stream; + byte key[32] = { }; // 256-bit key + byte tweak[16] = { }; // tweak value + byte plaintext[100] = { }; // data + byte ciphertext[100]; + + wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID); + wc_AesXtsEncryptInit(&aes, tweak, 16, &stream); + int ret = wc_AesXtsEncryptUpdate(&aes, ciphertext, plaintext, 100, + &stream); + if (ret != 0) { + // encryption failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncryptInit + \sa wc_AesXtsEncryptFinal +*/ +int wc_AesXtsEncryptUpdate(XtsAes* aes, byte* out, const byte* in, + word32 sz, struct XtsAesStreamData *stream); + +/*! + \ingroup AES + \brief This function performs an update step of streaming AES XTS + decryption. It processes a chunk of data and can be called multiple + times. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + + \param aes pointer to the XtsAes structure + \param out pointer to buffer to store decrypted data + \param in pointer to ciphertext data to decrypt + \param sz length of data in bytes + \param stream pointer to XtsAesStreamData structure for streaming state + + _Example_ + \code + XtsAes aes; + struct XtsAesStreamData stream; + byte key[32] = { }; // 256-bit key + byte tweak[16] = { }; // tweak value + byte ciphertext[100] = { }; // encrypted data + byte plaintext[100]; + + wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID); + wc_AesXtsDecryptInit(&aes, tweak, 16, &stream); + int ret = wc_AesXtsDecryptUpdate(&aes, plaintext, ciphertext, 100, + &stream); + if (ret != 0) { + // decryption failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsDecryptInit + \sa wc_AesXtsDecryptFinal +*/ +int wc_AesXtsDecryptUpdate(XtsAes* aes, byte* out, const byte* in, + word32 sz, struct XtsAesStreamData *stream); + +/*! + \ingroup AES + \brief This function finalizes streaming AES XTS encryption. It + processes any remaining data and completes the encryption operation. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + + \param aes pointer to the XtsAes structure + \param out pointer to buffer to store final encrypted data + \param in pointer to final plaintext data to encrypt + \param sz length of final data in bytes + \param stream pointer to XtsAesStreamData structure for streaming state + + _Example_ + \code + XtsAes aes; + struct XtsAesStreamData stream; + byte key[32] = { }; // 256-bit key + byte tweak[16] = { }; // tweak value + byte plaintext[50] = { }; // final data + byte ciphertext[50]; + + wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID); + wc_AesXtsEncryptInit(&aes, tweak, 16, &stream); + // ... update calls ... + int ret = wc_AesXtsEncryptFinal(&aes, ciphertext, plaintext, 50, + &stream); + if (ret != 0) { + // finalization failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncryptUpdate + \sa wc_AesXtsEncryptInit +*/ +int wc_AesXtsEncryptFinal(XtsAes* aes, byte* out, const byte* in, + word32 sz, struct XtsAesStreamData *stream); + +/*! + \ingroup AES + \brief This function finalizes streaming AES XTS decryption. It + processes any remaining data and completes the decryption operation. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + + \param aes pointer to the XtsAes structure + \param out pointer to buffer to store final decrypted data + \param in pointer to final ciphertext data to decrypt + \param sz length of final data in bytes + \param stream pointer to XtsAesStreamData structure for streaming state + + _Example_ + \code + XtsAes aes; + struct XtsAesStreamData stream; + byte key[32] = { }; // 256-bit key + byte tweak[16] = { }; // tweak value + byte ciphertext[50] = { }; // final encrypted data + byte plaintext[50]; + + wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID); + wc_AesXtsDecryptInit(&aes, tweak, 16, &stream); + // ... update calls ... + int ret = wc_AesXtsDecryptFinal(&aes, plaintext, ciphertext, 50, + &stream); + if (ret != 0) { + // finalization failed + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsDecryptUpdate + \sa wc_AesXtsDecryptInit +*/ +int wc_AesXtsDecryptFinal(XtsAes* aes, byte* out, const byte* in, + word32 sz, struct XtsAesStreamData *stream); + +/*! + \ingroup AES + \brief This function retrieves the key size from an initialized AES + structure. It returns the size of the key currently set in the AES + object. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or keySize is NULL. + + \param aes pointer to the AES structure + \param keySize pointer to word32 to store the key size in bytes + + _Example_ + \code + Aes aes; + byte key[16] = { }; // 128-bit key + word32 keySize; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, 16, NULL, AES_ENCRYPTION); + int ret = wc_AesGetKeySize(&aes, &keySize); + if (ret == 0) { + // keySize now contains 16 + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesSetKey + \sa wc_AesInit +*/ +int wc_AesGetKeySize(Aes* aes, word32* keySize); + +/*! + \ingroup AES + \brief This function initializes an AES structure with an ID. This is + useful for tracking or identifying specific AES instances in + applications that manage multiple AES contexts. + + \note This API is only available when WOLF_PRIVATE_KEY_ID is defined, + which is set for PKCS11 support. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or id is NULL, or if len is invalid. + + \param aes pointer to the AES structure to initialize + \param id pointer to the ID buffer + \param len length of the ID in bytes + \param heap pointer to heap hint for memory allocation (can be NULL) + \param devId device ID for hardware acceleration (use INVALID_DEVID + for software) + + _Example_ + \code + Aes aes; + byte id[8] = { }; // unique identifier + + int ret = wc_AesInit_Id(&aes, id, 8, NULL, INVALID_DEVID); + if (ret != 0) { + // initialization failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesInit + \sa wc_AesInit_Label +*/ +int wc_AesInit_Id(Aes* aes, unsigned char* id, int len, void* heap, + int devId); + +/*! + \ingroup AES + \brief This function initializes an AES structure with a label string. + This is useful for tracking or identifying specific AES instances with + human-readable names. + + \note This API is only available when WOLF_PRIVATE_KEY_ID is defined, + which is set for PKCS11 support. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or label is NULL. + + \param aes pointer to the AES structure to initialize + \param label pointer to the null-terminated label string + \param heap pointer to heap hint for memory allocation (can be NULL) + \param devId device ID for hardware acceleration (use INVALID_DEVID + for software) + + _Example_ + \code + Aes aes; + + int ret = wc_AesInit_Label(&aes, "MyAESContext", NULL, INVALID_DEVID); + if (ret != 0) { + // initialization failed + } + wc_AesFree(&aes); + \endcode + + \sa wc_AesInit + \sa wc_AesInit_Id +*/ +int wc_AesInit_Label(Aes* aes, const char* label, void* heap, int devId); + +/*! + \ingroup AES + \brief This function allocates and initializes a new AES structure. + It returns a pointer to the allocated structure, which must be freed + with wc_AesDelete when no longer needed. These New/Delete functions + are exposed to support allocation of the structure using dynamic memory + to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return Pointer to allocated Aes structure on success. + \return NULL on allocation failure. + + \param heap pointer to heap hint for memory allocation (can be NULL) + \param devId device ID for hardware acceleration (use INVALID_DEVID + for software) + \param result_code pointer to int to store result code (can be NULL) + + _Example_ + \code + int result; + Aes* aes = wc_AesNew(NULL, INVALID_DEVID, &result); + if (aes == NULL || result != 0) { + // allocation or initialization failed + } + // use aes... + wc_AesDelete(aes, &aes); + \endcode + + \sa wc_AesDelete + \sa wc_AesInit +*/ +Aes* wc_AesNew(void* heap, int devId, int *result_code); + +/*! + \ingroup AES + \brief This function frees an AES structure that was allocated with + wc_AesNew. It also sets the pointer to NULL to prevent use-after-free. + These New/Delete functions are exposed to support allocation of the + structure using dynamic memory to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return 0 On success. + \return BAD_FUNC_ARG If aes or aes_p is NULL. + + \param aes pointer to the AES structure to free + \param aes_p pointer to the AES pointer (will be set to NULL) + + _Example_ + \code + Aes* aes = wc_AesNew(NULL, INVALID_DEVID, NULL); + if (aes != NULL) { + // use aes... + int ret = wc_AesDelete(aes, &aes); + // aes is now NULL + } + \endcode + + \sa wc_AesNew + \sa wc_AesFree +*/ +int wc_AesDelete(Aes* aes, Aes** aes_p); + +/*! + \ingroup AES + \brief This function performs AES-SIV (Synthetic IV) encryption with + extended parameters. AES-SIV provides nonce-misuse resistance and + deterministic authenticated encryption. + + \return 0 On success. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param key pointer to the key buffer (32, 48, or 64 bytes for SIV) + \param keySz length of the key in bytes + \param assoc pointer to array of associated data structures + \param numAssoc number of associated data items + \param nonce pointer to the nonce buffer (can be NULL) + \param nonceSz length of the nonce in bytes + \param in pointer to plaintext to encrypt + \param inSz length of plaintext in bytes + \param siv pointer to buffer to store the SIV (16 bytes) + \param out pointer to buffer to store ciphertext + + _Example_ + \code + byte key[32] = { }; // 256-bit key for AES-128-SIV + AesSivAssoc assoc[1]; + byte aad[20] = { }; // associated data + byte nonce[12] = { }; // nonce + byte plaintext[100] = { }; // data + byte siv[16]; + byte ciphertext[100]; + + assoc[0].data = aad; + assoc[0].sz = 20; + + int ret = wc_AesSivEncrypt_ex(key, 32, assoc, 1, nonce, 12, + plaintext, 100, siv, ciphertext); + if (ret != 0) { + // encryption failed + } + \endcode + + \sa wc_AesSivDecrypt_ex + \sa wc_AesSivEncrypt +*/ +int wc_AesSivEncrypt_ex(const byte* key, word32 keySz, + const AesSivAssoc* assoc, word32 numAssoc, + const byte* nonce, word32 nonceSz, const byte* in, + word32 inSz, byte* siv, byte* out); + +/*! + \ingroup AES + \brief This function performs AES-SIV (Synthetic IV) decryption with + extended parameters. It verifies the SIV and decrypts the ciphertext. + + \return 0 On successful decryption and verification. + \return AES_SIV_AUTH_E If SIV verification fails. + \return BAD_FUNC_ARG If parameters are invalid. + \return Other negative values on error. + + \param key pointer to the key buffer (32, 48, or 64 bytes for SIV) + \param keySz length of the key in bytes + \param assoc pointer to array of associated data structures + \param numAssoc number of associated data items + \param nonce pointer to the nonce buffer (can be NULL) + \param nonceSz length of the nonce in bytes + \param in pointer to ciphertext to decrypt + \param inSz length of ciphertext in bytes + \param siv pointer to the SIV to verify (16 bytes) + \param out pointer to buffer to store plaintext + + _Example_ + \code + byte key[32] = { }; // 256-bit key for AES-128-SIV + AesSivAssoc assoc[1]; + byte aad[20] = { }; // associated data + byte nonce[12] = { }; // nonce + byte ciphertext[100] = { }; // encrypted data + byte siv[16] = { }; // received SIV + byte plaintext[100]; + + assoc[0].data = aad; + assoc[0].sz = 20; + + int ret = wc_AesSivDecrypt_ex(key, 32, assoc, 1, nonce, 12, + ciphertext, 100, siv, plaintext); + if (ret != 0) { + // decryption or verification failed + } + \endcode + + \sa wc_AesSivEncrypt_ex + \sa wc_AesSivDecrypt +*/ +int wc_AesSivDecrypt_ex(const byte* key, word32 keySz, + const AesSivAssoc* assoc, word32 numAssoc, + const byte* nonce, word32 nonceSz, const byte* in, + word32 inSz, byte* siv, byte* out); diff --git a/doc/dox_comments/header_files/arc4.h b/doc/dox_comments/header_files/arc4.h index bcc2d47a3..3bbcced77 100644 --- a/doc/dox_comments/header_files/arc4.h +++ b/doc/dox_comments/header_files/arc4.h @@ -57,3 +57,57 @@ int wc_Arc4Process(Arc4* arc4, byte* out, const byte* in, word32 length); \sa wc_Arc4Process */ int wc_Arc4SetKey(Arc4* arc4, const byte* key, word32 length); + +/*! + \ingroup ARC4 + \brief This function initializes an ARC4 structure for use with + asynchronous cryptographic operations. It sets up the heap hint and + device ID for hardware acceleration support. + + \return 0 On success. + \return BAD_FUNC_ARG If arc4 is NULL. + + \param arc4 pointer to the Arc4 structure to initialize + \param heap pointer to heap hint for memory allocation (can be NULL) + \param devId device ID for hardware acceleration (use INVALID_DEVID + for software) + + _Example_ + \code + Arc4 arc4; + int ret = wc_Arc4Init(&arc4, NULL, INVALID_DEVID); + if (ret != 0) { + // initialization failed + } + // use arc4 for encryption/decryption + wc_Arc4Free(&arc4); + \endcode + + \sa wc_Arc4SetKey + \sa wc_Arc4Free +*/ +int wc_Arc4Init(Arc4* arc4, void* heap, int devId); + +/*! + \ingroup ARC4 + \brief This function frees an ARC4 structure, releasing any resources + allocated for asynchronous cryptographic operations. It should be + called when the ARC4 structure is no longer needed. + + \return none No return value. + + \param arc4 pointer to the Arc4 structure to free + + _Example_ + \code + Arc4 arc4; + wc_Arc4Init(&arc4, NULL, INVALID_DEVID); + wc_Arc4SetKey(&arc4, key, keyLen); + // use arc4 for encryption/decryption + wc_Arc4Free(&arc4); + \endcode + + \sa wc_Arc4Init + \sa wc_Arc4SetKey +*/ +void wc_Arc4Free(Arc4* arc4); diff --git a/doc/dox_comments/header_files/ascon.h b/doc/dox_comments/header_files/ascon.h index 3aab14fc9..4d0c0b540 100644 --- a/doc/dox_comments/header_files/ascon.h +++ b/doc/dox_comments/header_files/ascon.h @@ -466,4 +466,109 @@ int wc_AsconAEAD128_DecryptUpdate(wc_AsconAEAD128* a, byte* out, const byte* in, */ int wc_AsconAEAD128_DecryptFinal(wc_AsconAEAD128* a, const byte* tag); +/*! + \ingroup ASCON + \brief This function allocates and initializes a new Ascon Hash256 + context. The returned context must be freed with wc_AsconHash256_Free + when no longer needed. + + \return Pointer to allocated wc_AsconHash256 structure on success. + \return NULL on allocation or initialization failure. + + _Example_ + \code + wc_AsconHash256* hash = wc_AsconHash256_New(); + if (hash == NULL) { + // handle allocation error + } + byte data[]; // data to hash + wc_AsconHash256_Update(hash, data, sizeof(data)); + byte digest[ASCON_HASH256_SZ]; + wc_AsconHash256_Final(hash, digest); + wc_AsconHash256_Free(hash); + \endcode + + \sa wc_AsconHash256_Free + \sa wc_AsconHash256_Init +*/ +wc_AsconHash256* wc_AsconHash256_New(void); + +/*! + \ingroup ASCON + \brief This function frees an Ascon Hash256 context that was allocated + with wc_AsconHash256_New. It clears the context before freeing to + prevent information leakage. + + \return none No return value. + + \param a pointer to the wc_AsconHash256 structure to free + + _Example_ + \code + wc_AsconHash256* hash = wc_AsconHash256_New(); + if (hash != NULL) { + // use hash context + wc_AsconHash256_Free(hash); + } + \endcode + + \sa wc_AsconHash256_New + \sa wc_AsconHash256_Clear +*/ +void wc_AsconHash256_Free(wc_AsconHash256* a); + +/*! + \ingroup ASCON + \brief This function clears an Ascon Hash256 context by zeroing all + internal state. This should be called to securely erase sensitive + data from memory. + + \return none No return value. + + \param a pointer to the wc_AsconHash256 structure to clear + + _Example_ + \code + wc_AsconHash256 hash; + wc_AsconHash256_Init(&hash); + byte data[]; // data to hash + wc_AsconHash256_Update(&hash, data, sizeof(data)); + byte digest[ASCON_HASH256_SZ]; + wc_AsconHash256_Final(&hash, digest); + wc_AsconHash256_Clear(&hash); + \endcode + + \sa wc_AsconHash256_Init + \sa wc_AsconHash256_Free +*/ +void wc_AsconHash256_Clear(wc_AsconHash256* a); + +/*! + \ingroup ASCON + \brief This function allocates and initializes a new Ascon AEAD128 + context. The returned context must be freed with wc_AsconAEAD128_Free + when no longer needed. + + \return Pointer to allocated wc_AsconAEAD128 structure on success. + \return NULL on allocation or initialization failure. + + _Example_ + \code + wc_AsconAEAD128* aead = wc_AsconAEAD128_New(); + if (aead == NULL) { + // handle allocation error + } + byte key[ASCON_AEAD128_KEY_SZ] = { }; // key + byte nonce[ASCON_AEAD128_NONCE_SZ] = { }; // nonce + wc_AsconAEAD128_SetKey(aead, key); + wc_AsconAEAD128_SetNonce(aead, nonce); + // perform encryption/decryption + wc_AsconAEAD128_Free(aead); + \endcode + + \sa wc_AsconAEAD128_Free + \sa wc_AsconAEAD128_Init +*/ +wc_AsconAEAD128* wc_AsconAEAD128_New(void); + diff --git a/doc/dox_comments/header_files/asn.h b/doc/dox_comments/header_files/asn.h index e69de29bb..a26ac6e53 100644 --- a/doc/dox_comments/header_files/asn.h +++ b/doc/dox_comments/header_files/asn.h @@ -0,0 +1,239 @@ +/*! + \ingroup ASN + \brief This function converts BER (Basic Encoding Rules) formatted data + to DER (Distinguished Encoding Rules) format. BER allows indefinite + length encoding while DER requires definite lengths. This function + calculates definite lengths for all indefinite length items. + + \return 0 On success. + \return ASN_PARSE_E If the BER data is invalid. + \return BAD_FUNC_ARG If ber or derSz are NULL. + \return BUFFER_E If der is not NULL and derSz is too small. + + \param ber pointer to the buffer containing BER formatted data + \param berSz size of the BER data in bytes + \param der pointer to buffer to store DER formatted data (can be NULL + to calculate required size) + \param derSz pointer to size of der buffer; updated with actual size + needed or used + + \note This API is not public by default. Define WOLFSSL_PUBLIC_ASN to + expose APIs marked WOLFSSL_ASN_API. + + _Example_ + \code + byte ber[256] = { }; // BER encoded data + byte der[256]; + word32 derSz = sizeof(der); + + int ret = wc_BerToDer(ber, sizeof(ber), der, &derSz); + if (ret == 0) { + // der now contains DER formatted data of length derSz + } + \endcode + + \sa wc_EncodeObjectId +*/ +int wc_BerToDer(const byte* ber, word32 berSz, byte* der, word32* derSz); + +/*! + \ingroup ASN + \brief This function frees a linked list of alternative names + (DNS_entry structures). It deallocates each node and its associated + name string, IP string, and RID string if present. + + \return none No return value. + + \param altNames pointer to the head of the alternative names linked list + \param heap pointer to heap hint for memory deallocation (can be NULL) + + \note This API is not public by default. Define WOLFSSL_PUBLIC_ASN to + expose APIs marked WOLFSSL_ASN_API. + + _Example_ + \code + DNS_entry* altNames = NULL; + // populate altNames with certificate alternative names + + FreeAltNames(altNames, NULL); + // altNames list is now freed + \endcode + + \sa AltNameNew +*/ +void FreeAltNames(DNS_entry* altNames, void* heap); + +/*! + \ingroup ASN + \brief This function sets an extended callback for handling unknown + certificate extensions during certificate parsing. The callback + receives additional context information compared to the basic + callback. + + \return 0 On success. + \return BAD_FUNC_ARG If cert is NULL. + + \param cert pointer to the DecodedCert structure + \param cb callback function to handle unknown extensions + \param ctx context pointer passed to the callback + + \note This API is not public by default. Define WOLFSSL_PUBLIC_ASN to + expose APIs marked WOLFSSL_ASN_API. + + _Example_ + \code + DecodedCert cert; + + int UnknownExtCallback(const byte* oid, word32 oidSz, int crit, + const byte* der, word32 derSz, void* ctx) { + // handle unknown extension + return 0; + } + + wc_InitDecodedCert(&cert, derCert, derCertSz, NULL); + wc_SetUnknownExtCallbackEx(&cert, UnknownExtCallback, myContext); + wc_ParseCert(&cert, CERT_TYPE, NO_VERIFY, NULL); + \endcode + + \sa wc_SetUnknownExtCallback + \sa wc_InitDecodedCert +*/ +int wc_SetUnknownExtCallbackEx(DecodedCert* cert, + wc_UnknownExtCallbackEx cb, void *ctx); + +/*! + \ingroup ASN + \brief This function verifies the signature on a certificate using a + certificate manager. It checks that the certificate is properly + signed by a trusted CA. + + \return 0 On successful signature verification. + \return ASN_SIG_CONFIRM_E If signature verification fails. + \return Other negative values on error. + + \param cert pointer to the DER encoded certificate + \param certSz size of the certificate in bytes + \param heap pointer to heap hint for memory allocation (can be NULL) + \param cm pointer to certificate manager containing trusted CAs + + _Example_ + \code + byte cert[2048] = { }; // DER encoded certificate + word32 certSz = sizeof(cert); + WOLFSSL_CERT_MANAGER* cm; + + cm = wolfSSL_CertManagerNew(); + wolfSSL_CertManagerLoadCA(cm, "ca-cert.pem", NULL); + + int ret = wc_CheckCertSignature(cert, certSz, NULL, cm); + if (ret == 0) { + // certificate signature is valid + } + wolfSSL_CertManagerFree(cm); + \endcode + + \sa wolfSSL_CertManagerNew + \sa wolfSSL_CertManagerLoadCA +*/ +int wc_CheckCertSignature(const byte* cert, word32 certSz, void* heap, + void* cm); + +/*! + \ingroup ASN + \brief This function encodes an array of word16 values into an ASN.1 + Object Identifier (OID) in DER format. OIDs are used to identify + algorithms, extensions, and other objects in certificates and + cryptographic protocols. + + \return 0 On success. + \return BAD_FUNC_ARG If in, inSz, or outSz are invalid. + \return BUFFER_E If out is not NULL and outSz is too small. + + \param in pointer to array of word16 values representing OID components + \param inSz number of components in the OID + \param out pointer to buffer to store encoded OID (can be NULL to + calculate size) + \param outSz pointer to size of out buffer; updated with actual size + + _Example_ + \code + word16 oid[] = {1, 2, 840, 113549, 1, 1, 11}; // sha256WithRSAEncryption + byte encoded[32]; + word32 encodedSz = sizeof(encoded); + + int ret = wc_EncodeObjectId(oid, sizeof(oid)/sizeof(word16), + encoded, &encodedSz); + if (ret == 0) { + // encoded contains DER encoded OID + } + \endcode + + \sa wc_BerToDer +*/ +int wc_EncodeObjectId(const word16* in, word32 inSz, byte* out, + word32* outSz); + +/*! + \ingroup ASN + \brief This function sets the algorithm identifier in DER format. It + encodes the algorithm OID and optional parameters based on the + algorithm type and curve size. + + \return Length of the encoded algorithm identifier on success. + \return Negative value on error. + + \param algoOID algorithm object identifier constant + \param output pointer to buffer to store encoded algorithm ID + \param type type of encoding (oidSigType, oidHashType, etc.) + \param curveSz size of the curve for ECC algorithms (0 for non-ECC) + + _Example_ + \code + byte algId[32]; + word32 len; + + len = SetAlgoID(CTC_SHA256wRSA, algId, oidSigType, 0); + if (len > 0) { + // algId contains encoded algorithm identifier + } + \endcode + + \sa wc_EncodeObjectId +*/ +word32 SetAlgoID(int algoOID, byte* output, int type, int curveSz); + +/*! + \ingroup ASN + \brief This function decodes a DER encoded Diffie-Hellman public key. + It extracts the public key value from the DER encoding and stores it + in the DhKey structure. + + \return 0 On success. + \return BAD_FUNC_ARG If input, inOutIdx, key, or inSz are invalid. + \return ASN_PARSE_E If the DER encoding is invalid. + \return Other negative values on error. + + \param input pointer to buffer containing DER encoded public key + \param inOutIdx pointer to index in buffer; updated to end of key + \param key pointer to DhKey structure to store decoded public key + \param inSz size of the input buffer + + _Example_ + \code + byte derKey[256] = { }; // DER encoded DH public key + word32 idx = 0; + DhKey key; + + wc_InitDhKey(&key); + int ret = wc_DhPublicKeyDecode(derKey, &idx, &key, sizeof(derKey)); + if (ret == 0) { + // key now contains the decoded public key + } + wc_FreeDhKey(&key); + \endcode + + \sa wc_InitDhKey + \sa wc_DhKeyDecode +*/ +int wc_DhPublicKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, + word32 inSz); diff --git a/doc/dox_comments/header_files/asn_public.h b/doc/dox_comments/header_files/asn_public.h index aa8ed94d3..b4c537ec7 100644 --- a/doc/dox_comments/header_files/asn_public.h +++ b/doc/dox_comments/header_files/asn_public.h @@ -53,6 +53,31 @@ int wc_InitCert(Cert* cert); */ Cert* wc_CertNew(void* heap); +/*! + \ingroup ASN + \brief Initializes certificate with heap hint and device ID. + + \return 0 on success + \return BAD_FUNC_ARG if cert is NULL + + \param cert Cert structure to initialize + \param heap Heap hint for memory allocation + \param devId Device ID for hardware acceleration + + _Example_ + \code + Cert myCert; + int ret = wc_InitCert_ex(&myCert, NULL, INVALID_DEVID); + if (ret != 0) { + // error initializing cert + } + \endcode + + \sa wc_InitCert + \sa wc_MakeCert_ex +*/ +int wc_InitCert_ex(Cert* cert, void* heap, int devId); + /*! \ingroup ASN @@ -127,6 +152,248 @@ void wc_CertFree(Cert* cert); int wc_MakeCert(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* rsaKey, ecc_key* eccKey, WC_RNG* rng); +/*! + \ingroup ASN + \brief Makes certificate with generic key type support. + + \return Size of certificate on success + \return MEMORY_E if memory allocation fails + \return BUFFER_E if buffer too small + \return Other error codes on failure + + \param cert Initialized cert structure + \param derBuffer Buffer for generated certificate + \param derSz Size of derBuffer + \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.) + \param key Pointer to key structure + \param rng Random number generator + + _Example_ + \code + Cert myCert; + wc_InitCert(&myCert); + byte derCert[4096]; + RsaKey key; + WC_RNG rng; + int certSz = wc_MakeCert_ex(&myCert, derCert, sizeof(derCert), + RSA_TYPE, &key, &rng); + \endcode + + \sa wc_MakeCert + \sa wc_SignCert_ex +*/ +int wc_MakeCert_ex(Cert* cert, byte* derBuffer, word32 derSz, + int keyType, void* key, WC_RNG* rng); + +/*! + \ingroup ASN + \brief Makes certificate request with generic key type support. + + \return Size of certificate request on success + \return MEMORY_E if memory allocation fails + \return BUFFER_E if buffer too small + \return Other error codes on failure + + \param cert Initialized cert structure + \param derBuffer Buffer for generated certificate request + \param derSz Size of derBuffer + \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.) + \param key Pointer to key structure + + _Example_ + \code + Cert myCert; + wc_InitCert(&myCert); + byte derCert[4096]; + EccKey key; + int certSz = wc_MakeCertReq_ex(&myCert, derCert, sizeof(derCert), + ECC_TYPE, &key); + \endcode + + \sa wc_MakeCertReq + \sa wc_SignCert_ex +*/ +int wc_MakeCertReq_ex(Cert* cert, byte* derBuffer, word32 derSz, + int keyType, void* key); + +/*! + \ingroup ASN + \brief Signs certificate with generic key type support. + + \return New size of certificate with signature on success + \return MEMORY_E if memory allocation fails + \return BUFFER_E if buffer too small + \return Other error codes on failure + + \param requestSz Size of certificate body to sign + \param sType Signature type + \param buf Buffer containing certificate to sign + \param buffSz Total size of buffer + \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.) + \param key Pointer to key structure + \param rng Random number generator + + _Example_ + \code + Cert myCert; + byte derCert[4096]; + RsaKey key; + WC_RNG rng; + // Initialize cert and set fields (issuer, subject, dates, etc.) + wc_InitCert(&myCert); + // ... set myCert fields ... + // Generate certificate body (TBS - To Be Signed) + int bodySz = wc_MakeCert_ex(&myCert, derCert, sizeof(derCert), + RSA_TYPE, &key, &rng); + if (bodySz > 0) { + // bodySz is the size of the unsigned certificate body + // Sign the certificate body and append signature + int certSz = wc_SignCert_ex(bodySz, CTC_SHA256wRSA, + derCert, sizeof(derCert), RSA_TYPE, + &key, &rng); + // derCert now contains complete signed certificate of size certSz + } + \endcode + + \sa wc_SignCert + \sa wc_MakeCert_ex +*/ +int wc_SignCert_ex(int requestSz, int sType, byte* buf, word32 buffSz, + int keyType, void* key, WC_RNG* rng); + +/*! + \ingroup ASN + \brief Makes signature with bit string encoding. This function is used + for dual algorithm certificate signing, where an alternative signature + is created using a secondary key algorithm (e.g., a post-quantum algorithm + alongside a traditional algorithm). + + \note This API is only available when WOLFSSL_DUAL_ALG_CERTS is defined, + which enables support for dual algorithm certificates used in Post-Quantum + cryptography to provide hybrid signing with both traditional and PQ + algorithms. + + \return Size of signature on success + \return Negative on error + + \param sig Output buffer for signature + \param sigSz Size of signature buffer + \param sType Signature type + \param buf Data to sign (typically the TBS - To Be Signed - + certificate data) + \param bufSz Size of data + \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.) + \param key Pointer to key structure + \param rng Random number generator + + _Example_ + \code + byte sig[512], data[256]; + RsaKey key; + WC_RNG rng; + int sigSz = wc_MakeSigWithBitStr(sig, sizeof(sig), CTC_SHA256wRSA, + data, sizeof(data), RSA_TYPE, + &key, &rng); + \endcode + + \sa wc_SignCert_ex + \sa wc_GeneratePreTBS +*/ +int wc_MakeSigWithBitStr(byte *sig, int sigSz, int sType, byte* buf, + word32 bufSz, int keyType, void* key, + WC_RNG* rng); + +/*! + \ingroup ASN + \brief Gets certificate validity dates. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + + \param cert Certificate structure + \param before Output for notBefore date + \param after Output for notAfter date + + _Example_ + \code + Cert myCert; + struct tm beforeDate, afterDate; + int ret = wc_GetCertDates(&myCert, &beforeDate, &afterDate); + \endcode + + \sa wc_InitCert +*/ +int wc_GetCertDates(Cert* cert, struct tm* before, struct tm* after); + +/*! + \ingroup ASN + \brief Extracts date information from certificate date field. This + function parses an ASN.1 encoded date (including tag and length) and + returns a pointer to the raw date value bytes, the ASN.1 time type, + and the length of the date value. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + \return ASN_PARSE_E if date parsing fails + + \param certDate Certificate date buffer containing ASN.1 encoded date + (tag + length + value) + \param certDateSz Size of certificate date buffer + \param date Output pointer set to the raw date value bytes (without + tag/length) + \param format Output byte indicating ASN.1 time type: ASN_UTC_TIME + (0x17) or ASN_GENERALIZED_TIME (0x18) + \param length Output length of the raw date value in bytes + + _Example_ + \code + const byte* certDate; + const byte* date; + byte format; + int length; + int ret = wc_GetDateInfo(certDate, certDateSz, &date, + &format, &length); + if (ret == 0) { + // date points to raw time bytes, format indicates UTC or + // Generalized time, length is the number of date value bytes + } + \endcode + + \sa wc_GetCertDates + \sa wc_GetDateAsCalendarTime +*/ +int wc_GetDateInfo(const byte* certDate, int certDateSz, + const byte** date, byte* format, int* length); + +/*! + \ingroup ASN + \brief Converts certificate date to calendar time structure. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + \return ASN_TIME_E if time conversion fails + + \param date Date buffer + \param length Length of date buffer + \param format Date format (ASN_UTC_TIME or ASN_GENERALIZED_TIME) + \param timearg Pointer to tm structure to fill + + _Example_ + \code + const byte* date; + int length; + byte format; + struct tm timeInfo; + int ret = wc_GetDateAsCalendarTime(date, length, format, + &timeInfo); + \endcode + + \sa wc_GetDateInfo + \sa wc_GetCertDates +*/ +int wc_GetDateAsCalendarTime(const byte* date, int length, + byte format, struct tm* timearg); + /*! \ingroup ASN @@ -898,6 +1165,32 @@ int wc_SetDatesBuffer(Cert* cert, const byte* der, int derSz); int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, ecc_key *eckey); +/*! + \ingroup ASN + \brief Sets authority key ID from public key with generic key type. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + \return MEMORY_E if memory allocation fails + + \param cert Certificate structure + \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.) + \param key Pointer to key structure + + _Example_ + \code + Cert myCert; + wc_InitCert(&myCert); + RsaKey key; + int ret = wc_SetAuthKeyIdFromPublicKey_ex(&myCert, RSA_TYPE, + &key); + \endcode + + \sa wc_SetAuthKeyIdFromPublicKey +*/ +int wc_SetAuthKeyIdFromPublicKey_ex(Cert *cert, int keyType, + void* key); + /*! \ingroup ASN @@ -989,6 +1282,33 @@ int wc_SetAuthKeyId(Cert *cert, const char* file); int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, ecc_key *eckey); +/*! + \ingroup ASN + \brief Sets subject key ID from public key with generic key type. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + \return MEMORY_E if memory allocation fails + \return PUBLIC_KEY_E if error getting public key + + \param cert Certificate structure + \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.) + \param key Pointer to key structure + + _Example_ + \code + Cert myCert; + wc_InitCert(&myCert); + EccKey key; + int ret = wc_SetSubjectKeyIdFromPublicKey_ex(&myCert, ECC_TYPE, + &key); + \endcode + + \sa wc_SetSubjectKeyIdFromPublicKey +*/ +int wc_SetSubjectKeyIdFromPublicKey_ex(Cert *cert, int keyType, + void* key); + /*! \ingroup ASN @@ -1053,6 +1373,58 @@ int wc_SetSubjectKeyId(Cert *cert, const char* file); */ int wc_SetKeyUsage(Cert *cert, const char *value); +/*! + \ingroup ASN + \brief Sets extended key usage using comma-delimited string. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + \return MEMORY_E if memory allocation fails + + \param cert Certificate structure + \param value Comma-delimited string of extended key usage values + + _Example_ + \code + Cert myCert; + wc_InitCert(&myCert); + int ret = wc_SetExtKeyUsage(&myCert, + "serverAuth,clientAuth"); + \endcode + + \sa wc_SetKeyUsage + \sa wc_SetExtKeyUsageOID +*/ +int wc_SetExtKeyUsage(Cert *cert, const char *value); + +/*! + \ingroup ASN + \brief Sets extended key usage using OID string. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + \return MEMORY_E if memory allocation fails + + \param cert Certificate structure + \param oid OID string + \param sz Length of OID string + \param idx Index for multiple OIDs + \param heap Heap hint for memory allocation + + _Example_ + \code + Cert myCert; + wc_InitCert(&myCert); + const char* oid = "1.3.6.1.5.5.7.3.1"; + int ret = wc_SetExtKeyUsageOID(&myCert, oid, strlen(oid), + 0, NULL); + \endcode + + \sa wc_SetExtKeyUsage +*/ +int wc_SetExtKeyUsageOID(Cert *cert, const char *oid, word32 sz, + byte idx, void* heap); + /*! \ingroup ASN @@ -1084,6 +1456,31 @@ int wc_SetKeyUsage(Cert *cert, const char *value); int wc_PemPubKeyToDer(const char* fileName, unsigned char* derBuf, int derSz); +/*! + \ingroup ASN + \brief Loads PEM public key from file to DER buffer. + + \return 0 on success + \return negative on error + + \param fileName Path to PEM file + \param der Pointer to DerBuffer pointer to allocate + + _Example_ + \code + DerBuffer* der = NULL; + int ret = wc_PemPubKeyToDer_ex("pubkey.pem", &der); + if (ret == 0) { + // Use der->buffer and der->length + wc_FreeDer(&der); + } + \endcode + + \sa wc_PemPubKeyToDer + \sa wc_FreeDer +*/ +int wc_PemPubKeyToDer_ex(const char* fileName, DerBuffer** der); + /*! \ingroup ASN @@ -1116,6 +1513,111 @@ int wc_PemPubKeyToDer(const char* fileName, int wc_PubKeyPemToDer(const unsigned char* pem, int pemSz, unsigned char* buff, int buffSz); +/*! + \ingroup ASN + \brief Gets PEM header and footer strings for given type. + + \return 0 on success + \return BAD_FUNC_ARG if parameters invalid + + \param type PEM type (CERT_TYPE, PRIVATEKEY_TYPE, etc.) + \param header Pointer to header string pointer + \param footer Pointer to footer string pointer + + _Example_ + \code + const char* header; + const char* footer; + int ret = wc_PemGetHeaderFooter(CERT_TYPE, &header, &footer); + \endcode + + \sa wc_PemToDer +*/ +int wc_PemGetHeaderFooter(int type, const char** header, + const char** footer); + +/*! + \ingroup ASN + \brief Allocates DER buffer with specified length and type. + + \return 0 on success + \return BAD_FUNC_ARG if pDer is NULL + \return MEMORY_E if allocation fails + + \param pDer Pointer to DerBuffer pointer to allocate + \param length Length of buffer to allocate + \param type Buffer type for tracking + \param heap Heap hint for memory allocation + + _Example_ + \code + DerBuffer* der = NULL; + int ret = wc_AllocDer(&der, 1024, CERT_TYPE, NULL); + if (ret == 0) { + // Use der->buffer + wc_FreeDer(&der); + } + \endcode + + \sa wc_FreeDer +*/ +int wc_AllocDer(DerBuffer** pDer, word32 length, int type, + void* heap); + +/*! + \ingroup ASN + \brief Frees DER buffer allocated by wc_AllocDer or wc_PemToDer. + + \param pDer Pointer to DerBuffer pointer to free + + _Example_ + \code + DerBuffer* der = NULL; + wc_AllocDer(&der, 1024, CERT_TYPE, NULL); + // Use der + wc_FreeDer(&der); + \endcode + + \sa wc_AllocDer + \sa wc_PemToDer +*/ +void wc_FreeDer(DerBuffer** pDer); + +/*! + \ingroup ASN + \brief Converts PEM to DER format with encryption info support. + + \return 0 on success + \return negative on error + + \param buff PEM buffer + \param longSz Size of PEM buffer + \param type PEM type (CERT_TYPE, PRIVATEKEY_TYPE, etc.) + \param pDer Pointer to DerBuffer pointer to allocate + \param heap Heap hint for memory allocation + \param info Encryption info for encrypted PEM + \param keyFormat Pointer to store key format + + _Example_ + \code + const unsigned char* pem; + DerBuffer* der = NULL; + EncryptedInfo info; + int keyFormat; + int ret = wc_PemToDer(pem, pemSz, PRIVATEKEY_TYPE, &der, + NULL, &info, &keyFormat); + if (ret == 0) { + wc_FreeDer(&der); + } + \endcode + + \sa wc_PemCertToDer + \sa wc_FreeDer +*/ +int wc_PemToDer(const unsigned char* buff, long longSz, int type, + DerBuffer** pDer, void* heap, EncryptedInfo* info, + int* keyFormat); + /*! \ingroup ASN @@ -1309,6 +1811,138 @@ int wc_KeyPemToDer(const unsigned char* pem, int pemSz, int wc_CertPemToDer(const unsigned char* pem, int pemSz, unsigned char* buff, int buffSz, int type); +/*! + \ingroup ASN + \brief Loads PEM certificate from file to DER buffer. + + \return 0 on success + \return negative on error + + \param fileName Path to PEM certificate file + \param der Pointer to DerBuffer pointer to allocate + + _Example_ + \code + DerBuffer* der = NULL; + int ret = wc_PemCertToDer_ex("cert.pem", &der); + if (ret == 0) { + // Use der->buffer and der->length + wc_FreeDer(&der); + } + \endcode + + \sa wc_CertPemToDer + \sa wc_FreeDer +*/ +int wc_PemCertToDer_ex(const char* fileName, DerBuffer** der); + +/*! + \ingroup ASN + \brief Adds PKCS padding to buffer for RSA encryption. + + \return Padded size on success + \return 0 on error + + \param buf Buffer to pad + \param sz Current size of data in buffer + \param blockSz Block size for padding + + _Example_ + \code + byte buffer[256]; + word32 dataSz = 100; + word32 paddedSz = wc_PkcsPad(buffer, dataSz, 256); + \endcode + + \sa wc_RsaPublicEncrypt +*/ +word32 wc_PkcsPad(byte* buf, word32 sz, word32 blockSz); + +/*! + \ingroup RSA + \brief Decodes RSA public key and extracts modulus and exponent. + + \return 0 on success + \return negative on error + + \param input DER encoded RSA public key buffer + \param inOutIdx Pointer to index in buffer + \param inSz Size of input buffer + \param n Pointer to modulus pointer + \param nSz Pointer to modulus size + \param e Pointer to exponent pointer + \param eSz Pointer to exponent size + + _Example_ + \code + const byte* n; + const byte* e; + word32 nSz, eSz, idx = 0; + int ret = wc_RsaPublicKeyDecode_ex(derBuf, &idx, derSz, + &n, &nSz, &e, &eSz); + \endcode + + \sa wc_RsaPublicKeyDecode +*/ +int wc_RsaPublicKeyDecode_ex(const byte* input, word32* inOutIdx, + word32 inSz, const byte** n, word32* nSz, + const byte** e, word32* eSz); + +/*! + \ingroup RSA + \brief Calculates DER encoded RSA public key size. + + \return Size on success + \return negative on error + + \param key RSA key structure + \param with_header Include sequence header if non-zero + + _Example_ + \code + RsaKey key; + int derSz = wc_RsaPublicKeyDerSize(&key, 1); + \endcode + + \sa wc_RsaKeyToDer +*/ +int wc_RsaPublicKeyDerSize(RsaKey* key, int with_header); + +/*! + \ingroup RSA + \brief Validates DER encoded RSA private key format. This function + validates the ASN.1 syntax and structure of the RSA private key + (sequences, integer tags, and lengths) without loading the key values + into an RsaKey structure. It does not perform mathematical validation + of the RSA key parameters (e.g., checking if p and q are prime, or if + the key components satisfy RSA mathematical relationships). + + \return 0 on success (valid ASN.1 structure) + \return ASN_PARSE_E if ASN.1 parsing fails + \return ASN_RSA_KEY_E if RSA key structure is invalid + \return BAD_FUNC_ARG if parameters are invalid + + \param input DER encoded RSA private key buffer + \param inOutIdx Pointer to index in buffer (updated on success) + \param keySz Pointer to store modulus size in bytes + \param inSz Size of input buffer + + _Example_ + \code + word32 idx = 0; + int keySz; + int ret = wc_RsaPrivateKeyValidate(derBuf, &idx, &keySz, + derSz); + if (ret == 0) { + // ASN.1 structure is valid, keySz contains modulus size + } + \endcode + + \sa wc_RsaPrivateKeyDecode +*/ +int wc_RsaPrivateKeyValidate(const byte* input, word32* inOutIdx, + int* keySz, word32 inSz); + /*! \ingroup CertsKeys @@ -1332,6 +1966,145 @@ int wc_CertPemToDer(const unsigned char* pem, int pemSz, int wc_GetPubKeyDerFromCert(struct DecodedCert* cert, byte* derKey, word32* derKeySz); +/*! + \ingroup DSA + \brief Decodes DSA parameters from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded DSA parameters buffer + \param inOutIdx Pointer to index in buffer + \param key DSA key structure to store parameters + \param inSz Size of input buffer + + _Example_ + \code + DsaKey key; + word32 idx = 0; + int ret = wc_DsaParamsDecode(derBuf, &idx, &key, derSz); + \endcode + + \sa wc_DsaKeyToParamsDer +*/ +int wc_DsaParamsDecode(const byte* input, word32* inOutIdx, + DsaKey* key, word32 inSz); + +/*! + \ingroup DSA + \brief Encodes DSA parameters to DER format. + + \return Size on success + \return negative on error + + \param key DSA key structure with parameters + \param output Buffer for DER encoded parameters + \param inLen Size of output buffer + + _Example_ + \code + DsaKey key; + byte der[1024]; + int derSz = wc_DsaKeyToParamsDer(&key, der, sizeof(der)); + \endcode + + \sa wc_DsaParamsDecode +*/ +int wc_DsaKeyToParamsDer(DsaKey* key, byte* output, word32 inLen); + +/*! + \ingroup DSA + \brief Encodes DSA parameters to DER with size output. + + \return 0 on success + \return negative on error + + \param key DSA key structure with parameters + \param output Buffer for DER encoded parameters + \param inLen Pointer to buffer size (in/out) + + _Example_ + \code + DsaKey key; + byte der[1024]; + word32 derSz = sizeof(der); + int ret = wc_DsaKeyToParamsDer_ex(&key, der, &derSz); + \endcode + + \sa wc_DsaKeyToParamsDer +*/ +int wc_DsaKeyToParamsDer_ex(DsaKey* key, byte* output, + word32* inLen); + +/*! + \ingroup DH + \brief Encodes DH parameters to DER format. + + \return 0 on success + \return negative on error + + \param key DH key structure with parameters + \param out Buffer for DER encoded parameters + \param outSz Pointer to buffer size (in/out) + + _Example_ + \code + DhKey key; + byte der[1024]; + word32 derSz = sizeof(der); + int ret = wc_DhParamsToDer(&key, der, &derSz); + \endcode + + \sa wc_DhKeyToDer +*/ +int wc_DhParamsToDer(DhKey* key, byte* out, word32* outSz); + +/*! + \ingroup DH + \brief Encodes DH public key to DER format. + + \return 0 on success + \return negative on error + + \param key DH key structure with public key + \param out Buffer for DER encoded public key + \param outSz Pointer to buffer size (in/out) + + _Example_ + \code + DhKey key; + byte der[1024]; + word32 derSz = sizeof(der); + int ret = wc_DhPubKeyToDer(&key, der, &derSz); + \endcode + + \sa wc_DhKeyToDer +*/ +int wc_DhPubKeyToDer(DhKey* key, byte* out, word32* outSz); + +/*! + \ingroup DH + \brief Encodes DH private key to DER format. + + \return 0 on success + \return negative on error + + \param key DH key structure with private key + \param out Buffer for DER encoded private key + \param outSz Pointer to buffer size (in/out) + + _Example_ + \code + DhKey key; + byte der[1024]; + word32 derSz = sizeof(der); + int ret = wc_DhPrivKeyToDer(&key, der, &derSz); + \endcode + + \sa wc_DhKeyToDer +*/ +int wc_DhPrivKeyToDer(DhKey* key, byte* out, word32* outSz); + /*! \ingroup ASN @@ -1392,6 +2165,117 @@ int wc_GetPubKeyDerFromCert(struct DecodedCert* cert, int wc_EccPrivateKeyDecode(const byte* input, word32* inOutIdx, ecc_key* key, word32 inSz); +/*! + \ingroup ECC + \brief Encodes ECC private key to DER format. + + \return Size on success + \return negative on error + + \param key ECC key structure with private key + \param output Buffer for DER encoded private key + \param inLen Size of output buffer + + _Example_ + \code + ecc_key key; + byte der[1024]; + int derSz = wc_EccPrivateKeyToDer(&key, der, sizeof(der)); + \endcode + + \sa wc_EccPrivateKeyDecode +*/ +int wc_EccPrivateKeyToDer(ecc_key* key, byte* output, + word32 inLen); + +/*! + \ingroup ECC + \brief Calculates DER encoded ECC key size. + + \return Size on success + \return negative on error + + \param key ECC key structure + \param pub Non-zero to include public key + + _Example_ + \code + ecc_key key; + int derSz = wc_EccKeyDerSize(&key, 1); + \endcode + + \sa wc_EccPrivateKeyToDer +*/ +int wc_EccKeyDerSize(ecc_key* key, int pub); + +/*! + \ingroup ECC + \brief Encodes ECC private key to PKCS#8 format. + + \return Size on success + \return negative on error + + \param key ECC key structure with private key + \param output Buffer for PKCS#8 encoded key + \param inLen Pointer to buffer size (in/out) + + _Example_ + \code + ecc_key key; + byte pkcs8[1024]; + word32 pkcs8Sz = sizeof(pkcs8); + int ret = wc_EccPrivateKeyToPKCS8(&key, pkcs8, &pkcs8Sz); + \endcode + + \sa wc_EccPrivateKeyToDer +*/ +int wc_EccPrivateKeyToPKCS8(ecc_key* key, byte* output, + word32* inLen); + +/*! + \ingroup ECC + \brief Encodes ECC key pair to PKCS#8 format. + + \return Size on success + \return negative on error + + \param key ECC key structure with key pair + \param output Buffer for PKCS#8 encoded key + \param inLen Pointer to buffer size (in/out) + + _Example_ + \code + ecc_key key; + byte pkcs8[1024]; + word32 pkcs8Sz = sizeof(pkcs8); + int ret = wc_EccKeyToPKCS8(&key, pkcs8, &pkcs8Sz); + \endcode + + \sa wc_EccPrivateKeyToPKCS8 +*/ +int wc_EccKeyToPKCS8(ecc_key* key, byte* output, + word32* inLen); + +/*! + \ingroup ECC + \brief Calculates DER encoded ECC public key size. + + \return Size on success + \return negative on error + + \param key ECC key structure + \param with_AlgCurve Include algorithm and curve if non-zero + + _Example_ + \code + ecc_key key; + int derSz = wc_EccPublicKeyDerSize(&key, 1); + \endcode + + \sa wc_EccPublicKeyToDer +*/ +int wc_EccPublicKeyDerSize(ecc_key* key, int with_AlgCurve); + /*! \ingroup ASN @@ -1770,6 +2654,345 @@ int wc_Curve25519PublicKeyToDer(curve25519_key* key, byte* output, word32 inLen, int wc_Curve25519KeyToDer(curve25519_key* key, byte* output, word32 inLen, int withAlg); +/*! + \ingroup Ed25519 + \brief Decodes Ed25519 private key from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded Ed25519 private key buffer + \param inOutIdx Pointer to index in buffer + \param key Ed25519 key structure to store key + \param inSz Size of input buffer + + _Example_ + \code + ed25519_key key; + word32 idx = 0; + int ret = wc_Ed25519PrivateKeyDecode(derBuf, &idx, &key, + derSz); + \endcode + + \sa wc_Ed25519PrivateKeyToDer +*/ +int wc_Ed25519PrivateKeyDecode(const byte* input, word32* inOutIdx, + ed25519_key* key, word32 inSz); + +/*! + \ingroup Ed25519 + \brief Decodes Ed25519 public key from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded Ed25519 public key buffer + \param inOutIdx Pointer to index in buffer + \param key Ed25519 key structure to store key + \param inSz Size of input buffer + + _Example_ + \code + ed25519_key key; + word32 idx = 0; + int ret = wc_Ed25519PublicKeyDecode(derBuf, &idx, &key, + derSz); + \endcode + + \sa wc_Ed25519PublicKeyToDer +*/ +int wc_Ed25519PublicKeyDecode(const byte* input, word32* inOutIdx, + ed25519_key* key, word32 inSz); + +/*! + \ingroup Ed25519 + \brief Encodes Ed25519 key to DER format. + + \return Size on success + \return negative on error + + \param key Ed25519 key structure + \param output Buffer for DER encoded key + \param inLen Size of output buffer + + _Example_ + \code + ed25519_key key; + byte der[1024]; + int derSz = wc_Ed25519KeyToDer(&key, der, sizeof(der)); + \endcode + + \sa wc_Ed25519PrivateKeyToDer +*/ +int wc_Ed25519KeyToDer(const ed25519_key* key, byte* output, + word32 inLen); + +/*! + \ingroup Ed25519 + \brief Encodes Ed25519 private key to DER format. + + \return Size on success + \return negative on error + + \param key Ed25519 key structure with private key + \param output Buffer for DER encoded private key + \param inLen Size of output buffer + + _Example_ + \code + ed25519_key key; + byte der[1024]; + int derSz = wc_Ed25519PrivateKeyToDer(&key, der, + sizeof(der)); + \endcode + + \sa wc_Ed25519PrivateKeyDecode +*/ +int wc_Ed25519PrivateKeyToDer(const ed25519_key* key, byte* output, + word32 inLen); + +/*! + \ingroup Ed25519 + \brief Encodes Ed25519 public key to DER format. + + \return Size on success + \return negative on error + + \param key Ed25519 key structure with public key + \param output Buffer for DER encoded public key + \param inLen Size of output buffer + + _Example_ + \code + ed25519_key key; + byte der[1024]; + int derSz = wc_Ed25519PublicKeyToDer(&key, der, + sizeof(der)); + \endcode + + \sa wc_Ed25519PublicKeyDecode +*/ +int wc_Ed25519PublicKeyToDer(const ed25519_key* key, byte* output, + int inLen); + +/*! + \ingroup Ed448 + \brief Decodes Ed448 private key from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded Ed448 private key buffer + \param inOutIdx Pointer to index in buffer + \param key Ed448 key structure to store key + \param inSz Size of input buffer + + _Example_ + \code + ed448_key key; + word32 idx = 0; + int ret = wc_Ed448PrivateKeyDecode(derBuf, &idx, &key, + derSz); + \endcode + + \sa wc_Ed448PrivateKeyToDer +*/ +int wc_Ed448PrivateKeyDecode(const byte* input, word32* inOutIdx, + ed448_key* key, word32 inSz); + +/*! + \ingroup Ed448 + \brief Decodes Ed448 public key from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded Ed448 public key buffer + \param inOutIdx Pointer to index in buffer + \param key Ed448 key structure to store key + \param inSz Size of input buffer + + _Example_ + \code + ed448_key key; + word32 idx = 0; + int ret = wc_Ed448PublicKeyDecode(derBuf, &idx, &key, + derSz); + \endcode + + \sa wc_Ed448PublicKeyToDer +*/ +int wc_Ed448PublicKeyDecode(const byte* input, word32* inOutIdx, + ed448_key* key, word32 inSz); + +/*! + \ingroup Ed448 + \brief Encodes Ed448 key to DER format. + + \return Size on success + \return negative on error + + \param key Ed448 key structure + \param output Buffer for DER encoded key + \param inLen Size of output buffer + + _Example_ + \code + ed448_key key; + byte der[1024]; + int derSz = wc_Ed448KeyToDer(&key, der, sizeof(der)); + \endcode + + \sa wc_Ed448PrivateKeyToDer +*/ +int wc_Ed448KeyToDer(ed448_key* key, byte* output, word32 inLen); + +/*! + \ingroup Ed448 + \brief Encodes Ed448 private key to DER format. + + \return Size on success + \return negative on error + + \param key Ed448 key structure with private key + \param output Buffer for DER encoded private key + \param inLen Size of output buffer + + _Example_ + \code + ed448_key key; + byte der[1024]; + int derSz = wc_Ed448PrivateKeyToDer(&key, der, + sizeof(der)); + \endcode + + \sa wc_Ed448PrivateKeyDecode +*/ +int wc_Ed448PrivateKeyToDer(ed448_key* key, byte* output, + word32 inLen); + +/*! + \ingroup Ed448 + \brief Encodes Ed448 public key to DER format. + + \return Size on success + \return negative on error + + \param key Ed448 key structure with public key + \param output Buffer for DER encoded public key + \param inLen Size of output buffer + + _Example_ + \code + ed448_key key; + byte der[1024]; + int derSz = wc_Ed448PublicKeyToDer(&key, der, + sizeof(der)); + \endcode + + \sa wc_Ed448PublicKeyDecode +*/ +int wc_Ed448PublicKeyToDer(ed448_key* key, byte* output, + int inLen); + +/*! + \ingroup Curve448 + \brief Decodes Curve448 private key from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded Curve448 private key buffer + \param inOutIdx Pointer to index in buffer + \param key Curve448 key structure to store key + \param inSz Size of input buffer + + _Example_ + \code + curve448_key key; + word32 idx = 0; + int ret = wc_Curve448PrivateKeyDecode(derBuf, &idx, &key, + derSz); + \endcode + + \sa wc_Curve448PrivateKeyToDer +*/ +int wc_Curve448PrivateKeyDecode(const byte* input, word32* inOutIdx, + curve448_key* key, word32 inSz); + +/*! + \ingroup Curve448 + \brief Decodes Curve448 public key from DER format. + + \return 0 on success + \return negative on error + + \param input DER encoded Curve448 public key buffer + \param inOutIdx Pointer to index in buffer + \param key Curve448 key structure to store key + \param inSz Size of input buffer + + _Example_ + \code + curve448_key key; + word32 idx = 0; + int ret = wc_Curve448PublicKeyDecode(derBuf, &idx, &key, + derSz); + \endcode + + \sa wc_Curve448PublicKeyToDer +*/ +int wc_Curve448PublicKeyDecode(const byte* input, word32* inOutIdx, + curve448_key* key, word32 inSz); + +/*! + \ingroup Curve448 + \brief Encodes Curve448 private key to DER format. + + \return Size on success + \return negative on error + + \param key Curve448 key structure with private key + \param output Buffer for DER encoded private key + \param inLen Size of output buffer + + _Example_ + \code + curve448_key key; + byte der[1024]; + int derSz = wc_Curve448PrivateKeyToDer(&key, der, + sizeof(der)); + \endcode + + \sa wc_Curve448PrivateKeyDecode +*/ +int wc_Curve448PrivateKeyToDer(curve448_key* key, byte* output, + word32 inLen); + +/*! + \ingroup Curve448 + \brief Encodes Curve448 public key to DER format. + + \return Size on success + \return negative on error + + \param key Curve448 key structure with public key + \param output Buffer for DER encoded public key + \param inLen Size of output buffer + + _Example_ + \code + curve448_key key; + byte der[1024]; + int derSz = wc_Curve448PublicKeyToDer(&key, der, + sizeof(der)); + \endcode + + \sa wc_Curve448PublicKeyDecode +*/ +int wc_Curve448PublicKeyToDer(curve448_key* key, byte* output, + word32 inLen); + /*! \ingroup ASN @@ -2013,11 +3236,318 @@ int wc_EncryptPKCS8Key(byte* key, word32 keySz, byte* out, int pbeOid, int encAlgId, byte* salt, word32 saltSz, int itt, WC_RNG* rng, void* heap); +/*! + \ingroup ASN + \brief Encrypts PKCS#8 key with extended parameters. + + \return Size on success + \return negative on error + + \param key Private key buffer + \param keySz Size of private key + \param out Output buffer for encrypted key + \param outSz Pointer to output buffer size (in/out) + \param password Password for encryption + \param passwordSz Password length + \param vPKCS PKCS version + \param pbeOid PBE algorithm OID + \param encAlgId Encryption algorithm ID + \param salt Salt buffer + \param saltSz Salt size + \param itt Iteration count + \param rng Random number generator + \param heap Heap hint for memory allocation + \param devId Device ID for hardware acceleration + + _Example_ + \code + byte key[256], encrypted[512]; + word32 encSz = sizeof(encrypted); + WC_RNG rng; + int ret = wc_EncryptPKCS8Key_ex(key, keySz, encrypted, + &encSz, "password", 8, + PKCS5, PBES2, AES256CBCb, + NULL, 0, 2048, &rng, NULL, + INVALID_DEVID); + \endcode + + \sa wc_EncryptPKCS8Key +*/ +int wc_EncryptPKCS8Key_ex(byte* key, word32 keySz, byte* out, + word32* outSz, const char* password, + int passwordSz, int vPKCS, int pbeOid, + int encAlgId, byte* salt, word32 saltSz, + int itt, WC_RNG* rng, void* heap, + int devId); + +/*! + \ingroup ASN + \brief Gets current time for certificate operations. + + \return 0 on success + \return negative on error + + \param timePtr Pointer to time buffer + \param timeSize Size of time buffer + + _Example_ + \code + time_t currentTime; + int ret = wc_GetTime(¤tTime, sizeof(currentTime)); + \endcode + + \sa wc_GetDateInfo +*/ +int wc_GetTime(void* timePtr, word32 timeSize); + +/*! + \ingroup ASN + \brief Gets encryption info from encrypted PEM. + + \return 0 on success + \return negative on error + + \param info EncryptedInfo structure to populate + \param cipherName Cipher name string + + _Example_ + \code + EncryptedInfo info; + int ret = wc_EncryptedInfoGet(&info, "AES-256-CBC"); + \endcode + + \sa wc_PemToDer +*/ +int wc_EncryptedInfoGet(EncryptedInfo* info, + const char* cipherName); + +/*! + \ingroup ASN + \brief Parses PIV certificate format. + + \return 0 on success + \return negative on error + + \param cert PIV certificate structure to populate + \param buf Buffer containing PIV certificate + \param totalSz Size of buffer + + _Example_ + \code + wc_CertPIV cert; + int ret = wc_ParseCertPIV(&cert, pivBuf, pivSz); + \endcode + + \sa wc_InitDecodedCert +*/ +int wc_ParseCertPIV(wc_CertPIV* cert, const byte* buf, + word32 totalSz); + +/*! + \ingroup ASN + \brief Extracts subject public key info from certificate. + + \return Size on success + \return negative on error + + \param certDer DER encoded certificate buffer + \param certDerSz Size of certificate + \param pubKeyDer Output buffer for public key + \param pubKeyDerSz Pointer to output buffer size (in/out) + + _Example_ + \code + byte pubKey[1024]; + word32 pubKeySz = sizeof(pubKey); + int ret = wc_GetSubjectPubKeyInfoDerFromCert(certDer, + certSz, + pubKey, + &pubKeySz); + \endcode + + \sa wc_GetPubKeyDerFromCert +*/ +int wc_GetSubjectPubKeyInfoDerFromCert(const byte* certDer, + word32 certDerSz, + byte* pubKeyDer, + word32* pubKeyDerSz); + +/*! + \ingroup ASN + \brief Extracts UUID from certificate. + + \return 0 on success + \return negative on error + + \param cert Decoded certificate structure + \param uuid Output buffer for UUID + \param uuidSz Pointer to UUID buffer size (in/out) + + _Example_ + \code + DecodedCert cert; + byte uuid[16]; + int uuidSz = sizeof(uuid); + int ret = wc_GetUUIDFromCert(&cert, uuid, &uuidSz); + \endcode + + \sa wc_ParseCert +*/ +int wc_GetUUIDFromCert(struct DecodedCert* cert, + byte* uuid, int* uuidSz); + +/*! + \ingroup ASN + \brief Extracts FASCN from certificate. + + \return 0 on success + \return negative on error + + \param cert Decoded certificate structure + \param fascn Output buffer for FASCN + \param fascnSz Pointer to FASCN buffer size (in/out) + + _Example_ + \code + DecodedCert cert; + byte fascn[25]; + int fascnSz = sizeof(fascn); + int ret = wc_GetFASCNFromCert(&cert, fascn, &fascnSz); + \endcode + + \sa wc_ParseCert +*/ +int wc_GetFASCNFromCert(struct DecodedCert* cert, + byte* fascn, int* fascnSz); + +/*! + \ingroup ASN + \brief Generates the pre-TBS (To Be Signed) certificate data from a + decoded certificate. The TBS portion is the certificate data that gets + signed by the certificate authority. This function is used in dual + algorithm certificate creation where the TBS data needs to be extracted + for signing with an alternative algorithm (e.g., a post-quantum algorithm). + + \note This API is only available when WOLFSSL_DUAL_ALG_CERTS is defined, + which enables support for dual algorithm certificates used in Post-Quantum + cryptography to provide hybrid signing with both traditional and PQ + algorithms. + + \return Size of the pre-TBS data on success + \return Negative error code on failure + + \param cert Decoded certificate structure containing the certificate to + extract TBS data from + \param der Output buffer for the pre-TBS DER-encoded data + \param derSz Size of output buffer in bytes + + _Example_ + \code + DecodedCert cert; + byte preTbs[2048]; + int ret = wc_GeneratePreTBS(&cert, preTbs, sizeof(preTbs)); + if (ret > 0) { + // ret contains the size of the pre-TBS data + // preTbs can now be signed with an alternative algorithm + } + \endcode + + \sa wc_MakeCert + \sa wc_MakeSigWithBitStr +*/ +int wc_GeneratePreTBS(struct DecodedCert* cert, byte *der, + int derSz); + +/*! + \ingroup ASN + \brief Initializes decoded attribute certificate structure. + + \return void + + \param acert Attribute certificate structure to initialize + \param heap Heap hint for memory allocation + + _Example_ + \code + DecodedAcert acert; + wc_InitDecodedAcert(&acert, NULL); + \endcode + + \sa wc_FreeDecodedAcert +*/ +void wc_InitDecodedAcert(struct DecodedAcert* acert, + void* heap); + +/*! + \ingroup ASN + \brief Frees decoded attribute certificate structure. + + \return void + + \param acert Attribute certificate structure to free + + _Example_ + \code + DecodedAcert acert; + wc_InitDecodedAcert(&acert, NULL); + wc_FreeDecodedAcert(&acert); + \endcode + + \sa wc_InitDecodedAcert +*/ +void wc_FreeDecodedAcert(struct DecodedAcert * acert); + +/*! + \ingroup ASN + \brief Parses X.509 attribute certificate. + + \return 0 on success + \return negative on error + + \param acert Decoded attribute certificate structure + \param verify Non-zero to verify signature + + _Example_ + \code + DecodedAcert acert; + wc_InitDecodedAcert(&acert, NULL); + int ret = wc_ParseX509Acert(&acert, 1); + \endcode + + \sa wc_VerifyX509Acert +*/ +int wc_ParseX509Acert(struct DecodedAcert* acert, int verify); + +/*! + \ingroup ASN + \brief Verifies X.509 attribute certificate. + + \return 0 on success + \return negative on error + + \param acert Attribute certificate buffer + \param acertSz Size of attribute certificate + \param issuerCert Issuer certificate buffer + \param issuerCertSz Size of issuer certificate + \param cm Certificate manager + + _Example_ + \code + int ret = wc_VerifyX509Acert(acertBuf, acertSz, + issuerBuf, issuerSz, cm); + \endcode + + \sa wc_ParseX509Acert +*/ +int wc_VerifyX509Acert(const byte* acert, word32 acertSz, + const byte* issuerCert, + word32 issuerCertSz, void* cm); + /*! \ingroup ASN \brief This function takes an encrypted PKCS#8 DER key and decrypts it to - PKCS#8 unencrypted DER. Undoes the encryption done by wc_EncryptPKCS8Key. + PKCS#8 unencrypted DER.Undoes the encryption done by wc_EncryptPKCS8Key. See RFC5208. The input buffer is overwritten with the decrypted data. \return The length of the decrypted buffer on success. @@ -2524,3 +4054,24 @@ int wc_Asn1_SetFile(Asn1* asn1, XFILE file); */ int wc_Asn1_PrintAll(Asn1* asn1, Asn1PrintOptions* opts, unsigned char* data, word32 len); + +/*! + \ingroup ASN + \brief Sets OID to name callback for ASN.1 parsing. + + \return 0 on success + \return negative on error + + \param asn1 ASN.1 structure + \param nameCb Callback function to convert OID to name + + _Example_ + \code + Asn1 asn1; + int ret = wc_Asn1_SetOidToNameCb(&asn1, myOidToNameCb); + \endcode + + \sa wc_Asn1_PrintAll +*/ +int wc_Asn1_SetOidToNameCb(Asn1* asn1, Asn1OidToNameCb nameCb); + diff --git a/doc/dox_comments/header_files/chacha.h b/doc/dox_comments/header_files/chacha.h index 3daacd85b..890b82702 100644 --- a/doc/dox_comments/header_files/chacha.h +++ b/doc/dox_comments/header_files/chacha.h @@ -97,3 +97,44 @@ int wc_Chacha_Process(ChaCha* ctx, byte* cipher, const byte* plain, \sa wc_Chacha_Process */ int wc_Chacha_SetKey(ChaCha* ctx, const byte* key, word32 keySz); + +/*! + \ingroup ChaCha + \brief This function sets the key and nonce for an XChaCha cipher + context. XChaCha extends ChaCha20 to use a 192-bit nonce instead of + 96 bits, providing better security for applications that need to + encrypt many messages with the same key. + + \return 0 On success. + \return BAD_FUNC_ARG If ctx, key, or nonce is NULL, or if keySz is + invalid, or if nonceSz is not XCHACHA_NONCE_BYTES (24 bytes). + \return Other negative values on error. + + \param ctx pointer to the ChaCha structure to initialize + \param key pointer to the key buffer (16 or 32 bytes) + \param keySz length of the key in bytes (16 or 32) + \param nonce pointer to the nonce buffer (must be 24 bytes) + \param nonceSz length of the nonce in bytes (must be 24) + \param counter initial block counter value (usually 0) + + _Example_ + \code + ChaCha ctx; + byte key[32] = { }; // 256-bit key + byte nonce[24] = { }; // 192-bit nonce + byte plaintext[100] = { }; // data to encrypt + byte ciphertext[100]; + + int ret = wc_XChacha_SetKey(&ctx, key, 32, nonce, 24, 0); + if (ret != 0) { + // error setting XChaCha key + } + wc_Chacha_Process(&ctx, ciphertext, plaintext, 100); + \endcode + + \sa wc_Chacha_SetKey + \sa wc_Chacha_SetIV + \sa wc_Chacha_Process +*/ +int wc_XChacha_SetKey(ChaCha *ctx, const byte *key, word32 keySz, + const byte *nonce, word32 nonceSz, word32 counter); diff --git a/doc/dox_comments/header_files/chacha20_poly1305.h b/doc/dox_comments/header_files/chacha20_poly1305.h index 53e2f5ef2..661940746 100644 --- a/doc/dox_comments/header_files/chacha20_poly1305.h +++ b/doc/dox_comments/header_files/chacha20_poly1305.h @@ -122,3 +122,273 @@ int wc_ChaCha20Poly1305_Decrypt( const byte* inCiphertext, word32 inCiphertextLen, const byte inAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE], byte* outPlaintext); + +/*! + \ingroup ChaCha20Poly1305 + \brief Compares two authentication tags in constant time to prevent + timing attacks. + + \return 0 If tags match + \return MAC_CMP_FAILED_E If tags do not match + + \param authTag First authentication tag + \param authTagChk Second authentication tag to compare + + _Example_ + \code + byte tag1[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]; + byte tag2[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]; + + int ret = wc_ChaCha20Poly1305_CheckTag(tag1, tag2); + if (ret != 0) { + // tags do not match + } + \endcode + + \sa wc_ChaCha20Poly1305_Decrypt +*/ +int wc_ChaCha20Poly1305_CheckTag( + const byte authTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE], + const byte authTagChk[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); + +/*! + \ingroup ChaCha20Poly1305 + \brief Initializes a ChaChaPoly_Aead structure for incremental + encryption or decryption operations. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + + \param aead Pointer to ChaChaPoly_Aead structure to initialize + \param inKey 32-byte encryption key + \param inIV 12-byte initialization vector + \param isEncrypt 1 for encryption, 0 for decryption + + _Example_ + \code + ChaChaPoly_Aead aead; + byte key[CHACHA20_POLY1305_AEAD_KEYSIZE]; + byte iv[CHACHA20_POLY1305_AEAD_IV_SIZE]; + + int ret = wc_ChaCha20Poly1305_Init(&aead, key, iv, 1); + if (ret != 0) { + // error initializing + } + \endcode + + \sa wc_ChaCha20Poly1305_UpdateAad + \sa wc_ChaCha20Poly1305_UpdateData + \sa wc_ChaCha20Poly1305_Final +*/ +int wc_ChaCha20Poly1305_Init(ChaChaPoly_Aead* aead, + const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE], + const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE], + int isEncrypt); + +/*! + \ingroup ChaCha20Poly1305 + \brief Updates the AEAD context with additional authenticated data + (AAD). Must be called after Init and before UpdateData. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + + \param aead Pointer to initialized ChaChaPoly_Aead structure + \param inAAD Additional authenticated data + \param inAADLen Length of AAD in bytes + + _Example_ + \code + ChaChaPoly_Aead aead; + byte aad[]; // AAD data + + wc_ChaCha20Poly1305_Init(&aead, key, iv, 1); + int ret = wc_ChaCha20Poly1305_UpdateAad(&aead, aad, sizeof(aad)); + if (ret != 0) { + // error updating AAD + } + \endcode + + \sa wc_ChaCha20Poly1305_Init + \sa wc_ChaCha20Poly1305_UpdateData +*/ +int wc_ChaCha20Poly1305_UpdateAad(ChaChaPoly_Aead* aead, + const byte* inAAD, word32 inAADLen); + +/*! + \ingroup ChaCha20Poly1305 + \brief Encrypts or decrypts data incrementally. Can be called + multiple times to process data in chunks. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + + \param aead Pointer to initialized ChaChaPoly_Aead structure + \param inData Input data (plaintext or ciphertext) + \param outData Output buffer for result + \param dataLen Length of data to process + + _Example_ + \code + ChaChaPoly_Aead aead; + byte plain[]; // plaintext + byte cipher[sizeof(plain)]; + + wc_ChaCha20Poly1305_Init(&aead, key, iv, 1); + wc_ChaCha20Poly1305_UpdateAad(&aead, aad, aadLen); + int ret = wc_ChaCha20Poly1305_UpdateData(&aead, plain, + cipher, sizeof(plain)); + \endcode + + \sa wc_ChaCha20Poly1305_Init + \sa wc_ChaCha20Poly1305_Final +*/ +int wc_ChaCha20Poly1305_UpdateData(ChaChaPoly_Aead* aead, + const byte* inData, byte* outData, word32 dataLen); + +/*! + \ingroup ChaCha20Poly1305 + \brief Finalizes the AEAD operation and generates the + authentication tag. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + + \param aead Pointer to ChaChaPoly_Aead structure + \param outAuthTag Buffer to store 16-byte authentication tag + + _Example_ + \code + ChaChaPoly_Aead aead; + byte authTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]; + + wc_ChaCha20Poly1305_Init(&aead, key, iv, 1); + wc_ChaCha20Poly1305_UpdateAad(&aead, aad, aadLen); + wc_ChaCha20Poly1305_UpdateData(&aead, plain, cipher, plainLen); + int ret = wc_ChaCha20Poly1305_Final(&aead, authTag); + \endcode + + \sa wc_ChaCha20Poly1305_Init + \sa wc_ChaCha20Poly1305_UpdateData +*/ +int wc_ChaCha20Poly1305_Final(ChaChaPoly_Aead* aead, + byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); + +/*! + \ingroup ChaCha20Poly1305 + \brief Initializes XChaCha20-Poly1305 AEAD with extended nonce. + XChaCha20 uses a 24-byte nonce instead of 12-byte. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + + \param aead Pointer to ChaChaPoly_Aead structure + \param ad Additional authenticated data + \param ad_len Length of AAD + \param inKey Encryption key + \param inKeySz Key size (must be 32) + \param inIV Initialization vector + \param inIVSz IV size (must be 24 for XChaCha20) + \param isEncrypt 1 for encryption, 0 for decryption + + _Example_ + \code + ChaChaPoly_Aead aead; + byte key[32]; + byte iv[24]; + byte aad[]; // AAD + + int ret = wc_XChaCha20Poly1305_Init(&aead, aad, sizeof(aad), + key, 32, iv, 24, 1); + \endcode + + \sa wc_XChaCha20Poly1305_Encrypt + \sa wc_XChaCha20Poly1305_Decrypt +*/ +int wc_XChaCha20Poly1305_Init(ChaChaPoly_Aead* aead, + const byte *ad, word32 ad_len, + const byte *inKey, word32 inKeySz, + const byte *inIV, word32 inIVSz, + int isEncrypt); + +/*! + \ingroup ChaCha20Poly1305 + \brief One-shot XChaCha20-Poly1305 encryption with 24-byte nonce. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + \return BUFFER_E If dst_space is insufficient + + \param dst Output buffer for ciphertext and tag + \param dst_space Size of output buffer + \param src Input plaintext + \param src_len Length of plaintext + \param ad Additional authenticated data + \param ad_len Length of AAD + \param nonce 24-byte nonce + \param nonce_len Nonce length (must be 24) + \param key 32-byte encryption key + \param key_len Key length (must be 32) + + _Example_ + \code + byte key[32], nonce[24]; + byte plain[]; // plaintext + byte cipher[sizeof(plain) + 16]; + + int ret = wc_XChaCha20Poly1305_Encrypt(cipher, sizeof(cipher), + plain, sizeof(plain), + NULL, 0, nonce, 24, + key, 32); + \endcode + + \sa wc_XChaCha20Poly1305_Decrypt +*/ +int wc_XChaCha20Poly1305_Encrypt(byte *dst, size_t dst_space, + const byte *src, size_t src_len, + const byte *ad, size_t ad_len, + const byte *nonce, size_t nonce_len, + const byte *key, size_t key_len); + +/*! + \ingroup ChaCha20Poly1305 + \brief One-shot XChaCha20-Poly1305 decryption with 24-byte nonce. + + \return 0 On success + \return BAD_FUNC_ARG If parameters are invalid + \return BUFFER_E If dst_space is insufficient + \return MAC_CMP_FAILED_E If authentication fails + + \param dst Output buffer for plaintext + \param dst_space Size of output buffer + \param src Input ciphertext with tag + \param src_len Length of ciphertext plus tag + \param ad Additional authenticated data + \param ad_len Length of AAD + \param nonce 24-byte nonce + \param nonce_len Nonce length (must be 24) + \param key 32-byte decryption key + \param key_len Key length (must be 32) + + _Example_ + \code + byte key[32], nonce[24]; + byte cipher[]; // ciphertext + tag + byte plain[sizeof(cipher) - 16]; + + int ret = wc_XChaCha20Poly1305_Decrypt(plain, sizeof(plain), + cipher, sizeof(cipher), + NULL, 0, nonce, 24, + key, 32); + if (ret == MAC_CMP_FAILED_E) { + // authentication failed + } + \endcode + + \sa wc_XChaCha20Poly1305_Encrypt +*/ +int wc_XChaCha20Poly1305_Decrypt(byte *dst, size_t dst_space, + const byte *src, size_t src_len, + const byte *ad, size_t ad_len, + const byte *nonce, size_t nonce_len, + const byte *key, size_t key_len); diff --git a/doc/dox_comments/header_files/cmac.h b/doc/dox_comments/header_files/cmac.h index 989d2ed42..4de7810a8 100644 --- a/doc/dox_comments/header_files/cmac.h +++ b/doc/dox_comments/header_files/cmac.h @@ -206,3 +206,82 @@ int wc_AesCmacVerify(const byte* check, word32 checkSz, \endcode */ int wc_CMAC_Grow(Cmac* cmac, const byte* in, int inSz); + +/*! + \ingroup CMAC + \brief Single shot AES-CMAC generation with extended parameters + including heap and device ID. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + + \param cmac Pointer to Cmac structure (can be NULL for one-shot) + \param out Buffer to store MAC output + \param outSz Pointer to output size (in/out) + \param in Input data to authenticate + \param inSz Length of input data + \param key AES key + \param keySz Key size (16, 24, or 32 bytes) + \param heap Heap hint for memory allocation (can be NULL) + \param devId Device ID for hardware acceleration (use + INVALID_DEVID for software) + + _Example_ + \code + byte mac[AES_BLOCK_SIZE]; + word32 macSz = sizeof(mac); + byte key[16], msg[64]; + + int ret = wc_AesCmacGenerate_ex(NULL, mac, &macSz, msg, + sizeof(msg), key, sizeof(key), + NULL, INVALID_DEVID); + \endcode + + \sa wc_AesCmacGenerate + \sa wc_AesCmacVerify_ex +*/ +int wc_AesCmacGenerate_ex(Cmac *cmac, byte* out, word32* outSz, + const byte* in, word32 inSz, + const byte* key, word32 keySz, + void* heap, int devId); + +/*! + \ingroup CMAC + \brief Single shot AES-CMAC verification with extended parameters + including heap and device ID. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + \return MAC_CMP_FAILED_E if MAC verification fails + + \param cmac Pointer to Cmac structure (can be NULL for one-shot) + \param check Expected MAC value to verify + \param checkSz Size of expected MAC + \param in Input data to authenticate + \param inSz Length of input data + \param key AES key + \param keySz Key size (16, 24, or 32 bytes) + \param heap Heap hint for memory allocation (can be NULL) + \param devId Device ID for hardware acceleration (use + INVALID_DEVID for software) + + _Example_ + \code + byte mac[AES_BLOCK_SIZE]; + byte key[16], msg[64]; + + int ret = wc_AesCmacVerify_ex(NULL, mac, sizeof(mac), msg, + sizeof(msg), key, sizeof(key), + NULL, INVALID_DEVID); + if (ret == MAC_CMP_FAILED_E) { + // MAC verification failed + } + \endcode + + \sa wc_AesCmacVerify + \sa wc_AesCmacGenerate_ex +*/ +int wc_AesCmacVerify_ex(Cmac* cmac, const byte* check, word32 checkSz, + const byte* in, word32 inSz, + const byte* key, word32 keySz, + void* heap, int devId); diff --git a/doc/dox_comments/header_files/coding.h b/doc/dox_comments/header_files/coding.h index 60677ab1d..e1d7d5e9f 100644 --- a/doc/dox_comments/header_files/coding.h +++ b/doc/dox_comments/header_files/coding.h @@ -235,3 +235,43 @@ int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen); */ int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen); + +/*! + \ingroup Base_Encoding + \brief This function decodes Base64 encoded input without using + constant-time operations. This is faster than the constant-time + version but may be vulnerable to timing attacks. Use only when + timing attacks are not a concern. + + \return 0 On successfully decoding the Base64 encoded input. + \return BAD_FUNC_ARG If the output buffer is too small to store the + decoded input. + \return ASN_INPUT_E If a character in the input buffer falls outside + of the Base64 range or if there is an invalid line ending. + \return BUFFER_E If running out of buffer while decoding. + + \param in pointer to the input buffer to decode + \param inLen length of the input buffer to decode + \param out pointer to the output buffer to store decoded message + \param outLen pointer to length of output buffer; updated with bytes + written + + _Example_ + \code + byte encoded[] = "SGVsbG8gV29ybGQ="; // "Hello World" in Base64 + byte decoded[64]; + word32 outLen = sizeof(decoded); + + int ret = Base64_Decode_nonCT(encoded, sizeof(encoded)-1, decoded, + &outLen); + if (ret != 0) { + // error decoding input + } + // decoded now contains "Hello World" + \endcode + + \sa Base64_Decode + \sa Base64_Encode +*/ +int Base64_Decode_nonCT(const byte* in, word32 inLen, byte* out, + word32* outLen); diff --git a/doc/dox_comments/header_files/compress.h b/doc/dox_comments/header_files/compress.h index d17111cda..2d225ee47 100644 --- a/doc/dox_comments/header_files/compress.h +++ b/doc/dox_comments/header_files/compress.h @@ -70,3 +70,131 @@ int wc_Compress(byte* out, word32 outSz, const byte* in, word32 inSz, word32 fla \sa wc_Compress */ int wc_DeCompress(byte* out, word32 outSz, const byte* in, word32 inSz); + +/*! + \ingroup Compression + \brief This function compresses the given input data using Huffman + coding with extended parameters. This is similar to wc_Compress but + allows specification of compression flags and window bits for more + control over the compression process. + + \return On successfully compressing the input data, returns the + number of bytes stored in the output buffer + \return COMPRESS_INIT_E Returned if there is an error initializing + the stream for compression + \return COMPRESS_E Returned if an error occurs during compression + + \param out pointer to the output buffer in which to store the + compressed data + \param outSz size available in the output buffer for storage + \param in pointer to the buffer containing the message to compress + \param inSz size of the input message to compress + \param flags flags to control how compression operates + \param windowBits the base two logarithm of the window size (8..15) + + _Example_ + \code + byte message[] = { // initialize text to compress }; + byte compressed[(sizeof(message) + sizeof(message) * .001 + 12)]; + word32 flags = 0; + word32 windowBits = 15; // 32KB window + + int ret = wc_Compress_ex(compressed, sizeof(compressed), message, + sizeof(message), flags, windowBits); + if (ret < 0) { + // error compressing data + } + \endcode + + \sa wc_Compress + \sa wc_DeCompress_ex +*/ +int wc_Compress_ex(byte* out, word32 outSz, const byte* in, word32 inSz, + word32 flags, word32 windowBits); + +/*! + \ingroup Compression + \brief This function decompresses the given compressed data using + Huffman coding with extended parameters. This is similar to + wc_DeCompress but allows specification of window bits for more + control over the decompression process. + + \return On successfully decompressing the input data, returns the + number of bytes stored in the output buffer + \return COMPRESS_INIT_E Returned if there is an error initializing + the stream for decompression + \return COMPRESS_E Returned if an error occurs during decompression + + \param out pointer to the output buffer in which to store the + decompressed data + \param outSz size available in the output buffer for storage + \param in pointer to the buffer containing the message to decompress + \param inSz size of the input message to decompress + \param windowBits the base two logarithm of the window size (8..15) + + _Example_ + \code + byte compressed[] = { // initialize compressed message }; + byte decompressed[MAX_MESSAGE_SIZE]; + int windowBits = 15; + + int ret = wc_DeCompress_ex(decompressed, sizeof(decompressed), + compressed, sizeof(compressed), + windowBits); + if (ret < 0) { + // error decompressing data + } + \endcode + + \sa wc_DeCompress + \sa wc_Compress_ex +*/ +int wc_DeCompress_ex(byte* out, word32 outSz, const byte* in, word32 inSz, + int windowBits); + +/*! + \ingroup Compression + \brief This function decompresses the given compressed data using + Huffman coding with dynamic memory allocation. The output buffer is + allocated dynamically and the caller is responsible for freeing it. + + \return On successfully decompressing the input data, returns the + number of bytes stored in the output buffer + \return COMPRESS_INIT_E Returned if there is an error initializing + the stream for decompression + \return COMPRESS_E Returned if an error occurs during decompression + \return MEMORY_E Returned if memory allocation fails + + \param out pointer to pointer that will be set to the allocated + output buffer + \param max maximum size to allocate for output buffer + \param memoryType type of memory to allocate (DYNAMIC_TYPE_TMP_BUFFER) + \param in pointer to the buffer containing the message to decompress + \param inSz size of the input message to decompress + \param windowBits the base two logarithm of the window size (8..15) + \param heap heap hint for memory allocation (can be NULL) + + _Example_ + \code + byte compressed[] = { // initialize compressed message }; + byte* decompressed = NULL; + int max = 1024 * 1024; // 1MB max + + int ret = wc_DeCompressDynamic(&decompressed, max, + DYNAMIC_TYPE_TMP_BUFFER, compressed, + sizeof(compressed), 15, NULL); + if (ret < 0) { + // error decompressing data + } + else { + // use decompressed data + XFREE(decompressed, NULL, DYNAMIC_TYPE_TMP_BUFFER); + } + \endcode + + \sa wc_DeCompress + \sa wc_DeCompress_ex +*/ +int wc_DeCompressDynamic(byte** out, int max, int memoryType, + const byte* in, word32 inSz, int windowBits, + void* heap); diff --git a/doc/dox_comments/header_files/cryptocb.h b/doc/dox_comments/header_files/cryptocb.h index 35cc88ef2..145d8c9ff 100644 --- a/doc/dox_comments/header_files/cryptocb.h +++ b/doc/dox_comments/header_files/cryptocb.h @@ -109,3 +109,74 @@ int wc_CryptoCb_RegisterDevice(int devId, CryptoDevCallbackFunc cb, void* ctx); \sa wolfSSL_CTX_SetDevId */ void wc_CryptoCb_UnRegisterDevice(int devId); + +/*! + \ingroup CryptoCb + \brief This function returns the default device ID for crypto + callbacks. This is useful when you want to get the device ID that + was set as the default for the library. + + \return The default device ID, or INVALID_DEVID if no default is set. + + _Example_ + \code + int devId = wc_CryptoCb_DefaultDevID(); + if (devId != INVALID_DEVID) { + // default device ID is set + } + \endcode + + \sa wc_CryptoCb_RegisterDevice + \sa wc_CryptoCb_UnRegisterDevice +*/ +int wc_CryptoCb_DefaultDevID(void); + +/*! + \ingroup CryptoCb + \brief This function sets a callback for finding crypto devices. + The callback is invoked when a device ID needs to be resolved to + a device context. This is useful for dynamic device management. + + \return none No returns. + + \param cb callback function with prototype: + typedef void* (*CryptoDevCallbackFind)(int devId); + + _Example_ + \code + void* myDeviceFindCb(int devId) { + // lookup device context by ID + return deviceContext; + } + + wc_CryptoCb_SetDeviceFindCb(myDeviceFindCb); + \endcode + + \sa wc_CryptoCb_RegisterDevice +*/ +void wc_CryptoCb_SetDeviceFindCb(CryptoDevCallbackFind cb); + +/*! + \ingroup CryptoCb + \brief This function converts a wc_CryptoInfo structure to a + human-readable string for debugging purposes. The string is printed + to stdout and describes the cryptographic operation being performed. + + \return none No returns. + + \param info pointer to the wc_CryptoInfo structure to convert + + _Example_ + \code + int myCryptoCb(int devId, wc_CryptoInfo* info, void* ctx) { + // print debug info about the operation + wc_CryptoCb_InfoString(info); + + // handle the operation + return CRYPTOCB_UNAVAILABLE; + } + \endcode + + \sa wc_CryptoCb_RegisterDevice +*/ +void wc_CryptoCb_InfoString(wc_CryptoInfo* info); diff --git a/doc/dox_comments/header_files/curve25519.h b/doc/dox_comments/header_files/curve25519.h index 1c12300bc..a6458dafc 100644 --- a/doc/dox_comments/header_files/curve25519.h +++ b/doc/dox_comments/header_files/curve25519.h @@ -769,3 +769,326 @@ int wc_curve25519_export_key_raw_ex(curve25519_key* key, */ int wc_curve25519_size(curve25519_key* key); + +/*! + \ingroup Curve25519 + \brief This function generates a Curve25519 public key from a given + private key. This is a lower-level function that operates directly + on byte buffers rather than curve25519_key structures. + + \return 0 On successfully generating the public key + \return ECC_BAD_ARG_E If the key sizes are invalid + \return BAD_FUNC_ARG If any input parameters are NULL + + \param public_size Size of the public key buffer (must be 32) + \param pub Pointer to buffer to store the public key + \param private_size Size of the private key (must be 32) + \param priv Pointer to buffer containing the private key + + _Example_ + \code + byte priv[CURVE25519_KEYSIZE]; + byte pub[CURVE25519_KEYSIZE]; + + // initialize priv with private key + int ret = wc_curve25519_make_pub(sizeof(pub), pub, sizeof(priv), + priv); + if (ret != 0) { + // error generating public key + } + \endcode + + \sa wc_curve25519_make_key + \sa wc_curve25519_make_pub_blind +*/ +int wc_curve25519_make_pub(int public_size, byte* pub, int private_size, + const byte* priv); + +/*! + \ingroup Curve25519 + \brief This function generates a Curve25519 public key from a given + private key with blinding to resist side-channel attacks. This adds + randomization to the scalar multiplication operation. + + \return 0 On successfully generating the public key + \return ECC_BAD_ARG_E If the key sizes are invalid + \return BAD_FUNC_ARG If any input parameters are NULL + + \param public_size Size of the public key buffer (must be 32) + \param pub Pointer to buffer to store the public key + \param private_size Size of the private key (must be 32) + \param priv Pointer to buffer containing the private key + \param rng Pointer to initialized RNG for blinding + + _Example_ + \code + WC_RNG rng; + byte priv[CURVE25519_KEYSIZE]; + byte pub[CURVE25519_KEYSIZE]; + + wc_InitRng(&rng); + // initialize priv with private key + int ret = wc_curve25519_make_pub_blind(sizeof(pub), pub, + sizeof(priv), priv, &rng); + if (ret != 0) { + // error generating public key + } + \endcode + + \sa wc_curve25519_make_pub + \sa wc_curve25519_generic_blind +*/ +int wc_curve25519_make_pub_blind(int public_size, byte* pub, + int private_size, const byte* priv, + WC_RNG* rng); + +/*! + \ingroup Curve25519 + \brief This function performs a generic Curve25519 scalar + multiplication with a custom basepoint. This allows computing + scalar * basepoint for any basepoint, not just the standard + generator. + + \return 0 On successfully computing the result + \return ECC_BAD_ARG_E If the sizes are invalid + \return BAD_FUNC_ARG If any input parameters are NULL + + \param public_size Size of the output buffer (must be 32) + \param pub Pointer to buffer to store the result + \param private_size Size of the scalar (must be 32) + \param priv Pointer to buffer containing the scalar + \param basepoint_size Size of the basepoint (must be 32) + \param basepoint Pointer to buffer containing the basepoint + + _Example_ + \code + byte scalar[CURVE25519_KEYSIZE]; + byte basepoint[CURVE25519_KEYSIZE]; + byte result[CURVE25519_KEYSIZE]; + + // initialize scalar and basepoint + int ret = wc_curve25519_generic(sizeof(result), result, + sizeof(scalar), scalar, + sizeof(basepoint), basepoint); + if (ret != 0) { + // error computing result + } + \endcode + + \sa wc_curve25519_shared_secret + \sa wc_curve25519_generic_blind +*/ +int wc_curve25519_generic(int public_size, byte* pub, int private_size, + const byte* priv, int basepoint_size, + const byte* basepoint); + +/*! + \ingroup Curve25519 + \brief This function performs a generic Curve25519 scalar + multiplication with a custom basepoint and blinding to resist + side-channel attacks. + + \return 0 On successfully computing the result + \return ECC_BAD_ARG_E If the sizes are invalid + \return BAD_FUNC_ARG If any input parameters are NULL + + \param public_size Size of the output buffer (must be 32) + \param pub Pointer to buffer to store the result + \param private_size Size of the scalar (must be 32) + \param priv Pointer to buffer containing the scalar + \param basepoint_size Size of the basepoint (must be 32) + \param basepoint Pointer to buffer containing the basepoint + \param rng Pointer to initialized RNG for blinding + + _Example_ + \code + WC_RNG rng; + byte scalar[CURVE25519_KEYSIZE]; + byte basepoint[CURVE25519_KEYSIZE]; + byte result[CURVE25519_KEYSIZE]; + + wc_InitRng(&rng); + // initialize scalar and basepoint + int ret = wc_curve25519_generic_blind(sizeof(result), result, + sizeof(scalar), scalar, + sizeof(basepoint), basepoint, + &rng); + \endcode + + \sa wc_curve25519_generic + \sa wc_curve25519_make_pub_blind +*/ +int wc_curve25519_generic_blind(int public_size, byte* pub, + int private_size, const byte* priv, + int basepoint_size, const byte* basepoint, + WC_RNG* rng); + +/*! + \ingroup Curve25519 + \brief This function generates a Curve25519 private key using the + given random number generator. This is a lower-level function that + generates only the private key bytes. + + \return 0 On successfully generating the private key + \return ECC_BAD_ARG_E If keysize is invalid + \return BAD_FUNC_ARG If any input parameters are NULL + \return RNG_FAILURE_E If random number generation fails + + \param rng Pointer to initialized RNG + \param keysize Size of the key to generate (must be 32) + \param priv Pointer to buffer to store the private key + + _Example_ + \code + WC_RNG rng; + byte priv[CURVE25519_KEYSIZE]; + + wc_InitRng(&rng); + int ret = wc_curve25519_make_priv(&rng, sizeof(priv), priv); + if (ret != 0) { + // error generating private key + } + \endcode + + \sa wc_curve25519_make_key + \sa wc_curve25519_make_pub +*/ +int wc_curve25519_make_priv(WC_RNG* rng, int keysize, byte* priv); + +/*! + \ingroup Curve25519 + \brief This function initializes a Curve25519 key with extended + parameters, allowing specification of custom heap and device ID + for hardware acceleration. + + \return 0 On successfully initializing the key + \return BAD_FUNC_ARG If key is NULL + + \param key Pointer to the curve25519_key structure to initialize + \param heap Pointer to heap hint for memory allocation (can be + NULL) + \param devId Device ID for hardware acceleration (use + INVALID_DEVID for software only) + + _Example_ + \code + curve25519_key key; + void* heap = NULL; + int devId = INVALID_DEVID; + + int ret = wc_curve25519_init_ex(&key, heap, devId); + if (ret != 0) { + // error initializing key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_free +*/ +int wc_curve25519_init_ex(curve25519_key* key, void* heap, int devId); + +/*! + \ingroup Curve25519 + \brief This function sets the RNG to be used with a Curve25519 + key. This is useful for operations that require randomness such + as blinded scalar multiplication. + + \return 0 On successfully setting the RNG + \return BAD_FUNC_ARG If key or rng is NULL + + \param key Pointer to the curve25519_key structure + \param rng Pointer to initialized RNG + + _Example_ + \code + WC_RNG rng; + curve25519_key key; + + wc_InitRng(&rng); + wc_curve25519_init(&key); + int ret = wc_curve25519_set_rng(&key, &rng); + if (ret != 0) { + // error setting RNG + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_make_key +*/ +int wc_curve25519_set_rng(curve25519_key* key, WC_RNG* rng); + +/*! + \ingroup Curve25519 + \brief This function allocates and initializes a new Curve25519 + key structure with extended parameters. The caller is responsible + for freeing the key with wc_curve25519_delete. These New/Delete + functions are exposed to support allocation of the structure using + dynamic memory to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return Pointer to newly allocated curve25519_key on success + \return NULL on failure + + \param heap Pointer to heap hint for memory allocation (can be + NULL) + \param devId Device ID for hardware acceleration (use + INVALID_DEVID for software only) + \param result_code Pointer to store result code (0 on success) + + _Example_ + \code + int ret; + curve25519_key* key; + + key = wc_curve25519_new(NULL, INVALID_DEVID, &ret); + if (key == NULL || ret != 0) { + // error allocating key + } + // use key + wc_curve25519_delete(key, &key); + \endcode + + \sa wc_curve25519_delete + \sa wc_curve25519_init_ex +*/ +curve25519_key* wc_curve25519_new(void* heap, int devId, + int *result_code); + +/*! + \ingroup Curve25519 + \brief This function frees a Curve25519 key structure that was + allocated with wc_curve25519_new and sets the pointer to NULL. + These New/Delete functions are exposed to support allocation of the + structure using dynamic memory to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return 0 On successfully freeing the key + \return BAD_FUNC_ARG If key or key_p is NULL + + \param key Pointer to the curve25519_key structure to free + \param key_p Pointer to the key pointer (will be set to NULL) + + _Example_ + \code + int ret; + curve25519_key* key; + + key = wc_curve25519_new(NULL, INVALID_DEVID, &ret); + // use key + ret = wc_curve25519_delete(key, &key); + if (ret != 0) { + // error freeing key + } + // key is now NULL + \endcode + + \sa wc_curve25519_new + \sa wc_curve25519_free +*/ +int wc_curve25519_delete(curve25519_key* key, curve25519_key** key_p); diff --git a/doc/dox_comments/header_files/curve448.h b/doc/dox_comments/header_files/curve448.h index 8e0e125a0..23ff7253c 100644 --- a/doc/dox_comments/header_files/curve448.h +++ b/doc/dox_comments/header_files/curve448.h @@ -766,3 +766,37 @@ int wc_curve448_export_key_raw_ex(curve448_key* key, */ int wc_curve448_size(curve448_key* key); + +/*! + \ingroup Curve448 + \brief This function generates a Curve448 public key from a given + private key. It computes the public key by performing scalar + multiplication of the base point with the private key. + + \return 0 On success. + \return ECC_BAD_ARG_E If public_size is not CURVE448_PUB_KEY_SIZE or + if private_size is not CURVE448_KEY_SIZE. + \return BAD_FUNC_ARG If pub or priv is NULL. + + \param public_size size of the public key buffer (must be 56 bytes) + \param pub pointer to buffer to store the generated public key + \param private_size size of the private key (must be 56 bytes) + \param priv pointer to the private key buffer + + _Example_ + \code + byte priv[CURVE448_KEY_SIZE] = { }; // private key + byte pub[CURVE448_PUB_KEY_SIZE]; + + int ret = wc_curve448_make_pub(CURVE448_PUB_KEY_SIZE, pub, + CURVE448_KEY_SIZE, priv); + if (ret != 0) { + // error generating public key + } + \endcode + + \sa wc_curve448_make_key + \sa wc_curve448_import_private +*/ +int wc_curve448_make_pub(int public_size, byte* pub, int private_size, + const byte* priv); diff --git a/doc/dox_comments/header_files/des3.h b/doc/dox_comments/header_files/des3.h index ded1a0406..9b071ad75 100644 --- a/doc/dox_comments/header_files/des3.h +++ b/doc/dox_comments/header_files/des3.h @@ -330,3 +330,124 @@ int wc_Des3_CbcEncrypt(Des3* des, byte* out, */ int wc_Des3_CbcDecrypt(Des3* des, byte* out, const byte* in,word32 sz); + +/*! + \ingroup 3DES + \brief This function decrypts the input ciphertext and stores the + resulting plaintext in the output buffer. It uses DES encryption + with Electronic Codebook (ECB) mode. Warning: In nearly all use + cases ECB mode is considered to be less secure. Please avoid using + ECB APIs directly whenever possible. + + \return 0 On successfully decrypting the given ciphertext + + \param des pointer to the Des structure to use for decryption + \param out pointer to the buffer in which to store the decrypted + plaintext + \param in pointer to the input buffer containing the ciphertext + \param sz length of the ciphertext to decrypt + + _Example_ + \code + Des dec; + byte cipher[]; // ciphertext to decrypt + byte plain[sizeof(cipher)]; + + wc_Des_SetKey(&dec, key, iv, DES_DECRYPTION); + if (wc_Des_EcbDecrypt(&dec, plain, cipher, sizeof(cipher)) != 0) { + // error decrypting message + } + \endcode + + \sa wc_Des_SetKey + \sa wc_Des_EcbEncrypt +*/ +int wc_Des_EcbDecrypt(Des* des, byte* out, const byte* in, word32 sz); + +/*! + \ingroup 3DES + \brief This function decrypts the input ciphertext and stores the + resulting plaintext in the output buffer. It uses Triple DES (3DES) + encryption with Electronic Codebook (ECB) mode. Warning: In nearly + all use cases ECB mode is considered to be less secure. Please + avoid using ECB APIs directly whenever possible. + + \return 0 On successfully decrypting the given ciphertext + + \param des pointer to the Des3 structure to use for decryption + \param out pointer to the buffer in which to store the decrypted + plaintext + \param in pointer to the input buffer containing the ciphertext + \param sz length of the ciphertext to decrypt + + _Example_ + \code + Des3 dec; + byte cipher[]; // ciphertext to decrypt + byte plain[sizeof(cipher)]; + + wc_Des3_SetKey(&dec, key, iv, DES_DECRYPTION); + if (wc_Des3_EcbDecrypt(&dec, plain, cipher, sizeof(cipher)) != 0) { + // error decrypting message + } + \endcode + + \sa wc_Des3_SetKey + \sa wc_Des3_EcbEncrypt +*/ +int wc_Des3_EcbDecrypt(Des3* des, byte* out, const byte* in, word32 sz); + +/*! + \ingroup 3DES + \brief This function initializes a Des3 structure for use with + hardware acceleration and custom memory management. This is an + extended version of the standard initialization that allows + specification of heap hints and device IDs. + + \return 0 On successfully initializing the Des3 structure + \return BAD_FUNC_ARG If des3 is NULL + + \param des3 pointer to the Des3 structure to initialize + \param heap pointer to heap hint for memory allocation (can be NULL) + \param devId device ID for hardware acceleration (use INVALID_DEVID + for software only) + + _Example_ + \code + Des3 des; + void* heap = NULL; + int devId = INVALID_DEVID; + + if (wc_Des3Init(&des, heap, devId) != 0) { + // error initializing Des3 structure + } + \endcode + + \sa wc_Des3_SetKey + \sa wc_Des3Free +*/ +int wc_Des3Init(Des3* des3, void* heap, int devId); + +/*! + \ingroup 3DES + \brief This function frees a Des3 structure and releases any + resources allocated for it. This should be called when finished + using the Des3 structure to prevent memory leaks. + + \return none No returns. + + \param des3 pointer to the Des3 structure to free + + _Example_ + \code + Des3 des; + wc_Des3Init(&des, NULL, INVALID_DEVID); + wc_Des3_SetKey(&des, key, iv, DES_ENCRYPTION); + // use des for encryption/decryption + wc_Des3Free(&des); + \endcode + + \sa wc_Des3Init + \sa wc_Des3_SetKey +*/ +void wc_Des3Free(Des3* des3); diff --git a/doc/dox_comments/header_files/dh.h b/doc/dox_comments/header_files/dh.h index d2a3868c7..a7caf644a 100644 --- a/doc/dox_comments/header_files/dh.h +++ b/doc/dox_comments/header_files/dh.h @@ -274,9 +274,348 @@ int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p, /*! \ingroup Diffie-Hellman + \brief Encodes DH parameters to DER format for OpenSSL compatibility. - \brief This function returns ... and requires that HAVE_FFDHE_2048 be - defined. + \return Length of DER encoding on success + \return Negative on error + + \param dh DH parameters to encode + \param out Output buffer pointer (if *out is NULL, allocates buffer) + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + unsigned char* der = NULL; + int derSz = wolfSSL_i2d_DHparams(dh, &der); + if (derSz > 0) { + // use der buffer + XFREE(der, NULL, DYNAMIC_TYPE_OPENSSL); + } + \endcode + + \sa wolfSSL_DH_new +*/ +int wolfSSL_i2d_DHparams(const WOLFSSL_DH *dh, unsigned char **out); + +/*! + \ingroup Diffie-Hellman + \brief Allocates and initializes a new DH structure for OpenSSL + compatibility. + + \return Pointer to WOLFSSL_DH on success + \return NULL on failure + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + if (dh == NULL) { + // error allocating DH + } + // use dh + wolfSSL_DH_free(dh); + \endcode + + \sa wolfSSL_DH_free + \sa wolfSSL_DH_generate_key +*/ +WOLFSSL_DH* wolfSSL_DH_new(void); + +/*! + \ingroup Diffie-Hellman + \brief Creates a new DH structure with named group parameters. + + \return Pointer to WOLFSSL_DH on success + \return NULL on failure + + \param nid Named group identifier (e.g., NID_ffdhe2048) + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new_by_nid(NID_ffdhe2048); + if (dh == NULL) { + // error creating DH with named group + } + \endcode + + \sa wolfSSL_DH_new +*/ +WOLFSSL_DH* wolfSSL_DH_new_by_nid(int nid); + +/*! + \ingroup Diffie-Hellman + \brief Frees a DH structure. + + \param dh DH structure to free + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + // use dh + wolfSSL_DH_free(dh); + \endcode + + \sa wolfSSL_DH_new +*/ +void wolfSSL_DH_free(WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Duplicates a DH structure. + + \return Pointer to new WOLFSSL_DH on success + \return NULL on failure + + \param dh DH structure to duplicate + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + WOLFSSL_DH* dhCopy = wolfSSL_DH_dup(dh); + \endcode + + \sa wolfSSL_DH_new +*/ +WOLFSSL_DH* wolfSSL_DH_dup(WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Increments reference count for DH structure. + + \return 1 on success + \return 0 on failure + + \param dh DH structure to increment reference + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + int ret = wolfSSL_DH_up_ref(dh); + \endcode + + \sa wolfSSL_DH_free +*/ +int wolfSSL_DH_up_ref(WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Validates DH parameters. + + \return 1 on success + \return 0 on failure + + \param dh DH parameters to check + \param codes Output for validation error codes + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + int codes; + int ret = wolfSSL_DH_check(dh, &codes); + if (ret != 1 || codes != 0) { + // validation failed + } + \endcode + + \sa wolfSSL_DH_generate_key +*/ +int wolfSSL_DH_check(const WOLFSSL_DH *dh, int *codes); + +/*! + \ingroup Diffie-Hellman + \brief Returns size of DH key in bytes. + + \return Key size in bytes on success + \return -1 on failure + + \param dh DH structure + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + int size = wolfSSL_DH_size(dh); + \endcode + + \sa wolfSSL_DH_new +*/ +int wolfSSL_DH_size(WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Generates DH public/private key pair. + + \return 1 on success + \return 0 on failure + + \param dh DH structure with parameters set + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + // set p and g parameters + int ret = wolfSSL_DH_generate_key(dh); + if (ret != 1) { + // key generation failed + } + \endcode + + \sa wolfSSL_DH_compute_key +*/ +int wolfSSL_DH_generate_key(WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Computes shared secret from peer's public key. + + \return Length of shared secret on success + \return -1 on failure + + \param key Output buffer for shared secret + \param pub Peer's public key + \param dh DH structure with private key + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + wolfSSL_DH_generate_key(dh); + byte secret[256]; + WOLFSSL_BIGNUM* peerPub = NULL; // peer's public key + int secretSz = wolfSSL_DH_compute_key(secret, peerPub, dh); + \endcode + + \sa wolfSSL_DH_generate_key +*/ +int wolfSSL_DH_compute_key(unsigned char* key, + const WOLFSSL_BIGNUM* pub, WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Computes shared secret with zero-padding to DH size. + + \return Length of shared secret on success + \return -1 on failure + + \param key Output buffer for shared secret + \param otherPub Peer's public key + \param dh DH structure with private key + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + wolfSSL_DH_generate_key(dh); + byte secret[256]; + WOLFSSL_BIGNUM* peerPub = NULL; + int secretSz = wolfSSL_DH_compute_key_padded(secret, peerPub, dh); + \endcode + + \sa wolfSSL_DH_compute_key +*/ +int wolfSSL_DH_compute_key_padded(unsigned char* key, + const WOLFSSL_BIGNUM* otherPub, + WOLFSSL_DH* dh); + +/*! + \ingroup Diffie-Hellman + \brief Loads DH parameters from DER buffer. + + \return WOLFSSL_SUCCESS on success + \return WOLFSSL_FAILURE on failure + + \param dh DH structure to load into + \param derBuf DER-encoded DH parameters + \param derSz Size of DER buffer + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + byte derBuf[256]; + int ret = wolfSSL_DH_LoadDer(dh, derBuf, sizeof(derBuf)); + \endcode + + \sa wolfSSL_DH_new +*/ +int wolfSSL_DH_LoadDer(WOLFSSL_DH* dh, const unsigned char* derBuf, + int derSz); + +/*! + \ingroup Diffie-Hellman + \brief Sets optional private key length. + + \return 1 on success + \return 0 on failure + + \param dh DH structure + \param len Private key length in bits + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + int ret = wolfSSL_DH_set_length(dh, 256); + \endcode + + \sa wolfSSL_DH_generate_key +*/ +int wolfSSL_DH_set_length(WOLFSSL_DH* dh, long len); + +/*! + \ingroup Diffie-Hellman + \brief Sets DH parameters p, q, and g. + + \return 1 on success + \return 0 on failure + + \param dh DH structure + \param p Prime modulus (takes ownership) + \param q Subgroup order (takes ownership, can be NULL) + \param g Generator (takes ownership) + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_new(); + WOLFSSL_BIGNUM *p = wolfSSL_BN_new(); + WOLFSSL_BIGNUM *g = wolfSSL_BN_new(); + // set p and g values + int ret = wolfSSL_DH_set0_pqg(dh, p, NULL, g); + \endcode + + \sa wolfSSL_DH_generate_key +*/ +int wolfSSL_DH_set0_pqg(WOLFSSL_DH *dh, WOLFSSL_BIGNUM *p, + WOLFSSL_BIGNUM *q, WOLFSSL_BIGNUM *g); + +/*! + \ingroup Diffie-Hellman + \brief Returns DH parameters for 2048-bit MODP group with 256-bit + subgroup. + + \return Pointer to WOLFSSL_DH on success + \return NULL on failure + + _Example_ + \code + WOLFSSL_DH* dh = wolfSSL_DH_get_2048_256(); + if (dh == NULL) { + // error getting standard group + } + \endcode + + \sa wolfSSL_DH_new_by_nid +*/ +WOLFSSL_DH* wolfSSL_DH_get_2048_256(void); + +/*! + \ingroup Diffie-Hellman + \brief Returns FFDHE 2048-bit group parameters. + + \return Pointer to DhParams structure + \return NULL if not compiled with HAVE_FFDHE_2048 + + _Example_ + \code + const DhParams* params = wc_Dh_ffdhe2048_Get(); + if (params != NULL) { + // use params + } + \endcode \sa wc_Dh_ffdhe3072_Get \sa wc_Dh_ffdhe4096_Get @@ -287,9 +626,18 @@ const DhParams* wc_Dh_ffdhe2048_Get(void); /*! \ingroup Diffie-Hellman + \brief Returns FFDHE 3072-bit group parameters. - \brief This function returns ... and requires that HAVE_FFDHE_3072 be - defined. + \return Pointer to DhParams structure + \return NULL if not compiled with HAVE_FFDHE_3072 + + _Example_ + \code + const DhParams* params = wc_Dh_ffdhe3072_Get(); + if (params != NULL) { + // use params + } + \endcode \sa wc_Dh_ffdhe2048_Get \sa wc_Dh_ffdhe4096_Get @@ -300,9 +648,18 @@ const DhParams* wc_Dh_ffdhe3072_Get(void); /*! \ingroup Diffie-Hellman + \brief Returns FFDHE 4096-bit group parameters. - \brief This function returns ... and requires that HAVE_FFDHE_4096 be - defined. + \return Pointer to DhParams structure + \return NULL if not compiled with HAVE_FFDHE_4096 + + _Example_ + \code + const DhParams* params = wc_Dh_ffdhe4096_Get(); + if (params != NULL) { + // use params + } + \endcode \sa wc_Dh_ffdhe2048_Get \sa wc_Dh_ffdhe3072_Get @@ -313,9 +670,18 @@ const DhParams* wc_Dh_ffdhe4096_Get(void); /*! \ingroup Diffie-Hellman + \brief Returns FFDHE 6144-bit group parameters. - \brief This function returns ... and requires that HAVE_FFDHE_6144 be - defined. + \return Pointer to DhParams structure + \return NULL if not compiled with HAVE_FFDHE_6144 + + _Example_ + \code + const DhParams* params = wc_Dh_ffdhe6144_Get(); + if (params != NULL) { + // use params + } + \endcode \sa wc_Dh_ffdhe2048_Get \sa wc_Dh_ffdhe3072_Get @@ -326,9 +692,18 @@ const DhParams* wc_Dh_ffdhe6144_Get(void); /*! \ingroup Diffie-Hellman + \brief Returns FFDHE 8192-bit group parameters. - \brief This function returns ... and requires that HAVE_FFDHE_8192 be - defined. + \return Pointer to DhParams structure + \return NULL if not compiled with HAVE_FFDHE_8192 + + _Example_ + \code + const DhParams* params = wc_Dh_ffdhe8192_Get(); + if (params != NULL) { + // use params + } + \endcode \sa wc_Dh_ffdhe2048_Get \sa wc_Dh_ffdhe3072_Get @@ -337,6 +712,291 @@ const DhParams* wc_Dh_ffdhe6144_Get(void); */ const DhParams* wc_Dh_ffdhe8192_Get(void); +/*! + \ingroup Diffie-Hellman + \brief Initializes DH key with heap hint and device ID. + + \return 0 on success + \return BAD_FUNC_ARG if key is NULL + + \param key DH key to initialize + \param heap Heap hint for memory allocation + \param devId Device ID for hardware acceleration + + _Example_ + \code + DhKey key; + int ret = wc_InitDhKey_ex(&key, NULL, INVALID_DEVID); + if (ret != 0) { + // error initializing key + } + \endcode + + \sa wc_InitDhKey + \sa wc_FreeDhKey +*/ +int wc_InitDhKey_ex(DhKey* key, void* heap, int devId); + +/*! + \ingroup Diffie-Hellman + \brief Computes shared secret with constant-time operations. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + \return BUFFER_E if output buffer too small + + \param key DH key with parameters + \param agree Output buffer for shared secret + \param agreeSz Input: buffer size, Output: secret size + \param priv Private key + \param privSz Private key size + \param otherPub Peer's public key + \param pubSz Peer's public key size + + _Example_ + \code + DhKey key; + byte agree[256], priv[256], pub[256]; + word32 agreeSz = sizeof(agree); + int ret = wc_DhAgree_ct(&key, agree, &agreeSz, priv, + sizeof(priv), pub, sizeof(pub)); + \endcode + + \sa wc_DhAgree +*/ +int wc_DhAgree_ct(DhKey* key, byte* agree, word32 *agreeSz, + const byte* priv, word32 privSz, + const byte* otherPub, word32 pubSz); + +/*! + \ingroup Diffie-Hellman + \brief Sets DH key to use named group parameters. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + + \param key DH key to configure + \param name Named group identifier + + _Example_ + \code + DhKey key; + wc_InitDhKey(&key); + int ret = wc_DhSetNamedKey(&key, WC_FFDHE_2048); + \endcode + + \sa wc_DhGetNamedKeyParamSize +*/ +int wc_DhSetNamedKey(DhKey* key, int name); + +/*! + \ingroup Diffie-Hellman + \brief Gets parameter sizes for named group. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + + \param name Named group identifier + \param p Output for prime size + \param g Output for generator size + \param q Output for subgroup order size + + _Example_ + \code + word32 pSz, gSz, qSz; + int ret = wc_DhGetNamedKeyParamSize(WC_FFDHE_2048, &pSz, &gSz, + &qSz); + \endcode + + \sa wc_DhSetNamedKey +*/ +int wc_DhGetNamedKeyParamSize(int name, word32* p, word32* g, + word32* q); + +/*! + \ingroup Diffie-Hellman + \brief Gets minimum key size for named group. + + \return Minimum key size in bits + \return 0 if invalid name + + \param name Named group identifier + + _Example_ + \code + word32 minSize = wc_DhGetNamedKeyMinSize(WC_FFDHE_2048); + \endcode + + \sa wc_DhSetNamedKey +*/ +word32 wc_DhGetNamedKeyMinSize(int name); + +/*! + \ingroup Diffie-Hellman + \brief Compares parameters against named group. + + \return 0 if parameters match named group + \return Non-zero if parameters don't match + + \param name Named group identifier + \param noQ 1 to skip q comparison + \param p Prime modulus + \param pSz Prime size + \param g Generator + \param gSz Generator size + \param q Subgroup order + \param qSz Subgroup order size + + _Example_ + \code + byte p[256], g[256]; + int ret = wc_DhCmpNamedKey(WC_FFDHE_2048, 1, p, sizeof(p), + g, sizeof(g), NULL, 0); + \endcode + + \sa wc_DhSetNamedKey +*/ +int wc_DhCmpNamedKey(int name, int noQ, const byte* p, word32 pSz, + const byte* g, word32 gSz, const byte* q, + word32 qSz); + +/*! + \ingroup Diffie-Hellman + \brief Copies named group parameters to buffers. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + \return BUFFER_E if buffers too small + + \param name Named group identifier + \param p Output buffer for prime + \param pSz Input: buffer size, Output: prime size + \param g Output buffer for generator + \param gSz Input: buffer size, Output: generator size + \param q Output buffer for subgroup order + \param qSz Input: buffer size, Output: subgroup order size + + _Example_ + \code + byte p[512], g[512], q[512]; + word32 pSz = sizeof(p), gSz = sizeof(g), qSz = sizeof(q); + int ret = wc_DhCopyNamedKey(WC_FFDHE_2048, p, &pSz, g, &gSz, + q, &qSz); + \endcode + + \sa wc_DhSetNamedKey +*/ +int wc_DhCopyNamedKey(int name, byte* p, word32* pSz, byte* g, + word32* gSz, byte* q, word32* qSz); + +/*! + \ingroup Diffie-Hellman + \brief Generates public key from private key. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + + \param key DH key with parameters set + \param priv Private key + \param privSz Private key size + \param pub Output buffer for public key + \param pubSz Input: buffer size, Output: public key size + + _Example_ + \code + DhKey key; + byte priv[256], pub[256]; + word32 pubSz = sizeof(pub); + int ret = wc_DhGeneratePublic(&key, priv, sizeof(priv), pub, + &pubSz); + \endcode + + \sa wc_DhGenerateKeyPair +*/ +int wc_DhGeneratePublic(DhKey* key, byte* priv, word32 privSz, + byte* pub, word32* pubSz); + +/*! + \ingroup Diffie-Hellman + \brief Imports private and/or public key into DH key. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + + \param key DH key to import into + \param priv Private key (can be NULL) + \param privSz Private key size + \param pub Public key (can be NULL) + \param pubSz Public key size + + _Example_ + \code + DhKey key; + byte priv[256], pub[256]; + int ret = wc_DhImportKeyPair(&key, priv, sizeof(priv), pub, + sizeof(pub)); + \endcode + + \sa wc_DhExportKeyPair +*/ +int wc_DhImportKeyPair(DhKey* key, const byte* priv, word32 privSz, + const byte* pub, word32 pubSz); + +/*! + \ingroup Diffie-Hellman + \brief Exports private and public key from DH key. + + \return 0 on success + \return BAD_FUNC_ARG if parameters are invalid + \return BUFFER_E if buffers too small + + \param key DH key to export from + \param priv Output buffer for private key + \param pPrivSz Input: buffer size, Output: private key size + \param pub Output buffer for public key + \param pPubSz Input: buffer size, Output: public key size + + _Example_ + \code + DhKey key; + byte priv[256], pub[256]; + word32 privSz = sizeof(priv), pubSz = sizeof(pub); + int ret = wc_DhExportKeyPair(&key, priv, &privSz, pub, &pubSz); + \endcode + + \sa wc_DhImportKeyPair +*/ +int wc_DhExportKeyPair(DhKey* key, byte* priv, word32* pPrivSz, + byte* pub, word32* pPubSz); + +/*! + \ingroup Diffie-Hellman + \brief Validates public key value. + + \return 0 if public key is valid + \return BAD_FUNC_ARG if parameters are invalid + \return MP_VAL if public key is invalid + + \param prime Prime modulus + \param primeSz Prime size + \param pub Public key to validate + \param pubSz Public key size + + _Example_ + \code + byte prime[256], pub[256]; + int ret = wc_DhCheckPubValue(prime, sizeof(prime), pub, + sizeof(pub)); + if (ret != 0) { + // invalid public key + } + \endcode + + \sa wc_DhCheckPubKey +*/ +int wc_DhCheckPubValue(const byte* prime, word32 primeSz, + const byte* pub, word32 pubSz); + /*! \ingroup Diffie-Hellman diff --git a/doc/dox_comments/header_files/dsa.h b/doc/dox_comments/header_files/dsa.h index d66ccbcb5..f60200265 100644 --- a/doc/dox_comments/header_files/dsa.h +++ b/doc/dox_comments/header_files/dsa.h @@ -340,3 +340,298 @@ int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa); \sa wc_InitDsaKey */ int wc_MakeDsaParameters(WC_RNG *rng, int modulus_size, DsaKey *dsa); +/*! + \ingroup DSA + \brief Initializes DSA key with heap hint. + + \return 0 on success + \return negative on failure + + \param key DSA key structure + \param h Heap hint for memory allocation + + _Example_ + \code + DsaKey key; + int ret = wc_InitDsaKey_h(&key, NULL); + \endcode + + \sa wc_InitDsaKey +*/ +int wc_InitDsaKey_h(DsaKey* key, void* h); + +/*! + \ingroup DSA + \brief Signs digest with extended parameters. + + \return 0 on success + \return negative on failure + + \param digest Digest to sign + \param digestSz Digest size + \param out Output signature buffer + \param key DSA key + \param rng Random number generator + + _Example_ + \code + byte digest[WC_SHA_DIGEST_SIZE]; + byte sig[40]; + WC_RNG rng; + int ret = wc_DsaSign_ex(digest, sizeof(digest), sig, &key, + &rng); + \endcode + + \sa wc_DsaSign +*/ +int wc_DsaSign_ex(const byte* digest, word32 digestSz, byte* out, + DsaKey* key, WC_RNG* rng); + +/*! + \ingroup DSA + \brief Verifies signature with extended parameters. + + \return 0 on success + \return negative on failure + + \param digest Digest + \param digestSz Digest size + \param sig Signature buffer + \param key DSA key + \param answer Verification result + + _Example_ + \code + byte digest[WC_SHA_DIGEST_SIZE]; + byte sig[40]; + int answer; + int ret = wc_DsaVerify_ex(digest, sizeof(digest), sig, &key, + &answer); + \endcode + + \sa wc_DsaVerify +*/ +int wc_DsaVerify_ex(const byte* digest, word32 digestSz, + const byte* sig, DsaKey* key, int* answer); + +/*! + \ingroup DSA + \brief Sets DSA public key in output buffer. + + \return Size on success + \return negative on failure + + \param output Output buffer + \param key DSA key + \param outLen Output buffer length + \param with_header Include header flag + + _Example_ + \code + byte output[256]; + int ret = wc_SetDsaPublicKey(output, &key, sizeof(output), 1); + \endcode + + \sa wc_DsaKeyToPublicDer +*/ +int wc_SetDsaPublicKey(byte* output, DsaKey* key, int outLen, + int with_header); + +/*! + \ingroup DSA + \brief Converts DSA key to public DER format. + + \return Size on success + \return negative on failure + + \param key DSA key + \param output Output buffer + \param inLen Output buffer length + + _Example_ + \code + DsaKey key; + WC_RNG rng; + byte output[256]; + + // Initialize key and RNG + wc_InitDsaKey(&key); + wc_InitRng(&rng); + + // Generate DSA key or import existing key + wc_MakeDsaKey(&rng, &key); + + // Convert to public DER format + int ret = wc_DsaKeyToPublicDer(&key, output, sizeof(output)); + if (ret > 0) { + // output contains DER encoded public key of size ret + } + + wc_FreeDsaKey(&key); + wc_FreeRng(&rng); + \endcode + + \sa wc_SetDsaPublicKey +*/ +int wc_DsaKeyToPublicDer(DsaKey* key, byte* output, word32 inLen); + +/*! + \ingroup DSA + \brief Imports DSA parameters from raw format. The parameters p, q, and + g must be provided as ASCII hexadecimal strings (without 0x prefix). + These represent the DSA domain parameters: p is the prime modulus, q is + the prime divisor (subgroup order), and g is the generator. + + \return 0 on success + \return negative on failure + + \param dsa DSA key structure (must be initialized) + \param p P parameter as ASCII hex string (prime modulus) + \param q Q parameter as ASCII hex string (prime divisor/subgroup order) + \param g G parameter as ASCII hex string (generator) + + _Example_ + \code + DsaKey dsa; + wc_InitDsaKey(&dsa); + + // DSA parameters as ASCII hexadecimal strings (example values) + const char* pStr = "E0A67598CD1B763BC98C8ABB333E5DDA0CD3AA0E5E1F" + "B5BA8A7B4EABC10BA338FAE06DD4B90FDA70D7CF0CB0" + "C638BE3341BEC0AF8A7330A3307DED2299A0EE606DF0" + "35177A239C34A912C202AA5F83B9C4A7CF0235B5316B" + "FC6EFB9A248411258B30B839AF172440F32563056CB6" + "7A861158DDD90E6A894C72A5BBEF9E286C6B"; + const char* qStr = "E950511EAB424B9A19A2AEB4E159B7844C589C4F"; + const char* gStr = "D29D5121B0423C2769AB21843E5A3240FF19CACC792D" + "C6E7925E6D1A4E6E4E3D119A3D133C8D3C8C8C8C8C8C" + "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C" + "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C"; + + int ret = wc_DsaImportParamsRaw(&dsa, pStr, qStr, gStr); + if (ret == 0) { + // DSA parameters successfully imported + // Can now use dsa for key generation or signing + } + wc_FreeDsaKey(&dsa); + \endcode + + \sa wc_DsaImportParamsRawCheck + \sa wc_InitDsaKey +*/ +int wc_DsaImportParamsRaw(DsaKey* dsa, const char* p, const char* q, + const char* g); + +/*! + \ingroup DSA + \brief Imports DSA parameters from raw format with optional validation. + The parameters p, q, and g must be provided as ASCII hexadecimal strings + (without 0x prefix). The trusted parameter controls whether the prime p + is validated: when trusted=1, prime checking is skipped (use when + parameters come from a trusted source); when trusted=0, performs full + primality testing on p (recommended for untrusted sources). + + \return 0 on success + \return DH_CHECK_PUB_E if p fails primality test (when trusted=0) + \return negative on other failures + + \param dsa DSA key structure (must be initialized) + \param p P parameter as ASCII hex string (prime modulus) + \param q Q parameter as ASCII hex string (prime divisor/subgroup order) + \param g G parameter as ASCII hex string (generator) + \param trusted If 1, skip prime validation (trusted source); if 0, + perform full primality test on p + \param rng Random number generator (required when trusted=0 for + primality testing) + + _Example_ + \code + DsaKey dsa; + WC_RNG rng; + + // Initialize DSA key and RNG + wc_InitDsaKey(&dsa); + wc_InitRng(&rng); + + // DSA parameters as ASCII hexadecimal strings + const char* pStr = "E0A67598CD1B763BC98C8ABB333E5DDA0CD3AA0E5E1F" + "B5BA8A7B4EABC10BA338FAE06DD4B90FDA70D7CF0CB0" + "C638BE3341BEC0AF8A7330A3307DED2299A0EE606DF0" + "35177A239C34A912C202AA5F83B9C4A7CF0235B5316B" + "FC6EFB9A248411258B30B839AF172440F32563056CB6" + "7A861158DDD90E6A894C72A5BBEF9E286C6B"; + const char* qStr = "E950511EAB424B9A19A2AEB4E159B7844C589C4F"; + const char* gStr = "D29D5121B0423C2769AB21843E5A3240FF19CACC792D" + "C6E7925E6D1A4E6E4E3D119A3D133C8D3C8C8C8C8C8C" + "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C" + "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C"; + + // Import with validation (trusted=0 performs primality test on p) + int ret = wc_DsaImportParamsRawCheck(&dsa, pStr, qStr, gStr, 0, + &rng); + if (ret == 0) { + // Parameters imported and validated successfully + } + + wc_FreeDsaKey(&dsa); + wc_FreeRng(&rng); + \endcode + + \sa wc_DsaImportParamsRaw + \sa wc_InitDsaKey +*/ +int wc_DsaImportParamsRawCheck(DsaKey* dsa, const char* p, + const char* q, const char* g, int trusted, WC_RNG* rng); + +/*! + \ingroup DSA + \brief Exports DSA parameters to raw format. + + \return 0 on success + \return negative on failure + + \param dsa DSA key structure + \param p P parameter buffer + \param pSz P parameter size (in/out) + \param q Q parameter buffer + \param qSz Q parameter size (in/out) + \param g G parameter buffer + \param gSz G parameter size (in/out) + + _Example_ + \code + byte p[256], q[32], g[256]; + word32 pSz = sizeof(p), qSz = sizeof(q), gSz = sizeof(g); + int ret = wc_DsaExportParamsRaw(&dsa, p, &pSz, q, &qSz, g, + &gSz); + \endcode + + \sa wc_DsaImportParamsRaw +*/ +int wc_DsaExportParamsRaw(DsaKey* dsa, byte* p, word32* pSz, byte* q, + word32* qSz, byte* g, word32* gSz); + +/*! + \ingroup DSA + \brief Exports DSA key to raw format. + + \return 0 on success + \return negative on failure + + \param dsa DSA key structure + \param x Private key buffer + \param xSz Private key size (in/out) + \param y Public key buffer + \param ySz Public key size (in/out) + + _Example_ + \code + byte x[32], y[256]; + word32 xSz = sizeof(x), ySz = sizeof(y); + int ret = wc_DsaExportKeyRaw(&dsa, x, &xSz, y, &ySz); + \endcode + + \sa wc_DsaImportParamsRaw +*/ +int wc_DsaExportKeyRaw(DsaKey* dsa, byte* x, word32* xSz, byte* y, + word32* ySz); diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h index 5becaf5a9..bdcfdf50e 100644 --- a/doc/dox_comments/header_files/ecc.h +++ b/doc/dox_comments/header_files/ecc.h @@ -2143,3 +2143,1244 @@ int wc_ecc_set_nonblock(ecc_key *key, ecc_nb_ctx_t* ctx); \endcode */ int wc_ecc_set_curve(ecc_key *key, int keysize, int curve_id); + +/*! + \ingroup ECC + \brief Gets private key mp_int from ECC key. + + \return mp_int pointer on success + \return NULL on failure + + \param key ECC key structure + + _Example_ + \code + ecc_key key; + mp_int* priv = wc_ecc_key_get_priv(&key); + \endcode + + \sa wc_ecc_init +*/ +mp_int* wc_ecc_key_get_priv(ecc_key* key); + +/*! + \ingroup ECC + \brief Allocates and initializes new ECC key. + + \return ecc_key pointer on success + \return NULL on failure + + \param heap Heap hint for memory allocation + + _Example_ + \code + ecc_key* key = wc_ecc_key_new(NULL); + if (key != NULL) { + // use key + wc_ecc_key_free(key); + } + \endcode + + \sa wc_ecc_key_free +*/ +ecc_key* wc_ecc_key_new(void* heap); + +/*! + \ingroup ECC + \brief Returns number of supported ECC curve sets. + + \return Number of curve sets + + _Example_ + \code + size_t count = wc_ecc_get_sets_count(); + \endcode + + \sa wc_ecc_get_curve_params +*/ +size_t wc_ecc_get_sets_count(void); + +/*! + \ingroup ECC + \brief Gets curve name from curve ID. + + \return Curve name string on success + \return NULL on failure + + \param curve_id Curve identifier + + _Example_ + \code + const char* name = wc_ecc_get_name(ECC_SECP256R1); + \endcode + + \sa wc_ecc_get_curve_id +*/ +const char* wc_ecc_get_name(int curve_id); + +/*! + \ingroup ECC + \brief Makes ECC key with extended options. + + \return 0 on success + \return negative on error + + \param rng Random number generator + \param keysize Key size in bytes + \param key ECC key structure + \param curve_id Curve identifier + \param flags Additional flags + + _Example_ + \code + WC_RNG rng; + ecc_key key; + int ret = wc_ecc_make_key_ex2(&rng, 32, &key, + ECC_SECP256R1, 0); + \endcode + + \sa wc_ecc_make_key_ex +*/ +int wc_ecc_make_key_ex2(WC_RNG* rng, int keysize, ecc_key* key, + int curve_id, int flags); + +/*! + \ingroup ECC + \brief Checks if point is on curve. + + \return 1 if point is on curve + \return 0 if not on curve + \return negative on error + + \param ecp ECC point + \param a Curve parameter a + \param b Curve parameter b + \param prime Curve prime + + _Example_ + \code + ecc_point* point; + mp_int a, b, prime; + int ret = wc_ecc_is_point(point, &a, &b, &prime); + \endcode + + \sa wc_ecc_point_is_on_curve +*/ +int wc_ecc_is_point(ecc_point* ecp, mp_int* a, mp_int* b, + mp_int* prime); + +/*! + \ingroup ECC + \brief Gets generator point for curve. + + \return 0 on success + \return negative on error + + \param ecp ECC point to store generator + \param curve_idx Curve index + + _Example_ + \code + ecc_point* gen = wc_ecc_new_point(); + int ret = wc_ecc_get_generator(gen, 0); + \endcode + + \sa wc_ecc_get_curve_params +*/ +int wc_ecc_get_generator(ecc_point* ecp, int curve_idx); + +/*! + \ingroup ECC + \brief Sets deterministic signing mode. + + \return 0 on success + \return negative on error + + \param key ECC key + \param flag Enable/disable flag + + _Example_ + \code + ecc_key key; + int ret = wc_ecc_set_deterministic(&key, 1); + \endcode + + \sa wc_ecc_set_deterministic_ex +*/ +int wc_ecc_set_deterministic(ecc_key* key, byte flag); + +/*! + \ingroup ECC + \brief Sets deterministic signing with hash type. + + \return 0 on success + \return negative on error + + \param key ECC key + \param flag Enable/disable flag + \param hashType Hash algorithm type + + _Example_ + \code + ecc_key key; + int ret = wc_ecc_set_deterministic_ex(&key, 1, WC_HASH_TYPE_SHA256); + \endcode + + \sa wc_ecc_set_deterministic +*/ +int wc_ecc_set_deterministic_ex(ecc_key* key, byte flag, + enum wc_HashType hashType); + +/*! + \ingroup ECC + \brief Generates deterministic k value for signing. + + \return 0 on success + \return negative on error + + \param hash Hash value + \param hashSz Hash size + \param hashType Hash algorithm type + \param priv Private key + \param k Output k value + \param order Curve order + \param heap Heap hint + + _Example_ + \code + byte hash[32]; + mp_int priv, k, order; + int ret = wc_ecc_gen_deterministic_k(hash, 32, + WC_HASH_TYPE_SHA256, + &priv, &k, &order, NULL); + \endcode + + \sa wc_ecc_sign_set_k +*/ +int wc_ecc_gen_deterministic_k(const byte* hash, word32 hashSz, + enum wc_HashType hashType, mp_int* priv, mp_int* k, + mp_int* order, void* heap); + +/*! + \ingroup ECC + \brief Sets k value for signing. + + \return 0 on success + \return negative on error + + \param k K value buffer + \param klen K value length + \param key ECC key + + _Example_ + \code + byte k[32]; + ecc_key key; + int ret = wc_ecc_sign_set_k(k, sizeof(k), &key); + \endcode + + \sa wc_ecc_gen_deterministic_k +*/ +int wc_ecc_sign_set_k(const byte* k, word32 klen, ecc_key* key); + +/*! + \ingroup ECC + \brief Initializes ECC key with ID. + + \note This API is only available when WOLF_PRIVATE_KEY_ID is defined, + which is set for PKCS11 support. + + \return 0 on success + \return negative on error + + \param key ECC key + \param id ID buffer + \param len ID length + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + ecc_key key; + unsigned char id[] = "mykey"; + int ret = wc_ecc_init_id(&key, id, sizeof(id), NULL, + INVALID_DEVID); + \endcode + + \sa wc_ecc_init_label +*/ +int wc_ecc_init_id(ecc_key* key, unsigned char* id, int len, + void* heap, int devId); + +/*! + \ingroup ECC + \brief Initializes ECC key with label. + + \note This API is only available when WOLF_PRIVATE_KEY_ID is defined, + which is set for PKCS11 support. + + \return 0 on success + \return negative on error + + \param key ECC key + \param label Label string + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + ecc_key key; + int ret = wc_ecc_init_label(&key, "mykey", NULL, + INVALID_DEVID); + \endcode + + \sa wc_ecc_init_id +*/ +int wc_ecc_init_label(ecc_key* key, const char* label, void* heap, + int devId); + +/*! + \ingroup ECC + \brief Sets flags on ECC key. + + \return 0 on success + \return negative on error + + \param key ECC key + \param flags Flags to set + + _Example_ + \code + ecc_key key; + int ret = wc_ecc_set_flags(&key, WC_ECC_FLAG_COFACTOR); + \endcode + + \sa wc_ecc_init +*/ +int wc_ecc_set_flags(ecc_key* key, word32 flags); + +/*! + \ingroup ECC + \brief Initializes fixed-point cache. + + \return none No returns + + _Example_ + \code + wc_ecc_fp_init(); + \endcode + + \sa wc_ecc_init +*/ +void wc_ecc_fp_init(void); + +/*! + \ingroup ECC + \brief Sets RNG for ECC key. + + \return 0 on success + \return negative on error + + \param key ECC key + \param rng Random number generator + + _Example_ + \code + ecc_key key; + WC_RNG rng; + int ret = wc_ecc_set_rng(&key, &rng); + \endcode + + \sa wc_ecc_make_key +*/ +int wc_ecc_set_rng(ecc_key* key, WC_RNG* rng); + +/*! + \ingroup ECC + \brief Gets curve index from curve ID. + + \return Curve index on success + \return negative on error + + \param curve_id Curve identifier + + _Example_ + \code + int idx = wc_ecc_get_curve_idx(ECC_SECP256R1); + \endcode + + \sa wc_ecc_get_curve_id +*/ +int wc_ecc_get_curve_idx(int curve_id); + +/*! + \ingroup ECC + \brief Gets curve ID from curve index. + + \return Curve ID on success + \return negative on error + + \param curve_idx Curve index + + _Example_ + \code + int id = wc_ecc_get_curve_id(0); + \endcode + + \sa wc_ecc_get_curve_idx +*/ +int wc_ecc_get_curve_id(int curve_idx); + +/*! + \ingroup ECC + \brief Gets curve size from curve ID. + + \return Key size in bytes on success + \return negative on error + + \param curve_id Curve identifier + + _Example_ + \code + int size = wc_ecc_get_curve_size_from_id(ECC_SECP256R1); + \endcode + + \sa wc_ecc_get_curve_id +*/ +int wc_ecc_get_curve_size_from_id(int curve_id); + +/*! + \ingroup ECC + \brief Gets curve index from curve name. + + \return Curve index on success + \return negative on error + + \param curveName Curve name string + + _Example_ + \code + int idx = wc_ecc_get_curve_idx_from_name("SECP256R1"); + \endcode + + \sa wc_ecc_get_name +*/ +int wc_ecc_get_curve_idx_from_name(const char* curveName); + +/*! + \ingroup ECC + \brief Gets curve size from curve name. + + \return Key size in bytes on success + \return negative on error + + \param curveName Curve name string + + _Example_ + \code + int size = wc_ecc_get_curve_size_from_name("SECP256R1"); + \endcode + + \sa wc_ecc_get_curve_idx_from_name +*/ +int wc_ecc_get_curve_size_from_name(const char* curveName); + +/*! + \ingroup ECC + \brief Gets curve ID from curve name. + + \return Curve ID on success + \return negative on error + + \param curveName Curve name string + + _Example_ + \code + int id = wc_ecc_get_curve_id_from_name("SECP256R1"); + \endcode + + \sa wc_ecc_get_name +*/ +int wc_ecc_get_curve_id_from_name(const char* curveName); + +/*! + \ingroup ECC + \brief Gets curve ID from curve parameters. + + \return Curve ID on success + \return negative on error + + \param fieldSize Field size + \param prime Prime modulus + \param primeSz Prime size + \param Af Curve parameter A + \param AfSz A size + \param Bf Curve parameter B + \param BfSz B size + \param order Curve order + \param orderSz Order size + \param Gx Generator X coordinate + \param GxSz Gx size + \param Gy Generator Y coordinate + \param GySz Gy size + \param cofactor Curve cofactor + + _Example_ + \code + int id = wc_ecc_get_curve_id_from_params(256, prime, 32, + Af, 32, Bf, 32, + order, 32, Gx, 32, + Gy, 32, 1); + \endcode + + \sa wc_ecc_get_curve_params +*/ +int wc_ecc_get_curve_id_from_params(int fieldSize, + const byte* prime, word32 primeSz, const byte* Af, word32 AfSz, + const byte* Bf, word32 BfSz, const byte* order, word32 orderSz, + const byte* Gx, word32 GxSz, const byte* Gy, word32 GySz, + int cofactor); + +/*! + \ingroup ECC + \brief Gets curve ID from domain parameters. + + \return Curve ID on success + \return negative on error + + \param dp Domain parameters + + _Example_ + \code + const ecc_set_type* dp; + int id = wc_ecc_get_curve_id_from_dp_params(dp); + \endcode + + \sa wc_ecc_get_curve_params +*/ +int wc_ecc_get_curve_id_from_dp_params(const ecc_set_type* dp); + +/*! + \ingroup ECC + \brief Gets curve ID from OID. + + \return Curve ID on success + \return negative on error + + \param oid OID buffer + \param len OID length + + _Example_ + \code + byte oid[] = {0x2A, 0x86, 0x48, 0xCE, 0x3D, 0x03, 0x01, 0x07}; + int id = wc_ecc_get_curve_id_from_oid(oid, sizeof(oid)); + \endcode + + \sa wc_ecc_get_oid +*/ +int wc_ecc_get_curve_id_from_oid(const byte* oid, word32 len); + +/*! + \ingroup ECC + \brief Gets curve parameters from curve index. + + \return ecc_set_type pointer on success + \return NULL on failure + + \param curve_idx Curve index + + _Example_ + \code + const ecc_set_type* params = wc_ecc_get_curve_params(0); + \endcode + + \sa wc_ecc_get_curve_idx +*/ +const ecc_set_type* wc_ecc_get_curve_params(int curve_idx); + +/*! + \ingroup ECC + \brief Allocates new ECC point. + + \return ecc_point pointer on success + \return NULL on failure + + _Example_ + \code + ecc_point* point = wc_ecc_new_point(); + if (point != NULL) { + // use point + wc_ecc_del_point(point); + } + \endcode + + \sa wc_ecc_del_point +*/ +ecc_point* wc_ecc_new_point(void); + +/*! + \ingroup ECC + \brief Allocates new ECC point with heap hint. + + \return ecc_point pointer on success + \return NULL on failure + + \param h Heap hint + + _Example_ + \code + ecc_point* point = wc_ecc_new_point_h(NULL); + if (point != NULL) { + // use point + wc_ecc_del_point_h(point, NULL); + } + \endcode + + \sa wc_ecc_del_point_h +*/ +ecc_point* wc_ecc_new_point_h(void* h); + +/*! + \ingroup ECC + \brief Frees ECC point with heap hint. + + \return none No returns + + \param p ECC point to free + \param h Heap hint + + _Example_ + \code + ecc_point* point = wc_ecc_new_point_h(NULL); + // use point + wc_ecc_del_point_h(point, NULL); + \endcode + + \sa wc_ecc_new_point_h +*/ +void wc_ecc_del_point_h(ecc_point* p, void* h); + +/*! + \ingroup ECC + \brief Securely zeros ECC point. + + \return none No returns + + \param p ECC point to zero + + _Example_ + \code + ecc_point* point; + wc_ecc_forcezero_point(point); + \endcode + + \sa wc_ecc_del_point +*/ +void wc_ecc_forcezero_point(ecc_point* p); + +/*! + \ingroup ECC + \brief Checks if point is on curve. + + \return 1 if on curve + \return 0 if not on curve + \return negative on error + + \param p ECC point + \param curve_idx Curve index + + _Example_ + \code + ecc_point* point; + int ret = wc_ecc_point_is_on_curve(point, 0); + \endcode + + \sa wc_ecc_is_point +*/ +int wc_ecc_point_is_on_curve(ecc_point *p, int curve_idx); + +/*! + \ingroup ECC + \brief Imports X9.63 format with curve ID. + + \return 0 on success + \return negative on error + + \param in Input buffer + \param inLen Input length + \param key ECC key + \param curve_id Curve identifier + + _Example_ + \code + byte x963[65]; + ecc_key key; + int ret = wc_ecc_import_x963_ex(x963, sizeof(x963), &key, + ECC_SECP256R1); + \endcode + + \sa wc_ecc_import_x963 +*/ +int wc_ecc_import_x963_ex(const byte* in, word32 inLen, + ecc_key* key, int curve_id); + +/*! + \ingroup ECC + \brief Imports private key with curve ID. + + \return 0 on success + \return negative on error + + \param priv Private key buffer + \param privSz Private key size + \param pub Public key buffer + \param pubSz Public key size + \param key ECC key + \param curve_id Curve identifier + + _Example_ + \code + byte priv[32], pub[65]; + ecc_key key; + int ret = wc_ecc_import_private_key_ex(priv, 32, pub, 65, + &key, ECC_SECP256R1); + \endcode + + \sa wc_ecc_import_private_key +*/ +int wc_ecc_import_private_key_ex(const byte* priv, word32 privSz, + const byte* pub, word32 pubSz, ecc_key* key, int curve_id); + +/*! + \ingroup ECC + \brief Converts raw r,s to signature. + + \return 0 on success + \return negative on error + + \param r R value buffer + \param rSz R value size + \param s S value buffer + \param sSz S value size + \param out Output signature buffer + \param outlen Output signature length + + _Example_ + \code + byte r[32], s[32], sig[72]; + word32 sigLen = sizeof(sig); + int ret = wc_ecc_rs_raw_to_sig(r, 32, s, 32, sig, &sigLen); + \endcode + + \sa wc_ecc_sig_to_rs +*/ +int wc_ecc_rs_raw_to_sig(const byte* r, word32 rSz, const byte* s, + word32 sSz, byte* out, word32* outlen); + +/*! + \ingroup ECC + \brief Converts signature to raw r,s. + + \return 0 on success + \return negative on error + + \param sig Signature buffer + \param sigLen Signature length + \param r R value buffer + \param rLen R value length + \param s S value buffer + \param sLen S value length + + _Example_ + \code + byte sig[72], r[32], s[32]; + word32 rLen = 32, sLen = 32; + int ret = wc_ecc_sig_to_rs(sig, 72, r, &rLen, s, &sLen); + \endcode + + \sa wc_ecc_rs_raw_to_sig +*/ +int wc_ecc_sig_to_rs(const byte* sig, word32 sigLen, byte* r, + word32* rLen, byte* s, word32* sLen); + +/*! + \ingroup ECC + \brief Imports raw key with curve ID. + + \return 0 on success + \return negative on error + + \param key ECC key + \param qx X coordinate string + \param qy Y coordinate string + \param d Private key string + \param curve_id Curve identifier + + _Example_ + \code + ecc_key key; + int ret = wc_ecc_import_raw_ex(&key, qxStr, qyStr, dStr, + ECC_SECP256R1); + \endcode + + \sa wc_ecc_import_raw +*/ +int wc_ecc_import_raw_ex(ecc_key* key, const char* qx, + const char* qy, const char* d, int curve_id); + +/*! + \ingroup ECC + \brief Imports unsigned key with curve ID. + + \return 0 on success + \return negative on error + + \param key ECC key + \param qx X coordinate buffer + \param qy Y coordinate buffer + \param d Private key buffer + \param curve_id Curve identifier + + _Example_ + \code + ecc_key key; + byte qx[32], qy[32], d[32]; + int ret = wc_ecc_import_unsigned(&key, qx, qy, d, + ECC_SECP256R1); + \endcode + + \sa wc_ecc_import_raw_ex +*/ +int wc_ecc_import_unsigned(ecc_key* key, const byte* qx, + const byte* qy, const byte* d, int curve_id); + +/*! + \ingroup ECC + \brief Exports key with encoding type. + + \return 0 on success + \return negative on error + + \param key ECC key + \param qx X coordinate buffer + \param qxLen X coordinate length + \param qy Y coordinate buffer + \param qyLen Y coordinate length + \param d Private key buffer + \param dLen Private key length + \param encType Encoding type + + _Example_ + \code + ecc_key key; + byte qx[32], qy[32], d[32]; + word32 qxLen = 32, qyLen = 32, dLen = 32; + int ret = wc_ecc_export_ex(&key, qx, &qxLen, qy, &qyLen, + d, &dLen, 0); + \endcode + + \sa wc_ecc_export_public_raw +*/ +int wc_ecc_export_ex(ecc_key* key, byte* qx, word32* qxLen, + byte* qy, word32* qyLen, byte* d, word32* dLen, int encType); + +/*! + \ingroup ECC + \brief Exports public key in raw format. + + \return 0 on success + \return negative on error + + \param key ECC key + \param qx X coordinate buffer + \param qxLen X coordinate length + \param qy Y coordinate buffer + \param qyLen Y coordinate length + + _Example_ + \code + ecc_key key; + byte qx[32], qy[32]; + word32 qxLen = 32, qyLen = 32; + int ret = wc_ecc_export_public_raw(&key, qx, &qxLen, qy, + &qyLen); + \endcode + + \sa wc_ecc_export_private_raw +*/ +int wc_ecc_export_public_raw(ecc_key* key, byte* qx, + word32* qxLen, byte* qy, word32* qyLen); + +/*! + \ingroup ECC + \brief Exports private key in raw format. + + \return 0 on success + \return negative on error + + \param key ECC key + \param qx X coordinate buffer + \param qxLen X coordinate length + \param qy Y coordinate buffer + \param qyLen Y coordinate length + \param d Private key buffer + \param dLen Private key length + + _Example_ + \code + ecc_key key; + byte qx[32], qy[32], d[32]; + word32 qxLen = 32, qyLen = 32, dLen = 32; + int ret = wc_ecc_export_private_raw(&key, qx, &qxLen, qy, + &qyLen, d, &dLen); + \endcode + + \sa wc_ecc_export_public_raw +*/ +int wc_ecc_export_private_raw(ecc_key* key, byte* qx, + word32* qxLen, byte* qy, word32* qyLen, byte* d, word32* dLen); + +/*! + \ingroup ECC + \brief Exports point in DER format with compression. + + \return Size on success + \return negative on error + + \param curve_idx Curve index + \param point ECC point + \param out Output buffer + \param outLen Output length + \param compressed Compression flag + + _Example_ + \code + ecc_point* point; + byte out[65]; + word32 outLen = sizeof(out); + int ret = wc_ecc_export_point_der_ex(0, point, out, &outLen, + 0); + \endcode + + \sa wc_ecc_export_point_der +*/ +int wc_ecc_export_point_der_ex(const int curve_idx, + ecc_point* point, byte* out, word32* outLen, int compressed); + +/*! + \ingroup ECC + \brief Imports point from DER format. + + \return 0 on success + \return negative on error + + \param in Input buffer + \param inLen Input length + \param curve_idx Curve index + \param point ECC point + \param shortKeySize Short key size flag + + _Example_ + \code + byte der[65]; + ecc_point* point = wc_ecc_new_point(); + int ret = wc_ecc_import_point_der_ex(der, sizeof(der), 0, + point, 0); + \endcode + + \sa wc_ecc_import_point_der +*/ +int wc_ecc_import_point_der_ex(const byte* in, word32 inLen, + const int curve_idx, ecc_point* point, int shortKeySize); + +/*! + \ingroup ECC + \brief Gets OID for curve. + + \return 0 on success + \return negative on error + + \param oidSum OID sum + \param oid OID buffer pointer + \param oidSz OID size pointer + + _Example_ + \code + const byte* oid; + word32 oidSz; + int ret = wc_ecc_get_oid(0x2A8648CE3D030107, &oid, &oidSz); + \endcode + + \sa wc_ecc_get_curve_id_from_oid +*/ +int wc_ecc_get_oid(word32 oidSum, const byte** oid, word32* oidSz); + +/*! + \ingroup ECC + \brief Sets custom curve parameters. + + \return 0 on success + \return negative on error + + \param key ECC key + \param dp Domain parameters + + _Example_ + \code + ecc_key key; + ecc_set_type dp; + int ret = wc_ecc_set_custom_curve(&key, &dp); + \endcode + + \sa wc_ecc_get_curve_params +*/ +int wc_ecc_set_custom_curve(ecc_key* key, const ecc_set_type* dp); + +/*! + \ingroup ECC + \brief Creates new ECC encryption context. + + \return ecEncCtx pointer on success + \return NULL on failure + + \param flags Context flags + \param rng Random number generator + + _Example_ + \code + WC_RNG rng; + ecEncCtx* ctx = wc_ecc_ctx_new(0, &rng); + \endcode + + \sa wc_ecc_ctx_free +*/ +ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng); + +/*! + \ingroup ECC + \brief Creates new ECC encryption context with heap. + + \return ecEncCtx pointer on success + \return NULL on failure + + \param flags Context flags + \param rng Random number generator + \param heap Heap hint + + _Example_ + \code + WC_RNG rng; + ecEncCtx* ctx = wc_ecc_ctx_new_ex(0, &rng, NULL); + \endcode + + \sa wc_ecc_ctx_new +*/ +ecEncCtx* wc_ecc_ctx_new_ex(int flags, WC_RNG* rng, void* heap); + +/*! + \ingroup ECC + \brief Resets ECC encryption context. + + \return 0 on success + \return negative on error + + \param ctx ECC encryption context + \param rng Random number generator + + _Example_ + \code + ecEncCtx* ctx; + WC_RNG rng; + int ret = wc_ecc_ctx_reset(ctx, &rng); + \endcode + + \sa wc_ecc_ctx_new +*/ +int wc_ecc_ctx_reset(ecEncCtx* ctx, WC_RNG* rng); + +/*! + \ingroup ECC + \brief Gets own salt from context. + + \return Salt pointer on success + \return NULL on failure + + \param ctx ECC encryption context + + _Example_ + \code + ecEncCtx* ctx; + const byte* salt = wc_ecc_ctx_get_own_salt(ctx); + \endcode + + \sa wc_ecc_ctx_set_own_salt +*/ +const byte* wc_ecc_ctx_get_own_salt(ecEncCtx* ctx); + +/*! + \ingroup ECC + \brief Sets own salt in context. + + \return 0 on success + \return negative on error + + \param ctx ECC encryption context + \param salt Salt buffer + \param sz Salt size + + _Example_ + \code + ecEncCtx* ctx; + byte salt[16]; + int ret = wc_ecc_ctx_set_own_salt(ctx, salt, sizeof(salt)); + \endcode + + \sa wc_ecc_ctx_get_own_salt +*/ +int wc_ecc_ctx_set_own_salt(ecEncCtx* ctx, const byte* salt, + word32 sz); + +/*! + \ingroup ECC + \brief X9.63 Key Derivation Function. + + \return 0 on success + \return negative on error + + \param type Hash type + \param secret Shared secret + \param secretSz Secret size + \param sinfo Shared info + \param sinfoSz Shared info size + \param out Output buffer + \param outSz Output size + + _Example_ + \code + byte secret[32], sinfo[10], out[32]; + int ret = wc_X963_KDF(WC_HASH_TYPE_SHA256, secret, 32, + sinfo, 10, out, 32); + \endcode + + \sa wc_ecc_shared_secret +*/ +int wc_X963_KDF(enum wc_HashType type, const byte* secret, + word32 secretSz, const byte* sinfo, word32 sinfoSz, + byte* out, word32 outSz); + +/*! + \ingroup ECC + \brief Initializes curve cache. + + \return 0 on success + \return negative on error + + _Example_ + \code + int ret = wc_ecc_curve_cache_init(); + \endcode + + \sa wc_ecc_curve_cache_free +*/ +int wc_ecc_curve_cache_init(void); + +/*! + \ingroup ECC + \brief Frees curve cache. + + \return none No returns + + _Example_ + \code + wc_ecc_curve_cache_free(); + \endcode + + \sa wc_ecc_curve_cache_init +*/ +void wc_ecc_curve_cache_free(void); + +/*! + \ingroup ECC + \brief Generates random k value. + + \return 0 on success + \return negative on error + + \param rng Random number generator + \param size Key size + \param k Output k value + \param order Curve order + + _Example_ + \code + WC_RNG rng; + mp_int k, order; + int ret = wc_ecc_gen_k(&rng, 32, &k, &order); + \endcode + + \sa wc_ecc_sign_hash +*/ +int wc_ecc_gen_k(WC_RNG* rng, int size, mp_int* k, mp_int* order); + +/*! + \ingroup ECC + \brief Sets remote handle for hardware. + + \return 0 on success + \return negative on error + + \param key ECC key + \param handle Remote handle + + _Example_ + \code + ecc_key key; + remote_handle64 handle = 0x1234; + int ret = wc_ecc_set_handle(&key, handle); + \endcode + + \sa wc_ecc_init +*/ +int wc_ecc_set_handle(ecc_key* key, remote_handle64 handle); + +/*! + \ingroup ECC + \brief Uses key ID for hardware. + + \return 0 on success + \return negative on error + + \param key ECC key + \param keyId Key identifier + \param flags Flags + + _Example_ + \code + ecc_key key; + int ret = wc_ecc_use_key_id(&key, 1, 0); + \endcode + + \sa wc_ecc_get_key_id +*/ +int wc_ecc_use_key_id(ecc_key* key, word32 keyId, word32 flags); + +/*! + \ingroup ECC + \brief Gets key ID from hardware key. + + \return 0 on success + \return negative on error + + \param key ECC key + \param keyId Key identifier pointer + + _Example_ + \code + ecc_key key; + word32 keyId; + int ret = wc_ecc_get_key_id(&key, &keyId); + \endcode + + \sa wc_ecc_use_key_id +*/ +int wc_ecc_get_key_id(ecc_key* key, word32* keyId); diff --git a/doc/dox_comments/header_files/ed25519.h b/doc/dox_comments/header_files/ed25519.h index 977a8e4a9..13443c6fa 100644 --- a/doc/dox_comments/header_files/ed25519.h +++ b/doc/dox_comments/header_files/ed25519.h @@ -1087,3 +1087,218 @@ int wc_ed25519_pub_size(const ed25519_key* key); */ int wc_ed25519_sig_size(const ed25519_key* key); +/*! + \ingroup ED25519 + \brief Signs message with extended parameters. + + \return 0 on success + \return negative on failure + + \param in Input message + \param inLen Input message length + \param out Output signature buffer + \param outLen Output signature length pointer + \param key Ed25519 key + \param type Signature type + \param context Context buffer + \param contextLen Context length + + _Example_ + \code + byte msg[] = "message"; + byte sig[ED25519_SIG_SIZE]; + word32 sigLen = sizeof(sig); + int ret = wc_ed25519_sign_msg_ex(msg, sizeof(msg), sig, &sigLen, + &key, Ed25519, NULL, 0); + \endcode + + \sa wc_ed25519_sign_msg +*/ +int wc_ed25519_sign_msg_ex(const byte* in, word32 inLen, byte* out, + word32 *outLen, ed25519_key* key, byte type, const byte* context, + byte contextLen); + +/*! + \ingroup ED25519 + \brief Verifies signature with extended parameters. + + \return 0 on success + \return negative on failure + + \param sig Signature buffer + \param sigLen Signature length + \param msg Message buffer + \param msgLen Message length + \param res Verification result pointer + \param key Ed25519 key + \param type Signature type + \param context Context buffer + \param contextLen Context length + + _Example_ + \code + byte msg[] = "message"; + byte sig[ED25519_SIG_SIZE]; + int res; + int ret = wc_ed25519_verify_msg_ex(sig, sizeof(sig), msg, + sizeof(msg), &res, &key, + Ed25519, NULL, 0); + \endcode + + \sa wc_ed25519_verify_msg +*/ +int wc_ed25519_verify_msg_ex(const byte* sig, word32 sigLen, + const byte* msg, word32 msgLen, int* res, ed25519_key* key, + byte type, const byte* context, byte contextLen); + +/*! + \ingroup ED25519 + \brief Initializes streaming verification. + + \return 0 on success + \return negative on failure + + \param sig Signature buffer + \param sigLen Signature length + \param key Ed25519 key + \param type Signature type + \param context Context buffer + \param contextLen Context length + + _Example_ + \code + byte sig[ED25519_SIG_SIZE]; + int ret = wc_ed25519_verify_msg_init(sig, sizeof(sig), &key, + Ed25519, NULL, 0); + \endcode + + \sa wc_ed25519_verify_msg_update + \sa wc_ed25519_verify_msg_final +*/ +int wc_ed25519_verify_msg_init(const byte* sig, word32 sigLen, + ed25519_key* key, byte type, const byte* context, + byte contextLen); + +/*! + \ingroup ED25519 + \brief Updates streaming verification with message segment. + + \return 0 on success + \return negative on failure + + \param msgSegment Message segment buffer + \param msgSegmentLen Message segment length + \param key Ed25519 key + + _Example_ + \code + byte msgPart[] = "part"; + int ret = wc_ed25519_verify_msg_update(msgPart, sizeof(msgPart), + &key); + \endcode + + \sa wc_ed25519_verify_msg_init + \sa wc_ed25519_verify_msg_final +*/ +int wc_ed25519_verify_msg_update(const byte* msgSegment, + word32 msgSegmentLen, ed25519_key* key); + +/*! + \ingroup ED25519 + \brief Finalizes streaming verification. + + \return 0 on success + \return negative on failure + + \param sig Signature buffer + \param sigLen Signature length + \param res Verification result pointer + \param key Ed25519 key + + _Example_ + \code + byte sig[ED25519_SIG_SIZE]; + int res; + int ret = wc_ed25519_verify_msg_final(sig, sizeof(sig), &res, + &key); + \endcode + + \sa wc_ed25519_verify_msg_init + \sa wc_ed25519_verify_msg_update +*/ +int wc_ed25519_verify_msg_final(const byte* sig, word32 sigLen, + int* res, ed25519_key* key); + +/*! + \ingroup ED25519 + \brief Initializes Ed25519 key with extended parameters. + + \return 0 on success + \return negative on failure + + \param key Ed25519 key structure + \param heap Heap hint for memory allocation + \param devId Device ID for hardware acceleration + + _Example_ + \code + ed25519_key key; + int ret = wc_ed25519_init_ex(&key, NULL, INVALID_DEVID); + \endcode + + \sa wc_ed25519_init +*/ +int wc_ed25519_init_ex(ed25519_key* key, void* heap, int devId); + +/*! + \ingroup ED25519 + \brief Allocates and initializes new Ed25519 key. These New/Delete + functions are exposed to support allocation of the structure using + dynamic memory to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return ed25519_key pointer on success + \return NULL on failure + + \param heap Heap hint for memory allocation + \param devId Device ID for hardware acceleration + \param result_code Result code pointer + + _Example_ + \code + int result; + ed25519_key* key = wc_ed25519_new(NULL, INVALID_DEVID, &result); + \endcode + + \sa wc_ed25519_delete +*/ +ed25519_key* wc_ed25519_new(void* heap, int devId, int *result_code); + +/*! + \ingroup ED25519 + \brief Frees and deletes Ed25519 key. These New/Delete functions are + exposed to support allocation of the structure using dynamic memory + to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return 0 on success + \return negative on failure + + \param key Ed25519 key to delete + \param key_p Pointer to key pointer (set to NULL after delete) + + _Example_ + \code + ed25519_key* key = wc_ed25519_new(NULL, INVALID_DEVID, NULL); + int ret = wc_ed25519_delete(key, &key); + \endcode + + \sa wc_ed25519_new +*/ +int wc_ed25519_delete(ed25519_key* key, ed25519_key** key_p); diff --git a/doc/dox_comments/header_files/iotsafe.h b/doc/dox_comments/header_files/iotsafe.h index 46bd2e5da..31d97838e 100644 --- a/doc/dox_comments/header_files/iotsafe.h +++ b/doc/dox_comments/header_files/iotsafe.h @@ -288,6 +288,43 @@ int wc_iotsafe_ecc_import_public(ecc_key *key, byte key_id); */ 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 + wc_iotsafe_ecc_export_public, except that it can be invoked with a + key ID of two or more bytes. + + \return 0 upon success + \return < 0 in case of failure + + \param key the ecc_key object containing the key to be exported + \param key_id pointer to the key id in the IoT-Safe applet where + the public key will be stored + \param id_size the key id size in bytes + + _Example_ + \code + ecc_key key; + word16 keyId = 0x0302; + + wc_ecc_init(&key); + wc_ecc_make_key(&rng, 32, &key); + + int ret = wc_iotsafe_ecc_export_public_ex(&key, (byte*)&keyId, + sizeof(keyId)); + if (ret != 0) { + // error exporting public key + } + \endcode + + \sa wc_iotsafe_ecc_export_public + \sa wc_iotsafe_ecc_import_public_ex + \sa wc_iotsafe_ecc_export_private_ex +*/ +int wc_iotsafe_ecc_export_public_ex(ecc_key *key, byte *key_id, + word16 id_size); + /*! \ingroup IoTSafe @@ -462,4 +499,4 @@ int wc_iotsafe_ecc_gen_k(byte key_id); \sa wc_iotsafe_ecc_sign_hash_ex \sa wc_iotsafe_ecc_verify_hash_ex */ -int wc_iotsafe_ecc_gen_k(byte key_id); +int wc_iotsafe_ecc_gen_k_ex(byte *key_id, word16 id_size); diff --git a/doc/dox_comments/header_files/pkcs7.h b/doc/dox_comments/header_files/pkcs7.h index 925c5223b..69d927c69 100644 --- a/doc/dox_comments/header_files/pkcs7.h +++ b/doc/dox_comments/header_files/pkcs7.h @@ -877,3 +877,1329 @@ int wc_PKCS7_DecodeOneSymmetricKeyAttribute(const byte * osk, */ int wc_PKCS7_DecodeOneSymmetricKeyKey(const byte * osk, word32 oskSz, const byte ** key, word32 * keySz); + +/*! + \ingroup PKCS7 + \brief Creates new PKCS7 structure. + + \return Pointer to new PKCS7 structure on success + \return NULL on error + + \param none No parameters + + _Example_ + \code + PKCS7* pkcs7 = wolfSSL_PKCS7_new(); + if (pkcs7 != NULL) { + // use pkcs7 + wolfSSL_PKCS7_free(pkcs7); + } + \endcode + + \sa wolfSSL_PKCS7_free +*/ +PKCS7* wolfSSL_PKCS7_new(void); + +/*! + \ingroup PKCS7 + \brief Creates new PKCS7_SIGNED structure. + + \return Pointer to new PKCS7_SIGNED structure on success + \return NULL on error + + \param none No parameters + + _Example_ + \code + PKCS7_SIGNED* p7 = wolfSSL_PKCS7_SIGNED_new(); + if (p7 != NULL) { + // use p7 + wolfSSL_PKCS7_SIGNED_free(p7); + } + \endcode + + \sa wolfSSL_PKCS7_SIGNED_free +*/ +PKCS7_SIGNED* wolfSSL_PKCS7_SIGNED_new(void); + +/*! + \ingroup PKCS7 + \brief Frees PKCS7 structure. + + \return none No returns + + \param p7 PKCS7 structure to free + + _Example_ + \code + PKCS7* pkcs7 = wolfSSL_PKCS7_new(); + wolfSSL_PKCS7_free(pkcs7); + \endcode + + \sa wolfSSL_PKCS7_new +*/ +void wolfSSL_PKCS7_free(PKCS7* p7); + +/*! + \ingroup PKCS7 + \brief Frees PKCS7_SIGNED structure. + + \return none No returns + + \param p7 PKCS7_SIGNED structure to free + + _Example_ + \code + PKCS7_SIGNED* p7 = wolfSSL_PKCS7_SIGNED_new(); + wolfSSL_PKCS7_SIGNED_free(p7); + \endcode + + \sa wolfSSL_PKCS7_SIGNED_new +*/ +void wolfSSL_PKCS7_SIGNED_free(PKCS7_SIGNED* p7); + +/*! + \ingroup PKCS7 + \brief Decodes DER-encoded PKCS7 structure. + + \return Pointer to decoded PKCS7 structure on success + \return NULL on error + + \param p7 Pointer to PKCS7 pointer (can be NULL) + \param in Pointer to DER-encoded data + \param len Length of DER data + + _Example_ + \code + PKCS7* p7 = NULL; + const unsigned char* der = ...; // DER data + p7 = wolfSSL_d2i_PKCS7(&p7, &der, derLen); + \endcode + + \sa wolfSSL_i2d_PKCS7 +*/ +PKCS7* wolfSSL_d2i_PKCS7(PKCS7** p7, const unsigned char** in, int len); + +/*! + \ingroup PKCS7 + \brief Decodes PKCS7 from BIO. + + \return Pointer to decoded PKCS7 structure on success + \return NULL on error + + \param bio BIO to read from + \param p7 Pointer to PKCS7 pointer (can be NULL) + + _Example_ + \code + WOLFSSL_BIO* bio = wolfSSL_BIO_new_file("pkcs7.der", "rb"); + PKCS7* p7 = wolfSSL_d2i_PKCS7_bio(bio, NULL); + \endcode + + \sa wolfSSL_i2d_PKCS7_bio +*/ +PKCS7* wolfSSL_d2i_PKCS7_bio(WOLFSSL_BIO* bio, PKCS7** p7); + +/*! + \ingroup PKCS7 + \brief Encodes PKCS7 to BIO. + + \return Length written on success + \return negative on error + + \param bio BIO to write to + \param p7 PKCS7 structure to encode + + _Example_ + \code + WOLFSSL_BIO* bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem()); + int ret = wolfSSL_i2d_PKCS7_bio(bio, p7); + \endcode + + \sa wolfSSL_d2i_PKCS7_bio +*/ +int wolfSSL_i2d_PKCS7_bio(WOLFSSL_BIO *bio, PKCS7 *p7); + +/*! + \ingroup PKCS7 + \brief Encodes PKCS7 to DER. + + \return Length written on success + \return negative on error + + \param p7 PKCS7 structure to encode + \param out Pointer to output buffer pointer + + _Example_ + \code + unsigned char* der = NULL; + int len = wolfSSL_i2d_PKCS7(p7, &der); + \endcode + + \sa wolfSSL_d2i_PKCS7 +*/ +int wolfSSL_i2d_PKCS7(PKCS7 *p7, unsigned char **out); + +/*! + \ingroup PKCS7 + \brief Creates signed PKCS7 message. + + \return Pointer to signed PKCS7 structure on success + \return NULL on error + + \param signer Signer certificate + \param pkey Private key + \param certs Additional certificates + \param in Input data BIO + \param flags Operation flags + + _Example_ + \code + PKCS7* p7 = wolfSSL_PKCS7_sign(cert, pkey, NULL, bio, 0); + \endcode + + \sa wolfSSL_PKCS7_verify +*/ +PKCS7* wolfSSL_PKCS7_sign(WOLFSSL_X509* signer, WOLFSSL_EVP_PKEY* pkey, + WOLFSSL_STACK* certs, WOLFSSL_BIO* in, int flags); + +/*! + \ingroup PKCS7 + \brief Verifies signed PKCS7 message. + + \return 1 on success + \return 0 or negative on error + + \param p7 PKCS7 structure to verify + \param certs Certificate stack + \param store Certificate store + \param in Input data BIO + \param out Output BIO + \param flags Operation flags + + _Example_ + \code + int ret = wolfSSL_PKCS7_verify(p7, NULL, store, NULL, out, 0); + \endcode + + \sa wolfSSL_PKCS7_sign +*/ +int wolfSSL_PKCS7_verify(PKCS7* p7, WOLFSSL_STACK* certs, + WOLFSSL_X509_STORE* store, WOLFSSL_BIO* in, + WOLFSSL_BIO* out, int flags); + +/*! + \ingroup PKCS7 + \brief Finalizes PKCS7 structure with data. + + \return 1 on success + \return 0 or negative on error + + \param pkcs7 PKCS7 structure + \param in Input data BIO + \param flags Operation flags + + _Example_ + \code + int ret = wolfSSL_PKCS7_final(pkcs7, bio, 0); + \endcode + + \sa wolfSSL_PKCS7_sign +*/ +int wolfSSL_PKCS7_final(PKCS7* pkcs7, WOLFSSL_BIO* in, int flags); + +/*! + \ingroup PKCS7 + \brief Encodes certificates into PKCS7. + + \return 1 on success + \return 0 or negative on error + + \param p7 PKCS7 structure + \param certs Certificate stack + \param out Output BIO + + _Example_ + \code + int ret = wolfSSL_PKCS7_encode_certs(p7, certs, bio); + \endcode + + \sa wolfSSL_PKCS7_to_stack +*/ +int wolfSSL_PKCS7_encode_certs(PKCS7* p7, WOLFSSL_STACK* certs, + WOLFSSL_BIO* out); + +/*! + \ingroup PKCS7 + \brief Converts PKCS7 certificates to stack. + + \return Pointer to certificate stack on success + \return NULL on error + + \param pkcs7 PKCS7 structure + + _Example_ + \code + WOLFSSL_STACK* certs = wolfSSL_PKCS7_to_stack(pkcs7); + \endcode + + \sa wolfSSL_PKCS7_encode_certs +*/ +WOLFSSL_STACK* wolfSSL_PKCS7_to_stack(PKCS7* pkcs7); + +/*! + \ingroup PKCS7 + \brief Gets signer certificates from PKCS7. + + \return Pointer to signer certificate stack on success + \return NULL on error + + \param p7 PKCS7 structure + \param certs Certificate stack + \param flags Operation flags + + _Example_ + \code + WOLFSSL_STACK* signers = wolfSSL_PKCS7_get0_signers(p7, NULL, 0); + \endcode + + \sa wolfSSL_PKCS7_verify +*/ +WOLFSSL_STACK* wolfSSL_PKCS7_get0_signers(PKCS7* p7, WOLFSSL_STACK* certs, + int flags); + +/*! + \ingroup PKCS7 + \brief Writes PKCS7 to BIO in PEM format. + + \return 1 on success + \return 0 or negative on error + + \param bio Output BIO + \param p7 PKCS7 structure + + _Example_ + \code + int ret = wolfSSL_PEM_write_bio_PKCS7(bio, p7); + \endcode + + \sa wolfSSL_SMIME_write_PKCS7 +*/ +int wolfSSL_PEM_write_bio_PKCS7(WOLFSSL_BIO* bio, PKCS7* p7); + +/*! + \ingroup PKCS7 + \brief Reads S/MIME PKCS7 from BIO. + + \return Pointer to PKCS7 structure on success + \return NULL on error + + \param in Input BIO + \param bcont Pointer to content BIO pointer + + _Example_ + \code + WOLFSSL_BIO* cont = NULL; + PKCS7* p7 = wolfSSL_SMIME_read_PKCS7(bio, &cont); + \endcode + + \sa wolfSSL_SMIME_write_PKCS7 +*/ +PKCS7* wolfSSL_SMIME_read_PKCS7(WOLFSSL_BIO* in, WOLFSSL_BIO** bcont); + +/*! + \ingroup PKCS7 + \brief Writes PKCS7 to BIO in S/MIME format. + + \return 1 on success + \return 0 or negative on error + + \param out Output BIO + \param pkcs7 PKCS7 structure + \param in Input data BIO + \param flags Operation flags + + _Example_ + \code + int ret = wolfSSL_SMIME_write_PKCS7(out, pkcs7, in, 0); + \endcode + + \sa wolfSSL_SMIME_read_PKCS7 +*/ +int wolfSSL_SMIME_write_PKCS7(WOLFSSL_BIO* out, PKCS7* pkcs7, + WOLFSSL_BIO* in, int flags); + +/*! + \ingroup PKCS7 + \brief Creates new wc_PKCS7 structure. + + \return Pointer to new wc_PKCS7 structure on success + \return NULL on error + + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_PKCS7* pkcs7 = wc_PKCS7_New(NULL, INVALID_DEVID); + \endcode + + \sa wc_PKCS7_Init +*/ +wc_PKCS7* wc_PKCS7_New(void* heap, int devId); + +/*! + \ingroup PKCS7 + \brief Sets unknown extension callback. + + \return none No returns + + \param pkcs7 PKCS7 structure + \param cb Callback function + + _Example_ + \code + wc_PKCS7_SetUnknownExtCallback(pkcs7, myCallback); + \endcode + + \sa wc_PKCS7_Init +*/ +void wc_PKCS7_SetUnknownExtCallback(wc_PKCS7* pkcs7, + wc_UnknownExtCallback cb); + +/*! + \ingroup PKCS7 + \brief Initializes wc_PKCS7 structure. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_PKCS7 pkcs7; + int ret = wc_PKCS7_Init(&pkcs7, NULL, INVALID_DEVID); + \endcode + + \sa wc_PKCS7_New +*/ +int wc_PKCS7_Init(wc_PKCS7* pkcs7, void* heap, int devId); + +/*! + \ingroup PKCS7 + \brief Adds certificate to PKCS7. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param der DER-encoded certificate + \param derSz Certificate size + + _Example_ + \code + int ret = wc_PKCS7_AddCertificate(&pkcs7, cert, certSz); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_AddCertificate(wc_PKCS7* pkcs7, byte* der, word32 derSz); + +/*! + \ingroup PKCS7 + \brief Gets attribute value from PKCS7. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param oid Attribute OID + \param oidSz OID size + \param out Output buffer + \param outSz Output buffer size pointer + + _Example_ + \code + byte value[256]; + word32 valueSz = sizeof(value); + int ret = wc_PKCS7_GetAttributeValue(&pkcs7, oid, oidSz, value, + &valueSz); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_GetAttributeValue(wc_PKCS7* pkcs7, const byte* oid, + word32 oidSz, byte* out, word32* outSz); + +/*! + \ingroup PKCS7 + \brief Sets signer identifier type. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param type Identifier type + + _Example_ + \code + int ret = wc_PKCS7_SetSignerIdentifierType(&pkcs7, CMS_SKID); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetSignerIdentifierType(wc_PKCS7* pkcs7, int type); + +/*! + \ingroup PKCS7 + \brief Sets content type. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param contentType Content type OID + \param sz OID size + + _Example_ + \code + int ret = wc_PKCS7_SetContentType(&pkcs7, DATA, sizeof(DATA)); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetContentType(wc_PKCS7* pkcs7, byte* contentType, word32 sz); + +/*! + \ingroup PKCS7 + \brief Gets padding size for block cipher. + + \return Padding size + + \param inputSz Input size + \param blockSz Block size + + _Example_ + \code + int padSz = wc_PKCS7_GetPadSize(dataSz, AES_BLOCK_SIZE); + \endcode + + \sa wc_PKCS7_PadData +*/ +int wc_PKCS7_GetPadSize(word32 inputSz, word32 blockSz); + +/*! + \ingroup PKCS7 + \brief Pads data for block cipher. + + \return 0 on success + \return negative on error + + \param in Input data + \param inSz Input size + \param out Output buffer + \param outSz Output buffer size + \param blockSz Block size + + _Example_ + \code + int ret = wc_PKCS7_PadData(data, dataSz, padded, paddedSz, + AES_BLOCK_SIZE); + \endcode + + \sa wc_PKCS7_GetPadSize +*/ +int wc_PKCS7_PadData(byte* in, word32 inSz, byte* out, word32 outSz, + word32 blockSz); + +/*! + \ingroup PKCS7 + \brief Sets custom subject key identifier. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param in SKID data + \param inSz SKID size + + _Example_ + \code + int ret = wc_PKCS7_SetCustomSKID(&pkcs7, skid, skidSz); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetCustomSKID(wc_PKCS7* pkcs7, const byte* in, word16 inSz); + +/*! + \ingroup PKCS7 + \brief Sets detached signature flag. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param flag Detached flag (1=detached, 0=attached) + + _Example_ + \code + int ret = wc_PKCS7_SetDetached(&pkcs7, 1); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetDetached(wc_PKCS7* pkcs7, word16 flag); + +/*! + \ingroup PKCS7 + \brief Disables default signed attributes. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + + _Example_ + \code + int ret = wc_PKCS7_NoDefaultSignedAttribs(&pkcs7); + \endcode + + \sa wc_PKCS7_SetDefaultSignedAttribs +*/ +int wc_PKCS7_NoDefaultSignedAttribs(wc_PKCS7* pkcs7); + +/*! + \ingroup PKCS7 + \brief Sets default signed attributes flag. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param flag Default attributes flag + + _Example_ + \code + int ret = wc_PKCS7_SetDefaultSignedAttribs(&pkcs7, 1); + \endcode + + \sa wc_PKCS7_NoDefaultSignedAttribs +*/ +int wc_PKCS7_SetDefaultSignedAttribs(wc_PKCS7* pkcs7, word16 flag); + +/*! + \ingroup PKCS7 + \brief Allows degenerate PKCS7 (no signers). + + \return none No returns + + \param pkcs7 PKCS7 structure + \param flag Allow degenerate flag + + _Example_ + \code + wc_PKCS7_AllowDegenerate(&pkcs7, 1); + \endcode + + \sa wc_PKCS7_Init +*/ +void wc_PKCS7_AllowDegenerate(wc_PKCS7* pkcs7, word16 flag); + +/*! + \ingroup PKCS7 + \brief Gets signer subject identifier. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param out Output buffer + \param outSz Output buffer size pointer + + _Example_ + \code + byte sid[256]; + word32 sidSz = sizeof(sid); + int ret = wc_PKCS7_GetSignerSID(&pkcs7, sid, &sidSz); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_GetSignerSID(wc_PKCS7* pkcs7, byte* out, word32* outSz); + +/*! + \ingroup PKCS7 + \brief Encodes signed FirmwarePackageData. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param privateKey Private key + \param privateKeySz Private key size + \param signOID Signature algorithm OID + \param hashOID Hash algorithm OID + \param content Content data + \param contentSz Content size + \param signedAttribs Signed attributes + \param signedAttribsSz Signed attributes count + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeSignedFPD(&pkcs7, key, keySz, RSAk, SHAh, + data, dataSz, NULL, 0, out, outSz); + \endcode + + \sa wc_PKCS7_EncodeSignedData +*/ +int wc_PKCS7_EncodeSignedFPD(wc_PKCS7* pkcs7, byte* privateKey, + word32 privateKeySz, int signOID, int hashOID, + byte* content, word32 contentSz, + PKCS7Attrib* signedAttribs, + word32 signedAttribsSz, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Encodes signed encrypted FirmwarePackageData. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param encryptKey Encryption key + \param encryptKeySz Encryption key size + \param privateKey Private key + \param privateKeySz Private key size + \param encryptOID Encryption algorithm OID + \param signOID Signature algorithm OID + \param hashOID Hash algorithm OID + \param content Content data + \param contentSz Content size + \param unprotectedAttribs Unprotected attributes + \param unprotectedAttribsSz Unprotected attributes count + \param signedAttribs Signed attributes + \param signedAttribsSz Signed attributes count + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeSignedEncryptedFPD(&pkcs7, encKey, encKeySz, + key, keySz, AES256CBCb, + RSAk, SHAh, data, dataSz, + NULL, 0, NULL, 0, out, + outSz); + \endcode + + \sa wc_PKCS7_EncodeSignedFPD +*/ +int wc_PKCS7_EncodeSignedEncryptedFPD(wc_PKCS7* pkcs7, byte* encryptKey, + word32 encryptKeySz, byte* privateKey, + word32 privateKeySz, int encryptOID, + int signOID, int hashOID, byte* content, + word32 contentSz, + PKCS7Attrib* unprotectedAttribs, + word32 unprotectedAttribsSz, + PKCS7Attrib* signedAttribs, + word32 signedAttribsSz, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Encodes signed compressed FirmwarePackageData. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param privateKey Private key + \param privateKeySz Private key size + \param signOID Signature algorithm OID + \param hashOID Hash algorithm OID + \param content Content data + \param contentSz Content size + \param signedAttribs Signed attributes + \param signedAttribsSz Signed attributes count + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeSignedCompressedFPD(&pkcs7, key, keySz, RSAk, + SHAh, data, dataSz, NULL, + 0, out, outSz); + \endcode + + \sa wc_PKCS7_EncodeSignedFPD +*/ +int wc_PKCS7_EncodeSignedCompressedFPD(wc_PKCS7* pkcs7, byte* privateKey, + word32 privateKeySz, int signOID, + int hashOID, byte* content, + word32 contentSz, + PKCS7Attrib* signedAttribs, + word32 signedAttribsSz, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Encodes signed encrypted compressed FirmwarePackageData. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param encryptKey Encryption key + \param encryptKeySz Encryption key size + \param privateKey Private key + \param privateKeySz Private key size + \param encryptOID Encryption algorithm OID + \param signOID Signature algorithm OID + \param hashOID Hash algorithm OID + \param content Content data + \param contentSz Content size + \param unprotectedAttribs Unprotected attributes + \param unprotectedAttribsSz Unprotected attributes count + \param signedAttribs Signed attributes + \param signedAttribsSz Signed attributes count + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeSignedEncryptedCompressedFPD(&pkcs7, encKey, + encKeySz, key, + keySz, AES256CBCb, + RSAk, SHAh, data, + dataSz, NULL, 0, + NULL, 0, out, + outSz); + \endcode + + \sa wc_PKCS7_EncodeSignedCompressedFPD +*/ +int wc_PKCS7_EncodeSignedEncryptedCompressedFPD(wc_PKCS7* pkcs7, + byte* encryptKey, + word32 encryptKeySz, + byte* privateKey, + word32 privateKeySz, + int encryptOID, int signOID, + int hashOID, byte* content, + word32 contentSz, + PKCS7Attrib* unprotectedAttribs, + word32 unprotectedAttribsSz, + PKCS7Attrib* signedAttribs, + word32 signedAttribsSz, + byte* output, word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Adds KTRI recipient. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param cert Recipient certificate + \param certSz Certificate size + \param options Options flags + + _Example_ + \code + int ret = wc_PKCS7_AddRecipient_KTRI(&pkcs7, cert, certSz, 0); + \endcode + + \sa wc_PKCS7_AddRecipient_KARI +*/ +int wc_PKCS7_AddRecipient_KTRI(wc_PKCS7* pkcs7, const byte* cert, + word32 certSz, int options); + +/*! + \ingroup PKCS7 + \brief Adds KARI recipient. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param cert Recipient certificate + \param certSz Certificate size + \param keyWrapOID Key wrap algorithm OID + \param keyAgreeOID Key agreement algorithm OID + \param ukm User keying material + \param ukmSz UKM size + \param options Options flags + + _Example_ + \code + int ret = wc_PKCS7_AddRecipient_KARI(&pkcs7, cert, certSz, AES256_WRAP, + dhSinglePass_stdDH_sha256kdf_scheme, + NULL, 0, 0); + \endcode + + \sa wc_PKCS7_AddRecipient_KTRI +*/ +int wc_PKCS7_AddRecipient_KARI(wc_PKCS7* pkcs7, const byte* cert, + word32 certSz, int keyWrapOID, + int keyAgreeOID, byte* ukm, word32 ukmSz, + int options); + +/*! + \ingroup PKCS7 + \brief Sets encryption key. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param key Encryption key + \param keySz Key size + + _Example_ + \code + int ret = wc_PKCS7_SetKey(&pkcs7, key, keySz); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetKey(wc_PKCS7* pkcs7, byte* key, word32 keySz); + +/*! + \ingroup PKCS7 + \brief Adds KEKRI recipient. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param keyWrapOID Key wrap algorithm OID + \param kek Key encryption key + \param kekSz KEK size + \param keyID Key identifier + \param keyIdSz Key ID size + \param timePtr Time pointer + \param otherOID Other OID + \param otherOIDSz Other OID size + \param other Other data + \param otherSz Other data size + \param options Options flags + + _Example_ + \code + int ret = wc_PKCS7_AddRecipient_KEKRI(&pkcs7, AES256_WRAP, kek, kekSz, + keyId, keyIdSz, NULL, NULL, 0, + NULL, 0, 0); + \endcode + + \sa wc_PKCS7_AddRecipient_KTRI +*/ +int wc_PKCS7_AddRecipient_KEKRI(wc_PKCS7* pkcs7, int keyWrapOID, byte* kek, + word32 kekSz, byte* keyID, word32 keyIdSz, + void* timePtr, byte* otherOID, + word32 otherOIDSz, byte* other, + word32 otherSz, int options); + +/*! + \ingroup PKCS7 + \brief Sets password for PWRI. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param passwd Password + \param pLen Password length + + _Example_ + \code + int ret = wc_PKCS7_SetPassword(&pkcs7, password, passwordLen); + \endcode + + \sa wc_PKCS7_AddRecipient_PWRI +*/ +int wc_PKCS7_SetPassword(wc_PKCS7* pkcs7, byte* passwd, word32 pLen); + +/*! + \ingroup PKCS7 + \brief Adds PWRI recipient. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param passwd Password + \param pLen Password length + \param salt Salt + \param saltSz Salt size + \param kdfOID KDF algorithm OID + \param prfOID PRF algorithm OID + \param iterations Iteration count + \param kekEncryptOID KEK encryption algorithm OID + \param options Options flags + + _Example_ + \code + int ret = wc_PKCS7_AddRecipient_PWRI(&pkcs7, password, passwordLen, + salt, saltSz, PBKDF2_OID, HMACh, + 10000, AES256CBCb, 0); + \endcode + + \sa wc_PKCS7_SetPassword +*/ +int wc_PKCS7_AddRecipient_PWRI(wc_PKCS7* pkcs7, byte* passwd, word32 pLen, + byte* salt, word32 saltSz, int kdfOID, + int prfOID, int iterations, + int kekEncryptOID, int options); + +/*! + \ingroup PKCS7 + \brief Sets originator encryption context. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param ctx Context pointer + + _Example_ + \code + int ret = wc_PKCS7_SetOriEncryptCtx(&pkcs7, myContext); + \endcode + + \sa wc_PKCS7_SetOriDecryptCtx +*/ +int wc_PKCS7_SetOriEncryptCtx(wc_PKCS7* pkcs7, void* ctx); + +/*! + \ingroup PKCS7 + \brief Sets originator decryption context. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param ctx Context pointer + + _Example_ + \code + int ret = wc_PKCS7_SetOriDecryptCtx(&pkcs7, myContext); + \endcode + + \sa wc_PKCS7_SetOriEncryptCtx +*/ +int wc_PKCS7_SetOriDecryptCtx(wc_PKCS7* pkcs7, void* ctx); + +/*! + \ingroup PKCS7 + \brief Sets originator decryption callback. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param cb Callback function + + _Example_ + \code + int ret = wc_PKCS7_SetOriDecryptCb(&pkcs7, myDecryptCallback); + \endcode + + \sa wc_PKCS7_SetOriDecryptCtx +*/ +int wc_PKCS7_SetOriDecryptCb(wc_PKCS7* pkcs7, CallbackOriDecrypt cb); + +/*! + \ingroup PKCS7 + \brief Adds ORI recipient. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param cb Originator encryption callback + \param options Options flags + + _Example_ + \code + int ret = wc_PKCS7_AddRecipient_ORI(&pkcs7, myEncryptCallback, 0); + \endcode + + \sa wc_PKCS7_SetOriDecryptCb +*/ +int wc_PKCS7_AddRecipient_ORI(wc_PKCS7* pkcs7, CallbackOriEncrypt cb, + int options); + +/*! + \ingroup PKCS7 + \brief Sets CEK wrap callback. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param wrapCEKCb Wrap CEK callback + + _Example_ + \code + int ret = wc_PKCS7_SetWrapCEKCb(&pkcs7, myWrapCEKCallback); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetWrapCEKCb(wc_PKCS7* pkcs7, CallbackWrapCEK wrapCEKCb); + +/*! + \ingroup PKCS7 + \brief Sets RSA sign raw digest callback. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param cb Callback function + + _Example_ + \code + int ret = wc_PKCS7_SetRsaSignRawDigestCb(&pkcs7, mySignCallback); + \endcode + + \sa wc_PKCS7_Init +*/ +int wc_PKCS7_SetRsaSignRawDigestCb(wc_PKCS7* pkcs7, + CallbackRsaSignRawDigest cb); + +/*! + \ingroup PKCS7 + \brief Encodes authenticated enveloped data. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeAuthEnvelopedData(&pkcs7, out, outSz); + \endcode + + \sa wc_PKCS7_DecodeAuthEnvelopedData +*/ +int wc_PKCS7_EncodeAuthEnvelopedData(wc_PKCS7* pkcs7, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Decodes authenticated enveloped data. + + \return Size of decoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param pkiMsg Input message + \param pkiMsgSz Input message size + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_DecodeAuthEnvelopedData(&pkcs7, msg, msgSz, out, + outSz); + \endcode + + \sa wc_PKCS7_EncodeAuthEnvelopedData +*/ +int wc_PKCS7_DecodeAuthEnvelopedData(wc_PKCS7* pkcs7, byte* pkiMsg, + word32 pkiMsgSz, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Encodes encrypted data. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeEncryptedData(&pkcs7, out, outSz); + \endcode + + \sa wc_PKCS7_DecodeEncryptedData +*/ +int wc_PKCS7_EncodeEncryptedData(wc_PKCS7* pkcs7, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Sets decode encrypted callback. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param decryptionCb Decryption callback + + _Example_ + \code + int ret = wc_PKCS7_SetDecodeEncryptedCb(&pkcs7, myDecryptCallback); + \endcode + + \sa wc_PKCS7_SetDecodeEncryptedCtx +*/ +int wc_PKCS7_SetDecodeEncryptedCb(wc_PKCS7* pkcs7, + CallbackDecryptContent decryptionCb); + +/*! + \ingroup PKCS7 + \brief Sets decode encrypted context. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param ctx Context pointer + + _Example_ + \code + int ret = wc_PKCS7_SetDecodeEncryptedCtx(&pkcs7, myContext); + \endcode + + \sa wc_PKCS7_SetDecodeEncryptedCb +*/ +int wc_PKCS7_SetDecodeEncryptedCtx(wc_PKCS7* pkcs7, void* ctx); + +/*! + \ingroup PKCS7 + \brief Sets stream mode for PKCS7. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param flag Stream mode flag + \param getContentCb Get content callback + \param streamOutCb Stream output callback + \param ctx Context pointer + + _Example_ + \code + int ret = wc_PKCS7_SetStreamMode(&pkcs7, 1, getContent, streamOut, + ctx); + \endcode + + \sa wc_PKCS7_GetStreamMode +*/ +int wc_PKCS7_SetStreamMode(wc_PKCS7* pkcs7, byte flag, + CallbackGetContent getContentCb, + CallbackStreamOut streamOutCb, void* ctx); + +/*! + \ingroup PKCS7 + \brief Gets stream mode setting. + + \return Stream mode flag + + \param pkcs7 PKCS7 structure + + _Example_ + \code + int mode = wc_PKCS7_GetStreamMode(&pkcs7); + \endcode + + \sa wc_PKCS7_SetStreamMode +*/ +int wc_PKCS7_GetStreamMode(wc_PKCS7* pkcs7); + +/*! + \ingroup PKCS7 + \brief Sets no certificates flag. + + \return 0 on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param flag No certificates flag + + _Example_ + \code + int ret = wc_PKCS7_SetNoCerts(&pkcs7, 1); + \endcode + + \sa wc_PKCS7_GetNoCerts +*/ +int wc_PKCS7_SetNoCerts(wc_PKCS7* pkcs7, byte flag); + +/*! + \ingroup PKCS7 + \brief Gets no certificates flag. + + \return No certificates flag + + \param pkcs7 PKCS7 structure + + _Example_ + \code + int noCerts = wc_PKCS7_GetNoCerts(&pkcs7); + \endcode + + \sa wc_PKCS7_SetNoCerts +*/ +int wc_PKCS7_GetNoCerts(wc_PKCS7* pkcs7); + +/*! + \ingroup PKCS7 + \brief Encodes compressed data. + + \return Size of encoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_EncodeCompressedData(&pkcs7, out, outSz); + \endcode + + \sa wc_PKCS7_DecodeCompressedData +*/ +int wc_PKCS7_EncodeCompressedData(wc_PKCS7* pkcs7, byte* output, + word32 outputSz); + +/*! + \ingroup PKCS7 + \brief Decodes compressed data. + + \return Size of decoded data on success + \return negative on error + + \param pkcs7 PKCS7 structure + \param pkiMsg Input message + \param pkiMsgSz Input message size + \param output Output buffer + \param outputSz Output buffer size + + _Example_ + \code + int ret = wc_PKCS7_DecodeCompressedData(&pkcs7, msg, msgSz, out, + outSz); + \endcode + + \sa wc_PKCS7_EncodeCompressedData +*/ +int wc_PKCS7_DecodeCompressedData(wc_PKCS7* pkcs7, byte* pkiMsg, + word32 pkiMsgSz, byte* output, + word32 outputSz); diff --git a/doc/dox_comments/header_files/poly1305.h b/doc/dox_comments/header_files/poly1305.h index 725526e23..dcbce80d4 100644 --- a/doc/dox_comments/header_files/poly1305.h +++ b/doc/dox_comments/header_files/poly1305.h @@ -137,3 +137,71 @@ int wc_Poly1305Final(Poly1305* poly1305, byte* tag); */ int wc_Poly1305_MAC(Poly1305* ctx, const byte* additional, word32 addSz, const byte* input, word32 sz, byte* tag, word32 tagSz); + +/*! + \ingroup Poly1305 + \brief Adds padding to Poly1305 context. + + \return 0 on success + \return BAD_FUNC_ARG if ctx is NULL + + \param ctx Poly1305 context + \param lenToPad Length to pad + + _Example_ + \code + Poly1305 ctx; + byte key[32]; + wc_Poly1305SetKey(&ctx, key, sizeof(key)); + int ret = wc_Poly1305_Pad(&ctx, 10); + \endcode + + \sa wc_Poly1305_MAC +*/ +int wc_Poly1305_Pad(Poly1305* ctx, word32 lenToPad); + +/*! + \ingroup Poly1305 + \brief Encodes AAD and data sizes for Poly1305. + + \return 0 on success + \return BAD_FUNC_ARG if ctx is NULL + + \param ctx Poly1305 context + \param aadSz Additional authenticated data size + \param dataSz Data size + + _Example_ + \code + Poly1305 ctx; + byte key[32]; + wc_Poly1305SetKey(&ctx, key, sizeof(key)); + int ret = wc_Poly1305_EncodeSizes(&ctx, 16, 100); + \endcode + + \sa wc_Poly1305_MAC +*/ +int wc_Poly1305_EncodeSizes(Poly1305* ctx, word32 aadSz, word32 dataSz); + +/*! + \ingroup Poly1305 + \brief Encodes AAD and data sizes for Poly1305 using 64-bit values. + + \return 0 on success + \return BAD_FUNC_ARG if ctx is NULL + + \param ctx Poly1305 context + \param aadSz Additional authenticated data size + \param dataSz Data size + + _Example_ + \code + Poly1305 ctx; + byte key[32]; + wc_Poly1305SetKey(&ctx, key, sizeof(key)); + int ret = wc_Poly1305_EncodeSizes64(&ctx, 16, 100); + \endcode + + \sa wc_Poly1305_EncodeSizes +*/ +int wc_Poly1305_EncodeSizes64(Poly1305* ctx, word64 aadSz, word64 dataSz); diff --git a/doc/dox_comments/header_files/psa.h b/doc/dox_comments/header_files/psa.h index 7c87f0bf4..3eb29c339 100644 --- a/doc/dox_comments/header_files/psa.h +++ b/doc/dox_comments/header_files/psa.h @@ -94,3 +94,65 @@ void wolfSSL_free_psa_ctx(struct psa_ssl_ctx *ctx); int wolfSSL_psa_set_private_key_id(struct psa_ssl_ctx *ctx, psa_key_id_t id); + +/*! + \ingroup PSA + \brief This function generates random bytes using the PSA crypto API. + This is a wrapper around the PSA random number generation functions. + + \return 0 On success + \return Negative value on error + + \param out pointer to buffer to store random bytes + \param sz number of random bytes to generate + + _Example_ + \code + byte random[32]; + + int ret = wc_psa_get_random(random, sizeof(random)); + if (ret != 0) { + // error generating random bytes + } + \endcode + + \sa wc_RNG_GenerateBlock +*/ +int wc_psa_get_random(unsigned char *out, word32 sz); + +/*! + \ingroup PSA + \brief This function performs AES encryption or decryption using the + PSA crypto API. It supports various AES modes through the algorithm + parameter. + + \return 0 On success + \return Negative value on error + + \param aes pointer to initialized Aes structure + \param input pointer to input data buffer + \param output pointer to output data buffer + \param length length of data to process + \param alg PSA algorithm identifier specifying the AES mode + \param direction encryption (1) or decryption (0) + + _Example_ + \code + Aes aes; + byte key[16] = { }; // AES key + byte input[16] = { }; // plaintext + byte output[16]; + + wc_AesInit(&aes, NULL, INVALID_DEVID); + wc_AesSetKey(&aes, key, sizeof(key), NULL, AES_ENCRYPTION); + int ret = wc_psa_aes_encrypt_decrypt(&aes, input, output, + sizeof(input), + PSA_ALG_ECB_NO_PADDING, 1); + \endcode + + \sa wc_AesEncrypt + \sa wc_AesDecrypt +*/ +int wc_psa_aes_encrypt_decrypt(Aes *aes, const uint8_t *input, + uint8_t *output, size_t length, + psa_algorithm_t alg, int direction); diff --git a/doc/dox_comments/header_files/pwdbased.h b/doc/dox_comments/header_files/pwdbased.h index e5dd9c79b..25870b835 100644 --- a/doc/dox_comments/header_files/pwdbased.h +++ b/doc/dox_comments/header_files/pwdbased.h @@ -168,3 +168,173 @@ int wc_PBKDF2(byte* output, const byte* passwd, int pLen, int wc_PKCS12_PBKDF(byte* output, const byte* passwd, int passLen, const byte* salt, int saltLen, int iterations, int kLen, int hashType, int id); + +/*! + \ingroup Password + \brief Extended version of PBKDF1 with heap hint. + + \return 0 on success + \return BAD_FUNC_ARG on invalid arguments + \return MEMORY_E on memory allocation error + + \param key Output key buffer + \param keyLen Key length + \param iv Output IV buffer + \param ivLen IV length + \param passwd Password buffer + \param passwdLen Password length + \param salt Salt buffer + \param saltLen Salt length + \param iterations Iteration count + \param hashType Hash algorithm type + \param heap Heap hint for memory allocation + + _Example_ + \code + byte key[16], iv[16]; + byte pass[] = "password"; + byte salt[] = "salt"; + int ret = wc_PBKDF1_ex(key, sizeof(key), iv, sizeof(iv), + pass, sizeof(pass), salt, sizeof(salt), 1000, WC_SHA, NULL); + \endcode + + \sa wc_PBKDF1 +*/ +int wc_PBKDF1_ex(byte* key, int keyLen, byte* iv, int ivLen, + const byte* passwd, int passwdLen, const byte* salt, int saltLen, + int iterations, int hashType, void* heap); + +/*! + \ingroup Password + \brief Extended version of PBKDF2 with heap hint and device ID. + + \return 0 on success + \return BAD_FUNC_ARG on invalid arguments + \return MEMORY_E on memory allocation error + + \param output Output key buffer + \param passwd Password buffer + \param pLen Password length + \param salt Salt buffer + \param sLen Salt length + \param iterations Iteration count + \param kLen Key length + \param hashType Hash algorithm type + \param heap Heap hint for memory allocation + \param devId Device ID for hardware acceleration + + _Example_ + \code + byte key[32]; + byte pass[] = "password"; + byte salt[] = "salt"; + int ret = wc_PBKDF2_ex(key, pass, sizeof(pass), salt, + sizeof(salt), 2048, sizeof(key), WC_SHA256, NULL, + INVALID_DEVID); + \endcode + + \sa wc_PBKDF2 +*/ +int wc_PBKDF2_ex(byte* output, const byte* passwd, int pLen, + const byte* salt, int sLen, int iterations, int kLen, + int hashType, void* heap, int devId); + +/*! + \ingroup Password + \brief Extended version of PKCS12_PBKDF with heap hint. + + \return 0 on success + \return BAD_FUNC_ARG on invalid arguments + \return MEMORY_E on memory allocation error + + \param output Output key buffer + \param passwd Password buffer + \param passLen Password length + \param salt Salt buffer + \param saltLen Salt length + \param iterations Iteration count + \param kLen Key length + \param hashType Hash algorithm type + \param id Purpose identifier (1=key, 2=IV, 3=MAC) + \param heap Heap hint for memory allocation + + _Example_ + \code + byte key[32]; + byte pass[] = "password"; + byte salt[] = "salt"; + int ret = wc_PKCS12_PBKDF_ex(key, pass, sizeof(pass), salt, + sizeof(salt), 2048, sizeof(key), WC_SHA256, 1, NULL); + \endcode + + \sa wc_PKCS12_PBKDF +*/ +int wc_PKCS12_PBKDF_ex(byte* output, const byte* passwd,int passLen, + const byte* salt, int saltLen, int iterations, int kLen, + int hashType, int id, void* heap); + +/*! + \ingroup Password + \brief Implements scrypt key derivation function. + + \return 0 on success + \return BAD_FUNC_ARG on invalid arguments + \return MEMORY_E on memory allocation error + + \param output Output key buffer + \param passwd Password buffer + \param passLen Password length + \param salt Salt buffer + \param saltLen Salt length + \param cost CPU/memory cost parameter (N) + \param blockSize Block size parameter (r) + \param parallel Parallelization parameter (p) + \param dkLen Derived key length + + _Example_ + \code + byte key[32]; + byte pass[] = "password"; + byte salt[] = "salt"; + int ret = wc_scrypt(key, pass, sizeof(pass), salt, + sizeof(salt), 16384, 8, 1, sizeof(key)); + \endcode + + \sa wc_scrypt_ex +*/ +int wc_scrypt(byte* output, const byte* passwd, int passLen, + const byte* salt, int saltLen, int cost, int blockSize, + int parallel, int dkLen); + +/*! + \ingroup Password + \brief Extended scrypt with iteration count instead of cost. + + \return 0 on success + \return BAD_FUNC_ARG on invalid arguments + \return MEMORY_E on memory allocation error + + \param output Output key buffer + \param passwd Password buffer + \param passLen Password length + \param salt Salt buffer + \param saltLen Salt length + \param iterations Iteration count + \param blockSize Block size parameter (r) + \param parallel Parallelization parameter (p) + \param dkLen Derived key length + + _Example_ + \code + byte key[32]; + byte pass[] = "password"; + byte salt[] = "salt"; + int ret = wc_scrypt_ex(key, pass, sizeof(pass), salt, + sizeof(salt), 16384, 8, 1, sizeof(key)); + \endcode + + \sa wc_scrypt +*/ +int wc_scrypt_ex(byte* output, const byte* passwd, int passLen, + const byte* salt, int saltLen, word32 iterations, int blockSize, + int parallel, int dkLen); diff --git a/doc/dox_comments/header_files/quic.h b/doc/dox_comments/header_files/quic.h index 66b19a9ec..f7c3a980e 100644 --- a/doc/dox_comments/header_files/quic.h +++ b/doc/dox_comments/header_files/quic.h @@ -342,6 +342,42 @@ WOLFSSL_API int wolfSSL_process_quic_post_handshake(WOLFSSL *ssl); */ int wolfSSL_quic_read_write(WOLFSSL *ssl); +/*! + \ingroup QUIC + + \brief Perform the QUIC handshake. This function processes CRYPTO + data that has been provided via wolfSSL_provide_quic_data() and + advances the handshake state. It should be called repeatedly until + the handshake is complete. + + \return WOLFSSL_SUCCESS If handshake completed successfully + \return WOLFSSL_FATAL_ERROR If a fatal error occurred + \return Other values indicating handshake is in progress + + \param ssl pointer to a WOLFSSL structure created using + wolfSSL_new() + + _Example_ + \code + WOLFSSL* ssl; + // initialize ssl with QUIC method + + while (!wolfSSL_is_init_finished(ssl)) { + int ret = wolfSSL_quic_do_handshake(ssl); + if (ret == WOLFSSL_FATAL_ERROR) { + // handle error + break; + } + // provide more CRYPTO data if available + } + \endcode + + \sa wolfSSL_provide_quic_data + \sa wolfSSL_quic_read_write + \sa wolfSSL_is_init_finished +*/ +int wolfSSL_quic_do_handshake(WOLFSSL* ssl); + /*! \ingroup QUIC diff --git a/doc/dox_comments/header_files/random.h b/doc/dox_comments/header_files/random.h index 8d415db21..16e8fd662 100644 --- a/doc/dox_comments/header_files/random.h +++ b/doc/dox_comments/header_files/random.h @@ -325,3 +325,323 @@ WC_RNG* wc_rng_free(WC_RNG* rng); int wc_RNG_HealthTest(int reseed, const byte* seedA, word32 seedASz, const byte* seedB, word32 seedBSz, byte* output, word32 outputSz); + +/*! + \ingroup Random + \brief Generates seed from OS entropy source. Lower-level function + used internally by wc_InitRng. + + \return 0 On success + \return WINCRYPT_E Failed to acquire context (Windows) + \return CRYPTGEN_E Failed to generate random (Windows) + \return RNG_FAILURE_E Failed to read entropy + + \param os Pointer to OS_Seed structure + \param output Buffer to store seed + \param sz Size of seed in bytes + + _Example_ + \code + OS_Seed os; + byte seed[32]; + int ret = wc_GenerateSeed(&os, seed, sizeof(seed)); + \endcode + + \sa wc_InitRng +*/ +int wc_GenerateSeed(OS_Seed* os, byte* output, word32 sz); + +/*! + \ingroup Random + \brief Allocates and initializes new WC_RNG with optional nonce. + + \return Pointer to WC_RNG on success + \return NULL on failure + + \param nonce Nonce buffer (can be NULL) + \param nonceSz Nonce size + \param heap Heap hint (can be NULL) + + _Example_ + \code + WC_RNG* rng = wc_rng_new(NULL, 0, NULL); + wc_rng_free(rng); + \endcode + + \sa wc_rng_free +*/ +WC_RNG* wc_rng_new(byte* nonce, word32 nonceSz, void* heap); + +/*! + \ingroup Random + \brief Allocates and initializes WC_RNG with extended parameters. + + \return 0 On success + \return BAD_FUNC_ARG If rng is NULL + \return MEMORY_E Memory allocation failed + + \param rng Pointer to store WC_RNG pointer + \param nonce Nonce buffer (can be NULL) + \param nonceSz Nonce size + \param heap Heap hint (can be NULL) + \param devId Device ID (INVALID_DEVID for software) + + _Example_ + \code + WC_RNG* rng; + int ret = wc_rng_new_ex(&rng, NULL, 0, NULL, INVALID_DEVID); + wc_rng_free(rng); + \endcode + + \sa wc_rng_new +*/ +int wc_rng_new_ex(WC_RNG **rng, byte* nonce, word32 nonceSz, void* heap, + int devId); + +/*! + \ingroup Random + \brief Frees WC_RNG allocated with wc_rng_new. + + \param rng WC_RNG to free + + _Example_ + \code + WC_RNG* rng = wc_rng_new(NULL, 0, NULL); + wc_rng_free(rng); + \endcode + + \sa wc_rng_new +*/ +void wc_rng_free(WC_RNG* rng); + +/*! + \ingroup Random + \brief Initializes WC_RNG with extended parameters. + + \return 0 On success + \return BAD_FUNC_ARG If rng is NULL + \return RNG_FAILURE_E Initialization failed + + \param rng WC_RNG to initialize + \param heap Heap hint (can be NULL) + \param devId Device ID (INVALID_DEVID for software) + + _Example_ + \code + WC_RNG rng; + int ret = wc_InitRng_ex(&rng, NULL, INVALID_DEVID); + wc_FreeRng(&rng); + \endcode + + \sa wc_InitRng +*/ +int wc_InitRng_ex(WC_RNG* rng, void* heap, int devId); + +/*! + \ingroup Random + \brief Initializes WC_RNG with nonce. + + \return 0 On success + \return BAD_FUNC_ARG If rng is NULL + \return RNG_FAILURE_E Initialization failed + + \param rng WC_RNG to initialize + \param nonce Nonce buffer + \param nonceSz Nonce size + + _Example_ + \code + WC_RNG rng; + byte nonce[16]; + int ret = wc_InitRngNonce(&rng, nonce, sizeof(nonce)); + wc_FreeRng(&rng); + \endcode + + \sa wc_InitRng +*/ +int wc_InitRngNonce(WC_RNG* rng, byte* nonce, word32 nonceSz); + +/*! + \ingroup Random + \brief Initializes WC_RNG with nonce and extended parameters. + + \return 0 On success + \return BAD_FUNC_ARG If rng is NULL + \return RNG_FAILURE_E Initialization failed + + \param rng WC_RNG to initialize + \param nonce Nonce buffer + \param nonceSz Nonce size + \param heap Heap hint (can be NULL) + \param devId Device ID (INVALID_DEVID for software) + + _Example_ + \code + WC_RNG rng; + byte nonce[16]; + int ret = wc_InitRngNonce_ex(&rng, nonce, sizeof(nonce), NULL, + INVALID_DEVID); + wc_FreeRng(&rng); + \endcode + + \sa wc_InitRngNonce +*/ +int wc_InitRngNonce_ex(WC_RNG* rng, byte* nonce, word32 nonceSz, + void* heap, int devId); + +/*! + \ingroup Random + \brief Sets callback for custom seed generation. + + \return 0 On success + \return BAD_FUNC_ARG If cb is NULL + + \param cb Seed callback function + + _Example_ + \code + int my_cb(OS_Seed* os, byte* out, word32 sz) { return 0; } + wc_SetSeed_Cb(my_cb); + \endcode + + \sa wc_GenerateSeed +*/ +int wc_SetSeed_Cb(wc_RngSeed_Cb cb); + +/*! + \ingroup Random + \brief Reseeds DRBG with new entropy. + + \return 0 On success + \return BAD_FUNC_ARG If rng or seed is NULL + \return RNG_FAILURE_E Reseed failed + + \param rng WC_RNG to reseed + \param seed Seed buffer + \param seedSz Seed size + + _Example_ + \code + WC_RNG rng; + byte seed[32]; + wc_InitRng(&rng); + int ret = wc_RNG_DRBG_Reseed(&rng, seed, sizeof(seed)); + \endcode + + \sa wc_InitRng +*/ +int wc_RNG_DRBG_Reseed(WC_RNG* rng, const byte* seed, word32 seedSz); + +/*! + \ingroup Random + \brief Tests seed validity for DRBG. + + \return 0 If valid + \return BAD_FUNC_ARG If seed is NULL + \return RNG_FAILURE_E Validation failed + + \param seed Seed to test + \param seedSz Seed size + + _Example_ + \code + byte seed[32]; + int ret = wc_RNG_TestSeed(seed, sizeof(seed)); + \endcode + + \sa wc_InitRng +*/ +int wc_RNG_TestSeed(const byte* seed, word32 seedSz); + +/*! + \ingroup Random + \brief RNG health test with extended parameters. + + \return 0 On success + \return BAD_FUNC_ARG If required params NULL + \return -1 Test failed + + \param reseed Non-zero to test reseeding + \param nonce Nonce buffer (can be NULL) + \param nonceSz Nonce size + \param seedA Initial seed + \param seedASz Initial seed size + \param seedB Reseed buffer (required if reseed set) + \param seedBSz Reseed size + \param output Output buffer + \param outputSz Output size + \param heap Heap hint (can be NULL) + \param devId Device ID (INVALID_DEVID for software) + + _Example_ + \code + byte seedA[32], seedB[32], out[64]; + int ret = wc_RNG_HealthTest_ex(1, NULL, 0, seedA, 32, seedB, 32, + out, 64, NULL, INVALID_DEVID); + \endcode + + \sa wc_RNG_HealthTest +*/ +int wc_RNG_HealthTest_ex(int reseed, const byte* nonce, word32 nonceSz, + const byte* seedA, word32 seedASz, + const byte* seedB, word32 seedBSz, byte* output, + word32 outputSz, void* heap, int devId); + +/*! + \ingroup Random + \brief Gets raw entropy without DRBG processing. + + \return 0 On success + \return BAD_FUNC_ARG If raw is NULL + \return RNG_FAILURE_E Failed + + \param raw Buffer for entropy + \param cnt Bytes to retrieve + + _Example_ + \code + byte raw[32]; + int ret = wc_Entropy_GetRawEntropy(raw, sizeof(raw)); + \endcode + + \sa wc_Entropy_Get +*/ +int wc_Entropy_GetRawEntropy(unsigned char* raw, int cnt); + +/*! + \ingroup Random + \brief Gets processed entropy with specified bits. + + \return 0 On success + \return BAD_FUNC_ARG If entropy is NULL + \return RNG_FAILURE_E Failed + + \param bits Entropy bits required + \param entropy Buffer for entropy + \param len Buffer size + + _Example_ + \code + byte entropy[32]; + int ret = wc_Entropy_Get(256, entropy, sizeof(entropy)); + \endcode + + \sa wc_Entropy_GetRawEntropy +*/ +int wc_Entropy_Get(int bits, unsigned char* entropy, word32 len); + +/*! + \ingroup Random + \brief Tests entropy source on demand. + + \return 0 On success + \return RNG_FAILURE_E Test failed + + _Example_ + \code + int ret = wc_Entropy_OnDemandTest(); + \endcode + + \sa wc_Entropy_Get +*/ +int wc_Entropy_OnDemandTest(void); diff --git a/doc/dox_comments/header_files/rsa.h b/doc/dox_comments/header_files/rsa.h index 692821828..895ea6c6c 100644 --- a/doc/dox_comments/header_files/rsa.h +++ b/doc/dox_comments/header_files/rsa.h @@ -43,6 +43,9 @@ int wc_InitRsaKey(RsaKey* key, void* heap); The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled. + \note This API is only available when WOLF_PRIVATE_KEY_ID is defined, + which is set for PKCS11 support. + \return 0 Returned upon successfully initializing the RSA structure for use with encryption and decryption \return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL @@ -1612,3 +1615,591 @@ int wc_RsaSetNonBlock(RsaKey* key, RsaNb* nb); */ int wc_RsaSetNonBlockTime(RsaKey* key, word32 maxBlockUs, word32 cpuMHz); +/*! + \ingroup RSA + \brief Initializes RSA key with heap and device ID. + + \return 0 on success + \return negative on error + + \param key RSA key structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + RsaKey key; + int ret = wc_InitRsaKey_ex(&key, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitRsaKey +*/ +int wc_InitRsaKey_ex(RsaKey* key, void* heap, int devId); + +/*! + \ingroup RSA + \brief Allocates and initializes new RSA key. These New/Delete functions + are exposed to support allocation of the structure using dynamic memory + to provide better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return RsaKey pointer on success + \return NULL on failure + + \param heap Heap hint + \param devId Device ID + \param result_code Result code pointer + + _Example_ + \code + int result; + RsaKey* key = wc_NewRsaKey(NULL, INVALID_DEVID, &result); + \endcode + + \sa wc_DeleteRsaKey +*/ +RsaKey* wc_NewRsaKey(void* heap, int devId, int *result_code); + +/*! + \ingroup RSA + \brief Deletes and frees RSA key. These New/Delete functions are exposed + to support allocation of the structure using dynamic memory to provide + better ABI compatibility. + + \note This API is only available when WC_NO_CONSTRUCTORS is not defined. + WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is + defined. + + \return 0 on success + \return negative on error + + \param key RSA key to delete + \param key_p Pointer to key pointer + + _Example_ + \code + RsaKey* key; + int ret = wc_DeleteRsaKey(key, &key); + \endcode + + \sa wc_NewRsaKey +*/ +int wc_DeleteRsaKey(RsaKey* key, RsaKey** key_p); + +/*! + \ingroup RSA + \brief Initializes RSA key with label. + + \note This API is only available when WOLF_PRIVATE_KEY_ID is defined, + which is set for PKCS11 support. + + \return 0 on success + \return negative on error + + \param key RSA key structure + \param label Label string + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + RsaKey key; + int ret = wc_InitRsaKey_Label(&key, "mykey", NULL, + INVALID_DEVID); + \endcode + + \sa wc_InitRsaKey_ex +*/ +int wc_InitRsaKey_Label(RsaKey* key, const char* label, void* heap, + int devId); + +/*! + \ingroup RSA + \brief Checks RSA key validity. + + \return 0 on success + \return negative on error + + \param key RSA key to check + + _Example_ + \code + RsaKey key; + int ret = wc_CheckRsaKey(&key); + \endcode + + \sa wc_MakeRsaKey +*/ +int wc_CheckRsaKey(RsaKey* key); + +/*! + \ingroup RSA + \brief Uses key ID for hardware RSA. + + \return 0 on success + \return negative on error + + \param key RSA key + \param keyId Key identifier + \param flags Flags + + _Example_ + \code + RsaKey key; + int ret = wc_RsaUseKeyId(&key, 1, 0); + \endcode + + \sa wc_RsaGetKeyId +*/ +int wc_RsaUseKeyId(RsaKey* key, word32 keyId, word32 flags); + +/*! + \ingroup RSA + \brief Gets key ID from hardware RSA key. + + \return 0 on success + \return negative on error + + \param key RSA key + \param keyId Key identifier pointer + + _Example_ + \code + RsaKey key; + word32 keyId; + int ret = wc_RsaGetKeyId(&key, &keyId); + \endcode + + \sa wc_RsaUseKeyId +*/ +int wc_RsaGetKeyId(RsaKey* key, word32* keyId); + +/*! + \ingroup RSA + \brief Performs RSA operation. + + \return 0 on success + \return negative on error + + \param in Input buffer + \param inLen Input length + \param out Output buffer + \param outLen Output length pointer + \param type Operation type + \param key RSA key + \param rng Random number generator + + _Example_ + \code + RsaKey key; + WC_RNG rng; + byte in[256], out[256]; + word32 outLen = sizeof(out); + int ret = wc_RsaFunction(in, 256, out, &outLen, + RSA_PUBLIC_ENCRYPT, &key, &rng); + \endcode + + \sa wc_RsaPublicEncrypt +*/ +int wc_RsaFunction(const byte* in, word32 inLen, byte* out, + word32* outLen, int type, RsaKey* key, WC_RNG* rng); + +/*! + \ingroup RSA + \brief Signs with RSA-PSS extended options. + + \return Size of signature on success + \return negative on error + + \param in Input buffer + \param inLen Input length + \param out Output buffer + \param outLen Output buffer size + \param hash Hash type + \param mgf MGF type + \param saltLen Salt length + \param key RSA key + \param rng Random number generator + + _Example_ + \code + RsaKey key; + WC_RNG rng; + byte in[32], sig[256]; + int ret = wc_RsaPSS_Sign_ex(in, 32, sig, sizeof(sig), + WC_HASH_TYPE_SHA256, + WC_MGF1SHA256, 32, &key, &rng); + \endcode + + \sa wc_RsaPSS_Sign +*/ +int wc_RsaPSS_Sign_ex(const byte* in, word32 inLen, byte* out, + word32 outLen, enum wc_HashType hash, int mgf, int saltLen, + RsaKey* key, WC_RNG* rng); + +/*! + \ingroup RSA + \brief Verifies RSA signature with padding type. + + \return Size of decrypted data on success + \return negative on error + + \param in Input signature + \param inLen Signature length + \param out Output buffer + \param outLen Output buffer size + \param key RSA key + \param pad_type Padding type + + _Example_ + \code + RsaKey key; + byte sig[256], out[256]; + int ret = wc_RsaSSL_Verify_ex(sig, 256, out, sizeof(out), + &key, RSA_PKCS1_PADDING); + \endcode + + \sa wc_RsaSSL_Verify +*/ +int wc_RsaSSL_Verify_ex(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key, int pad_type); + +/*! + \ingroup RSA + \brief Verifies RSA signature with hash type. + + \return Size of decrypted data on success + \return negative on error + + \param in Input signature + \param inLen Signature length + \param out Output buffer + \param outLen Output buffer size + \param key RSA key + \param pad_type Padding type + \param hash Hash type + + _Example_ + \code + RsaKey key; + byte sig[256], out[256]; + int ret = wc_RsaSSL_Verify_ex2(sig, 256, out, sizeof(out), + &key, RSA_PKCS1_PADDING, + WC_HASH_TYPE_SHA256); + \endcode + + \sa wc_RsaSSL_Verify_ex +*/ +int wc_RsaSSL_Verify_ex2(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key, int pad_type, + enum wc_HashType hash); + +/*! + \ingroup RSA + \brief Verifies RSA-PSS inline with extended options. + + \return Size of verified data on success + \return negative on error + + \param in Input/output buffer + \param inLen Input length + \param out Output pointer + \param hash Hash type + \param mgf MGF type + \param saltLen Salt length + \param key RSA key + + _Example_ + \code + RsaKey key; + byte sig[256]; + byte* out; + int ret = wc_RsaPSS_VerifyInline_ex(sig, 256, &out, + WC_HASH_TYPE_SHA256, + WC_MGF1SHA256, 32, &key); + \endcode + + \sa wc_RsaPSS_VerifyInline +*/ +int wc_RsaPSS_VerifyInline_ex(byte* in, word32 inLen, byte** out, + enum wc_HashType hash, int mgf, int saltLen, RsaKey* key); + +/*! + \ingroup RSA + \brief Verifies RSA-PSS with extended options. + + \return Size of verified data on success + \return negative on error + + \param in Input signature + \param inLen Signature length + \param out Output buffer + \param outLen Output buffer size + \param hash Hash type + \param mgf MGF type + \param saltLen Salt length + \param key RSA key + + _Example_ + \code + RsaKey key; + byte sig[256], out[256]; + int ret = wc_RsaPSS_Verify_ex(sig, 256, out, sizeof(out), + WC_HASH_TYPE_SHA256, + WC_MGF1SHA256, 32, &key); + \endcode + + \sa wc_RsaPSS_Verify +*/ +int wc_RsaPSS_Verify_ex(const byte* in, word32 inLen, byte* out, + word32 outLen, enum wc_HashType hash, int mgf, int saltLen, + RsaKey* key); + +/*! + \ingroup RSA + \brief Checks RSA-PSS padding with extended options. + + \return 0 on success + \return negative on error + + \param in Padded data + \param inLen Padded data length + \param sig Signature + \param sigSz Signature size + \param hashType Hash type + \param saltLen Salt length + \param bits Key size in bits + \param heap Heap hint + + _Example_ + \code + byte padded[256], sig[256]; + int ret = wc_RsaPSS_CheckPadding_ex2(padded, 256, sig, 256, + WC_HASH_TYPE_SHA256, 32, + 2048, NULL); + \endcode + + \sa wc_RsaPSS_CheckPadding_ex +*/ +int wc_RsaPSS_CheckPadding_ex2(const byte* in, word32 inLen, + const byte* sig, word32 sigSz, enum wc_HashType hashType, + int saltLen, int bits, void* heap); + +/*! + \ingroup RSA + \brief Exports RSA key components. + + \return 0 on success + \return negative on error + + \param key RSA key + \param e Public exponent buffer + \param eSz Public exponent size pointer + \param n Modulus buffer + \param nSz Modulus size pointer + \param d Private exponent buffer + \param dSz Private exponent size pointer + \param p Prime p buffer + \param pSz Prime p size pointer + \param q Prime q buffer + \param qSz Prime q size pointer + + _Example_ + \code + RsaKey key; + byte e[3], n[256], d[256], p[128], q[128]; + word32 eSz = 3, nSz = 256, dSz = 256, pSz = 128, qSz = 128; + int ret = wc_RsaExportKey(&key, e, &eSz, n, &nSz, d, &dSz, + p, &pSz, q, &qSz); + \endcode + + \sa wc_RsaFlattenPublicKey +*/ +int wc_RsaExportKey(const RsaKey* key, byte* e, word32* eSz, + byte* n, word32* nSz, byte* d, word32* dSz, byte* p, + word32* pSz, byte* q, word32* qSz); + +/*! + \ingroup RSA + \brief Checks probable prime with extended options. + + \return 0 on success + \return negative on error + + \param p Prime p buffer + \param pSz Prime p size + \param q Prime q buffer + \param qSz Prime q size + \param e Public exponent buffer + \param eSz Public exponent size + \param nlen Modulus length + \param isPrime Prime result pointer + \param rng Random number generator + + _Example_ + \code + byte p[128], q[128], e[3]; + int isPrime; + WC_RNG rng; + int ret = wc_CheckProbablePrime_ex(p, 128, q, 128, e, 3, + 2048, &isPrime, &rng); + \endcode + + \sa wc_CheckProbablePrime +*/ +int wc_CheckProbablePrime_ex(const byte* p, word32 pSz, + const byte* q, word32 qSz, const byte* e, word32 eSz, + int nlen, int* isPrime, WC_RNG* rng); + +/*! + \ingroup RSA + \brief Checks probable prime. + + \return 0 on success + \return negative on error + + \param p Prime p buffer + \param pSz Prime p size + \param q Prime q buffer + \param qSz Prime q size + \param e Public exponent buffer + \param eSz Public exponent size + \param nlen Modulus length + \param isPrime Prime result pointer + + _Example_ + \code + byte p[128], q[128], e[3]; + int isPrime; + int ret = wc_CheckProbablePrime(p, 128, q, 128, e, 3, 2048, + &isPrime); + \endcode + + \sa wc_CheckProbablePrime_ex +*/ +int wc_CheckProbablePrime(const byte* p, word32 pSz, + const byte* q, word32 qSz, const byte* e, word32 eSz, + int nlen, int* isPrime); + +/*! + \ingroup RSA + \brief Pads data with extended options. + + \return 0 on success + \return negative on error + + \param input Input data + \param inputLen Input length + \param pkcsBlock Output padded block + \param pkcsBlockLen Padded block size + \param padValue Pad value + \param rng Random number generator + \param padType Padding type + \param hType Hash type + \param mgf MGF type + \param optLabel Optional label + \param labelLen Label length + \param saltLen Salt length + \param bits Key size in bits + \param heap Heap hint + + _Example_ + \code + byte in[32], padded[256]; + WC_RNG rng; + int ret = wc_RsaPad_ex(in, 32, padded, 256, 0x00, &rng, + RSA_BLOCK_TYPE_1, + WC_HASH_TYPE_SHA256, WC_MGF1SHA256, + NULL, 0, 32, 2048, NULL); + \endcode + + \sa wc_RsaUnPad_ex +*/ +int wc_RsaPad_ex(const byte* input, word32 inputLen, + byte* pkcsBlock, word32 pkcsBlockLen, byte padValue, + WC_RNG* rng, int padType, enum wc_HashType hType, int mgf, + byte* optLabel, word32 labelLen, int saltLen, int bits, + void* heap); + +/*! + \ingroup RSA + \brief Unpads data with extended options. + + \return Size of unpadded data on success + \return negative on error + + \param pkcsBlock Padded block + \param pkcsBlockLen Padded block length + \param out Output pointer + \param padValue Pad value + \param padType Padding type + \param hType Hash type + \param mgf MGF type + \param optLabel Optional label + \param labelLen Label length + \param saltLen Salt length + \param bits Key size in bits + \param heap Heap hint + + _Example_ + \code + byte padded[256]; + byte* out; + int ret = wc_RsaUnPad_ex(padded, 256, &out, 0x00, + RSA_BLOCK_TYPE_1, + WC_HASH_TYPE_SHA256, WC_MGF1SHA256, + NULL, 0, 32, 2048, NULL); + \endcode + + \sa wc_RsaPad_ex +*/ +int wc_RsaUnPad_ex(byte* pkcsBlock, word32 pkcsBlockLen, + byte** out, byte padValue, int padType, + enum wc_HashType hType, int mgf, byte* optLabel, + word32 labelLen, int saltLen, int bits, void* heap); + +/*! + \ingroup RSA + \brief Decodes raw RSA private key. + + \return 0 on success + \return negative on error + + \param n Modulus buffer + \param nSz Modulus size + \param e Public exponent buffer + \param eSz Public exponent size + \param d Private exponent buffer + \param dSz Private exponent size + \param u Coefficient buffer + \param uSz Coefficient size + \param p Prime p buffer + \param pSz Prime p size + \param q Prime q buffer + \param qSz Prime q size + \param dP dP buffer + \param dPSz dP size + \param dQ dQ buffer + \param dQSz dQ size + \param key RSA key + + _Example_ + \code + RsaKey key; + byte n[256], e[3], d[256], u[256], p[128], q[128]; + byte dP[128], dQ[128]; + int ret = wc_RsaPrivateKeyDecodeRaw(n, 256, e, 3, d, 256, + u, 256, p, 128, q, 128, + dP, 128, dQ, 128, &key); + \endcode + + \sa wc_RsaPrivateKeyDecode +*/ +int wc_RsaPrivateKeyDecodeRaw(const byte* n, word32 nSz, + const byte* e, word32 eSz, const byte* d, word32 dSz, + const byte* u, word32 uSz, const byte* p, word32 pSz, + const byte* q, word32 qSz, const byte* dP, word32 dPSz, + const byte* dQ, word32 dQSz, RsaKey* key); diff --git a/doc/dox_comments/header_files/sha.h b/doc/dox_comments/header_files/sha.h index 56a9382d4..e6368fa4a 100644 --- a/doc/dox_comments/header_files/sha.h +++ b/doc/dox_comments/header_files/sha.h @@ -142,3 +142,124 @@ void wc_ShaFree(wc_Sha* sha); \sa wc_InitSha */ int wc_ShaGetHash(wc_Sha* sha, byte* hash); +/*! + \ingroup SHA + \brief Initializes SHA with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha SHA structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha sha; + int ret = wc_InitSha_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha +*/ +int wc_InitSha_ex(wc_Sha* sha, void* heap, int devId); + +/*! + \ingroup SHA + \brief Gets raw hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha SHA structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha sha; + byte hash[WC_SHA_DIGEST_SIZE]; + int ret = wc_ShaFinalRaw(&sha, hash); + \endcode + + \sa wc_ShaFinal +*/ +int wc_ShaFinalRaw(wc_Sha* sha, byte* hash); + +/*! + \ingroup SHA + \brief Copies SHA context. + + \return 0 on success + \return negative on error + + \param src Source SHA structure + \param dst Destination SHA structure + + _Example_ + \code + wc_Sha src, dst; + int ret = wc_ShaCopy(&src, &dst); + \endcode + + \sa wc_InitSha +*/ +int wc_ShaCopy(wc_Sha* src, wc_Sha* dst); + +/*! + \ingroup SHA + \brief Transforms SHA block. + + \return 0 on success + \return negative on error + + \param sha SHA structure + \param data Block data + + _Example_ + \code + wc_Sha sha; + unsigned char block[WC_SHA_BLOCK_SIZE]; + int ret = wc_ShaTransform(&sha, block); + \endcode + + \sa wc_ShaUpdate +*/ +int wc_ShaTransform(wc_Sha* sha, const unsigned char* data); + +/*! + \ingroup SHA + \brief Sets SHA size. + + \return none No returns + + \param sha SHA structure + \param len Size to set + + _Example_ + \code + wc_Sha sha; + wc_ShaSizeSet(&sha, 1000); + \endcode + + \sa wc_ShaUpdate +*/ +void wc_ShaSizeSet(wc_Sha* sha, word32 len); + +/*! + \ingroup SHA + \brief Sets SHA flags. + + \return 0 on success + \return negative on error + + \param sha SHA structure + \param flags Flags to set + + _Example_ + \code + wc_Sha sha; + int ret = wc_ShaSetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha +*/ +int wc_ShaSetFlags(wc_Sha* sha, word32 flags); diff --git a/doc/dox_comments/header_files/sha256.h b/doc/dox_comments/header_files/sha256.h index 93bfd836f..3a94b797b 100644 --- a/doc/dox_comments/header_files/sha256.h +++ b/doc/dox_comments/header_files/sha256.h @@ -194,7 +194,7 @@ int wc_InitSha224(wc_Sha224* sha224); _Example_ \code Sha224 sha224; - byte data[] = { /* Data to be hashed }; + byte data[]; // Data to be hashed word32 len = sizeof(data); if ((ret = wc_InitSha224(&sha224)) != 0) { @@ -227,7 +227,7 @@ int wc_Sha224Update(wc_Sha224* sha224, const byte* data, word32 len); _Example_ \code Sha224 sha224; - byte data[] = { /* Data to be hashed }; + byte data[]; // Data to be hashed word32 len = sizeof(data); if ((ret = wc_InitSha224(&sha224)) != 0) { @@ -244,3 +244,344 @@ int wc_Sha224Update(wc_Sha224* sha224, const byte* data, word32 len); \sa wc_Sha224Update */ int wc_Sha224Final(wc_Sha224* sha224, byte* hash); + +/*! + \ingroup SHA + \brief Initializes SHA256 with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha SHA256 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha256 sha; + int ret = wc_InitSha256_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha256 +*/ +int wc_InitSha256_ex(wc_Sha256* sha, void* heap, int devId); + +/*! + \ingroup SHA + \brief Gets raw hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha256 SHA256 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha256 sha; + byte hash[WC_SHA256_DIGEST_SIZE]; + int ret = wc_Sha256FinalRaw(&sha, hash); + \endcode + + \sa wc_Sha256Final +*/ +int wc_Sha256FinalRaw(wc_Sha256* sha256, byte* hash); + +/*! + \ingroup SHA + \brief Transforms SHA256 block. + + \return 0 on success + \return negative on error + + \param sha SHA256 structure + \param data Block data + + _Example_ + \code + wc_Sha256 sha; + unsigned char block[WC_SHA256_BLOCK_SIZE]; + int ret = wc_Sha256Transform(&sha, block); + \endcode + + \sa wc_Sha256Update +*/ +int wc_Sha256Transform(wc_Sha256* sha, const unsigned char* data); + +/*! + \ingroup SHA + \brief Hashes single block and outputs result. + + \return 0 on success + \return negative on error + + \param sha SHA256 structure + \param data Block data + \param hash Output hash buffer + + _Example_ + \code + wc_Sha256 sha; + unsigned char block[WC_SHA256_BLOCK_SIZE]; + unsigned char hash[WC_SHA256_DIGEST_SIZE]; + int ret = wc_Sha256HashBlock(&sha, block, hash); + \endcode + + \sa wc_Sha256Transform +*/ +int wc_Sha256HashBlock(wc_Sha256* sha, const unsigned char* data, + unsigned char* hash); + +/*! + \ingroup SHA + \brief Grows SHA256 buffer with input data. This function is only + available when WOLFSSL_HASH_KEEP is defined. It is used for keeping an + internal buffer to hold all data to be hashed rather than iterating + over update, which is necessary for some hardware acceleration + platforms that have restrictions on streaming hash operations. + + \return 0 on success + \return negative on error + + \param sha256 SHA256 structure + \param in Input data + \param inSz Input size + + _Example_ + \code + wc_Sha256 sha; + byte data[100]; + int ret = wc_Sha256_Grow(&sha, data, sizeof(data)); + \endcode + + \sa wc_Sha256Update +*/ +int wc_Sha256_Grow(wc_Sha256* sha256, const byte* in, int inSz); + +/*! + \ingroup SHA + \brief Copies SHA256 context. + + \return 0 on success + \return negative on error + + \param src Source SHA256 structure + \param dst Destination SHA256 structure + + _Example_ + \code + wc_Sha256 src, dst; + int ret = wc_Sha256Copy(&src, &dst); + \endcode + + \sa wc_InitSha256 +*/ +int wc_Sha256Copy(wc_Sha256* src, wc_Sha256* dst); + +/*! + \ingroup SHA + \brief Sets SHA256 size. + + \return none No returns + + \param sha256 SHA256 structure + \param len Size to set + + _Example_ + \code + wc_Sha256 sha; + wc_Sha256SizeSet(&sha, 1000); + \endcode + + \sa wc_Sha256Update +*/ +void wc_Sha256SizeSet(wc_Sha256* sha256, word32 len); + +/*! + \ingroup SHA + \brief Sets SHA256 flags. + + \return 0 on success + \return negative on error + + \param sha256 SHA256 structure + \param flags Flags to set + + _Example_ + \code + wc_Sha256 sha; + int ret = wc_Sha256SetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha256 +*/ +int wc_Sha256SetFlags(wc_Sha256* sha256, word32 flags); + +/*! + \ingroup SHA + \brief Gets SHA256 flags. + + \return 0 on success + \return negative on error + + \param sha256 SHA256 structure + \param flags Pointer to store flags + + _Example_ + \code + wc_Sha256 sha; + word32 flags; + int ret = wc_Sha256GetFlags(&sha, &flags); + \endcode + + \sa wc_Sha256SetFlags +*/ +int wc_Sha256GetFlags(wc_Sha256* sha256, word32* flags); + +/*! + \ingroup SHA + \brief Initializes SHA224 with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha224 SHA224 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha224 sha; + int ret = wc_InitSha224_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha224 +*/ +int wc_InitSha224_ex(wc_Sha224* sha224, void* heap, int devId); + +/*! + \ingroup SHA + \brief Frees SHA224 resources. + + \return none No returns + + \param sha224 SHA224 structure + + _Example_ + \code + wc_Sha224 sha; + wc_InitSha224(&sha); + wc_Sha224Free(&sha); + \endcode + + \sa wc_InitSha224 +*/ +void wc_Sha224Free(wc_Sha224* sha224); + +/*! + \ingroup SHA + \brief Grows SHA224 buffer with input data. This function is only + available when WOLFSSL_HASH_KEEP is defined. It is used for keeping an + internal buffer to hold all data to be hashed rather than iterating + over update, which is necessary for some hardware acceleration + platforms that have restrictions on streaming hash operations. + + \return 0 on success + \return negative on error + + \param sha224 SHA224 structure + \param in Input data + \param inSz Input size + + _Example_ + \code + wc_Sha224 sha; + byte data[100]; + int ret = wc_Sha224_Grow(&sha, data, sizeof(data)); + \endcode + + \sa wc_Sha224Update +*/ +int wc_Sha224_Grow(wc_Sha224* sha224, const byte* in, int inSz); + +/*! + \ingroup SHA + \brief Gets SHA224 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha224 SHA224 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha224 sha; + byte hash[WC_SHA224_DIGEST_SIZE]; + int ret = wc_Sha224GetHash(&sha, hash); + \endcode + + \sa wc_Sha224Final +*/ +int wc_Sha224GetHash(wc_Sha224* sha224, byte* hash); + +/*! + \ingroup SHA + \brief Copies SHA224 context. + + \return 0 on success + \return negative on error + + \param src Source SHA224 structure + \param dst Destination SHA224 structure + + _Example_ + \code + wc_Sha224 src, dst; + int ret = wc_Sha224Copy(&src, &dst); + \endcode + + \sa wc_InitSha224 +*/ +int wc_Sha224Copy(wc_Sha224* src, wc_Sha224* dst); + +/*! + \ingroup SHA + \brief Sets SHA224 flags. + + \return 0 on success + \return negative on error + + \param sha224 SHA224 structure + \param flags Flags to set + + _Example_ + \code + wc_Sha224 sha; + int ret = wc_Sha224SetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha224 +*/ +int wc_Sha224SetFlags(wc_Sha224* sha224, word32 flags); + +/*! + \ingroup SHA + \brief Gets SHA224 flags. + + \return 0 on success + \return negative on error + + \param sha224 SHA224 structure + \param flags Pointer to store flags + + _Example_ + \code + wc_Sha224 sha; + word32 flags; + int ret = wc_Sha224GetFlags(&sha, &flags); + \endcode + + \sa wc_Sha224SetFlags +*/ +int wc_Sha224GetFlags(wc_Sha224* sha224, word32* flags); diff --git a/doc/dox_comments/header_files/sha512.h b/doc/dox_comments/header_files/sha512.h index 915ae77a1..0f9c129a4 100644 --- a/doc/dox_comments/header_files/sha512.h +++ b/doc/dox_comments/header_files/sha512.h @@ -181,3 +181,827 @@ int wc_Sha384Update(wc_Sha384* sha, const byte* data, word32 len); \sa wc_InitSha384 */ int wc_Sha384Final(wc_Sha384* sha384, byte* hash); + +/*! + \ingroup SHA + \brief Initializes SHA512 with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_InitSha512_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha512 +*/ +int wc_InitSha512_ex(wc_Sha512* sha, void* heap, int devId); + +/*! + \ingroup SHA + \brief Gets raw hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_DIGEST_SIZE]; + int ret = wc_Sha512FinalRaw(&sha, hash); + \endcode + + \sa wc_Sha512Final +*/ +int wc_Sha512FinalRaw(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Frees SHA512 resources. + + \return none No returns + + \param sha SHA512 structure + + _Example_ + \code + wc_Sha512 sha; + wc_InitSha512(&sha); + wc_Sha512Free(&sha); + \endcode + + \sa wc_InitSha512 +*/ +void wc_Sha512Free(wc_Sha512* sha); + +/*! + \ingroup SHA + \brief Gets SHA512 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_DIGEST_SIZE]; + int ret = wc_Sha512GetHash(&sha, hash); + \endcode + + \sa wc_Sha512Final +*/ +int wc_Sha512GetHash(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Copies SHA512 context. + + \return 0 on success + \return negative on error + + \param src Source SHA512 structure + \param dst Destination SHA512 structure + + _Example_ + \code + wc_Sha512 src, dst; + int ret = wc_Sha512Copy(&src, &dst); + \endcode + + \sa wc_InitSha512 +*/ +int wc_Sha512Copy(wc_Sha512* src, wc_Sha512* dst); + +/*! + \ingroup SHA + \brief Grows SHA512 buffer with input data. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param in Input data + \param inSz Input size + + _Example_ + \code + wc_Sha512 sha; + byte data[100]; + int ret = wc_Sha512_Grow(&sha, data, sizeof(data)); + \endcode + + \sa wc_Sha512Update +*/ +int wc_Sha512_Grow(wc_Sha512* sha512, const byte* in, int inSz); + +/*! + \ingroup SHA + \brief Sets SHA512 flags. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param flags Flags to set + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_Sha512SetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha512 +*/ +int wc_Sha512SetFlags(wc_Sha512* sha512, word32 flags); + +/*! + \ingroup SHA + \brief Gets SHA512 flags. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param flags Pointer to store flags + + _Example_ + \code + wc_Sha512 sha; + word32 flags; + int ret = wc_Sha512GetFlags(&sha, &flags); + \endcode + + \sa wc_Sha512SetFlags +*/ +int wc_Sha512GetFlags(wc_Sha512* sha512, word32* flags); + +/*! + \ingroup SHA + \brief Transforms SHA512 block. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param data Block data + + _Example_ + \code + wc_Sha512 sha; + unsigned char block[WC_SHA512_BLOCK_SIZE]; + int ret = wc_Sha512Transform(&sha, block); + \endcode + + \sa wc_Sha512Update +*/ +int wc_Sha512Transform(wc_Sha512* sha, const unsigned char* data); + +/*! + \ingroup SHA + \brief Initializes SHA512/224. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_InitSha512_224(&sha); + \endcode + + \sa wc_Sha512_224Update +*/ +int wc_InitSha512_224(wc_Sha512* sha); + +/*! + \ingroup SHA + \brief Initializes SHA512/224 with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_InitSha512_224_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha512_224 +*/ +int wc_InitSha512_224_ex(wc_Sha512* sha, void* heap, int devId); + +/*! + \ingroup SHA + \brief Updates SHA512/224 hash with data. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param data Input data + \param len Input size + + _Example_ + \code + wc_Sha512 sha; + byte data[100]; + int ret = wc_Sha512_224Update(&sha, data, sizeof(data)); + \endcode + + \sa wc_InitSha512_224 +*/ +int wc_Sha512_224Update(wc_Sha512* sha, const byte* data, word32 len); + +/*! + \ingroup SHA + \brief Gets raw SHA512/224 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_224_DIGEST_SIZE]; + int ret = wc_Sha512_224FinalRaw(&sha, hash); + \endcode + + \sa wc_Sha512_224Final +*/ +int wc_Sha512_224FinalRaw(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Finalizes SHA512/224 hash. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_224_DIGEST_SIZE]; + int ret = wc_Sha512_224Final(&sha, hash); + \endcode + + \sa wc_Sha512_224Update +*/ +int wc_Sha512_224Final(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Frees SHA512/224 resources. + + \return none No returns + + \param sha SHA512 structure + + _Example_ + \code + wc_Sha512 sha; + wc_InitSha512_224(&sha); + wc_Sha512_224Free(&sha); + \endcode + + \sa wc_InitSha512_224 +*/ +void wc_Sha512_224Free(wc_Sha512* sha); + +/*! + \ingroup SHA + \brief Gets SHA512/224 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_224_DIGEST_SIZE]; + int ret = wc_Sha512_224GetHash(&sha, hash); + \endcode + + \sa wc_Sha512_224Final +*/ +int wc_Sha512_224GetHash(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Copies SHA512/224 context. + + \return 0 on success + \return negative on error + + \param src Source SHA512 structure + \param dst Destination SHA512 structure + + _Example_ + \code + wc_Sha512 src, dst; + int ret = wc_Sha512_224Copy(&src, &dst); + \endcode + + \sa wc_InitSha512_224 +*/ +int wc_Sha512_224Copy(wc_Sha512* src, wc_Sha512* dst); + +/*! + \ingroup SHA + \brief Sets SHA512/224 flags. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param flags Flags to set + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_Sha512_224SetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha512_224 +*/ +int wc_Sha512_224SetFlags(wc_Sha512* sha512, word32 flags); + +/*! + \ingroup SHA + \brief Gets SHA512/224 flags. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param flags Pointer to store flags + + _Example_ + \code + wc_Sha512 sha; + word32 flags; + int ret = wc_Sha512_224GetFlags(&sha, &flags); + \endcode + + \sa wc_Sha512_224SetFlags +*/ +int wc_Sha512_224GetFlags(wc_Sha512* sha512, word32* flags); + +/*! + \ingroup SHA + \brief Transforms SHA512/224 block. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param data Block data + + _Example_ + \code + wc_Sha512 sha; + unsigned char block[WC_SHA512_BLOCK_SIZE]; + int ret = wc_Sha512_224Transform(&sha, block); + \endcode + + \sa wc_Sha512_224Update +*/ +int wc_Sha512_224Transform(wc_Sha512* sha, const unsigned char* data); + +/*! + \ingroup SHA + \brief Initializes SHA512/256. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_InitSha512_256(&sha); + \endcode + + \sa wc_Sha512_256Update +*/ +int wc_InitSha512_256(wc_Sha512* sha); + +/*! + \ingroup SHA + \brief Initializes SHA512/256 with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_InitSha512_256_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha512_256 +*/ +int wc_InitSha512_256_ex(wc_Sha512* sha, void* heap, int devId); + +/*! + \ingroup SHA + \brief Updates SHA512/256 hash with data. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param data Input data + \param len Input size + + _Example_ + \code + wc_Sha512 sha; + byte data[100]; + int ret = wc_Sha512_256Update(&sha, data, sizeof(data)); + \endcode + + \sa wc_InitSha512_256 +*/ +int wc_Sha512_256Update(wc_Sha512* sha, const byte* data, word32 len); + +/*! + \ingroup SHA + \brief Gets raw SHA512/256 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_256_DIGEST_SIZE]; + int ret = wc_Sha512_256FinalRaw(&sha, hash); + \endcode + + \sa wc_Sha512_256Final +*/ +int wc_Sha512_256FinalRaw(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Finalizes SHA512/256 hash. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_256_DIGEST_SIZE]; + int ret = wc_Sha512_256Final(&sha, hash); + \endcode + + \sa wc_Sha512_256Update +*/ +int wc_Sha512_256Final(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Frees SHA512/256 resources. + + \return none No returns + + \param sha SHA512 structure + + _Example_ + \code + wc_Sha512 sha; + wc_InitSha512_256(&sha); + wc_Sha512_256Free(&sha); + \endcode + + \sa wc_InitSha512_256 +*/ +void wc_Sha512_256Free(wc_Sha512* sha); + +/*! + \ingroup SHA + \brief Gets SHA512/256 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha512 sha; + byte hash[WC_SHA512_256_DIGEST_SIZE]; + int ret = wc_Sha512_256GetHash(&sha, hash); + \endcode + + \sa wc_Sha512_256Final +*/ +int wc_Sha512_256GetHash(wc_Sha512* sha512, byte* hash); + +/*! + \ingroup SHA + \brief Copies SHA512/256 context. + + \return 0 on success + \return negative on error + + \param src Source SHA512 structure + \param dst Destination SHA512 structure + + _Example_ + \code + wc_Sha512 src, dst; + int ret = wc_Sha512_256Copy(&src, &dst); + \endcode + + \sa wc_InitSha512_256 +*/ +int wc_Sha512_256Copy(wc_Sha512* src, wc_Sha512* dst); + +/*! + \ingroup SHA + \brief Sets SHA512/256 flags. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param flags Flags to set + + _Example_ + \code + wc_Sha512 sha; + int ret = wc_Sha512_256SetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha512_256 +*/ +int wc_Sha512_256SetFlags(wc_Sha512* sha512, word32 flags); + +/*! + \ingroup SHA + \brief Gets SHA512/256 flags. + + \return 0 on success + \return negative on error + + \param sha512 SHA512 structure + \param flags Pointer to store flags + + _Example_ + \code + wc_Sha512 sha; + word32 flags; + int ret = wc_Sha512_256GetFlags(&sha, &flags); + \endcode + + \sa wc_Sha512_256SetFlags +*/ +int wc_Sha512_256GetFlags(wc_Sha512* sha512, word32* flags); + +/*! + \ingroup SHA + \brief Transforms SHA512/256 block. + + \return 0 on success + \return negative on error + + \param sha SHA512 structure + \param data Block data + + _Example_ + \code + wc_Sha512 sha; + unsigned char block[WC_SHA512_BLOCK_SIZE]; + int ret = wc_Sha512_256Transform(&sha, block); + \endcode + + \sa wc_Sha512_256Update +*/ +int wc_Sha512_256Transform(wc_Sha512* sha, const unsigned char* data); + +/*! + \ingroup SHA + \brief Initializes SHA384 with heap and device ID. + + \return 0 on success + \return negative on error + + \param sha SHA384 structure + \param heap Heap hint + \param devId Device ID + + _Example_ + \code + wc_Sha384 sha; + int ret = wc_InitSha384_ex(&sha, NULL, INVALID_DEVID); + \endcode + + \sa wc_InitSha384 +*/ +int wc_InitSha384_ex(wc_Sha384* sha, void* heap, int devId); + +/*! + \ingroup SHA + \brief Gets raw SHA384 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha384 SHA384 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha384 sha; + byte hash[WC_SHA384_DIGEST_SIZE]; + int ret = wc_Sha384FinalRaw(&sha, hash); + \endcode + + \sa wc_Sha384Final +*/ +int wc_Sha384FinalRaw(wc_Sha384* sha384, byte* hash); + +/*! + \ingroup SHA + \brief Frees SHA384 resources. + + \return none No returns + + \param sha SHA384 structure + + _Example_ + \code + wc_Sha384 sha; + wc_InitSha384(&sha); + wc_Sha384Free(&sha); + \endcode + + \sa wc_InitSha384 +*/ +void wc_Sha384Free(wc_Sha384* sha); + +/*! + \ingroup SHA + \brief Gets SHA384 hash without finalizing. + + \return 0 on success + \return negative on error + + \param sha384 SHA384 structure + \param hash Output hash buffer + + _Example_ + \code + wc_Sha384 sha; + byte hash[WC_SHA384_DIGEST_SIZE]; + int ret = wc_Sha384GetHash(&sha, hash); + \endcode + + \sa wc_Sha384Final +*/ +int wc_Sha384GetHash(wc_Sha384* sha384, byte* hash); + +/*! + \ingroup SHA + \brief Copies SHA384 context. + + \return 0 on success + \return negative on error + + \param src Source SHA384 structure + \param dst Destination SHA384 structure + + _Example_ + \code + wc_Sha384 src, dst; + int ret = wc_Sha384Copy(&src, &dst); + \endcode + + \sa wc_InitSha384 +*/ +int wc_Sha384Copy(wc_Sha384* src, wc_Sha384* dst); + +/*! + \ingroup SHA + \brief Grows SHA384 buffer with input data. + + \return 0 on success + \return negative on error + + \param sha384 SHA384 structure + \param in Input data + \param inSz Input size + + _Example_ + \code + wc_Sha384 sha; + byte data[100]; + int ret = wc_Sha384_Grow(&sha, data, sizeof(data)); + \endcode + + \sa wc_Sha384Update +*/ +int wc_Sha384_Grow(wc_Sha384* sha384, const byte* in, int inSz); + +/*! + \ingroup SHA + \brief Sets SHA384 flags. + + \return 0 on success + \return negative on error + + \param sha384 SHA384 structure + \param flags Flags to set + + _Example_ + \code + wc_Sha384 sha; + int ret = wc_Sha384SetFlags(&sha, WC_HASH_FLAG_WILLCOPY); + \endcode + + \sa wc_InitSha384 +*/ +int wc_Sha384SetFlags(wc_Sha384* sha384, word32 flags); + +/*! + \ingroup SHA + \brief Gets SHA384 flags. + + \return 0 on success + \return negative on error + + \param sha384 SHA384 structure + \param flags Pointer to store flags + + _Example_ + \code + wc_Sha384 sha; + word32 flags; + int ret = wc_Sha384GetFlags(&sha, &flags); + \endcode + + \sa wc_Sha384SetFlags +*/ +int wc_Sha384GetFlags(wc_Sha384* sha384, word32* flags); + +/*! + \ingroup SHA + \brief Transforms SHA384 block. + + \return 0 on success + \return negative on error + + \param sha SHA384 structure + \param data Block data + + _Example_ + \code + wc_Sha384 sha; + unsigned char block[WC_SHA384_BLOCK_SIZE]; + int ret = wc_Sha384Transform(&sha, block); + \endcode + + \sa wc_Sha384Update +*/ +int wc_Sha384Transform(wc_Sha384* sha, const unsigned char* data); diff --git a/doc/dox_comments/header_files/signature.h b/doc/dox_comments/header_files/signature.h index ab1468a26..35d9d5d5b 100644 --- a/doc/dox_comments/header_files/signature.h +++ b/doc/dox_comments/header_files/signature.h @@ -145,3 +145,206 @@ int wc_SignatureGenerate( byte* sig, word32 *sig_len, const void* key, word32 key_len, WC_RNG* rng); + +/*! + \ingroup Signature + \brief This function verifies a signature using a pre-computed hash. + Unlike wc_SignatureVerify which hashes the data first, this function + takes the hash directly and verifies the signature against it. + If sig_type is WC_SIGNATURE_TYPE_RSA_W_ENC, hash data must be encoded + with wc_EncodeSignature prior to calling. + + \return 0 Success + \return SIG_TYPE_E Signature type not enabled/available + \return BAD_FUNC_ARG Bad function argument provided + \return BUFFER_E Output buffer too small or input too large + + \param hash_type A hash type from enum wc_HashType + \param sig_type A signature type such as WC_SIGNATURE_TYPE_ECC or + WC_SIGNATURE_TYPE_RSA + \param hash_data Pointer to buffer containing the hash to verify + \param hash_len Length of the hash buffer + \param sig Pointer to buffer containing the signature + \param sig_len Length of the signature buffer + \param key Pointer to a key structure such as ecc_key or RsaKey + \param key_len Size of the key structure + + _Example_ + \code + ecc_key eccKey; + byte hash[WC_SHA256_DIGEST_SIZE]; + byte sig[ECC_MAX_SIG_SIZE]; + word32 sigLen = sizeof(sig); + + wc_ecc_init(&eccKey); + // import public key and compute hash + int ret = wc_SignatureVerifyHash(WC_HASH_TYPE_SHA256, + WC_SIGNATURE_TYPE_ECC, hash, + sizeof(hash), sig, sigLen, + &eccKey, sizeof(eccKey)); + if (ret == 0) { + // signature verified + } + \endcode + + \sa wc_SignatureVerify + \sa wc_SignatureGenerateHash +*/ +int wc_SignatureVerifyHash(enum wc_HashType hash_type, + enum wc_SignatureType sig_type, + const byte* hash_data, word32 hash_len, + const byte* sig, word32 sig_len, + const void* key, word32 key_len); + +/*! + \ingroup Signature + \brief This function generates a signature from a pre-computed hash. + Unlike wc_SignatureGenerate which hashes the data first, this + function takes the hash directly and signs it. + If sig_type is WC_SIGNATURE_TYPE_RSA_W_ENC, hash data must be encoded + with wc_EncodeSignature prior to calling. + + \return 0 Success + \return SIG_TYPE_E Signature type not enabled/available + \return BAD_FUNC_ARG Bad function argument provided + \return BUFFER_E Output buffer too small or input too large + + \param hash_type A hash type from enum wc_HashType + \param sig_type A signature type such as WC_SIGNATURE_TYPE_ECC or + WC_SIGNATURE_TYPE_RSA + \param hash_data Pointer to buffer containing the hash to sign + \param hash_len Length of the hash buffer + \param sig Pointer to buffer to output signature + \param sig_len Pointer to length of signature output buffer + \param key Pointer to a key structure such as ecc_key or RsaKey + \param key_len Size of the key structure + \param rng Pointer to an initialized RNG structure + + _Example_ + \code + WC_RNG rng; + ecc_key eccKey; + byte hash[WC_SHA256_DIGEST_SIZE]; + byte sig[ECC_MAX_SIG_SIZE]; + word32 sigLen = sizeof(sig); + + wc_InitRng(&rng); + wc_ecc_init(&eccKey); + wc_ecc_make_key(&rng, 32, &eccKey); + // compute hash + int ret = wc_SignatureGenerateHash(WC_HASH_TYPE_SHA256, + WC_SIGNATURE_TYPE_ECC, hash, + sizeof(hash), sig, &sigLen, + &eccKey, sizeof(eccKey), &rng); + \endcode + + \sa wc_SignatureGenerate + \sa wc_SignatureVerifyHash +*/ +int wc_SignatureGenerateHash(enum wc_HashType hash_type, + enum wc_SignatureType sig_type, + const byte* hash_data, word32 hash_len, + byte* sig, word32 *sig_len, + const void* key, word32 key_len, + WC_RNG* rng); + +/*! + \ingroup Signature + \brief This function generates a signature from a pre-computed hash + with extended options. This is similar to wc_SignatureGenerateHash + but allows optional verification of the signature after generation. + + \return 0 Success + \return SIG_TYPE_E Signature type not enabled/available + \return BAD_FUNC_ARG Bad function argument provided + \return BUFFER_E Output buffer too small or input too large + + \param hash_type A hash type from enum wc_HashType + \param sig_type A signature type such as WC_SIGNATURE_TYPE_ECC or + WC_SIGNATURE_TYPE_RSA + \param hash_data Pointer to buffer containing the hash to sign + \param hash_len Length of the hash buffer + \param sig Pointer to buffer to output signature + \param sig_len Pointer to length of signature output buffer + \param key Pointer to a key structure such as ecc_key or RsaKey + \param key_len Size of the key structure + \param rng Pointer to an initialized RNG structure + \param verify If non-zero, verify the signature after generation + + _Example_ + \code + WC_RNG rng; + ecc_key eccKey; + byte hash[WC_SHA256_DIGEST_SIZE]; + byte sig[ECC_MAX_SIG_SIZE]; + word32 sigLen = sizeof(sig); + + wc_InitRng(&rng); + wc_ecc_init(&eccKey); + wc_ecc_make_key(&rng, 32, &eccKey); + int ret = wc_SignatureGenerateHash_ex(WC_HASH_TYPE_SHA256, + WC_SIGNATURE_TYPE_ECC, hash, + sizeof(hash), sig, &sigLen, + &eccKey, sizeof(eccKey), + &rng, 1); + \endcode + + \sa wc_SignatureGenerateHash + \sa wc_SignatureGenerate_ex +*/ +int wc_SignatureGenerateHash_ex(enum wc_HashType hash_type, + enum wc_SignatureType sig_type, + const byte* hash_data, word32 hash_len, + byte* sig, word32 *sig_len, + const void* key, word32 key_len, + WC_RNG* rng, int verify); + +/*! + \ingroup Signature + \brief This function generates a signature from data with extended + options. This is similar to wc_SignatureGenerate but allows optional + verification of the signature after generation. + + \return 0 Success + \return SIG_TYPE_E Signature type not enabled/available + \return BAD_FUNC_ARG Bad function argument provided + \return BUFFER_E Output buffer too small or input too large + + \param hash_type A hash type from enum wc_HashType + \param sig_type A signature type such as WC_SIGNATURE_TYPE_ECC or + WC_SIGNATURE_TYPE_RSA + \param data Pointer to buffer containing the data to hash and sign + \param data_len Length of the data buffer + \param sig Pointer to buffer to output signature + \param sig_len Pointer to length of signature output buffer + \param key Pointer to a key structure such as ecc_key or RsaKey + \param key_len Size of the key structure + \param rng Pointer to an initialized RNG structure + \param verify If non-zero, verify the signature after generation + + _Example_ + \code + WC_RNG rng; + ecc_key eccKey; + byte data[]; // data to sign + byte sig[ECC_MAX_SIG_SIZE]; + word32 sigLen = sizeof(sig); + + wc_InitRng(&rng); + wc_ecc_init(&eccKey); + wc_ecc_make_key(&rng, 32, &eccKey); + int ret = wc_SignatureGenerate_ex(WC_HASH_TYPE_SHA256, + WC_SIGNATURE_TYPE_ECC, data, + sizeof(data), sig, &sigLen, + &eccKey, sizeof(eccKey), &rng, 1); + \endcode + + \sa wc_SignatureGenerate + \sa wc_SignatureGenerateHash_ex +*/ +int wc_SignatureGenerate_ex(enum wc_HashType hash_type, + enum wc_SignatureType sig_type, + const byte* data, word32 data_len, + byte* sig, word32 *sig_len, + const void* key, word32 key_len, + WC_RNG* rng, int verify); diff --git a/doc/dox_comments/header_files/srp.h b/doc/dox_comments/header_files/srp.h index 14f69190b..5a058d229 100644 --- a/doc/dox_comments/header_files/srp.h +++ b/doc/dox_comments/header_files/srp.h @@ -32,6 +32,49 @@ */ int wc_SrpInit(Srp* srp, SrpType type, SrpSide side); +/*! + \ingroup SRP + \brief Initializes the Srp struct for usage with extended parameters. + This function is similar to wc_SrpInit but allows specification of a + custom heap hint and device ID for hardware acceleration. + + \return 0 on success. + \return BAD_FUNC_ARG Returns when there's an issue with the arguments + such as srp being null or SrpSide not being SRP_CLIENT_SIDE or + SRP_SERVER_SIDE. + \return NOT_COMPILED_IN Returns when a type is passed as an argument + but hasn't been configured in the wolfCrypt build. + \return <0 on error. + + \param srp the Srp structure to be initialized. + \param type the hash type to be used. + \param side the side of the communication. + \param heap pointer to heap hint for memory allocation (can be NULL). + \param devId device ID for hardware acceleration (use INVALID_DEVID + for software only). + + _Example_ + \code + Srp srp; + void* heap = NULL; + int devId = INVALID_DEVID; + + if (wc_SrpInit_ex(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE, heap, + devId) != 0) { + // Initialization error + } + else { + wc_SrpTerm(&srp); + } + \endcode + + \sa wc_SrpInit + \sa wc_SrpTerm + \sa wc_SrpSetUsername +*/ +int wc_SrpInit_ex(Srp* srp, SrpType type, SrpSide side, void* heap, + int devId); + /*! \ingroup SRP diff --git a/doc/dox_comments/header_files/types.h b/doc/dox_comments/header_files/types.h index 6f1ecee26..e55748d6b 100644 --- a/doc/dox_comments/header_files/types.h +++ b/doc/dox_comments/header_files/types.h @@ -170,3 +170,301 @@ void XFREE(void *p, void* heap, int type); \sa CheckRunTimeFastMath */ word32 CheckRunTimeSettings(void); + +/*! + \ingroup String + \brief Thread-safe string tokenization. + + \return Pointer to next token or NULL + + \param str String to tokenize (NULL for continuation) + \param delim Delimiter characters + \param nextp Pointer to save position + + _Example_ + \code + char str[] = "one,two,three"; + char* saveptr; + char* token = wc_strtok(str, ",", &saveptr); + \endcode + + \sa wc_strsep +*/ +char* wc_strtok(char *str, const char *delim, char **nextp); + +/*! + \ingroup String + \brief Separates string by delimiter. + + \return Pointer to token or NULL + + \param stringp Pointer to string pointer + \param delim Delimiter characters + + _Example_ + \code + char str[] = "one,two,three"; + char* ptr = str; + char* token = wc_strsep(&ptr, ","); + \endcode + + \sa wc_strtok +*/ +char* wc_strsep(char **stringp, const char *delim); + +/*! + \ingroup String + \brief Safely copies string with size limit. + + \return Length of source string + + \param dst Destination buffer + \param src Source string + \param dstSize Destination buffer size + + _Example_ + \code + char dst[10]; + size_t len = wc_strlcpy(dst, "hello", sizeof(dst)); + \endcode + + \sa wc_strlcat +*/ +size_t wc_strlcpy(char *dst, const char *src, size_t dstSize); + +/*! + \ingroup String + \brief Safely concatenates strings with size limit. + + \return Total length attempted + + \param dst Destination buffer + \param src Source string + \param dstSize Destination buffer size + + _Example_ + \code + char dst[20] = "hello"; + size_t len = wc_strlcat(dst, " world", sizeof(dst)); + \endcode + + \sa wc_strlcpy +*/ +size_t wc_strlcat(char *dst, const char *src, size_t dstSize); + +/*! + \ingroup String + \brief Case-insensitive string comparison. + + \return 0 if equal, non-zero otherwise + + \param s1 First string + \param s2 Second string + + _Example_ + \code + if (wc_strcasecmp("Hello", "hello") == 0) { + // strings are equal + } + \endcode + + \sa wc_strncasecmp +*/ +int wc_strcasecmp(const char *s1, const char *s2); + +/*! + \ingroup String + \brief Case-insensitive string comparison with length limit. + + \return 0 if equal, non-zero otherwise + + \param s1 First string + \param s2 Second string + \param n Maximum characters to compare + + _Example_ + \code + if (wc_strncasecmp("Hello", "hello", 5) == 0) { + // strings are equal + } + \endcode + + \sa wc_strcasecmp +*/ +int wc_strncasecmp(const char *s1, const char *s2, size_t n); + +/*! + \ingroup Threading + \brief Creates a new thread. + + \return 0 on success + \return negative on error + + \param thread Thread handle pointer + \param cb Thread callback function + \param arg Argument to pass to callback + + _Example_ + \code + THREAD_TYPE thread; + int ret = wolfSSL_NewThread(&thread, myCallback, NULL); + \endcode + + \sa wolfSSL_JoinThread +*/ +int wolfSSL_NewThread(THREAD_TYPE* thread, THREAD_CB cb, void* arg); + +/*! + \ingroup Threading + \brief Creates a detached thread. + + \return 0 on success + \return negative on error + + \param cb Thread callback function + \param arg Argument to pass to callback + + _Example_ + \code + int ret = wolfSSL_NewThreadNoJoin(myCallback, NULL); + \endcode + + \sa wolfSSL_NewThread +*/ +int wolfSSL_NewThreadNoJoin(THREAD_CB_NOJOIN cb, void* arg); + +/*! + \ingroup Threading + \brief Waits for thread to complete. + + \return 0 on success + \return negative on error + + \param thread Thread handle + + _Example_ + \code + THREAD_TYPE thread; + wolfSSL_NewThread(&thread, myCallback, NULL); + int ret = wolfSSL_JoinThread(thread); + \endcode + + \sa wolfSSL_NewThread +*/ +int wolfSSL_JoinThread(THREAD_TYPE thread); + +/*! + \ingroup Threading + \brief Initializes condition variable. + + \return 0 on success + \return negative on error + + \param cond Condition variable pointer + + _Example_ + \code + COND_TYPE cond; + int ret = wolfSSL_CondInit(&cond); + \endcode + + \sa wolfSSL_CondFree +*/ +int wolfSSL_CondInit(COND_TYPE* cond); + +/*! + \ingroup Threading + \brief Frees condition variable. + + \return 0 on success + \return negative on error + + \param cond Condition variable pointer + + _Example_ + \code + COND_TYPE cond; + wolfSSL_CondInit(&cond); + int ret = wolfSSL_CondFree(&cond); + \endcode + + \sa wolfSSL_CondInit +*/ +int wolfSSL_CondFree(COND_TYPE* cond); + +/*! + \ingroup Threading + \brief Signals condition variable. + + \return 0 on success + \return negative on error + + \param cond Condition variable pointer + + _Example_ + \code + COND_TYPE cond; + int ret = wolfSSL_CondSignal(&cond); + \endcode + + \sa wolfSSL_CondWait +*/ +int wolfSSL_CondSignal(COND_TYPE* cond); + +/*! + \ingroup Threading + \brief Waits on condition variable. + + \return 0 on success + \return negative on error + + \param cond Condition variable pointer + + _Example_ + \code + COND_TYPE cond; + int ret = wolfSSL_CondWait(&cond); + \endcode + + \sa wolfSSL_CondSignal +*/ +int wolfSSL_CondWait(COND_TYPE* cond); + +/*! + \ingroup Threading + \brief Starts condition variable. + + \return 0 on success + \return negative on error + + \param cond Condition variable pointer + + _Example_ + \code + COND_TYPE cond; + int ret = wolfSSL_CondStart(&cond); + \endcode + + \sa wolfSSL_CondEnd +*/ +int wolfSSL_CondStart(COND_TYPE* cond); + +/*! + \ingroup Threading + \brief Ends condition variable. + + \return 0 on success + \return negative on error + + \param cond Condition variable pointer + + _Example_ + \code + COND_TYPE cond; + wolfSSL_CondStart(&cond); + int ret = wolfSSL_CondEnd(&cond); + \endcode + + \sa wolfSSL_CondStart +*/ +int wolfSSL_CondEnd(COND_TYPE* cond); diff --git a/doc/dox_comments/header_files/wc_encrypt.h b/doc/dox_comments/header_files/wc_encrypt.h index 54859e7ff..4f7e90117 100644 --- a/doc/dox_comments/header_files/wc_encrypt.h +++ b/doc/dox_comments/header_files/wc_encrypt.h @@ -210,3 +210,124 @@ int wc_Des3_CbcEncryptWithKey(byte* out, int wc_Des3_CbcDecryptWithKey(byte* out, const byte* in, word32 sz, const byte* key, const byte* iv); + +/*! + \ingroup AES + \brief This function encrypts a plaintext message and stores the + result in the output buffer. It uses AES encryption with cipher + block chaining (CBC) mode. This function does not require an AES + structure to be initialized. Instead, it takes in a key and an iv + and uses these to encrypt the message. + + \return 0 On successfully encrypting the message + \return BAD_ALIGN_E Returned on block align error + \return BAD_FUNC_ARG Returned if key length is invalid + \return MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and + XMALLOC fails to instantiate an AES object + + \param out pointer to the output buffer in which to store the + ciphertext of the encrypted message + \param in pointer to the input buffer containing plaintext to + encrypt + \param inSz size of input message + \param key 16, 24, or 32 byte secret key for encryption + \param keySz size of key used for encryption + \param iv pointer to the 16 byte initialization vector to use + + _Example_ + \code + byte key[]; // 16, 24, or 32 byte key + byte iv[]; // 16 byte iv + byte plain[]; // plaintext to encrypt + byte cipher[sizeof(plain)]; + + int ret = wc_AesCbcEncryptWithKey(cipher, plain, sizeof(plain), + key, sizeof(key), iv); + if (ret != 0) { + // encryption error + } + \endcode + + \sa wc_AesCbcDecryptWithKey + \sa wc_AesSetKey + \sa wc_AesCbcEncrypt +*/ +int wc_AesCbcEncryptWithKey(byte* out, const byte* in, word32 inSz, + const byte* key, word32 keySz, + const byte* iv); + +/*! + \ingroup Crypto + \brief This function decrypts an encrypted key buffer using the + provided password. It supports various encryption algorithms + including DES, 3DES, and AES. The encryption information is + provided in the EncryptedInfo structure. + + \return Length of decrypted key on success + \return Negative value on error + + \param info pointer to EncryptedInfo structure containing encryption + algorithm and parameters + \param der pointer to the encrypted key buffer + \param derSz size of the encrypted key buffer + \param password pointer to the password buffer + \param passwordSz size of the password + \param hashType hash algorithm to use for key derivation + + _Example_ + \code + EncryptedInfo info; + byte encryptedKey[]; // encrypted key data + byte password[] = "mypassword"; + + int ret = wc_BufferKeyDecrypt(&info, encryptedKey, + sizeof(encryptedKey), password, + sizeof(password)-1, WC_SHA256); + if (ret < 0) { + // decryption error + } + \endcode + + \sa wc_BufferKeyEncrypt +*/ +int wc_BufferKeyDecrypt(struct EncryptedInfo* info, byte* der, + word32 derSz, const byte* password, + int passwordSz, int hashType); + +/*! + \ingroup Crypto + \brief This function encrypts a key buffer using the provided + password. It supports various encryption algorithms including DES, + 3DES, and AES. The encryption information is provided in the + EncryptedInfo structure. + + \return Length of encrypted key on success + \return Negative value on error + + \param info pointer to EncryptedInfo structure containing encryption + algorithm and parameters + \param der pointer to the key buffer to encrypt + \param derSz size of the key buffer + \param password pointer to the password buffer + \param passwordSz size of the password + \param hashType hash algorithm to use for key derivation + + _Example_ + \code + EncryptedInfo info; + byte key[]; // key data to encrypt + byte password[] = "mypassword"; + + info.algo = AES256CBCb; + int ret = wc_BufferKeyEncrypt(&info, key, sizeof(key), password, + sizeof(password)-1, WC_SHA256); + if (ret < 0) { + // encryption error + } + \endcode + + \sa wc_BufferKeyDecrypt +*/ +int wc_BufferKeyEncrypt(struct EncryptedInfo* info, byte* der, + word32 derSz, const byte* password, + int passwordSz, int hashType); diff --git a/doc/dox_comments/header_files/wc_port.h b/doc/dox_comments/header_files/wc_port.h index 9a517ff64..74db950f9 100644 --- a/doc/dox_comments/header_files/wc_port.h +++ b/doc/dox_comments/header_files/wc_port.h @@ -41,3 +41,696 @@ int wolfCrypt_Init(void); \sa wolfCrypt_Init */ int wolfCrypt_Cleanup(void); + +/*! + \ingroup Atomic + \brief Initializes atomic integer. + + \return none No returns + + \param c Atomic integer pointer + \param i Initial value + + _Example_ + \code + wolfSSL_Atomic_Int counter; + wolfSSL_Atomic_Int_Init(&counter, 0); + \endcode + + \sa wolfSSL_Atomic_Int_FetchAdd +*/ +void wolfSSL_Atomic_Int_Init(wolfSSL_Atomic_Int* c, int i); + +/*! + \ingroup Atomic + \brief Initializes atomic unsigned integer. + + \return none No returns + + \param c Atomic unsigned integer pointer + \param i Initial value + + _Example_ + \code + wolfSSL_Atomic_Uint counter; + wolfSSL_Atomic_Uint_Init(&counter, 0); + \endcode + + \sa wolfSSL_Atomic_Uint_FetchAdd +*/ +void wolfSSL_Atomic_Uint_Init(wolfSSL_Atomic_Uint* c, unsigned int i); + +/*! + \ingroup Atomic + \brief Atomically adds to integer and returns old value. + + \return Old value before addition + + \param c Atomic integer pointer + \param i Value to add + + _Example_ + \code + wolfSSL_Atomic_Int counter; + int old = wolfSSL_Atomic_Int_FetchAdd(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Int_AddFetch +*/ +int wolfSSL_Atomic_Int_FetchAdd(wolfSSL_Atomic_Int* c, int i); + +/*! + \ingroup Atomic + \brief Atomically subtracts from integer and returns old value. + + \return Old value before subtraction + + \param c Atomic integer pointer + \param i Value to subtract + + _Example_ + \code + wolfSSL_Atomic_Int counter; + int old = wolfSSL_Atomic_Int_FetchSub(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Int_SubFetch +*/ +int wolfSSL_Atomic_Int_FetchSub(wolfSSL_Atomic_Int* c, int i); + +/*! + \ingroup Atomic + \brief Atomically adds to integer and returns new value. + + \return New value after addition + + \param c Atomic integer pointer + \param i Value to add + + _Example_ + \code + wolfSSL_Atomic_Int counter; + int new_val = wolfSSL_Atomic_Int_AddFetch(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Int_FetchAdd +*/ +int wolfSSL_Atomic_Int_AddFetch(wolfSSL_Atomic_Int* c, int i); + +/*! + \ingroup Atomic + \brief Atomically subtracts from integer and returns new value. + + \return New value after subtraction + + \param c Atomic integer pointer + \param i Value to subtract + + _Example_ + \code + wolfSSL_Atomic_Int counter; + int new_val = wolfSSL_Atomic_Int_SubFetch(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Int_FetchSub +*/ +int wolfSSL_Atomic_Int_SubFetch(wolfSSL_Atomic_Int* c, int i); + +/*! + \ingroup Atomic + \brief Atomically compares and exchanges integer. + + \return 1 if exchange occurred, 0 otherwise + + \param c Atomic integer pointer + \param expected_i Pointer to expected value + \param new_i New value to set + + _Example_ + \code + wolfSSL_Atomic_Int counter; + int expected = 0; + int ret = wolfSSL_Atomic_Int_CompareExchange(&counter, &expected, 1); + \endcode + + \sa wolfSSL_Atomic_Int_FetchAdd +*/ +int wolfSSL_Atomic_Int_CompareExchange(wolfSSL_Atomic_Int* c, + int *expected_i, int new_i); + +/*! + \ingroup Atomic + \brief Atomically adds to unsigned integer and returns old value. + + \return Old value before addition + + \param c Atomic unsigned integer pointer + \param i Value to add + + _Example_ + \code + wolfSSL_Atomic_Uint counter; + unsigned int old = wolfSSL_Atomic_Uint_FetchAdd(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Uint_AddFetch +*/ +unsigned int wolfSSL_Atomic_Uint_FetchAdd(wolfSSL_Atomic_Uint* c, + unsigned int i); + +/*! + \ingroup Atomic + \brief Atomically subtracts from unsigned integer, returns old value. + + \return Old value before subtraction + + \param c Atomic unsigned integer pointer + \param i Value to subtract + + _Example_ + \code + wolfSSL_Atomic_Uint counter; + unsigned int old = wolfSSL_Atomic_Uint_FetchSub(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Uint_SubFetch +*/ +unsigned int wolfSSL_Atomic_Uint_FetchSub(wolfSSL_Atomic_Uint* c, + unsigned int i); + +/*! + \ingroup Atomic + \brief Atomically adds to unsigned integer, returns new value. + + \return New value after addition + + \param c Atomic unsigned integer pointer + \param i Value to add + + _Example_ + \code + wolfSSL_Atomic_Uint counter; + unsigned int new_val = wolfSSL_Atomic_Uint_AddFetch(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Uint_FetchAdd +*/ +unsigned int wolfSSL_Atomic_Uint_AddFetch(wolfSSL_Atomic_Uint* c, + unsigned int i); + +/*! + \ingroup Atomic + \brief Atomically subtracts from unsigned integer, returns new value. + + \return New value after subtraction + + \param c Atomic unsigned integer pointer + \param i Value to subtract + + _Example_ + \code + wolfSSL_Atomic_Uint counter; + unsigned int new_val = wolfSSL_Atomic_Uint_SubFetch(&counter, 1); + \endcode + + \sa wolfSSL_Atomic_Uint_FetchSub +*/ +unsigned int wolfSSL_Atomic_Uint_SubFetch(wolfSSL_Atomic_Uint* c, + unsigned int i); + +/*! + \ingroup Atomic + \brief Atomically compares and exchanges unsigned integer. + + \return 1 if exchange occurred, 0 otherwise + + \param c Atomic unsigned integer pointer + \param expected_i Pointer to expected value + \param new_i New value to set + + _Example_ + \code + wolfSSL_Atomic_Uint counter; + unsigned int expected = 0; + int ret = wolfSSL_Atomic_Uint_CompareExchange(&counter, &expected, 1); + \endcode + + \sa wolfSSL_Atomic_Uint_FetchAdd +*/ +int wolfSSL_Atomic_Uint_CompareExchange(wolfSSL_Atomic_Uint* c, + unsigned int *expected_i, + unsigned int new_i); + +/*! + \ingroup Atomic + \brief Atomically compares and exchanges pointer. + + \return 1 if exchange occurred, 0 otherwise + + \param c Pointer to pointer + \param expected_ptr Pointer to expected pointer value + \param new_ptr New pointer value + + _Example_ + \code + void* ptr = NULL; + void* expected = NULL; + void* new_val = malloc(100); + int ret = wolfSSL_Atomic_Ptr_CompareExchange(&ptr, &expected, new_val); + \endcode + + \sa wolfSSL_Atomic_Int_CompareExchange +*/ +int wolfSSL_Atomic_Ptr_CompareExchange(void** c, void **expected_ptr, + void *new_ptr); + +/*! + \ingroup Mutex + \brief Initializes mutex. + + \return 0 on success + \return negative on error + + \param m Mutex pointer + + _Example_ + \code + wolfSSL_Mutex mutex; + int ret = wc_InitMutex(&mutex); + \endcode + + \sa wc_FreeMutex +*/ +int wc_InitMutex(wolfSSL_Mutex* m); + +/*! + \ingroup Mutex + \brief Frees mutex resources. + + \return 0 on success + \return negative on error + + \param m Mutex pointer + + _Example_ + \code + wolfSSL_Mutex mutex; + wc_InitMutex(&mutex); + int ret = wc_FreeMutex(&mutex); + \endcode + + \sa wc_InitMutex +*/ +int wc_FreeMutex(wolfSSL_Mutex* m); + +/*! + \ingroup Mutex + \brief Locks mutex. + + \return 0 on success + \return negative on error + + \param m Mutex pointer + + _Example_ + \code + wolfSSL_Mutex mutex; + int ret = wc_LockMutex(&mutex); + \endcode + + \sa wc_UnLockMutex +*/ +int wc_LockMutex(wolfSSL_Mutex* m); + +/*! + \ingroup Mutex + \brief Unlocks mutex. + + \return 0 on success + \return negative on error + + \param m Mutex pointer + + _Example_ + \code + wolfSSL_Mutex mutex; + wc_LockMutex(&mutex); + int ret = wc_UnLockMutex(&mutex); + \endcode + + \sa wc_LockMutex +*/ +int wc_UnLockMutex(wolfSSL_Mutex* m); + +/*! + \ingroup Mutex + \brief Initializes and allocates mutex. + + \return Pointer to mutex on success + \return NULL on error + + \param none No parameters + + _Example_ + \code + wolfSSL_Mutex* mutex = wc_InitAndAllocMutex(); + if (mutex != NULL) { + wc_LockMutex(mutex); + } + \endcode + + \sa wc_InitMutex +*/ +wolfSSL_Mutex* wc_InitAndAllocMutex(void); + +/*! + \ingroup RwLock + \brief Initializes read-write lock. + + \return 0 on success + \return negative on error + + \param m Read-write lock pointer + + _Example_ + \code + wolfSSL_RwLock lock; + int ret = wc_InitRwLock(&lock); + \endcode + + \sa wc_FreeRwLock +*/ +int wc_InitRwLock(wolfSSL_RwLock* m); + +/*! + \ingroup RwLock + \brief Frees read-write lock resources. + + \return 0 on success + \return negative on error + + \param m Read-write lock pointer + + _Example_ + \code + wolfSSL_RwLock lock; + wc_InitRwLock(&lock); + int ret = wc_FreeRwLock(&lock); + \endcode + + \sa wc_InitRwLock +*/ +int wc_FreeRwLock(wolfSSL_RwLock* m); + +/*! + \ingroup RwLock + \brief Locks read-write lock for writing. + + \return 0 on success + \return negative on error + + \param m Read-write lock pointer + + _Example_ + \code + wolfSSL_RwLock lock; + int ret = wc_LockRwLock_Wr(&lock); + \endcode + + \sa wc_UnLockRwLock +*/ +int wc_LockRwLock_Wr(wolfSSL_RwLock* m); + +/*! + \ingroup RwLock + \brief Locks read-write lock for reading. + + \return 0 on success + \return negative on error + + \param m Read-write lock pointer + + _Example_ + \code + wolfSSL_RwLock lock; + int ret = wc_LockRwLock_Rd(&lock); + \endcode + + \sa wc_UnLockRwLock +*/ +int wc_LockRwLock_Rd(wolfSSL_RwLock* m); + +/*! + \ingroup RwLock + \brief Unlocks read-write lock. + + \return 0 on success + \return negative on error + + \param m Read-write lock pointer + + _Example_ + \code + wolfSSL_RwLock lock; + wc_LockRwLock_Rd(&lock); + int ret = wc_UnLockRwLock(&lock); + \endcode + + \sa wc_LockRwLock_Rd +*/ +int wc_UnLockRwLock(wolfSSL_RwLock* m); + +/*! + \ingroup Mutex + \brief Locks mutex with debug info. + + \return 0 on success + \return negative on error + + \param flag Lock flag + \param type Lock type + \param file Source file name + \param line Source line number + + _Example_ + \code + int ret = wc_LockMutex_ex(0, 0, __FILE__, __LINE__); + \endcode + + \sa wc_LockMutex +*/ +int wc_LockMutex_ex(int flag, int type, const char* file, int line); + +/*! + \ingroup Mutex + \brief Sets mutex callback. + + \return 0 on success + \return negative on error + + \param cb Mutex callback pointer + + _Example_ + \code + mutex_cb cb; + int ret = wc_SetMutexCb(&cb); + \endcode + + \sa wc_GetMutexCb +*/ +int wc_SetMutexCb(mutex_cb* cb); + +/*! + \ingroup Mutex + \brief Gets mutex callback. + + \return Pointer to mutex callback + + \param none No parameters + + _Example_ + \code + mutex_cb* cb = wc_GetMutexCb(); + \endcode + + \sa wc_SetMutexCb +*/ +mutex_cb* wc_GetMutexCb(void); + +/*! + \ingroup Memory + \brief Checkpoints peak heap allocations. + + \return Peak allocation count + + \param none No parameters + + _Example_ + \code + long peak = wolfCrypt_heap_peakAllocs_checkpoint(); + \endcode + + \sa wolfCrypt_heap_peakBytes_checkpoint +*/ +long wolfCrypt_heap_peakAllocs_checkpoint(void); + +/*! + \ingroup Memory + \brief Checkpoints peak heap bytes. + + \return Peak bytes allocated + + \param none No parameters + + _Example_ + \code + long peak = wolfCrypt_heap_peakBytes_checkpoint(); + \endcode + + \sa wolfCrypt_heap_peakAllocs_checkpoint +*/ +long wolfCrypt_heap_peakBytes_checkpoint(void); + +/*! + \ingroup File + \brief Loads file into buffer. + + \return 0 on success + \return negative on error + + \param fname File name + \param buf Buffer pointer + \param bufLen Buffer length pointer + \param heap Heap hint + + _Example_ + \code + unsigned char* buf = NULL; + size_t len = 0; + int ret = wc_FileLoad("file.txt", &buf, &len, NULL); + \endcode + + \sa wc_FileExists +*/ +int wc_FileLoad(const char* fname, unsigned char** buf, size_t* bufLen, + void* heap); + +/*! + \ingroup File + \brief Reads first entry in directory. + + \return 0 on success + \return negative on error + + \param ctx Directory context + \param path Directory path + \param name Pointer to store entry name + + _Example_ + \code + ReadDirCtx ctx; + char* name; + int ret = wc_ReadDirFirst(&ctx, "/path", &name); + \endcode + + \sa wc_ReadDirNext +*/ +int wc_ReadDirFirst(ReadDirCtx* ctx, const char* path, char** name); + +/*! + \ingroup File + \brief Reads next entry in directory. + + \return 0 on success + \return negative on error + + \param ctx Directory context + \param path Directory path + \param name Pointer to store entry name + + _Example_ + \code + ReadDirCtx ctx; + char* name; + int ret = wc_ReadDirNext(&ctx, "/path", &name); + \endcode + + \sa wc_ReadDirFirst +*/ +int wc_ReadDirNext(ReadDirCtx* ctx, const char* path, char** name); + +/*! + \ingroup File + \brief Closes directory reading. + + \return none No returns + + \param ctx Directory context + + _Example_ + \code + ReadDirCtx ctx; + wc_ReadDirClose(&ctx); + \endcode + + \sa wc_ReadDirFirst +*/ +void wc_ReadDirClose(ReadDirCtx* ctx); + +/*! + \ingroup File + \brief Checks if file exists. + + \return 1 if file exists + \return 0 if file does not exist + + \param fname File name + + _Example_ + \code + if (wc_FileExists("file.txt")) { + // file exists + } + \endcode + + \sa wc_FileLoad +*/ +int wc_FileExists(const char* fname); + +/*! + \ingroup Callback + \brief Checks if handle callback is set. + + \return 1 if set + \return 0 if not set + + \param none No parameters + + _Example_ + \code + if (wolfSSL_GetHandleCbSet()) { + // callback is set + } + \endcode + + \sa wolfSSL_SetHandleCb +*/ +int wolfSSL_GetHandleCbSet(void); + +/*! + \ingroup Callback + \brief Sets handle callback. + + \return 0 on success + \return negative on error + + \param in Handle callback + + _Example_ + \code + int ret = wolfSSL_SetHandleCb(myHandleCallback); + \endcode + + \sa wolfSSL_GetHandleCbSet +*/ +int wolfSSL_SetHandleCb(wolfSSL_DSP_Handle_cb in); diff --git a/doc/dox_comments/header_files/wolfio.h b/doc/dox_comments/header_files/wolfio.h index 2197dbcc0..2ec951563 100644 --- a/doc/dox_comments/header_files/wolfio.h +++ b/doc/dox_comments/header_files/wolfio.h @@ -666,3 +666,801 @@ WOLFSSL_API void wolfSSL_SetRecvFrom(WOLFSSL* ssl, WolfSSLRecvFrom recvFrom); \sa wolfSSL_SSLSetIOSend */ WOLFSSL_API void wolfSSL_SetSendTo(WOLFSSL* ssl, WolfSSLSento sendTo); + +/*! + \ingroup IO + \brief Waits for socket to be ready for I/O with timeout. + + \return 0 on success + \return negative on error + + \param sockfd Socket file descriptor + \param to_sec Timeout in seconds + + _Example_ + \code + SOCKET_T sockfd; + int ret = wolfIO_Select(sockfd, 5); + \endcode + + \sa wolfIO_TcpConnect +*/ +int wolfIO_Select(SOCKET_T sockfd, int to_sec); + +/*! + \ingroup IO + \brief Connects to TCP server with timeout. + + \return 0 on success + \return negative on error + + \param sockfd Pointer to socket file descriptor + \param ip IP address string + \param port Port number + \param to_sec Timeout in seconds + + _Example_ + \code + SOCKET_T sockfd; + int ret = wolfIO_TcpConnect(&sockfd, "127.0.0.1", 443, 5); + \endcode + + \sa wolfIO_TcpBind +*/ +int wolfIO_TcpConnect(SOCKET_T* sockfd, const char* ip, + unsigned short port, int to_sec); + +/*! + \ingroup IO + \brief Accepts TCP connection. + + \return Socket descriptor on success + \return negative on error + + \param sockfd Socket file descriptor + \param peer_addr Peer address structure + \param peer_len Peer address length + + _Example_ + \code + SOCKET_T sockfd; + SOCKADDR peer; + XSOCKLENT len = sizeof(peer); + int ret = wolfIO_TcpAccept(sockfd, &peer, &len); + \endcode + + \sa wolfIO_TcpBind +*/ +int wolfIO_TcpAccept(SOCKET_T sockfd, SOCKADDR* peer_addr, + XSOCKLENT* peer_len); + +/*! + \ingroup IO + \brief Binds TCP socket to port. + + \return 0 on success + \return negative on error + + \param sockfd Pointer to socket file descriptor + \param port Port number + + _Example_ + \code + SOCKET_T sockfd; + int ret = wolfIO_TcpBind(&sockfd, 443); + \endcode + + \sa wolfIO_TcpAccept +*/ +int wolfIO_TcpBind(SOCKET_T* sockfd, word16 port); + +/*! + \ingroup IO + \brief Sends data on socket. + + \return Number of bytes sent on success + \return negative on error + + \param sd Socket descriptor + \param buf Buffer to send + \param sz Buffer size + \param wrFlags Write flags + + _Example_ + \code + SOCKET_T sd; + char buf[100]; + int ret = wolfIO_Send(sd, buf, sizeof(buf), 0); + \endcode + + \sa wolfIO_Recv +*/ +int wolfIO_Send(SOCKET_T sd, char *buf, int sz, int wrFlags); + +/*! + \ingroup IO + \brief Receives data from socket. + + \return Number of bytes received on success + \return negative on error + + \param sd Socket descriptor + \param buf Buffer to receive into + \param sz Buffer size + \param rdFlags Read flags + + _Example_ + \code + SOCKET_T sd; + char buf[100]; + int ret = wolfIO_Recv(sd, buf, sizeof(buf), 0); + \endcode + + \sa wolfIO_Send +*/ +int wolfIO_Recv(SOCKET_T sd, char *buf, int sz, int rdFlags); + +/*! + \ingroup IO + \brief Sends datagram to address. + + \return Number of bytes sent on success + \return negative on error + + \param sd Socket descriptor + \param addr Destination address + \param buf Buffer to send + \param sz Buffer size + \param wrFlags Write flags + + _Example_ + \code + SOCKET_T sd; + WOLFSSL_BIO_ADDR addr; + char buf[100]; + int ret = wolfIO_SendTo(sd, &addr, buf, sizeof(buf), 0); + \endcode + + \sa wolfIO_RecvFrom +*/ +int wolfIO_SendTo(SOCKET_T sd, WOLFSSL_BIO_ADDR *addr, char *buf, int sz, + int wrFlags); + +/*! + \ingroup IO + \brief Receives datagram from address. + + \return Number of bytes received on success + \return negative on error + + \param sd Socket descriptor + \param addr Source address + \param buf Buffer to receive into + \param sz Buffer size + \param rdFlags Read flags + + _Example_ + \code + SOCKET_T sd; + WOLFSSL_BIO_ADDR addr; + char buf[100]; + int ret = wolfIO_RecvFrom(sd, &addr, buf, sizeof(buf), 0); + \endcode + + \sa wolfIO_SendTo +*/ +int wolfIO_RecvFrom(SOCKET_T sd, WOLFSSL_BIO_ADDR *addr, char *buf, int sz, + int rdFlags); + +/*! + \ingroup IO + \brief BIO send callback. + + \return Number of bytes sent on success + \return negative on error + + \param ssl SSL object + \param buf Buffer to send + \param sz Buffer size + \param ctx Context pointer + + _Example_ + \code + WOLFSSL* ssl; + char buf[100]; + int ret = wolfSSL_BioSend(ssl, buf, sizeof(buf), NULL); + \endcode + + \sa wolfSSL_BioReceive +*/ +int wolfSSL_BioSend(WOLFSSL* ssl, char *buf, int sz, void *ctx); + +/*! + \ingroup IO + \brief BIO receive callback. + + \return Number of bytes received on success + \return negative on error + + \param ssl SSL object + \param buf Buffer to receive into + \param sz Buffer size + \param ctx Context pointer + + _Example_ + \code + WOLFSSL* ssl; + char buf[100]; + int ret = wolfSSL_BioReceive(ssl, buf, sizeof(buf), NULL); + \endcode + + \sa wolfSSL_BioSend +*/ +int wolfSSL_BioReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx); + +/*! + \ingroup IO + \brief Receives multicast datagram. + + \return Number of bytes received on success + \return negative on error + + \param ssl SSL object + \param buf Buffer to receive into + \param sz Buffer size + \param ctx Context pointer + + _Example_ + \code + WOLFSSL* ssl; + char buf[100]; + int ret = EmbedReceiveFromMcast(ssl, buf, sizeof(buf), NULL); + \endcode + + \sa EmbedReceiveFrom +*/ +int EmbedReceiveFromMcast(WOLFSSL *ssl, char *buf, int sz, void *ctx); + +/*! + \ingroup IO + \brief Builds HTTP OCSP request. + + \return Request size on success + \return negative on error + + \param domainName Domain name + \param path URL path + \param ocspReqSz OCSP request size + \param buf Output buffer + \param bufSize Buffer size + + _Example_ + \code + char buf[1024]; + int ret = wolfIO_HttpBuildRequestOcsp("example.com", "/ocsp", 100, + (unsigned char*)buf, sizeof(buf)); + \endcode + + \sa wolfIO_HttpProcessResponseOcsp +*/ +int wolfIO_HttpBuildRequestOcsp(const char* domainName, const char* path, + int ocspReqSz, unsigned char* buf, + int bufSize); + +/*! + \ingroup IO + \brief Processes HTTP OCSP response with generic I/O. + + \return 0 on success + \return negative on error + + \param ioCb I/O callback + \param ioCbCtx I/O callback context + \param respBuf Response buffer pointer + \param httpBuf HTTP buffer + \param httpBufSz HTTP buffer size + \param heap Heap hint + + _Example_ + \code + unsigned char* resp = NULL; + unsigned char httpBuf[1024]; + int ret = wolfIO_HttpProcessResponseOcspGenericIO(myIoCb, ctx, &resp, + httpBuf, + sizeof(httpBuf), NULL); + \endcode + + \sa wolfIO_HttpProcessResponseOcsp +*/ +int wolfIO_HttpProcessResponseOcspGenericIO(WolfSSLGenericIORecvCb ioCb, + void* ioCbCtx, + unsigned char** respBuf, + unsigned char* httpBuf, + int httpBufSz, void* heap); + +/*! + \ingroup IO + \brief Processes HTTP OCSP response. + + \return 0 on success + \return negative on error + + \param sfd Socket file descriptor + \param respBuf Response buffer pointer + \param httpBuf HTTP buffer + \param httpBufSz HTTP buffer size + \param heap Heap hint + + _Example_ + \code + int sfd; + unsigned char* resp = NULL; + unsigned char httpBuf[1024]; + int ret = wolfIO_HttpProcessResponseOcsp(sfd, &resp, httpBuf, + sizeof(httpBuf), NULL); + \endcode + + \sa wolfIO_HttpBuildRequestOcsp +*/ +int wolfIO_HttpProcessResponseOcsp(int sfd, unsigned char** respBuf, + unsigned char* httpBuf, int httpBufSz, + void* heap); + +/*! + \ingroup IO + \brief OCSP lookup callback. + + \return 0 on success + \return negative on error + + \param ctx Context pointer + \param url URL string + \param urlSz URL size + \param ocspReqBuf OCSP request buffer + \param ocspReqSz OCSP request size + \param ocspRespBuf OCSP response buffer pointer + + _Example_ + \code + byte* resp = NULL; + byte req[100]; + int ret = EmbedOcspLookup(NULL, "http://example.com/ocsp", 25, req, + sizeof(req), &resp); + \endcode + + \sa EmbedOcspRespFree +*/ +int EmbedOcspLookup(void* ctx, const char* url, int urlSz, + byte* ocspReqBuf, int ocspReqSz, byte** ocspRespBuf); + +/*! + \ingroup IO + \brief Builds HTTP CRL request. + + \return Request size on success + \return negative on error + + \param url URL string + \param urlSz URL size + \param domainName Domain name + \param buf Output buffer + \param bufSize Buffer size + + _Example_ + \code + char buf[1024]; + int ret = wolfIO_HttpBuildRequestCrl("http://example.com/crl", 22, + "example.com", + (unsigned char*)buf, sizeof(buf)); + \endcode + + \sa wolfIO_HttpProcessResponseCrl +*/ +int wolfIO_HttpBuildRequestCrl(const char* url, int urlSz, + const char* domainName, unsigned char* buf, + int bufSize); + +/*! + \ingroup IO + \brief Processes HTTP CRL response. + + \return 0 on success + \return negative on error + + \param crl CRL object + \param sfd Socket file descriptor + \param httpBuf HTTP buffer + \param httpBufSz HTTP buffer size + + _Example_ + \code + WOLFSSL_CRL crl; + int sfd; + unsigned char httpBuf[1024]; + int ret = wolfIO_HttpProcessResponseCrl(&crl, sfd, httpBuf, + sizeof(httpBuf)); + \endcode + + \sa wolfIO_HttpBuildRequestCrl +*/ +int wolfIO_HttpProcessResponseCrl(WOLFSSL_CRL* crl, int sfd, + unsigned char* httpBuf, int httpBufSz); + +/*! + \ingroup IO + \brief CRL lookup callback. + + \return 0 on success + \return negative on error + + \param crl CRL object + \param url URL string + \param urlSz URL size + + _Example_ + \code + WOLFSSL_CRL crl; + int ret = EmbedCrlLookup(&crl, "http://example.com/crl", 22); + \endcode + + \sa wolfIO_HttpBuildRequestCrl +*/ +int EmbedCrlLookup(WOLFSSL_CRL* crl, const char* url, int urlSz); + +/*! + \ingroup IO + \brief Decodes URL into components. + + \return 0 on success + \return negative on error + + \param url URL string + \param urlSz URL size + \param outName Output domain name + \param outPath Output path + \param outPort Output port + + _Example_ + \code + char name[256], path[256]; + unsigned short port; + int ret = wolfIO_DecodeUrl("http://example.com:443/path", 28, name, + path, &port); + \endcode + + \sa wolfIO_HttpBuildRequest +*/ +int wolfIO_DecodeUrl(const char* url, int urlSz, char* outName, + char* outPath, unsigned short* outPort); + +/*! + \ingroup IO + \brief Builds generic HTTP request. + + \return Request size on success + \return negative on error + + \param reqType Request type (GET, POST, etc.) + \param domainName Domain name + \param path URL path + \param pathLen Path length + \param reqSz Request body size + \param contentType Content type + \param buf Output buffer + \param bufSize Buffer size + + _Example_ + \code + char buf[1024]; + int ret = wolfIO_HttpBuildRequest("POST", "example.com", "/api", 4, + 100, "application/json", + (unsigned char*)buf, sizeof(buf)); + \endcode + + \sa wolfIO_HttpProcessResponse +*/ +int wolfIO_HttpBuildRequest(const char* reqType, const char* domainName, + const char* path, int pathLen, int reqSz, + const char* contentType, unsigned char* buf, + int bufSize); + +/*! + \ingroup IO + \brief Processes HTTP response with generic I/O. + + \return 0 on success + \return negative on error + + \param ioCb I/O callback + \param ioCbCtx I/O callback context + \param appStrList Application string list + \param respBuf Response buffer pointer + \param httpBuf HTTP buffer + \param httpBufSz HTTP buffer size + \param dynType Dynamic type + \param heap Heap hint + + _Example_ + \code + unsigned char* resp = NULL; + unsigned char httpBuf[1024]; + const char* appStrs[] = {"200 OK", NULL}; + int ret = wolfIO_HttpProcessResponseGenericIO(myIoCb, ctx, appStrs, + &resp, httpBuf, + sizeof(httpBuf), 0, NULL); + \endcode + + \sa wolfIO_HttpProcessResponse +*/ +int wolfIO_HttpProcessResponseGenericIO(WolfSSLGenericIORecvCb ioCb, + void* ioCbCtx, + const char** appStrList, + unsigned char** respBuf, + unsigned char* httpBuf, + int httpBufSz, int dynType, + void* heap); + +/*! + \ingroup IO + \brief Processes HTTP response. + + \return 0 on success + \return negative on error + + \param sfd Socket file descriptor + \param appStrList Application string list + \param respBuf Response buffer pointer + \param httpBuf HTTP buffer + \param httpBufSz HTTP buffer size + \param dynType Dynamic type + \param heap Heap hint + + _Example_ + \code + int sfd; + unsigned char* resp = NULL; + unsigned char httpBuf[1024]; + const char* appStrs[] = {"200 OK", NULL}; + int ret = wolfIO_HttpProcessResponse(sfd, appStrs, &resp, httpBuf, + sizeof(httpBuf), 0, NULL); + \endcode + + \sa wolfIO_HttpBuildRequest +*/ +int wolfIO_HttpProcessResponse(int sfd, const char** appStrList, + unsigned char** respBuf, + unsigned char* httpBuf, int httpBufSz, + int dynType, void* heap); + +/*! + \ingroup IO + \brief Sets I/O send callback for context. + + \return none No returns + + \param ctx SSL context + \param CBIOSend Send callback + + _Example_ + \code + WOLFSSL_CTX* ctx; + wolfSSL_CTX_SetIOSend(ctx, mySendCallback); + \endcode + + \sa wolfSSL_SSLSetIOSend +*/ +void wolfSSL_CTX_SetIOSend(WOLFSSL_CTX *ctx, CallbackIOSend CBIOSend); + +/*! + \ingroup IO + \brief Sets I/O receive callback for SSL object. + + \return none No returns + + \param ssl SSL object + \param CBIORecv Receive callback + + _Example_ + \code + WOLFSSL* ssl; + wolfSSL_SSLSetIORecv(ssl, myRecvCallback); + \endcode + + \sa wolfSSL_CTX_SetIORecv +*/ +void wolfSSL_SSLSetIORecv(WOLFSSL *ssl, CallbackIORecv CBIORecv); + +/*! + \ingroup IO + \brief Sets I/O send callback for SSL object. + + \return none No returns + + \param ssl SSL object + \param CBIOSend Send callback + + _Example_ + \code + WOLFSSL* ssl; + wolfSSL_SSLSetIOSend(ssl, mySendCallback); + \endcode + + \sa wolfSSL_CTX_SetIOSend +*/ +void wolfSSL_SSLSetIOSend(WOLFSSL *ssl, CallbackIOSend CBIOSend); + +/*! + \ingroup IO + \brief Sets I/O for Mynewt platform. + + \return none No returns + + \param ssl SSL object + \param mnSocket Mynewt socket + \param mnSockAddrIn Mynewt socket address + + _Example_ + \code + WOLFSSL* ssl; + struct mn_socket sock; + struct mn_sockaddr_in addr; + wolfSSL_SetIO_Mynewt(ssl, &sock, &addr); + \endcode + + \sa wolfSSL_SetIO_LwIP +*/ +void wolfSSL_SetIO_Mynewt(WOLFSSL* ssl, struct mn_socket* mnSocket, + struct mn_sockaddr_in* mnSockAddrIn); + +/*! + \ingroup IO + \brief Sets I/O for LwIP platform. + + \return 0 on success + \return negative on error + + \param ssl SSL object + \param pcb Protocol control block + \param recv Receive callback + \param sent Sent callback + \param arg Argument pointer + + _Example_ + \code + WOLFSSL* ssl; + struct tcp_pcb* pcb; + int ret = wolfSSL_SetIO_LwIP(ssl, pcb, myRecv, mySent, NULL); + \endcode + + \sa wolfSSL_SetIO_Mynewt +*/ +int wolfSSL_SetIO_LwIP(WOLFSSL* ssl, void *pcb, tcp_recv_fn recv, + tcp_sent_fn sent, void *arg); + +/*! + \ingroup IO + \brief Sets cookie context for DTLS. + + \return none No returns + + \param ssl SSL object + \param ctx Cookie context + + _Example_ + \code + WOLFSSL* ssl; + void* ctx; + wolfSSL_SetCookieCtx(ssl, ctx); + \endcode + + \sa wolfSSL_GetCookieCtx +*/ +void wolfSSL_SetCookieCtx(WOLFSSL* ssl, void *ctx); + +/*! + \ingroup IO + \brief Gets cookie context for DTLS. + + \return Cookie context pointer + + \param ssl SSL object + + _Example_ + \code + WOLFSSL* ssl; + void* ctx = wolfSSL_GetCookieCtx(ssl); + \endcode + + \sa wolfSSL_SetCookieCtx +*/ +void* wolfSSL_GetCookieCtx(WOLFSSL* ssl); + +/*! + \ingroup IO + \brief Sets get peer callback for context. + + \return none No returns + + \param ctx SSL context + \param cb Get peer callback + + _Example_ + \code + WOLFSSL_CTX* ctx; + wolfSSL_CTX_SetIOGetPeer(ctx, myGetPeerCallback); + \endcode + + \sa wolfSSL_CTX_SetIOSetPeer +*/ +void wolfSSL_CTX_SetIOGetPeer(WOLFSSL_CTX* ctx, CallbackGetPeer cb); + +/*! + \ingroup IO + \brief Sets set peer callback for context. + + \return none No returns + + \param ctx SSL context + \param cb Set peer callback + + _Example_ + \code + WOLFSSL_CTX* ctx; + wolfSSL_CTX_SetIOSetPeer(ctx, mySetPeerCallback); + \endcode + + \sa wolfSSL_CTX_SetIOGetPeer +*/ +void wolfSSL_CTX_SetIOSetPeer(WOLFSSL_CTX* ctx, CallbackSetPeer cb); + +/*! + \ingroup IO + \brief Gets peer information. + + \return 0 on success + \return negative on error + + \param ssl SSL object + \param ip IP address buffer + \param ipSz IP address buffer size pointer + \param port Port number pointer + \param fam Address family pointer + + _Example_ + \code + WOLFSSL* ssl; + char ip[46]; + int ipSz = sizeof(ip); + unsigned short port; + int fam; + int ret = EmbedGetPeer(ssl, ip, &ipSz, &port, &fam); + \endcode + + \sa EmbedSetPeer +*/ +int EmbedGetPeer(WOLFSSL* ssl, char* ip, int* ipSz, unsigned short* port, + int* fam); + +/*! + \ingroup IO + \brief Sets peer information. + + \return 0 on success + \return negative on error + + \param ssl SSL object + \param ip IP address string + \param ipSz IP address string size + \param port Port number + \param fam Address family + + _Example_ + \code + WOLFSSL* ssl; + int ret = EmbedSetPeer(ssl, "127.0.0.1", 9, 443, AF_INET); + \endcode + + \sa EmbedGetPeer +*/ +int EmbedSetPeer(WOLFSSL* ssl, char* ip, int ipSz, unsigned short port, + int fam);