From 8376a2adc2cdc8121da9ed3c3a3affbdae3b3510 Mon Sep 17 00:00:00 2001 From: David Garske Date: Wed, 28 Jul 2021 09:03:40 -0700 Subject: [PATCH 1/2] Improved memory documentation and examples. Resolves PR #3834. --- doc/dox_comments/header_files/memory.h | 179 +++++++------------------ doc/dox_comments/header_files/types.h | 18 +-- 2 files changed, 58 insertions(+), 139 deletions(-) diff --git a/doc/dox_comments/header_files/memory.h b/doc/dox_comments/header_files/memory.h index f94872516..3b955fb57 100644 --- a/doc/dox_comments/header_files/memory.h +++ b/doc/dox_comments/header_files/memory.h @@ -1,17 +1,21 @@ /*! \ingroup Memory - \brief This function calls the custom malloc function, if one has been - defined, or simply calls the default C malloc function if no custom - function exists. It is not called directly by wolfSSL, but instead - generally called by using XMALLOC, which may be replaced by - wolfSSL_Malloc during preprocessing. + \brief This function is similar to malloc(), but calls the memory + allocation function which wolfSSL has been configured to use. By default, + wolfSSL uses malloc(). This can be changed using the wolfSSL memory + abstraction layer - see wolfSSL_SetAllocators(). Note wolfSSL_Malloc is not + called directly by wolfSSL, but instead called by macro XMALLOC. + For the default build only the size argument exists. If using + WOLFSSL_STATIC_MEMORY build then heap and type arguments are included. - \return Success On successfully allocating the desired memory, - returns a void* to that location - \return NULL Returned when there is a failure to allocate memory + \return pointer If successful, this function returns a pointer to + allocated memory. + \return error If there is an error, NULL will be returned. \param size size, in bytes, of the memory to allocate + \param heap heap hint to use for memory. Can be NULL + \param type dynamic type (see DYNAMIC_TYPE_ list in types.h) _Example_ \code @@ -20,24 +24,29 @@ \sa wolfSSL_Free \sa wolfSSL_Realloc + \sa wolfSSL_SetAllocators \sa XMALLOC \sa XFREE \sa XREALLOC */ -WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* func, unsigned int line); +WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type); /*! \ingroup Memory - \brief This function calls a custom free function, if one has been - defined, or simply calls the default C free function if no custom - function exists. It is not called directly by wolfSSL, but instead - generally called by using XFREE, which may be replaced by wolfSSL_Free - during preprocessing. + \brief This function is similar to free(), but calls the memory free + function which wolfSSL has been configured to use. By default, wolfSSL + uses free(). This can be changed using the wolfSSL memory abstraction + layer - see wolfSSL_SetAllocators(). Note wolfSSL_Free is not + called directly by wolfSSL, but instead called by macro XFREE. + For the default build only the ptr argument exists. If using + WOLFSSL_STATIC_MEMORY build then heap and type arguments are included. \return none No returns. - \param ptr pointer to the memory to free + \param ptr pointer to the memory to be freed. + \param heap heap hint to use for memory. Can be NULL + \param type dynamic type (see DYNAMIC_TYPE_ list in types.h) _Example_ \code @@ -49,74 +58,14 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* } \endcode - \sa wolfSSL_Malloc - \sa wolfSSL_Realloc - \sa XMALLOC - \sa XFREE - \sa XREALLOC -*/ -WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func, unsigned int line); - -/*! - \ingroup Memory - - \brief This function calls a custom realloc function, if one has been - defined, or simply calls the default C realloc function if no custom - function exists. It is not called directly by wolfSSL, but instead - generally called by using XREALLOC, which may be replaced by - wolfSSL_Realloc during preprocessing. - - \return Success On successfully reallocating the desired memory, - returns a void* to that location - \return NULL Returned when there is a failure to reallocate memory - - \param ptr pointer to the memory to the memory to reallocate - \param size desired size after reallocation - - _Example_ - \code - int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); - int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2); - \endcode - - \sa wolfSSL_Malloc - \sa wolfSSL_Free - \sa XMALLOC - \sa XFREE - \sa XREALLOC -*/ -WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, const char* func, unsigned int line); - -/*! - \ingroup Memory - - \brief This function is similar to malloc(), but calls the memory - allocation function which wolfSSL has been configured to use. By default, - wolfSSL uses malloc(). This can be changed using the wolfSSL memory - abstraction layer - see wolfSSL_SetAllocators(). - - \return pointer If successful, this function returns a pointer to - allocated memory. - \return error If there is an error, NULL will be returned. - \return other Specific return values may be dependent on the underlying - memory allocation function being used (if not using the default malloc()). - - \param size number of bytes to allocate. - - _Example_ - \code - char* buffer; - buffer = (char*) wolfSSL_Malloc(20); - if (buffer == NULL) { - // failed to allocate memory - } - \endcode - - \sa wolfSSL_Free + \sa wolfSSL_Alloc \sa wolfSSL_Realloc \sa wolfSSL_SetAllocators + \sa XMALLOC + \sa XFREE + \sa XREALLOC */ -WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type); +WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type); /*! \ingroup Memory @@ -124,60 +73,36 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type); \brief This function is similar to realloc(), but calls the memory re-allocation function which wolfSSL has been configured to use. By default, wolfSSL uses realloc(). This can be changed using the - wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). + wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). + Note wolfSSL_Realloc is not called directly by wolfSSL, but instead called + by macro XREALLOC. For the default build only the size argument exists. + If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included. \return pointer If successful, this function returns a pointer to re-allocated memory. This may be the same pointer as ptr, or a new pointer location. \return Null If there is an error, NULL will be returned. - \return other Specific return values may be dependent on the - underlying memory re-allocation function being used - (if not using the default realloc()). \param ptr pointer to the previously-allocated memory, to be reallocated. \param size number of bytes to allocate. + \param heap heap hint to use for memory. Can be NULL + \param type dynamic type (see DYNAMIC_TYPE_ list in types.h) _Example_ \code - char* buffer; - - buffer = (char*) wolfSSL_Realloc(30); - if (buffer == NULL) { - // failed to re-allocate memory - } + int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); + int* twentyInts = (int*)wolfSSL_Realloc(tenInts, sizeof(int)*20); \endcode \sa wolfSSL_Free \sa wolfSSL_Malloc \sa wolfSSL_SetAllocators + \sa XMALLOC + \sa XFREE + \sa XREALLOC */ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type); -/*! - \ingroup Memory - - \brief This function is similar to free(), but calls the memory free - function which wolfSSL has been configured to use. By default, wolfSSL - uses free(). This can be changed using the wolfSSL memory abstraction - layer - see wolfSSL_SetAllocators(). - - \return none No returns. - - \param ptr pointer to the memory to be freed. - - _Example_ - \code - char* buffer; - ... - wolfSSL_Free(buffer); - \endcode - - \sa wolfSSL_Alloc - \sa wolfSSL_Realloc - \sa wolfSSL_SetAllocators -*/ -WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line); - /*! \ingroup Memory @@ -199,32 +124,26 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line); _Example_ \code - int ret = 0; - // Memory function prototypes - void* MyMalloc(size_t size); - void MyFree(void* ptr); - void* MyRealloc(void* ptr, size_t size); - - // Register custom memory functions with wolfSSL - ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc); - if (ret != 0) { - // failed to set memory functions - } - - void* MyMalloc(size_t size) + static void* MyMalloc(size_t size) { // custom malloc function } - void MyFree(void* ptr) + static void MyFree(void* ptr) { // custom free function } - void* MyRealloc(void* ptr, size_t size) + static void* MyRealloc(void* ptr, size_t size) { // custom realloc function } + + // Register custom memory functions with wolfSSL + int ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc); + if (ret != 0) { + // failed to set memory functions + } \endcode \sa none diff --git a/doc/dox_comments/header_files/types.h b/doc/dox_comments/header_files/types.h index 99419bb56..d0a822d5f 100644 --- a/doc/dox_comments/header_files/types.h +++ b/doc/dox_comments/header_files/types.h @@ -33,11 +33,10 @@ _Example_ \code - int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER); - - if ( ints == NULL) { - // error allocating space - return MEMORY_E; + int* tenInts = XMALLOC(sizeof(int)*10, NULL, DYNAMIC_TYPE_TMP_BUFFER); + if (tenInts == NULL) { + // error allocating space + return MEMORY_E; } \endcode @@ -84,7 +83,9 @@ WOLFSSL_API void* XMALLOC(size_t n, void* heap, int type); _Example_ \code - none + int* tenInts = (int*)XMALLOC(sizeof(int)*10, NULL, DYNAMIC_TYPE_TMP_BUFFER); + int* twentyInts = (int*)XREALLOC(tenInts, sizeof(int)*20, NULL, + DYNAMIC_TYPE_TMP_BUFFER); \endcode \sa wolfSSL_Malloc @@ -127,9 +128,8 @@ WOLFSSL_API void* XREALLOC(void *p, size_t n, void* heap, int type); _Example_ \code - int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER); - - if ( ints == NULL) { + int* tenInts = XMALLOC(sizeof(int) * 10, NULL, DYNAMIC_TYPE_TMP_BUFFER); + if (tenInts == NULL) { // error allocating space return MEMORY_E; } From c29a373308d762b394a59ba3fbcacd0bc8538339 Mon Sep 17 00:00:00 2001 From: David Garske Date: Wed, 28 Jul 2021 09:50:37 -0700 Subject: [PATCH 2/2] Cleanups for Arduino examples. Resolves PR #3126 --- IDE/ARDUINO/README.md | 4 +- .../wolfssl_client/wolfssl_client.ino | 11 ++-- .../wolfssl_server/wolfssl_server.ino | 17 +++-- IDE/ARDUINO/wolfssl-arduino.sh | 64 +++++++++++-------- 4 files changed, 58 insertions(+), 38 deletions(-) diff --git a/IDE/ARDUINO/README.md b/IDE/ARDUINO/README.md index a8135d750..f7d9788b6 100644 --- a/IDE/ARDUINO/README.md +++ b/IDE/ARDUINO/README.md @@ -17,8 +17,8 @@ Step 2: Copy the directory wolfSSL that was just created to: Step 3: Edit `/wolfSSL/user_settings.h` If building for Intel Galileo platform add: `#define INTEL_GALILEO`. -Add any other custom settings, for a good start see the below in wolfssl root. -(See wolfssl/IDE/ROWLEY-CROSSWORKS-ARM/user_settings.h) +Add any other custom settings, for a good start see the examples in wolfssl root +"/examples/configs/user_settings_*.h" Step 4: If you experience any issues with custom user_settings.h see the wolfssl porting guide here for more assistance: https://www.wolfssl.com/docs/porting-guide/ diff --git a/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino b/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino index b5c83aa41..6984d886f 100644 --- a/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino +++ b/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino @@ -24,8 +24,8 @@ #include #include -const char host[] = "192.168.1.148"; // server to connect to -const int port = 11111; // port on server to connect to +const char host[] = "192.168.1.148"; /* server to connect to */ +const int port = 11111; /* port on server to connect to */ int EthernetSend(WOLFSSL* ssl, char* msg, int sz, void* ctx); int EthernetReceive(WOLFSSL* ssl, char* reply, int sz, void* ctx); @@ -51,7 +51,7 @@ void setup() { Serial.println("unable to get ctx"); return; } - // initialize wolfSSL using callback functions + /* initialize wolfSSL using callback functions */ wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); wolfSSL_SetIOSend(ctx, EthernetSend); wolfSSL_SetIORecv(ctx, EthernetReceive); @@ -119,7 +119,10 @@ void loop() { if ((wolfSSL_write(ssl, msg, msgSz)) == msgSz) { Serial.print("Server response: "); - while (client.available() || wolfSSL_pending(ssl)) { + /* wait for data */ + while (!client.available()) {} + /* read data */ + while (wolfSSL_pending(ssl)) { input = wolfSSL_read(ssl, reply, sizeof(reply) - 1); total_input += input; if (input < 0) { diff --git a/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino b/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino index 6d5478d5a..2b2492ad8 100644 --- a/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino +++ b/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino @@ -31,7 +31,7 @@ #error Please undefine NO_WOLFSSL_SERVER for this example #endif -const int port = 11111; // port to listen on +const int port = 11111; /* port to listen on */ int EthernetSend(WOLFSSL* ssl, char* msg, int sz, void* ctx); int EthernetReceive(WOLFSSL* ssl, char* reply, int sz, void* ctx); @@ -59,12 +59,12 @@ void setup() { return; } - // initialize wolfSSL using callback functions + /* initialize wolfSSL using callback functions */ wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); wolfSSL_SetIOSend(ctx, EthernetSend); wolfSSL_SetIORecv(ctx, EthernetReceive); - // setup the private key and certificate + /* setup the private key and certificate */ err = wolfSSL_CTX_use_PrivateKey_buffer(ctx, ecc_key_der_256, sizeof_ecc_key_der_256, WOLFSSL_FILETYPE_ASN1); if (err != WOLFSSL_SUCCESS) { @@ -78,7 +78,7 @@ void setup() { return; } - // Start the server + /* Start the server */ server.begin(); return; @@ -110,7 +110,7 @@ void loop() { int replySz = 0; const char* cipherName; - // Listen for incoming client requests. + /* Listen for incoming client requests. */ client = server.available(); if (!client) { return; @@ -142,7 +142,10 @@ void loop() { Serial.println(cipherName); Serial.print("Server Read: "); - while (client.available() || wolfSSL_pending(ssl)) { + /* wait for data */ + while (!client.available()) {} + /* read data */ + while (wolfSSL_pending(ssl)) { input = wolfSSL_read(ssl, reply, sizeof(reply) - 1); if (input < 0) { err = wolfSSL_get_error(ssl, 0); @@ -159,7 +162,7 @@ void loop() { } } - // echo data + /* echo data */ if ((wolfSSL_write(ssl, reply, replySz)) != replySz) { err = wolfSSL_get_error(ssl, 0); wolfSSL_ERR_error_string(err, errBuf); diff --git a/IDE/ARDUINO/wolfssl-arduino.sh b/IDE/ARDUINO/wolfssl-arduino.sh index 076a2a628..e1267a862 100755 --- a/IDE/ARDUINO/wolfssl-arduino.sh +++ b/IDE/ARDUINO/wolfssl-arduino.sh @@ -11,20 +11,29 @@ space(){ } if [ "$DIR" = "ARDUINO" ]; then - rm -rf wolfSSL - mkdir wolfSSL + if [ ! -d "wolfSSL" ]; then + mkdir wolfSSL + fi cp ../../src/*.c ./wolfSSL cp ../../wolfcrypt/src/*.c ./wolfSSL - mkdir wolfSSL/wolfssl + if [ ! -d "wolfSSL/wolfssl" ]; then + mkdir wolfSSL/wolfssl + fi cp ../../wolfssl/*.h ./wolfSSL/wolfssl - mkdir wolfSSL/wolfssl/wolfcrypt + if [ ! -d "wolfSSL/wolfssl/wolfcrypt" ]; then + mkdir wolfSSL/wolfssl/wolfcrypt + fi cp ../../wolfssl/wolfcrypt/*.h ./wolfSSL/wolfssl/wolfcrypt # support misc.c as include in wolfcrypt/src - mkdir ./wolfSSL/wolfcrypt - mkdir ./wolfSSL/wolfcrypt/src + if [ ! -d "./wolfSSL/wolfcrypt" ]; then + mkdir ./wolfSSL/wolfcrypt + fi + if [ ! -d "./wolfSSL/wolfcrypt/src" ]; then + mkdir ./wolfSSL/wolfcrypt/src + fi cp ../../wolfcrypt/src/misc.c ./wolfSSL/wolfcrypt/src cp ../../wolfcrypt/src/asm.c ./wolfSSL/wolfcrypt/src @@ -37,31 +46,36 @@ if [ "$DIR" = "ARDUINO" ]; then cp ./wolfSSL/wolfssl/bio.c ./wolfSSL/wolfcrypt/src/bio.c # copy openssl compatibility headers to their appropriate location - mkdir ./wolfSSL/wolfssl/openssl + if [ ! -d "./wolfSSL/wolfssl/openssl" ]; then + mkdir ./wolfSSL/wolfssl/openssl + fi cp ../../wolfssl/openssl/* ./wolfSSL/wolfssl/openssl echo "/* Generated wolfSSL header file for Arduino */" > ./wolfSSL/wolfssl.h + echo "#include " >> ./wolfSSL/wolfssl.h echo "#include " >> ./wolfSSL/wolfssl.h echo "#include " >> ./wolfSSL/wolfssl.h - echo "/* Generated wolfSSL user_settings.h file for Arduino */" > ./wolfSSL/user_settings.h - echo "#ifndef ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h - echo "#define ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h - space wolfSSL/user_settings.h - echo "/* Platform */" >> ./wolfSSL/user_settings.h - echo "#define WOLFSSL_ARDUINO" >> ./wolfSSL/user_settings.h - space wolfSSL/user_settings.h - echo "/* Math library (remove this to use normal math)*/" >> ./wolfSSL/user_settings.h - echo "#define USE_FAST_MATH" >> ./wolfSSL/user_settings.h - echo "#define TFM_NO_ASM" >> ./wolfSSL/user_settings.h - space wolfSSL/user_settings.h - echo "/* RNG DEFAULT !!FOR TESTING ONLY!! */" >> ./wolfSSL/user_settings.h - echo "/* comment out the error below to get started w/ bad entropy source" >> ./wolfSSL/user_settings.h - echo " * This will need fixed before distribution but is OK to test with */" >> ./wolfSSL/user_settings.h - echo "#error \"needs solved, see: https://www.wolfssl.com/docs/porting-guide/\"" >> ./wolfSSL/user_settings.h - echo "#define WOLFSSL_GENSEED_FORTEST" >> ./wolfSSL/user_settings.h - space wolfSSL/user_settings.h - echo "#endif /* ARDUINO_USER_SETTINGS_H */" >> ./wolfSSL/user_settings.h + if [ ! -f "./wolfSSL/user_settings.h" ]; then + echo "/* Generated wolfSSL user_settings.h file for Arduino */" > ./wolfSSL/user_settings.h + echo "#ifndef ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h + echo "#define ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h + space ./wolfSSL/user_settings.h + echo "/* Platform */" >> ./wolfSSL/user_settings.h + echo "#define WOLFSSL_ARDUINO" >> ./wolfSSL/user_settings.h + space ./wolfSSL/user_settings.h + echo "/* Math library (remove this to use normal math)*/" >> ./wolfSSL/user_settings.h + echo "#define USE_FAST_MATH" >> ./wolfSSL/user_settings.h + echo "#define TFM_NO_ASM" >> ./wolfSSL/user_settings.h + space ./wolfSSL/user_settings.h + echo "/* RNG DEFAULT !!FOR TESTING ONLY!! */" >> ./wolfSSL/user_settings.h + echo "/* comment out the error below to get started w/ bad entropy source" >> ./wolfSSL/user_settings.h + echo " * This will need fixed before distribution but is OK to test with */" >> ./wolfSSL/user_settings.h + echo "#error \"needs solved, see: https://www.wolfssl.com/docs/porting-guide/\"" >> ./wolfSSL/user_settings.h + echo "#define WOLFSSL_GENSEED_FORTEST" >> ./wolfSSL/user_settings.h + space ./wolfSSL/user_settings.h + echo "#endif /* ARDUINO_USER_SETTINGS_H */" >> ./wolfSSL/user_settings.h + fi cp wolfSSL/wolfssl/wolfcrypt/settings.h wolfSSL/wolfssl/wolfcrypt/settings.h.bak echo " /* wolfSSL Generated ARDUINO settings */" > ./wolfSSL/wolfssl/wolfcrypt/settings.h