s2n-tls

An implementation of the TLS/SSL protocols

4,487

704

4,487

483

View on GitHub

Top Related Projects

wolfssl

2,283

The wolfSSL library is a small, fast, portable implementation of TLS/SSL for embedded devices to the cloud. wolfSSL supports up to TLS 1.3 and DTLS 1.3!

An open source, portable, easy to use, readable and flexible TLS library, and reference implementation of the PSA Cryptography API. Releases are on a varying cadence, typically around 3 - 6 months between releases.

boringssl

1,796

Mirror of BoringSSL

portable

1,349

LibreSSL Portable itself. This includes the build scaffold and compatibility layer that builds portable LibreSSL from the OpenBSD source code. Pull requests or patches sent to tech@openbsd.org are welcome.

Quick Overview

s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be simple, small, fast, and with security as a priority. It is developed by Amazon Web Services and is used in many AWS services that require TLS.

Pros

High performance and low latency
Strong focus on security with regular audits and formal verification
Designed to be simple and easy to understand, with a small codebase
Actively maintained by AWS with regular updates and improvements

Cons

Limited to TLS 1.2 and 1.3 protocols (no support for older versions)
May have a steeper learning curve compared to some other TLS libraries
Primarily focused on AWS ecosystem, which might limit its adoption in non-AWS projects
Less extensive documentation compared to some more established TLS libraries

Code Examples

Initializing s2n:

#include <s2n.h>

int main(int argc, char **argv) {
    if (s2n_init() < 0) {
        exit(1);
    }

    // Your TLS code here

    if (s2n_cleanup() < 0) {
        exit(1);
    }
}

Creating a TLS client connection:

struct s2n_connection *conn = s2n_connection_new(S2N_CLIENT);
if (conn == NULL) {
    // Error handling
}

s2n_connection_set_config(conn, config);

Performing a TLS handshake:

s2n_blocked_status blocked;
if (s2n_negotiate(conn, &blocked) < 0) {
    // Error handling
}

Sending and receiving data:

int bytes_written = s2n_send(conn, buffer, sizeof(buffer), &blocked);
int bytes_read = s2n_recv(conn, buffer, sizeof(buffer), &blocked);

Getting Started

To use s2n-tls in your project:

Clone the repository:

git clone https://github.com/aws/s2n-tls.git

Build s2n-tls:

cd s2n-tls
mkdir build
cd build
cmake ..
make

Include s2n-tls in your project:
```
#include <s2n.h>
```
Link against the s2n library when compiling your project:
```
gcc -o your_program your_program.c -ls2n
```

Remember to initialize s2n with s2n_init() at the beginning of your program and clean up with s2n_cleanup() at the end.

Competitor Comparisons

openssl

25,386

TLS/SSL and crypto library

Pros of OpenSSL

Comprehensive cryptographic library with a wide range of algorithms and protocols
Extensive documentation and community support
Cross-platform compatibility and widespread adoption

Cons of OpenSSL

Large codebase with potential security vulnerabilities
Complex API and configuration options
Higher resource consumption and slower performance in some scenarios

Code Comparison

OpenSSL:

SSL_CTX *ctx = SSL_CTX_new(TLS_method());
SSL *ssl = SSL_new(ctx);
SSL_set_fd(ssl, socket);
SSL_connect(ssl);

s2n-tls:

struct s2n_config *config = s2n_config_new();
struct s2n_connection *conn = s2n_connection_new(S2N_CLIENT);
s2n_connection_set_config(conn, config);
s2n_connection_set_fd(conn, socket);
s2n_negotiate(conn, &blocked);

Summary

OpenSSL is a feature-rich, widely-used cryptographic library with extensive support and documentation. However, its complexity and large codebase can lead to security concerns and performance overhead. s2n-tls, on the other hand, offers a simpler, more focused implementation of TLS/SSL protocols with an emphasis on security and performance. The code comparison shows that s2n-tls has a slightly more verbose API but provides more explicit control over the connection process.

wolfssl

2,283

