Introduce new Arduino examples and configuration updates. TLSX gating

.wolfssl_known_macro_extras

@@ -551,6 +551,7 @@ 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
@@ -599,6 +600,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
@@ -769,6 +771,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

IDE/ARDUINO/README.md

@@ -2,8 +2,17 @@
 
 See the [example sketches](./sketches/README.md):
 
-- [sketches/wolfssl_server](./sketches/wolfssl_server/README.md)
-- [sketches/wolfssl_client](./sketches/wolfssl_client/README.md)
+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) AEC 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` ad `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.
 

IDE/ARDUINO/include.am

@@ -2,16 +2,42 @@
 # 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
+
+# wolfssl_AES_CTR example sketch
+EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_AES_CTR/README.md
+EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_AES_CTR/wolfssl_AES_CTR.ino
+EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_AES_CTR/wolfssl_AES_CTR.adeps
+EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_AES_CTR/wolfssl_AES_CTR.sln
+EXTRA_DIST+= IDE/ARDUINO/sketches/wolfssl_AES_CTR/wolfssl_AES_CTR.vgdbproj
+
+# 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,18 @@
 # wolfSSL Arduino Examples
 
-There are currently two example Arduino sketches:
+There are currently five example Arduino sketches:
 
+* [template](./template/README.md): Reference template wolfSSL example, including optional VisualGDB project files.
+* [wolfssl_AES_CTR](./wolfssl_AES_CTR/README.md): Basic AES CTR Encryption / Decryption example.
 * [wolfssl_client](./wolfssl_client/README.md): Basic TLS listening client.
 * [wolfssl_server](./wolfssl_server/README.md): Basic TLS server.
+* [wolfssl_version](./wolfssl_version/README.md): 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 wolfsll examples can be found at [wolfSSL/wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples/).
 
 ## Using wolfSSL
 
@@ -20,15 +23,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 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/template/README.md

