Merge pull request #8514 from gojimmypi/pr-introduce-arduino-wolfssl_AES_CTR

Introduce and move new Arduino examples and configuration updates.

Author: dgarske

.wolfssl_known_macro_extras

@@ -9,9 +9,17 @@ APP_ESP_HTTP_CLIENT_EXAMPLE
 APSTUDIO_INVOKED
 ARCH_sim
 ARDUINO
+ARDUINO_ARCH_ESP32
+ARDUINO_ARCH_ESP8266
+ARDUINO_ARCH_MBED
+ARDUINO_ARCH_NRF52
 ARDUINO_ARCH_RP2040
+ARDUINO_ARCH_SAMD
+ARDUINO_ARCH_STM32
 ARDUINO_SAMD_NANO_33_IOT
 ARDUINO_SAM_DUE
+ARDUINO_SEEED_XIAO
+ARDUINO_TEENSY41
 ASN_DUMP_OID
 ASN_TEMPLATE_SKIP_ISCA_CHECK
 ATCAPRINTF
@@ -176,6 +184,7 @@ ESP_IDF_VERSION_MAJOR
 ESP_IDF_VERSION_MINOR
 ESP_PLATFORM
 ESP_TASK_MAIN_STACK
+ETHERNET_AVAILABLE
 EV_TRIGGER
 FP_ECC_CONTROL
 FREERTOS_TCP_WINSIM
@@ -554,11 +563,13 @@ WC_SSIZE_TYPE
 WC_STRICT_SIG
 WC_WANT_FLAG_DONT_USE_AESNI
 WC_XMSS_FULL_HASH
+WIFI_AVAILABLE
 WOLFCRYPT_FIPS_CORE_DYNAMIC_HASH_VALUE
 WOLFSENTRY_H
 WOLFSENTRY_NO_JSON
 WOLFSSL_32BIT_MILLI_TIME
 WOLFSSL_AARCH64_PRIVILEGE_MODE
+WOLFSSL_AES_CTR_EXAMPLE
 WOLFSSL_AESNI_BY4
 WOLFSSL_AESNI_BY6
 WOLFSSL_AFTER_DATE_CLOCK_SKEW
@@ -607,6 +618,7 @@ WOLFSSL_CHECK_DESKEY
 WOLFSSL_CHECK_MEM_ZERO
 WOLFSSL_CHIBIOS
 WOLFSSL_CLANG_TIDY
+WOLFSSL_CLIENT_EXAMPLE
 WOLFSSL_COMMERCIAL_LICENSE
 WOLFSSL_CONTIKI
 WOLFSSL_CRL_ALLOW_MISSING_CDP
@@ -780,6 +792,7 @@ WOLFSSL_SE050_INIT
 WOLFSSL_SE050_NO_RSA
 WOLFSSL_SE050_NO_TRNG
 WOLFSSL_SECURE_RENEGOTIATION_ON_BY_DEFAULT
+WOLFSSL_SERVER_EXAMPLE
 WOLFSSL_SETTINGS_FILE
 WOLFSSL_SH224
 WOLFSSL_SHA256_ALT_CH_MAJ
@@ -797,6 +810,7 @@ WOLFSSL_STM32_RNG_NOLIB
 WOLFSSL_STRONGEST_HASH_SIG
 WOLFSSL_STSAFE_TAKES_SLOT
 WOLFSSL_TELIT_M2MB
+WOLFSSL_TEMPLATE_EXAMPLE
 WOLFSSL_THREADED_CRYPT
 WOLFSSL_TICKET_DECRYPT_NO_CREATE
 WOLFSSL_TICKET_ENC_AES128_GCM

IDE/ARDUINO/README.md

@@ -2,8 +2,19 @@
 
 See the [example sketches](./sketches/README.md):
 
-- [sketches/wolfssl_server](./sketches/wolfssl_server/README.md)
-- [sketches/wolfssl_client](./sketches/wolfssl_client/README.md)
+NOTE: Moving; See https://github.com/wolfSSL/wolfssl-examples/pull/499
+
+Bare-bones templates:
+
+- [sketches/wolfssl_version](./sketches/wolfssl_version/README.md) single file.
+- [sketches/template](./sketches/template/README.md) multiple file example.
+
+Functional examples:
+- [sketches/wolfssl_AES_CTR](./sketches/wolfssl_AES_CTR/README.md) AES CTR Encrypt / decrypt.
+- [sketches/wolfssl_client](./sketches/wolfssl_client/README.md) TLS Client.
+- [sketches/wolfssl_server](./sketches/wolfssl_server/README.md) TLS Server.
+
+Both the `template` and `wolfssl_AES_CTR` examples include VisualGDB project files.
 
 When publishing a new version to the Arduino Registry, be sure to edit `WOLFSSL_VERSION_ARUINO_SUFFIX` in the `wolfssl-arduino.sh` script.
 
@@ -62,7 +73,7 @@ from within the `wolfssl/IDE/ARDUINO` directory:
 
 1. `./wolfssl-arduino.sh`
     - Creates an Arduino Library directory structure in the local `wolfSSL` directory of `IDE/ARDUINO`.