The wolfSSL library is a small, fast, portable implementation of TLS/SSL for embedded devices to the cloud. wolfSSL supports up to TLS 1.3 and DTLS 1.3!

Pros of wolfssl

More comprehensive SSL/TLS library with support for a wider range of protocols and algorithms
Highly portable, designed for embedded systems and IoT devices
Extensive documentation and commercial support options available

Cons of wolfssl

Larger codebase and potentially higher resource usage compared to s2n-tls
More complex API, which may require a steeper learning curve
Not as tightly integrated with AWS services as s2n-tls

Code Comparison

s2n-tls (simplified TLS handshake):

s2n_connection_set_config(conn, config);
s2n_negotiate(conn, &blocked);

wolfssl (simplified TLS handshake):

wolfSSL_CTX_new(method);
wolfSSL_new(ctx);
wolfSSL_connect(ssl);

Both libraries provide APIs for establishing secure connections, but wolfssl offers more flexibility and options, while s2n-tls focuses on simplicity and AWS integration. s2n-tls is designed specifically for TLS, whereas wolfssl supports a broader range of cryptographic protocols. The choice between them depends on specific project requirements, target platforms, and integration needs with AWS services.

mbedtls

5,199

Pros of mbedtls

More comprehensive cryptographic library with a wider range of algorithms and protocols
Highly portable, suitable for embedded systems and resource-constrained environments
Extensive documentation and community support

Cons of mbedtls

Larger codebase and memory footprint compared to s2n-tls
May have slower performance in some scenarios due to its broader feature set

Code Comparison

mbedtls example (TLS client):

#include "mbedtls/ssl.h"

mbedtls_ssl_context ssl;
mbedtls_ssl_init(&ssl);
mbedtls_ssl_setup(&ssl, &conf);
mbedtls_ssl_set_hostname(&ssl, "example.com");

s2n-tls example (TLS client):

#include "s2n.h"

struct s2n_connection *conn = s2n_connection_new(S2N_CLIENT);
s2n_set_server_name(conn, "example.com");
s2n_connection_set_config(conn, config);

Both libraries provide APIs for TLS functionality, but mbedtls offers a more granular approach with separate initialization steps, while s2n-tls aims for simplicity with a more streamlined API. mbedtls provides more flexibility and control over the TLS setup process, whereas s2n-tls focuses on ease of use and AWS integration.

boringssl

1,796

Mirror of BoringSSL

Pros of BoringSSL

More comprehensive cryptographic library with a wider range of algorithms and protocols
Actively maintained by Google, benefiting from their security expertise
Better compatibility with popular web browsers and servers

Cons of BoringSSL

Larger codebase, potentially more complex to audit and maintain
May include unnecessary features for some use cases, increasing attack surface
Less focus on specific cloud service provider integrations

Code Comparison

BoringSSL (error handling):

if (SSL_get_error(ssl, ret) == SSL_ERROR_WANT_READ) {
    // Handle WANT_READ condition
} else {
    // Handle other errors
}

s2n-tls (error handling):

if (s2n_error_get_type(s2n_errno) == S2N_ERR_T_BLOCKED) {
    // Handle blocked I/O
} else {
    // Handle other errors
}

Both libraries provide error handling mechanisms, but BoringSSL uses SSL-specific error codes, while s2n-tls uses a more generic error type system.

Summary

BoringSSL offers a more comprehensive cryptographic library with wider browser compatibility, while s2n-tls focuses on simplicity and AWS integration. BoringSSL may be preferred for general-purpose use, whereas s2n-tls could be more suitable for AWS-centric projects requiring a lightweight TLS implementation.

portable

1,349

Pros of LibreSSL

Broader compatibility with various operating systems and platforms
More comprehensive cryptographic library with a wider range of algorithms
Longer history and established track record in the open-source community

Cons of LibreSSL

Larger codebase, potentially leading to more complexity and maintenance challenges
May have slower development and update cycles compared to s2n-tls
Less focus on specific cloud service provider integrations

Code Comparison

s2n-tls (C):