@@ -0,0 +1,34 @@
+# Arduino AES CTR Example
+
+Open the [wolfssl_AES_CTR.ino](./wolfssl_AES_CTR.ino) file in the Arduino IDE.
+
+Other IDE products are also supported, such as:
+
+- [PlatformIO in VS Code](https://docs.platformio.org/en/latest/frameworks/arduino.html)
+- [VisualGDB](https://visualgdb.com/tutorials/arduino/)
+- [VisualMicro](https://www.visualmicro.com/)
+
+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/).
+
+
+### Troubleshooting
+
+When encountering odd errors such as `undefined reference to ``_impure_ptr'`, such as this:
+
+```text
+c:/users/gojimmypi/appdata/local/arduino15/packages/esp32/tools/xtensa-esp32-elf-gcc/esp-2021r2-patch5-8.4.0/bin/../lib/gcc/xtensa-esp32-elf/8.4.0/../../../../xtensa-esp32-elf/bin/ld.exe: C:\Users\gojimmypi\AppData\Local\Temp\arduino\sketches\EAB8D79A02D1ECF107884802D893914E\libraries\wolfSSL\wolfcrypt\src\logging.c.o:(.literal.wolfssl_log+0x8): undefined reference to `_impure_ptr'
+collect2.exe: error: ld returned 1 exit status
+
+exit status 1
+
+Compilation error: exit status 1
+```
+
+Try cleaning the Arduino cache directories. For Windows, that's typically in:
+
+```text
+C:\Users\%USERNAME%\AppData\Local\Temp\arduino\sketches
+```
+
+Remove all other boards from other serial ports, leaving one the one being programmed.

IDE/ARDUINO/sketches/template/template.adeps

@@ -0,0 +1,21 @@
+<!-- Add this file to source control in order to automatically restore library dependencies when opening the project on another machine -->
+<ArduinoDependencyCollection xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <Dependencies>
+    <Dependency>
+      <Type>Platform</Type>
+      <Key>
+        <Packager>teensy</Packager>
+        <Name>avr</Name>
+        <Version>1.59.0</Version>
+      </Key>
+    </Dependency>
+    <Dependency>
+      <Type>Library</Type>
+      <Key>
+        <Packager>wolfSSL Inc.</Packager>
+        <Name>wolfssl</Name>
+        <Version>5.7.6</Version>
+      </Key>
+    </Dependency>
+  </Dependencies>
+</ArduinoDependencyCollection>

IDE/ARDUINO/sketches/template/template.ino

@@ -0,0 +1,141 @@
+/* template.ino
+ *
+ * Copyright (C) 2006-2025 wolfSSL Inc.
+ *
+ * This file is part of wolfSSL.
+ *
+ * wolfSSL is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * wolfSSL is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ */
+
+#include <Arduino.h>
+
+/* 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 `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.
+ */
+
+/* This is Arduino reference sketch example 2 of 2: multiple file .ino   */
+/* See also template.ino project example using a single file project.    */
+
+/* Do not insert attempts at appending wolfssl user_settings.h here.
+ * All wolfssl settings needed by wolfSSL must be in the user_settings.h */
+#include <wolfssl.h>
+
+/* settings.h is included from Arduino `wolfssl.h`, but a good practice to
+ * include before any other wolfssl headers. As a reminder here: */
+#include <wolfssl/wolfcrypt/settings.h>
+
+/* Include a simple wolfSSL header to this example: */
+#include <wolfssl/version.h>
+
+/* There's a wolfSSL_Arduino_Serial_Print() for logging messages in wolfssl. */
+#include <wolfssl/wolfcrypt/logging.h>
+
+/* Include files (.c, .cpp, .h) typically in the same directory as the sketch;
+ * The wolfssl_helper is an example of this: */
+#include "wolfssl_helper.h"
+
+/* Arduino library header files are typically not in an `include` directory;
+ * The wolfssl_library is an example of a library directory: */
+#include "wolfssl_library/wolfssl_library.h"
+#include "wolfssl_library/src/wolfssl_library.cpp"  /* Force compilation */
+
+/* Choose a monitor serial baud rate: 9600, 14400, 19200, 57600, 74880, etc. */
+#define SERIAL_BAUD 115200
+
+/*****************************************************************************/
+/*****************************************************************************/
+/* Arduino setup()                                                           */
+/*****************************************************************************/
+/*****************************************************************************/
+void setup() {
+    Serial.begin(SERIAL_BAUD);
+    while (!Serial) {
+        /* wait for serial port to connect. Needed for native USB port only */
+        delay(10);
+    }
+    /* See https://github.com/wolfSSL/wolfssl/blob/master/examples/configs/user_settings_arduino.h  */
+    /* Various historical versions have differing features enabled. */
+#ifdef WOLFSSL_USER_SETTINGS_ID
+    /* Print the release version at runtime for reference. */
+    Serial.println(WOLFSSL_USER_SETTINGS_ID);
+#else
+    /* Introduced after v5.7.6, or otherwise missing from user_settings.h  */
+    Serial.println("A WOLFSSL_USER_SETTINGS_ID not found.");
+#endif
+
+    Serial.println(F("wolfSSL setup complete!!"));
+    Serial.println(F(""));
+    Serial.println(F(""));
+}
+
+/*****************************************************************************/
+/*****************************************************************************/
+/* Arduino loop()                                                            */
+/*****************************************************************************/
+/*****************************************************************************/
+void loop() {
+    int ret;
+    Serial.println("\nLOOP!\n\n");
+
+    Serial.print("wolfSSL Version: ");
+    Serial.println(LIBWOLFSSL_VERSION_STRING);
+
+    /* A project-level include.
+     * These files typically WILL be visible automatically in the Arduino IDE */
+    ret = wolfssl_helper_sample();
+    Serial.printf("- wolfssl_helper_sample ret = %d\r\n", ret);
+
+    /* A local library directory.
+     * These files typically WILL NOT be visible in the Arduino IDE */
+    ret = wolfssl_library_sample();
+    Serial.printf("- wolfssl_library_sample ret = %d\r\n", ret);
+
+    /* This next section demonstrates wolfSSL logging. Logging is toggled
+     * on or off for each Arduino loop() iteration. WOLFSSL_MSG() only
+     * prints messages when debugging is turned on. */
+
+    /* Internal wolfssl_log() uses wolfSSL_Arduino_Serial_Print() */
+    Serial.println("");
+    Serial.println("Example wolfSSL_Arduino_Serial_Print():");
+    wolfSSL_Arduino_Serial_Print("Hello from wolfSSL_Arduino_Serial_Print");
+
+    /* WOLFSSL_MSG uses wolfssl_log() for conditional messages. */
+    Serial.println("The next line is conditional depending on debug state:");
+    WOLFSSL_MSG("Hello from wolfssl_log");
+    Serial.println("");
+
+    ret = WOLFSSL_IS_DEBUG_ON();
+    if (ret == 0) {
+        Serial.println(""); /* nothing would have printed in WOLFSSL_MSG */
+        Serial.println("WOLFSSL_IS_DEBUG_ON is not set (debugging off)");
+
+        Serial.println("Calling wolfSSL_Debugging_ON()");
+        wolfSSL_Debugging_ON();
+    }
+    else {
+        Serial.println("WOLFSSL_IS_DEBUG_ON is set (debugging on)");
+
+        Serial.println("Calling wolfSSL_Debugging_OFF()");
+        wolfSSL_Debugging_OFF();
+    }
+
+    delay(60000);
+}

IDE/ARDUINO/sketches/template/template.sln

@@ -0,0 +1,32 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.12.35728.132
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{803FD0C6-D64E-4E16-9DC3-1DAEC859A3D2}") = "template", "template.vgdbproj", "{DB43C533-4CE4-4470-90D2-87277C378CF8}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Project Files", "Project Files", "{0BF06CD4-E54C-4212-BC24-278E0285C62B}"
+	ProjectSection(SolutionItems) = preProject
+		..\README.md = ..\README.md
+		..\..\wolfssl-arduino.sh = ..\..\wolfssl-arduino.sh
+		wolfssl_helper.c = wolfssl_helper.c
+		wolfssl_helper.h = wolfssl_helper.h
+		wolfssl_library\src\wolfssl_library.cpp = wolfssl_library\src\wolfssl_library.cpp
+		wolfssl_library\wolfssl_library.h = wolfssl_library\wolfssl_library.h
+	EndProjectSection
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Teensy_4 1 = Debug|Teensy_4 1
+		Release|Teensy_4 1 = Release|Teensy_4 1
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{DB43C533-4CE4-4470-90D2-87277C378CF8}.Debug|Teensy_4 1.ActiveCfg = Debug|Teensy_4 1
+		{DB43C533-4CE4-4470-90D2-87277C378CF8}.Debug|Teensy_4 1.Build.0 = Debug|Teensy_4 1
+		{DB43C533-4CE4-4470-90D2-87277C378CF8}.Release|Teensy_4 1.ActiveCfg = Release|Teensy_4 1
+		{DB43C533-4CE4-4470-90D2-87277C378CF8}.Release|Teensy_4 1.Build.0 = Release|Teensy_4 1
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal