Recently the question of building the wolfCrypt test and benchmark applications in a non-standard environment has been asked multiple times to our support team. We wanted to provide a solution for those who might be struggling! The wolfSSL embedded SSL/TLS library ships with both of these applications to help users get up and running on their platform with wolfSSL.
The wolfCrypt test application runs algorithm tests on all enabled algorithms to verify they are working correctly on your platform. This should be the first step taken when porting wolfSSL to a new platform.
The wolfCrypt benchmark application benchmarks cryptography algorithms enabled in wolfSSL. This gives users an idea of the cryptography library performance for their specific platform and configuration. This can also be helpful for seeing the performance difference in using software cryptography versus hardware cryptography.
To start let’s cover how you would call the wolfCrypt test or benchmark from your application.
typedef struct func_args {
int argc;
char** argv;
int return_code;
} func_args;
/* ... other code ... */
int main (void)
{
/* other function declarations */
func_args args;
/* ... system setup and initialization ... */
/* for wolfcrypt test app: */
ret = wolfcrypt_test(&args);
/* for benchmark app: */
/* ret = benchmark_test(&args); */
if (ret != 0) {
printf("wolfCrypt tests failed!\n")
printf("test returned error code: %d\n", ret);
printf("the crypto error code was: %d\n", args.return_code);
} else {
printf("crypto tests PASSED!\n");
}
while (1)
{
/* Application code TODO: Logic here */
}
}
In addition to the porting and tuning guides found at the links below, there may be some other items to add to your settings before the wolfCrypt tests or benchmark will run.
wolfSSL Porting Guide
wolfSSL Tuning Guide
Items not covered in the porting and tuning guide include:
- NO_MAIN_DRIVER
- BENCH_EMBEDDED
- NO_64BIT
- USE_CERT_BUFFERS_XXX(X)
- ALT_ECC_SIZE
- ECC_USER_CURVES (and related defines)
- FP_MAX_BITS.
And while the fastmath vs normal math libraries are covered, we wanted to expand on that explanation here, highlighting the difference between fastmath (uses more stack and less heap) versus the normal math library (uses more heap and less stack).
Please feel free to use these defines as a starting point when porting the wolfCrypt test application (<wolfssl-root>/wolcrypt/test/test.c) and wolfCrypt benchmark application (<wolfssl-root>/wolfcrypt/benchmark/benchmark.c) to your non-standard environment!
/* Other defines as determined from the wolfSSL porting guide found here:
* https://wolfssl.com/wolfSSL/Docs-wolfssl-porting-guide.html
*/
/* Purpose:
* If running the wolfcrypt/benchmark/benchmark.c
* app will reduce stack use for embedded devices
*/
#define BENCH_EMBEDDED
/* Purpose:
* Embedded systems already have a main method typically
* will remove the "main" in benchmark.c and test.c
*/
#define NO_MAIN_DRIVER
/* Purpose:
* If working on a 32-bit system, it will sometimes use 2x 32-bit types to execute 64-bit
* math operations which greatly slows down computation time. This define can speeds
* things up. Commented by default, uncomment if computation speeds are too slow.
*/
/* #define NO_64BIT */
/* Begin RSA Section */
/* --------------------------------------------------- */
/* Uncomment the define for NO_RSA to remove RSA */
/* #define NO_RSA */
#ifndef NO_RSA
#error "Please set RSA key size then comment out or delete this line."
/* XXXX should be "2048" for 2048 bit RSA keys
* XXXX should be "1024" for 1024 bit RSA keys
* IE choose one of the following to uncomment
*/
/* #define USE_CERT_BUFFERS_2048 */
/* #define USE_CERT_BUFFERS_1024 */
/*
* the certificate buffers can be found in <wolfssl-root>/wolfssl/test_certs.h
*/
/* Purpose:
* To reduce stack based on RSA key size chosen
*/
#ifdef USE_CERT_BUFFERS_1024
#define FP_MAX_BITS 2048 /* (RSA key size selected x2) */
#elif defined(USE_CERT_BUFFERS_2048)
#define FP_MAX_BITS 4096
#endif /* USE_CERT_BUFFERS_1024 */
#endif /* NO_RSA */
/* --------------------------------------------------- */
/* End File System and RSA section */
/* Begin ECC Section */
/* --------------------------------------------------- */
/* Purpose:
* enable ECC. Comment to remove ECC
*/
#define HAVE_ECC
#ifdef HAVE_ECC
#define ECC_TIMING_RESISTANT /* See explenation for TFM_TIMING_RESISTANT */
#define USE_CERT_BUFFERS_256 /* for ecc, see File System and RSA Section above */
/* the certificate buffers can be found in <wolfssl-root>/wolfssl/test_certs.h
/* Purpose:
* Reduce ECC memory use
*/
#define ALT_ECC_SIZE
/* Purpose:
* Only allow for 256-bit ecc keys by default. To remove support for 256-bit ECC keys
* uncomment the next line.
*/
/* #define NO_ECC256 */
/*
* A list of supported ECC curves is included below, uncomment as desired.
* For other ECC defines see <wolfssl-root>/wolfcrypt/src/ecc.c
*/
#define ECC_USER_CURVES
/* #define HAVE_ECC112 */
/* #define HAVE_ECC128 */
/* #define HAVE_ECC160 */
/* #define HAVE_ECC192 */
/* #define HAVE_ECC224 */
/* #define HAVE_ECC239 */
/* #define HAVE_ECC320 */
/* #define HAVE_ECC384 */
/* #define HAVE_ECC512 */
/* #define HAVE_ECC521 */
#endif /* HAVE_ECC */
/* --------------------------------------------------- */
/* End ECC Section */
If you have any other questions or comments on this or anything else please contact us!
support@wolfssl.com
facts@wolfssl.com