int s2n_init(void)
{
    if (s2n_is_initialized) {
        return 0;
    }
    s2n_is_initialized = 1;
    return s2n_mem_init();
}

LibreSSL (C):

int
OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings)
{
    static int init_done = 0;

    if (init_done)
        return 1;
    init_done = 1;
    return 1;
}

Both examples show initialization functions, but s2n-tls has a more streamlined approach, while LibreSSL follows the OpenSSL API structure.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be simple, small, fast, and with security as a priority. It is released and licensed under the Apache License 2.0.

s2n-tls is short for "signal to noise" and is a nod to the almost magical act of encryption â disguising meaningful signals, like your critical data, as seemingly random noise.

-- s2n-tls announcement

Quickstart for Ubuntu

# clone s2n-tls
git clone https://github.com/aws/s2n-tls.git
cd s2n-tls

# install build dependencies
sudo apt update
sudo apt install cmake

# install a libcrypto
sudo apt install libssl-dev

# build s2n-tls
cmake . -Bbuild \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=./s2n-tls-install
cmake --build build -j $(nproc)
CTEST_PARALLEL_LEVEL=$(nproc) ctest --test-dir build
cmake --install build

See the s2n-tls build documentation for further guidance on building s2n-tls for your platform.

Have a Question?

If you think you might have found a security impacting issue, please follow our Security Notification Process.

If you have any questions about submitting PRs, s2n-tls API usage, or something similar, please open an issue.

Documentation

s2n-tls uses Doxygen to document its public API. The latest s2n-tls documentation can be found on GitHub pages. The Usage Guide explains how different TLS features can be configured and used.

Documentation for older versions or branches of s2n-tls can be generated locally. To generate the documentation, install doxygen and run doxygen docs/doxygen/Doxyfile. The doxygen documentation can now be found at docs/doxygen/output/html/index.html.

Doxygen installation instructions are available at the Doxygen webpage.

Platform Support

Weâve listed the distributions and platforms under two tiers: Tier 1 platforms are guaranteed to build, run, and pass tests in CI. Tier 2 platforms are guaranteed to build and we'll address issues opened against them, but they aren't currently running in our CI and are not actively reviewed with every commit. If you use a platform not listed below and would like to request (or help!) add it to our CI, please open an issue for discussion.

Tier 1

Distribution in CI	Platforms
Ubuntu18, Ubuntu24**	x86_64
Ubuntu22	x86_64, i686
AL2, AL2023**	x86_64, aarch64
NixOS	x86_64, aarch64
OpenBSD 7.4	x86_64
FreeBSD latest	x86_64
OSX latest	aarch64

**Work in Progress

Tier 2

Distribution not in CI	Platforms
Fedora Core 34-36	x86_64, aarch64
Ubuntu14/16/20	x86_64, aarch64
Ubuntu18/22/24	aarch64
OSX 12-14	x86_64

These distribution lists are not exhaustive and missing tooling or a missing supported libcrypto library could prevent a successful build.

Using s2n-tls

The s2n-tls I/O APIs are designed to be intuitive to developers familiar with the widely-used POSIX I/O APIs, and s2n-tls supports blocking, non-blocking, and full-duplex I/O. Additionally there are no locks or mutexes within s2n-tls.

/* Create a server mode connection handle */
struct s2n_connection *conn = s2n_connection_new(S2N_SERVER);
if (conn == NULL) {
    ... error ...
}

/* Associate a connection with a file descriptor */
if (s2n_connection_set_fd(conn, fd) < 0) {
    ... error ...
}

/* Negotiate the TLS handshake */
s2n_blocked_status blocked;
if (s2n_negotiate(conn, &blocked) < 0) {
    ... error ...
}

/* Write data to the connection */
int bytes_written;
bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked);

For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the Usage Guide.

s2n-tls features

s2n-tls implements SSLv3, TLS1.0, TLS1.1, TLS1.2, and TLS1.3. For encryption, s2n-tls supports 128-bit and 256-bit AES in the CBC and GCM modes, ChaCha20, 3DES, and RC4. For forward secrecy, s2n-tls supports both DHE and ECDHE. s2n-tls also supports the Server Name Indicator (SNI), Application-Layer Protocol Negotiation (ALPN), and Online Certificate Status Protocol (OCSP) TLS extensions. SSLv3, RC4, 3DES, and DHE are each disabled by default for security reasons.

