mars-matrixssl

This repository is a mars-nwe special-purpose fork of MatrixSSL.

The fork intentionally keeps MatrixSSL native code mostly untouched and adds only a reduced OpenSSL-compatible surface needed by the mars-nwe consumers:

• nwwebui from mars-smart server-side TLS (SSL_CTX_*, SSL_*, error helpers).
• FLAIM/FTK client-side TLS and BIO calls used by F_SSLIOStream.

It does not resurrect the full historical MatrixSSL OpenSSL compatibility layer. The old opensslApi.c / opensslSocket.c implementation was used only as a reference for symbol names and is not restored. New compatibility code lives in matrixssl/openssl_compat.c with public shim headers under openssl/.

Build notes:

cmake -S . -B build -DMATRIXSSL_BUILD_OPENSSL_COMPAT=ON
cmake --build build
ctest --test-dir build --output-on-failure

MATRIXSSL_BUILD_OPENSSL_COMPAT defaults to ON in this fork. Disable it with -DMATRIXSSL_BUILD_OPENSSL_COMPAT=OFF to build only the native MatrixSSL API.

The CMake build also mirrors the legacy top-level Makefile more closely:

• MATRIXSSL_BUILD_TESTS=ON builds the crypto and MatrixSSL test programs from crypto/test, crypto/test/*perf, and matrixssl/test.
• MATRIXSSL_BUILD_APPS=ON builds the SSL/DTLS example applications from apps/common, apps/ssl, and apps/dtls.
• MATRIXSSL_BUILD_TOOLS=ON builds the malloc wrapper helper from core/wrapper on Unix-like systems.

Only safe smoke tests are registered with CTest. Interactive, benchmark, network server/client, and certificate-file tests are built but are not run automatically.

MATRIXSSL_LIBRARY_PREFIX changes the library output name, for example -DMATRIXSSL_LIBRARY_PREFIX=nw creates libnwmatrixssl. Test, app, and tool outputs use the same prefix by default through MATRIXSSL_PROGRAM_PREFIX, so the same build also creates names such as nwserver, nwclient, and nwwrap-malloc.so. Override MATRIXSSL_PROGRAM_PREFIX separately only when program names should differ from the library prefix.

When MatrixSSL is included with add_subdirectory() from another CMake project, the library still builds by default but tests, apps, and auxiliary tools default to OFF to avoid adding legacy standalone programs to the parent project's normal build. They can still be enabled explicitly with -DMATRIXSSL_BUILD_TESTS=ON, -DMATRIXSSL_BUILD_APPS=ON, or -DMATRIXSSL_BUILD_TOOLS=ON.

Security note: this compatibility layer is intentionally small and mars-nwe-specific. It should not be presented as a general OpenSSL replacement. In particular, the FTK-facing X509/BIO helper surface is limited to the calls that code uses.

---

Lightweight Embedded SSL/TLS Implementation Official source repository of MatrixSSL

##Overview MatrixSSL has been continuously maintained since 2002. It is the first open source small footprint SSL stack. Until recently, releases were tracked on http://freecode.com/projects/matrixssl

MatrixSSL is an embedded SSL and TLS implementation designed for small footprint IoT devices requiring low overhead per connection. It includes client and server support through TLS 1.3, mutual authentication, session resumption, and implementations of RSA, ECC, AES, SHA1, SHA-256, ChaCha20-Poly1305 and more. The source is well documented and contains portability layers for additional operating systems, cipher suites, and cryptography providers.

##Reporting Issues Please email matrixssl@rambus.com. Sensitive emails can be encrypted using the public key in this directory pgp.asc, Key fingerprint = C714 FAC4 3D95 3584 9926 25EB 4F08 F506 433F 9237.

##Features

• Small total footprint with crypto provider
• SSL 3.0 and TLS 1.0, 1.1, 1.2 and 1.3 server and client support
• Included crypto library - RSA, ECC, AES, 3DES, ARC4, SHA1, SHA256, MD5, ChaCha20-Poly1305
• Assembly language optimizations for Intel, ARM and MIPS
• Session re-keying and cipher renegotiation
• Full support for session resumption/caching
• Server Name Indication and Stateless Session Tickets
• RFC7301 Application Protocol Negotiation
• Server and client X.509 certificate chain authentication
• Client authentication with an external security token
• Parsing of X.509 .pem and ASN.1 DER certificate formats
• PKCS#1.5, PKCS#5 PKCS#8 and PKCS#12 support for key formatting
• RSASSA-PSS Signature Algorithm support
• Certificate Revocation List (CRL) support
• Fully cross platform, portable codebase; minimum use of system calls
• Pluggable cipher suite interface
• Pluggable crypto provider interface
• Pluggable operating system and malloc interface
• TCP/IP optional
• Multithreading optional
• Only a handful of external APIs, all non-blocking
• Example client and server code included
• Clean, heavily commented code in portable C
• User and developer documentation

CMake OpenSSL compatibility include layout

When the reduced OpenSSL compatibility layer is enabled, its headers are exported inside the MatrixSSL include root. With the default include directory this means matrixssl/openssl/*.h; with -DMATRIXSSL_LIBRARY_PREFIX=nw this becomes nwmatrixssl/openssl/*.h. Consumers may add the MatrixSSL include root itself and still include compatibility headers as <openssl/ssl.h>, without installing a top-level include/openssl directory that could conflict with system OpenSSL.