-    - You can add your own `user_settings.h`, or copy/rename the [default](../../examples/configs/user_settings_arduino.h).
+    - You can add your own `user_settings.h`, or copy/rename the [default](https://github.com/wolfSSL/wolfssl/blob/master/examples/configs/user_settings_arduino.h).
 
 2. `./wolfssl-arduino.sh INSTALL` (The most common option)
     - Creates an Arduino Library in the local `wolfSSL` directory

IDE/ARDUINO/include.am

@@ -2,16 +2,32 @@
 # included from Top Level Makefile.am
 # All paths should be given relative to the root
 
+# Library files:
 EXTRA_DIST+= IDE/ARDUINO/README.md
+
+# There's an Arduino-specific Arduino_README_prepend.md that will be prepended to wolfSSL README.md
+# Not to be confused with the interim PREPENDED_README.md that is created by script.
 EXTRA_DIST+= IDE/ARDUINO/Arduino_README_prepend.md
+
+# Core library files
+EXTRA_DIST+= IDE/ARDUINO/wolfssl.h
+EXTRA_DIST+= IDE/ARDUINO/wolfssl.h
+EXTRA_DIST+= IDE/ARDUINO/wolfssl-arduino.cpp
+
 EXTRA_DIST+= IDE/ARDUINO/keywords.txt
 EXTRA_DIST+= IDE/ARDUINO/library.properties.template
+
+# Sketch Examples
 EXTRA_DIST+= IDE/ARDUINO/sketches/README.md
+
+# wolfssl_client example sketch
 EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_client/README.md
-EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino
+
+# wolfssl_server example sketch
 EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_server/README.md
-EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino
+
+# wolfssl_version example sketch
 EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_version/README.md
-EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_version/wolfssl_version.ino
-EXTRA_DIST+= IDE/ARDUINO/wolfssl.h
+
+# Publishing script, either local install or to github.com/wolfSSL/Arduino-wolfSSL clone directory.
 EXTRA_DIST+= IDE/ARDUINO/wolfssl-arduino.sh

IDE/ARDUINO/sketches/README.md

@@ -1,15 +1,20 @@
 # wolfSSL Arduino Examples
 
-There are currently two example Arduino sketches:
+There are currently five example Arduino sketches:
 
-* [wolfssl_client](./wolfssl_client/README.md): Basic TLS listening client.
-* [wolfssl_server](./wolfssl_server/README.md): Basic TLS server.
+NOTE: Moving; See https://github.com/wolfSSL/wolfssl-examples/pull/499
+
+* `template`: Reference template wolfSSL example, including optional VisualGDB project files.
+* `wolfssl_AES_CTR`: Basic AES CTR Encryption / Decryption example.
+* `wolfssl_client`: Basic TLS listening client.
+* `wolfssl_server`: Basic TLS server.
+* `wolfssl_version`: Bare-bones wolfSSL example.
 
 Examples have been most recently confirmed operational on the
 [Arduino IDE](https://www.arduino.cc/en/software) 2.2.1.
 
 For examples on other platforms, see the [IDE directory](https://github.com/wolfssl/wolfssl/tree/master/IDE).
-Additional examples can be found on [wolfSSL/wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples/).
+Additional wolfssl examples can be found at [wolfSSL/wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples/).
 
 ## Using wolfSSL
 
@@ -20,15 +25,51 @@ The typical include will look something like this:
 
  /* wolfSSL user_settings.h must be included from settings.h
   * Make all configurations changes in user_settings.h
-  * Do not edit wolfSSL `settings.h` or `configh.h` files.
+  * Do not edit wolfSSL `settings.h` or `config.h` files.
   * Do not explicitly include user_settings.h in any source code.
   * Each Arduino sketch that uses wolfSSL must have: #include "wolfssl.h"
   * C/C++ source files can use: #include <wolfssl/wolfcrypt/settings.h>
   * The wolfSSL "settings.h" must be included in each source file using wolfSSL.
   * The wolfSSL "settings.h" must appear before any other wolfSSL include.
   */
 #include <wolfssl.h>
+
+/* settings.h is typically included in wolfssl.h, but here as a reminder: */
+#include <wolfssl/wolfcrypt/settings.h>
+
+/* Any other wolfSSL includes follow:*
 #include <wolfssl/version.h>
 ```
 
+## Configuring wolfSSL
+
+See the `user_settings.h` in the Arduino library `wolfssl/src` directory. For Windows users this is typically:
+
+```
+C:\Users\%USERNAME%\Documents\Arduino\libraries\wolfssl\src
+```
+
+WARNING: Changes to the library `user_settings.h` file will be lost when upgrading wolfSSL using the Arduino IDE.
+
+## Troubleshooting
+
+If compile problems are encountered, for example:
+
+```
+ctags: cannot open temporary file : File exists
+exit status 1
+
+Compilation error: exit status 1
+```
+
+Try deleting the Arduino cache directory:
+
+```
+C:\Users\%USERNAME%\AppData\Local\arduino\sketches
+```
+
+For VisualGDB users, delete the project `.vs`, `Output`, and `TraceReports` directories.
+
+## More Information
+
 For more details, see [IDE/ARDUINO/README.md](https://github.com/wolfSSL/wolfssl/blob/master/IDE/ARDUINO/README.md)

IDE/ARDUINO/sketches/wolfssl_client/README.md

@@ -1,6 +1,14 @@
 # Arduino Basic TLS Listening Client
 
-Open the [wolfssl_client.ino](./wolfssl_client.ino) file in the Arduino IDE.
+Open the `wolfssl_client.ino` file in the Arduino IDE.
+
+NOTE: Moving; See https://github.com/wolfSSL/wolfssl-examples/pull/499
+
+If using WiFi, be sure to set `ssid` and `password` values.
+
+May need "Ethernet by Various" library to be installed. Tested with v2.0.2 and v2.8.1.
+
+See the `#define WOLFSSL_TLS_SERVER_HOST` to set your own server address.
 
 Other IDE products are also supported, such as: