wolfssl-examples/tls

wolfSSL TLS Example Applications

This directory contains example applications demonstrating various wolfSSL TLS features.

Building the Examples

make

Configuration Requirements

Some examples require specific wolfSSL configuration options:

PKCallback Examples (client-tls-pkcallback, server-tls-pkcallback)

• Requires: --enable-pkcallbacks
• Purpose: Enable public key callback functionality
• Error if not enabled: "PK not compiled in"

TLS BIO and PKCS12 Examples (client-tls-bio, client-tls-pkcs12)

• Requires: --enable-opensslextra and --enable-des3
• Purpose: OpenSSL compatibility layer and DES3 for PKCS12
• Error if not enabled: "requires --enable-opensslextra" or "wolfSSL not configured with --enable-des3"

CryptoCB Examples (client-tls-cryptocb, server-tls-cryptocb)

• Requires: --enable-cryptocb
• Purpose: Enable crypto callback interface
• Error if not enabled: "Please configure wolfSSL with --enable-cryptocb"

WriteUp Examples (client-tls-writedup, server-tls-writedup)

• Requires: --enable-writedup
• Purpose: Enable file descriptor duplication
• Error if not enabled: "wolfSSL not configured with --enable-writedup"

ECH Examples (client-ech, server-ech-local)

• Requires: --enable-ech
• Purpose: Enable Encrypted Client Hello support
• Error if not enabled: "Please build wolfssl with --enable-ech"

TLS 1.3 Resume Example (client-tls13-resume)

• Requires: Client certificates (same as client-tls13)
• Files needed:
  • CERT_FILE: "../certs/client-cert.pem"
  • KEY_FILE: "../certs/client-key.pem"
  • CA_FILE: "../certs/ca-cert.pem"

Hardware Dependencies

UART Examples (client-tls-uart, server-tls-uart)

See UART Requirements for detailed setup instructions.

• Requires physical UART hardware
• Device must be accessible at /dev/ttyUSB0
• Cannot be tested in virtual environments

Troubleshooting

1. Missing Configuration

# Configure wolfSSL with all required features
cd ~/repos/wolfssl
./configure --enable-pkcallbacks \
           --enable-opensslextra \
           --enable-cryptocb \
           --enable-des3 \
           --enable-writedup \
           --enable-ech
make
sudo make install

2. Certificate Issues

• Ensure all required certificates are in ../certs/ directory
• Check file permissions
• Verify certificate paths in example code

3. Hardware Issues

• For UART examples, verify hardware connection
• Check device permissions
• Use alternative examples for testing when hardware is unavailable

Example Categories

1. Basic TLS Examples

• client-tls / server-tls
• client-tls13 / server-tls13

2. Session Resumption

• client-tls-resume (TLS 1.2)
• client-tls13-resume (TLS 1.3)

3. Callback Examples

• client-tls-callback / server-tls-callback
• client-tls-cryptocb / server-tls-cryptocb
• client-tls-pkcallback / server-tls-pkcallback

4. Performance Examples

• client-tls-perf
• server-tls-epoll-perf
• server-tls-poll-perf

5. Special Features

• client-tls-ecdhe / server-tls-ecdhe
• client-tls-nonblocking / server-tls-nonblocking
• client-tls-writedup / server-tls-writedup
• memory-tls