As it can be difficult to keep track of which encryption algorithms and protocols are best to use, s2n-tls features a simple API to use the latest "default" set of preferences. If you prefer to remain on a specific version for backwards compatibility, that is also supported.

/* Use the latest s2n-tls "default" set of ciphersuite and protocol preferences */
s2n_config_set_cipher_preferences(config, "default");

/* Use a specific set of preferences, update when you're ready */
s2n_config_set_cipher_preferences(config, "20150306")

s2n-tls safety mechanisms

Internally s2n-tls takes a systematic approach to data protection and includes several mechanisms designed to improve safety.

Small and auditable code base

Ignoring tests, blank lines and comments, s2n-tls is about 6,000 lines of code. s2n's code is also structured and written with a focus on reviewability. All s2n-tls code is subject to code review, and we plan to complete security evaluations of s2n-tls on an annual basis.

To date there have been two external code-level reviews of s2n-tls, including one by a commercial security vendor. s2n-tls has also been shared with some trusted members of the broader cryptography, security, and Open Source communities. Any issues discovered are always recorded in the s2n-tls issue tracker.

Static analysis, fuzz-testing and penetration testing

In addition to code reviews, s2n-tls is subject to regular static analysis, fuzz-testing, and penetration testing. Several penetration tests have occurred, including two by commercial vendors.

Unit tests and end-to-end testing

s2n-tls includes positive and negative unit tests and end-to-end test cases.

Unit test coverage can be viewed here. Note that this represents unit coverage for a particular build. Since that build won't necessarily support all s2n-tls features, test coverage may be artificially lowered.

Erase on read

s2n-tls encrypts or erases plaintext data as quickly as possible. For example, decrypted data buffers are erased as they are read by the application.

Built-in memory protection

s2n-tls uses operating system features to protect data from being swapped to disk or appearing in core dumps.

Minimalist feature adoption

s2n-tls avoids implementing rarely used options and extensions, as well as features with a history of triggering protocol-level vulnerabilities. For example there is no support for session renegotiation or DTLS.

Compartmentalized random number generation

The security of TLS and its associated encryption algorithms depends upon secure random number generation. s2n-tls provides every thread with two separate random number generators. One for "public" randomly generated data that may appear in the clear, and one for "private" data that should remain secret. This approach lessens the risk of potential predictability weaknesses in random number generation algorithms from leaking information across contexts.

Modularized encryption

s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports OpenSSL (versions 1.0.2, 1.1.1 and 3.0.x), LibreSSL, BoringSSL, AWS-LC, and the Apple Common Crypto framework to perform the underlying cryptographic operations.

Timing blinding

s2n-tls includes structured support for blinding time-based side-channels that may leak sensitive data. For example, if s2n-tls fails to parse a TLS record or handshake message, s2n-tls will add a randomized delay of between 10 and 30 seconds, granular to nanoseconds, before responding. This raises the complexity of real-world timing side-channel attacks by a factor of at least tens of trillions.

Table based state-machines

s2n-tls uses simple tables to drive the TLS/SSL state machines, making it difficult for invalid out-of-order states to arise.

C safety

s2n-tls is written in C, but makes light use of standard C library functions and wraps all memory handling, string handling, and serialization in systematic boundary-enforcing checks.

Security issue notifications

If you discover a potential security issue in s2n-tls we ask that you notify AWS Security via our vulnerability reporting page. Please do not create a public github issue.

If you package or distribute s2n-tls, or use s2n-tls as part of a large multi-user service, you may be eligible for pre-notification of future s2n-tls releases. Please contact s2n-pre-notification@amazon.com.

Contributing to s2n-tls

If you are interested in contributing to s2n-tls, please see our development guide.

Language Bindings for s2n-tls

See our language bindings list for language bindings for s2n-tls that we're aware of.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot