mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-07-07 21:50:49 +02:00
David Garske
77d9410aa0
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.
737 lines
14 KiB
C
737 lines
14 KiB
C
/*!
|
|
\ingroup wolfCrypt
|
|
|
|
\brief Used to initialize resources used by wolfCrypt.
|
|
|
|
\return 0 upon success.
|
|
\return <0 upon failure of init resources.
|
|
|
|
\param none No parameters.
|
|
|
|
_Example_
|
|
\code
|
|
...
|
|
if (wolfCrypt_Init() != 0) {
|
|
WOLFSSL_MSG("Error with wolfCrypt_Init call");
|
|
}
|
|
\endcode
|
|
|
|
\sa wolfCrypt_Cleanup
|
|
*/
|
|
int wolfCrypt_Init(void);
|
|
|
|
/*!
|
|
\ingroup wolfCrypt
|
|
|
|
\brief Used to clean up resources used by wolfCrypt.
|
|
|
|
\return 0 upon success.
|
|
\return <0 upon failure of cleaning up resources.
|
|
|
|
\param none No parameters.
|
|
|
|
_Example_
|
|
\code
|
|
...
|
|
if (wolfCrypt_Cleanup() != 0) {
|
|
WOLFSSL_MSG("Error with wolfCrypt_Cleanup call");
|
|
}
|
|
\endcode
|
|
|
|
\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);
|