AxlTls -- TLS Support
=====================

Optional TLS 1.2 support using `mbedTLS <https://github.com/Mbed-TLS/mbedtls>`_
3.6. Provides HTTPS server/client, self-signed certificate generation,
and transparent TCP encryption.

**Build requirement**: ``make AXL_TLS=1`` (adds ~200KB to the binary).
Without this flag, all TLS functions return -1/NULL/false.

Header: ``<axl/axl-tls.h>``

Overview
--------

AXL's TLS module wraps mbedTLS to provide:

- Self-signed ECDSA P-256 certificate generation
- TLS 1.2 server contexts (for HTTPS)
- TLS 1.2 client contexts (for HTTPS GET/POST)
- Transparent integration with ``AxlHttpServer`` and ``AxlHttpClient``

HTTPS Server
~~~~~~~~~~~~

Generate a certificate and enable TLS on the HTTP server:

.. code-block:: c

   #include <axl.h>

   axl_tls_init();

   // Generate self-signed cert (valid 10 years, ECDSA P-256)
   void *cert, *key;
   size_t cert_len, key_len;
   axl_tls_generate_self_signed("MyServer", NULL, 0,
                                &cert, &cert_len, &key, &key_len);

   // Create HTTPS server
   AxlHttpServer *s = axl_http_server_new(8443);
   axl_http_server_use_tls(s, cert, cert_len, key, key_len);
   axl_http_server_add_route(s, "GET", "/", handler, NULL);

   axl_free(cert);
   axl_free(key);

   axl_http_server_run(s);  // serves HTTPS

HTTPS Client
~~~~~~~~~~~~

HTTPS is automatic -- just use an ``https://`` URL:

.. code-block:: c

   AXL_AUTOPTR(AxlHttpClient) c = axl_http_client_new();
   AXL_AUTOPTR(AxlHttpClientResponse) resp = NULL;

   // TLS handshake happens automatically
   axl_http_get(c, "https://192.168.1.1:8443/api/status", &resp);

Certificate Generation
~~~~~~~~~~~~~~~~~~~~~~

``axl_tls_generate_self_signed`` creates an ECDSA P-256 certificate
with SHA-256 signature:

- **Subject**: ``CN=<name>,O=AximCode``
- **Validity**: current year to +10 years
- **SubjectAltName**: ``DNS:localhost``, ``IP:127.0.0.1``, plus any
  provided IP addresses
- **Output**: DER-encoded certificate and private key (caller frees)

Entropy
~~~~~~~

mbedTLS needs random numbers for key generation and TLS handshakes.
AXL provides entropy via:

1. **EFI_RNG_PROTOCOL** (hardware RNG) -- preferred, used when available
2. **Software fallback** -- system time + monotonic counter mixing.
   A warning is logged when the fallback is used.

Security Considerations
~~~~~~~~~~~~~~~~~~~~~~~

- Self-signed certificates are **not trusted** by browsers or standard
  TLS clients. Use ``curl --insecure`` or configure trust-on-first-use.
- Certificate verification is **disabled** for client connections
  (``MBEDTLS_SSL_VERIFY_NONE``). This is appropriate for BMC/embedded
  use but not for public internet TLS.
- The software entropy fallback is **not cryptographically strong**.
  For production use on hardware without an RNG, consider providing
  your own entropy source.

API Reference
-------------

.. doxygenfile:: axl-tls.h