From 30eb78847df3c35c808d821beb9c99b4f3013b7d Mon Sep 17 00:00:00 2001 From: Doug Chapman Date: Thu, 18 Feb 2021 12:26:40 -0800 Subject: [PATCH 01/23] Org change to aws --- README.md | 22 +++++++++++----------- codebuild/codebuild.config | 2 +- codebuild/common.config | 4 ++-- codebuild/integ_codebuild.config | 10 +++++----- docs/DEVELOPMENT-GUIDE.md | 24 ++++++++++++------------ docs/USAGE-GUIDE.md | 4 ++-- 6 files changed, 33 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index cdca230e20c..6c898aff2c6 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ s2n 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. -[![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/awslabs/s2n/) -[![Apache 2 License](https://img.shields.io/github/license/awslabs/s2n.svg)](http://aws.amazon.com/apache-2-0/) +[![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/) +[![Apache 2 License](https://img.shields.io/github/license/aws/s2n-ls.svg)](http://aws.amazon.com/apache-2-0/) [![C99](https://img.shields.io/badge/language-C99-blue.svg)](http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf) -[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/awslabs/s2n.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/awslabs/s2n/context:cpp) -[![codecov](https://codecov.io/gh/awslabs/s2n/branch/main/graph/badge.svg)](https://codecov.io/gh/awslabs/s2n) -[![Github forks](https://img.shields.io/github/forks/awslabs/s2n.svg)](https://github.com/awslabs/s2n/network) -[![Github stars](https://img.shields.io/github/stars/awslabs/s2n.svg)](https://github.com/awslabs/s2n/stargazers) -[![Join the chat at https://gitter.im/awslabs/s2n](https://badges.gitter.im/awslabs/s2n.svg)](https://gitter.im/awslabs/s2n?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/aws/s2n-tls.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/aws/s2n-tls/context:cpp) +[![codecov](https://codecov.io/gh/aws/s2n-tls/branch/main/graph/badge.svg)](https://codecov.io/gh/aws/s2n-tls) +[![Github forks](https://img.shields.io/github/forks/aws/s2n-tls.svg)](https://github.com/aws/s2n-tls/network) +[![Github stars](https://img.shields.io/github/stars/aws/s2n-tls.svg)](https://github.com/aws/s2n-tls/stargazers) +[![Join the chat at https://gitter.im/aws/s2n-tls](https://badges.gitter.im/aws/s2n-tls.svg)](https://gitter.im/aws/s2n-tls?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ## Quickstart for Ubuntu 1. Fork s2n on GitHub @@ -50,7 +50,7 @@ CTEST_PARALLEL_LEVEL=5 ninja test ``` ## Have a Question? -If you have any questions about Submitting PR's, Opening Issues, s2n API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/awslabs/s2n +If you have any questions about Submitting PR's, Opening Issues, s2n API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/aws/s2n-tls Otherwise, if you think you might have found a security impacting issue, please instead follow [our Security Notification Process.](#security-issue-notifications) @@ -81,7 +81,7 @@ int bytes_written; bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked); ``` -For details on building the s2n library and how to use s2n in an application you are developing, see the [API Reference](https://github.com/awslabs/s2n/blob/main/docs/USAGE-GUIDE.md). +For details on building the s2n library and how to use s2n in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). ## s2n features @@ -145,7 +145,7 @@ AWS Security via our [vulnerability reporting page](http://aws.amazon.com/securi If you package or distribute s2n, or use s2n as part of a large multi-user service, you may be eligible for pre-notification of future s2n releases. Please contact s2n-pre-notification@amazon.com. ## Contributing to s2n -If you are interested in contributing to s2n, please see our [development guide](https://github.com/awslabs/s2n/blob/main/docs/DEVELOPMENT-GUIDE.md). +If you are interested in contributing to s2n, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). ## Language Bindings for s2n -See our [language bindings list](https://github.com/awslabs/s2n/blob/main/docs/BINDINGS.md) for language bindings for s2n that we're aware of. +See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n that we're aware of. diff --git a/codebuild/codebuild.config b/codebuild/codebuild.config index 956d18b8e4d..e39499879f3 100644 --- a/codebuild/codebuild.config +++ b/codebuild/codebuild.config @@ -88,7 +88,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_2XLARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_sidetrail.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: diff --git a/codebuild/common.config b/codebuild/common.config index fb67335c647..855367987bf 100644 --- a/codebuild/common.config +++ b/codebuild/common.config @@ -15,7 +15,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_2XLARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -26,7 +26,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: diff --git a/codebuild/integ_codebuild.config b/codebuild/integ_codebuild.config index 40765ad1868..c81bb2ab9b6 100644 --- a/codebuild/integ_codebuild.config +++ b/codebuild/integ_codebuild.config @@ -11,7 +11,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl102.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -23,7 +23,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_boringlibre.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -36,7 +36,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl111.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -49,7 +49,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl102.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -62,7 +62,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl102_asanvalgrind.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md index 0755286d044..05f8e0ec59a 100644 --- a/docs/DEVELOPMENT-GUIDE.md +++ b/docs/DEVELOPMENT-GUIDE.md @@ -2,7 +2,7 @@ If you are curious about the internals of s2n, or interested in contributing to s2n, this document is for you. If instead you are interested in using s2n in an application -that you are developing, please see the accompanying [Usage Guide](https://github.com/awslabs/s2n/blob/main/docs/USAGE-GUIDE.md). +that you are developing, please see the accompanying [Usage Guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). ## s2n's development principles @@ -91,7 +91,7 @@ benefit is that functions can read quite declaratively. In the case of message parsers, the function contents can read almost like schemas of the message being parsed. -A good example file for message parsing to look at is [tls/s2n_server_finished.c](https://github.com/awslabs/s2n/blob/main/tls/s2n_server_finished.c). +A good example file for message parsing to look at is [tls/s2n_server_finished.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_server_finished.c). From reading the file it should be reasonably clear that a server finished message consists just of S2N_TLS_FINISHED_LEN number of bytes, what the next state is and so on. @@ -113,7 +113,7 @@ if (s2n_result_is_error(s2n_do_something(with_something_else))) { } ``` -is so common that [utils/s2n_safety.h](https://github.com/awslabs/s2n/blob/main/utils/s2n_safety.h) provides several macros for working with fallible functions. Notable macros include; +is so common that [utils/s2n_safety.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_safety.h) provides several macros for working with fallible functions. Notable macros include; ```c /** @@ -130,7 +130,7 @@ is so common that [utils/s2n_safety.h](https://github.com/awslabs/s2n/blob/main/ These macros should be used when calling functions you expect to succeed. Primarily these macros help save two lines that repeatedly clutter files, and secondarily they are very useful when developing and debugging code as it is easy to redefine the macro to implement a simple backtrace (even a simple printf will suffice, but a breakpoint is more usual). If a function does fail, it should use the `BAIL(errno)` macro provided for surfacing the error to an application. -New error translations, and their human-readable translations can be defined in [error/s2n_errno.h](https://github.com/awslabs/s2n/blob/main/error/s2n_errno.h) and [error/s2n_errno.c](https://github.com/awslabs/s2n/blob/main/error/s2n_errno.c). When called, e.g.: +New error translations, and their human-readable translations can be defined in [error/s2n_errno.h](https://github.com/aws/s2n-tls/blob/main/error/s2n_errno.h) and [error/s2n_errno.c](https://github.com/aws/s2n-tls/blob/main/error/s2n_errno.c). When called, e.g.: ```c BAIL(S2N_ERR_BAD_MESSAGE); @@ -140,7 +140,7 @@ the macro will set s2n_errno correctly, as well as some useful debug strings, an ### Safety checking -[utils/s2n_safety.h](https://github.com/awslabs/s2n/blob/main/utils/s2n_safety.h) provides several more convenience macros intended to make safety and bounds checking easier. There are checked versions of memcpy (`CHECKED_MEMCPY`) and memset (`CHECKED_MEMSET`), as well as predicate testers like `ENSURE`, `ENSURE_GTE`, `ENSURE_INCLUSIVE_RANGE`, `ENSURE_EXCLUSIVE_RANGE` for performing simple comparisons in a systematic, error-handled, way. +[utils/s2n_safety.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_safety.h) provides several more convenience macros intended to make safety and bounds checking easier. There are checked versions of memcpy (`CHECKED_MEMCPY`) and memset (`CHECKED_MEMSET`), as well as predicate testers like `ENSURE`, `ENSURE_GTE`, `ENSURE_INCLUSIVE_RANGE`, `ENSURE_EXCLUSIVE_RANGE` for performing simple comparisons in a systematic, error-handled, way. *Note*: In general, C preprocessor Macros with embedded control flow are a bad idea, but `GUARD`, `ENSURE`, and `BAIL` are so thoroughly used throughout s2n that it should be a clear and idiomatic pattern, almost forming a small domain specific language. @@ -167,7 +167,7 @@ As discussed below, s2n rarely allocates resources, and so has nothing to clean Branches can be a source of cognitive load, as they ask the reader to follow a path of thinking, while also remembering that there is another path to be explored. When branches are nested, they can often lead to impossible to grasp combinatorial explosions. s2n tries to systematically reduce the number of branches used in the code in several ways. -Firstly, there are almost no ifdef calls in s2n. Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/awslabs/s2n/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. +Firstly, there are almost no ifdef calls in s2n. Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. Secondly, s2n generally branches in the case of failure, rather than success. So instead of creating a nest of if's: @@ -217,15 +217,15 @@ There is also a brief set of other coding conventions: s2n is written in C99, a language which lacks a "standard" testing framework. Although there are some more well used C++ testing frameworks, s2n also targets some embedded platforms on which a C++ compiler is unavailable. -Since testing and test-cases are absolutely mandatory for all s2n functionality, s2n includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/awslabs/s2n/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. +Since testing and test-cases are absolutely mandatory for all s2n functionality, s2n includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/aws/s2n-tls/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. -Unit tests are added as .c files in [tests/unit/](https://github.com/awslabs/s2n/blob/main/tests/unit/). A simple example to look at is [tests/unit/s2n_stuffer_base64_test.c](https://github.com/awslabs/s2n/blob/main/tests/unit/s2n_stuffer_base64_test.c). The tests are started with BEGIN_TEST(), and expectations are tested with EXPECT_SUCCESS and EXPECT_EQUAL before exiting with an END_TEST call. +Unit tests are added as .c files in [tests/unit/](https://github.com/aws/s2n-tls/blob/main/tests/unit/). A simple example to look at is [tests/unit/s2n_stuffer_base64_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_stuffer_base64_test.c). The tests are started with BEGIN_TEST(), and expectations are tested with EXPECT_SUCCESS and EXPECT_EQUAL before exiting with an END_TEST call. The test framework will take care of compiling and executing the tests and indicates success or failure with green or red text in the console. In addition to fully covering functionality in the correct cases, s2n tests are also expected to include adversarial or "negative" test cases. For example, the tests performed on record encryption validate that s2n is tamper resistant by attempting to actually tamper with records. Similarly, we validate that our memory handling routines cannot be over-filled by attempting to over-fill them. -To avoid adding unneeded code to the production build of s2n, there is also a small test library defined at [tests/testlib/](https://github.com/awslabs/s2n/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. +To avoid adding unneeded code to the production build of s2n, there is also a small test library defined at [tests/testlib/](https://github.com/aws/s2n-tls/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. Unit tests are run automatically with `make`. To run a subset of the unit tests, set the `UNIT_TESTS` environment variable with the unit test name(s). For example: ``` @@ -247,7 +247,7 @@ struct s2n_blob { }; ``` -Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/awslabs/s2n/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n prevents the memory regions from being swapped to disk and from showing up in core files (where supported). +Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n prevents the memory regions from being swapped to disk and from showing up in core files (where supported). ### s2n_stuffer: a streaming buffer @@ -358,7 +358,7 @@ Every connection is associated with an s2n_connection structure. The details of When a TLS connection is being started, the first communication consists of handshake messages. The client sends the first message (a client hello), and then the server replies (with a server hello), and so on. Because a server must wait for a client and vice versa, this phase of a TLS connection is not full-duplex. To save on memory, s2n uses a single stuffer for both incoming and outgoing handshake messages and it is located as s2n_connection->handshake.io (which is a growable stuffer). -Borrowing another trick from functional programming, the state machine for handling handshake messages is implemented using a table of function pointers, located in [tls/s2n_handshake_io.c](https://github.com/awslabs/s2n/blob/main/tls/s2n_handshake_io.c). +Borrowing another trick from functional programming, the state machine for handling handshake messages is implemented using a table of function pointers, located in [tls/s2n_handshake_io.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_handshake_io.c). ```c static struct s2n_handshake_action state_machine[] = { @@ -386,7 +386,7 @@ One detail we've skipped over so far is that handshake messages are encapsulated ![TLS layers](images/s2n_tls_layers.png "s2n TLS layers") -In the outbound direction, s2n never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/awslabs/s2n/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. +In the outbound direction, s2n never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. To perform all of this, the s2n_connection structure has a few more internal stuffers: diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index 84fb3dfe07f..fea382c9f13 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -4,7 +4,7 @@ s2n is a C library, and is built using Make. To clone the latest copy of s2n from git use: ```shell -git clone https://github.com/awslabs/s2n.git +git clone https://github.com/aws/s2n-tls.git cd s2n ``` @@ -1759,6 +1759,6 @@ function that can free memory. # Examples -To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/awslabs/s2n/blob/main/bin/) directory +To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory includes an example client (s2nc) and server (s2nd). From 3fa6b4148506cb4b7330c996bc656bc3e3d60ff2 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Thu, 18 Feb 2021 12:57:42 -0800 Subject: [PATCH 02/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c898aff2c6..b3b0893eee2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ s2n -s2n 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 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. [![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/) [![Apache 2 License](https://img.shields.io/github/license/aws/s2n-ls.svg)](http://aws.amazon.com/apache-2-0/) From b01648b06bac690123ee9aa5f5f990b1c8c824ab Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Thu, 18 Feb 2021 12:57:49 -0800 Subject: [PATCH 03/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 68 ++++++------- docs/BINDINGS.md | 6 +- docs/DEVELOPMENT-GUIDE.md | 120 +++++++++++------------ docs/READING-LIST.md | 2 +- docs/STATE-MACHINE.md | 2 +- docs/USAGE-GUIDE.md | 198 +++++++++++++++++++------------------- 6 files changed, 198 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index b3b0893eee2..258f3ca72f1 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be [![Join the chat at https://gitter.im/aws/s2n-tls](https://badges.gitter.im/aws/s2n-tls.svg)](https://gitter.im/aws/s2n-tls?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ## Quickstart for Ubuntu -1. Fork s2n on GitHub +1. Fork s2n-tls on GitHub 2. Run the following commands on Ubuntu. ``` -git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n.git -cd s2n +git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n-tls.git +cd s2n-tls # Pick an "env" line from the codebuild/codebuild.config file and run it, in this case choose the openssl-1.1.1 with GCC 9 build S2N_LIBCRYPTO=openssl-1.1.1 BUILD_S2N=true TESTS=integration GCC_VERSION=9 @@ -36,27 +36,27 @@ An example of building on OSX: ```sh brew install ninja cmake -git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n.git -mkdir s2n_build -cd s2n_build +git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n-tls.git +mkdir s2n_tls_build +cd s2n_tls_build # Build with debug symbols and a specific OpenSSL version cmake -GNinja \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_PREFIX_PATH=/usr/local/Cellar/openssl@1.1/1.1.1g \ - ../s2n + ../s2n-tls ninja -j6 CTEST_PARALLEL_LEVEL=5 ninja test ``` ## Have a Question? -If you have any questions about Submitting PR's, Opening Issues, s2n API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/aws/s2n-tls +If you have any questions about Submitting PR's, Opening Issues, s2n-tls API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/aws/s2n-tls Otherwise, if you think you might have found a security impacting issue, please instead follow [our Security Notification Process.](#security-issue-notifications) -## Using s2n +## Using s2n-tls -The s2n I/O APIs are designed to be intuitive to developers familiar with the widely-used POSIX I/O APIs, and s2n supports blocking, non-blocking, and full-duplex I/O. Additionally there are no locks or mutexes within s2n. +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. ```c /* Create a server mode connection handle */ @@ -81,71 +81,71 @@ int bytes_written; bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked); ``` -For details on building the s2n library and how to use s2n in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). +For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). -## s2n features +## s2n-tls features -s2n implements SSLv3, TLS1.0, TLS1.1, and TLS1.2. For encryption, s2n supports 128-bit and 256-bit AES, in the CBC and GCM modes, ChaCha20, 3DES, and RC4. For forward secrecy, s2n supports both DHE and ECDHE. s2n also supports the Server Name Indicator (SNI), Application-Layer Protocol Negotiation (ALPN) and the Online Certificate Status Protocol (OCSP) TLS extensions. SSLv3, RC4, 3DES and DHE are each disabled by default for security reasons. +s2n-tls implements SSLv3, TLS1.0, TLS1.1, and TLS1.2. 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 the 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 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. +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. ```c -/* Use the latest s2n "default" set of ciphersuite and protocol preferences */ +/* 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 safety mechanisms +## s2n-tls safety mechanisms -Internally s2n takes a systematic approach to data protection and includes several mechanisms designed to improve safety. +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 is about 6,000 lines of code. s2n's code is also structured and written with a focus on reviewability. All s2n code is subject to code review, and we plan to complete security evaluations of s2n on an annual basis. +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, including one by a commercial security vendor. s2n 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 issue tracker. +To date there have been two external code-level reviews of s2n, 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 is subject to regular static analysis, fuzz-testing, and penetration testing. Several penetration tests have occurred, including two by commercial vendors. +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 includes positive and negative unit tests and end-to-end test cases. +s2n-tls includes positive and negative unit tests and end-to-end test cases. ##### Erase on read -s2n encrypts or erases plaintext data as quickly as possible. For example, decrypted data buffers are erased as they are read by the application. +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 uses operating system features to protect data from being swapped to disk or appearing in core dumps. +s2n-tls uses operating system features to protect data from being swapped to disk or appearing in core dumps. ##### Minimalist feature adoption -s2n 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. +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 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. +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 has been structured so that different encryption libraries may be used. Today s2n supports OpenSSL, LibreSSL, BoringSSL, and the Apple Common Crypto framework to perform the underlying cryptographic operations. +s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports OpenSSL, LibreSSL, BoringSSL, and the Apple Common Crypto framework to perform the underlying cryptographic operations. ##### Timing blinding -s2n includes structured support for blinding time-based side-channels that may leak sensitive data. For example, if s2n fails to parse a TLS record or handshake message, s2n 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. +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 uses simple tables to drive the TLS/SSL state machines, making it difficult for invalid out-of-order states to arise. +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 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. +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 we ask that you notify +If you discover a potential security issue in s2n-tls we ask that you notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. -If you package or distribute s2n, or use s2n as part of a large multi-user service, you may be eligible for pre-notification of future s2n releases. Please contact s2n-pre-notification@amazon.com. +If you package or distribute s2n, 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 +## Contributing to s2n-tls If you are interested in contributing to s2n, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). -## Language Bindings for s2n -See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n that we're aware of. +## Language Bindings for s2n-tls +See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n-tls that we're aware of. diff --git a/docs/BINDINGS.md b/docs/BINDINGS.md index 8455427d434..c8c39089ee5 100644 --- a/docs/BINDINGS.md +++ b/docs/BINDINGS.md @@ -1,8 +1,8 @@ -# Language Bindings for s2n +# Language Bindings for s2n-tls -The following are language bindings to s2n that we're aware of. They are not a part of the s2n project. +The following are language bindings to s2n-tls that we're aware of. They are not a part of the s2n-tls project. -Let us know if you know of a language binding to s2n that's not listed below. +Let us know if you know of a language binding to s2n-tls that's not listed below. ## Lua diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md index 05f8e0ec59a..aa19b2940fd 100644 --- a/docs/DEVELOPMENT-GUIDE.md +++ b/docs/DEVELOPMENT-GUIDE.md @@ -1,25 +1,25 @@ -# Development guide for s2n +c Development guide for s2n-tls -If you are curious about the internals of s2n, or interested in contributing to -s2n, this document is for you. If instead you are interested in using s2n in an application +If you are curious about the internals of s2n-tls, or interested in contributing to +s2n-tls, this document is for you. If instead you are interested in using s2n-tls in an application that you are developing, please see the accompanying [Usage Guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). -## s2n's development principles +## s2n-tls's development principles -Before getting into the detail of how s2n works internally, it's worth covering -s2n's development principles. These principles guide and inform many of the design +Before getting into the detail of how s2n-tls works internally, it's worth covering +s2n-tls's development principles. These principles guide and inform many of the design decisions we'll go through. We're always open to new principles, if you can think of better ones and make a case for them. #### Development principles * **Maintain an excellent TLS/SSL implementation**
Although it's hidden "*under the hood*", TLS/SSL is the direct interface with customers and end-users. Good performance and security are critical to a positive experience. -* **Protect user data and keys**
Above all else, s2n must ensure that user data and private keys are being handled correctly and carefully. Security is often a matter of trade-offs and costs; we should always strive to increase the costs for attackers whenever the tradeoffs are acceptable to users. +* **Protect user data and keys**
Above all else, s2n-tls must ensure that user data and private keys are being handled correctly and carefully. Security is often a matter of trade-offs and costs; we should always strive to increase the costs for attackers whenever the tradeoffs are acceptable to users. * **Stay simple**
Write as little code as necessary, omit rarely used optional features and support as few modes of operation as possible. We will also promote and encourage changes that reduce the size of our code base. -* **Write clear readable code with a light cognitive load**
s2n's code must be concise, easy to follow and legible to a proficient C programmer. Our code should be organized in a way that divides the implementation up into small units of work, with the entire context necessary at hand. We should also minimize the number of branches in our code, the depth of our call stacks, and the number of members in our structures. +* **Write clear readable code with a light cognitive load**
s2n-tls's code must be concise, easy to follow and legible to a proficient C programmer. Our code should be organized in a way that divides the implementation up into small units of work, with the entire context necessary at hand. We should also minimize the number of branches in our code, the depth of our call stacks, and the number of members in our structures. * **Defend in depth and systematically**
Great care and attention to detail is required to write good code, but we also use automation and mechanistic processes to protect against human error. -* **Be easy to use and maintain sane defaults**
It should be low effort, even for a novice developer, to use s2n in a safe way. We also shouldn't "*pass the buck*" and place the burden of subtle or complicated TLS-specific decision making upon application authors and system administrators. +* **Be easy to use and maintain sane defaults**
It should be low effort, even for a novice developer, to use s2n-tls in a safe way. We also shouldn't "*pass the buck*" and place the burden of subtle or complicated TLS-specific decision making upon application authors and system administrators. * **Provide great performance and responsiveness**
TLS/SSL is rapidly becoming ubiquitous. Even small inefficiencies and overhead can become significant when multiplied by billions of users and quintillions of sessions. -* **Stay paranoid**
s2n operates in a security critical space. Even with the most precautionary development methods it is impossible to guarantee the absence of defects. A subtle one-byte error on a single line may still cause problems. +* **Stay paranoid**
s2n-tls operates in a security critical space. Even with the most precautionary development methods it is impossible to guarantee the absence of defects. A subtle one-byte error on a single line may still cause problems. * **Make data-driven decisions**
Opinions can differ on security best practices, sometimes in contradictory ways. Where possible, we are guided by facts and measurable data. #### Priorities @@ -33,7 +33,7 @@ When weighing up difficult implementation trade-offs our ordered set of prioriti #### Commit and code-review policy -s2n is review-then-commit for code changes, and commit-then-review for +s2n-tls is review-then-commit for code changes, and commit-then-review for documentation changes. Code additions are made by pull requests, no author may merge their own pull request on code. Changes to documentation, including code comments, may be made more freely. @@ -41,19 +41,19 @@ comments, may be made more freely. ## Coding style and conventions Per our development principles, an important goal is to reduce the cognitive load required to -read, review and extend s2n. Although s2n is written in C, s2n adopts several +read, review and extend s2n-tls . Although s2n-tls is written in C, s2n-tls adopts several patterns more common to functional programming. Though they are used in a way that is idiomatic and shouldn't feel completely alien in C. ### High level function design -The first convention is that's s2n's functions are generally quite small, no +The first convention is that's s2n-tls's functions are generally quite small, no more than a page or two at most and commonly just a few lines. Functions have a clear input and output and are in that sense "pure" functions; for example handling a particular TLS handshake message type takes the message as input, and the output is connection state. ```c -/* An idiomatic s2n function generally has: +/* An idiomatic s2n-tls function generally has: * * An s2n_result return value. This is used to signal success or error. * An input, often a struct. @@ -62,16 +62,16 @@ as input, and the output is connection state. S2N_RESULT s2n_do_something(struct *some_input, struct *some_output); ``` -s2n functions also operate in a message passing style. For example, +s2n-tls functions also operate in a message passing style. For example, a simplified version of the flow when handling a TLS client finished message might looks like this: -![s2n message passing](images/s2n_lambda.png "s2n message passing") +![s2n-tls message passing](images/s2n_lambda.png "s2n-tls message passing") each function handles a clear, well-defined piece of work, before passing on responsibility to the next function. -The second convention of s2n's functions is that functions are +The second convention of s2n-tls's functions is that functions are split into two kinds: those that handle control flow and coordinate other functions, and those that parse messages. For example, in the above diagram, it might appear that the functions are calling each other directly @@ -103,9 +103,9 @@ one place. ### Error handling and Macros -As may also be clear from the above examples, s2n has some conventions for how errors are handled. Firstly, s2n functions should always return `S2N_RESULT_ERROR` or `NULL` on error, and `S2N_RESULT_OK` or a valid pointer on success. s2n also includes a thread local variable: s2n_errno, for indicating the cause of the error. This follows the convention set by libc (with errno), getaddrinfo (gai_errno), net-snmp (snmp_errno), and countless other libraries. +As may also be clear from the above examples, s2n-tls has some conventions for how errors are handled. Firstly, s2n-tls functions should always return `S2N_RESULT_ERROR` or `NULL` on error, and `S2N_RESULT_OK` or a valid pointer on success. s2n-tls also includes a thread local variable: s2n_errno, for indicating the cause of the error. This follows the convention set by libc (with errno), getaddrinfo (gai_errno), net-snmp (snmp_errno), and countless other libraries. -In s2n, we **always** check return values. Because of that, the coding pattern: +In s2n-tls, we **always** check return values. Because of that, the coding pattern: ```c if (s2n_result_is_error(s2n_do_something(with_something_else))) { @@ -142,10 +142,10 @@ the macro will set s2n_errno correctly, as well as some useful debug strings, an [utils/s2n_safety.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_safety.h) provides several more convenience macros intended to make safety and bounds checking easier. There are checked versions of memcpy (`CHECKED_MEMCPY`) and memset (`CHECKED_MEMSET`), as well as predicate testers like `ENSURE`, `ENSURE_GTE`, `ENSURE_INCLUSIVE_RANGE`, `ENSURE_EXCLUSIVE_RANGE` for performing simple comparisons in a systematic, error-handled, way. -*Note*: In general, C preprocessor Macros with embedded control flow are a bad idea, but `GUARD`, `ENSURE`, and `BAIL` are so thoroughly used throughout s2n that it should be a clear and idiomatic pattern, almost forming a small domain specific language. +*Note*: In general, C preprocessor Macros with embedded control flow are a bad idea, but `GUARD`, `ENSURE`, and `BAIL` are so thoroughly used throughout s2n-tls that it should be a clear and idiomatic pattern, almost forming a small domain specific language. ### Cleanup on Error -As discussed below, s2n rarely allocates resources, and so has nothing to clean up on error. For cases where functions do allocate resources which must be cleaned up, s2n offers two macros: +As discussed below, s2n-tls rarely allocates resources, and so has nothing to clean up on error. For cases where functions do allocate resources which must be cleaned up, s2n-tls offers two macros: ```c /** @@ -165,11 +165,11 @@ As discussed below, s2n rarely allocates resources, and so has nothing to clean ### Control flow and the state machine -Branches can be a source of cognitive load, as they ask the reader to follow a path of thinking, while also remembering that there is another path to be explored. When branches are nested, they can often lead to impossible to grasp combinatorial explosions. s2n tries to systematically reduce the number of branches used in the code in several ways. +Branches can be a source of cognitive load, as they ask the reader to follow a path of thinking, while also remembering that there is another path to be explored. When branches are nested, they can often lead to impossible to grasp combinatorial explosions. s2n-tls tries to systematically reduce the number of branches used in the code in several ways. -Firstly, there are almost no ifdef calls in s2n. Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. +Firstly, there are almost no ifdef calls in s2n-tls . Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. -Secondly, s2n generally branches in the case of failure, rather than success. So instead of creating a nest of if's: +Secondly, s2n-tls generally branches in the case of failure, rather than success. So instead of creating a nest of if's: ```c if (s2n_foo() == 0) { @@ -185,29 +185,29 @@ GUARD(s2n_bar()); GUARD(s2n_baz()); ``` -This pattern leads to a linear control flow, where the main body of a function describes everything that happens in a regular, "*happy*" case. Any deviation is usually a fatal error and we exit the function. This is safe because s2n rarely allocates resources, and so has nothing to clean up on error. +This pattern leads to a linear control flow, where the main body of a function describes everything that happens in a regular, "*happy*" case. Any deviation is usually a fatal error and we exit the function. This is safe because s2n-tls rarely allocates resources, and so has nothing to clean up on error. -This pattern also leads to extremely few "else" clauses in the s2n code base. Within s2n, else clauses should be treated with suspicion and examined for potential eradication. Where an else clause is necessary, we try to ensure that the first if block is the most likely case. This aids readability, and also results in a more efficient compiled instruction pipeline (although good CPU branch prediction will rapidly correct any mis-ordering). +This pattern also leads to extremely few "else" clauses in the s2n-tls code base. Within s2n-tls, else clauses should be treated with suspicion and examined for potential eradication. Where an else clause is necessary, we try to ensure that the first if block is the most likely case. This aids readability, and also results in a more efficient compiled instruction pipeline (although good CPU branch prediction will rapidly correct any mis-ordering). -For branches on small enumerated types, s2n generally favors switch statements: though switch statements taking up more than about 25 lines of code are discouraged, and a "default:" block is mandatory. +For branches on small enumerated types, s2n-tls generally favors switch statements: though switch statements taking up more than about 25 lines of code are discouraged, and a "default:" block is mandatory. -Another technique for complexity avoidance is that the core TLS state machine within s2n does not use branches and instead uses a table of function pointers (another technique borrowed from functional programming) to dispatch data to the correct handler. This is covered in more detail later in this document. +Another technique for complexity avoidance is that the core TLS state machine within s2n-tls does not use branches and instead uses a table of function pointers (another technique borrowed from functional programming) to dispatch data to the correct handler. This is covered in more detail later in this document. -Lastly, s2n studiously avoids locks. s2n is designed to be thread-safe, but does so by using atomic data types in the small number of well-isolated variables that may be accessed by multiple threads. +Lastly, s2n-tls studiously avoids locks. s2n-tls is designed to be thread-safe, but does so by using atomic data types in the small number of well-isolated variables that may be accessed by multiple threads. ### Code formatting and commenting -s2n is written in C99. The code formatting and indentation should be relatively clear from reading some s2n source files, but there is also an automated "make indent" target that will indent the s2n sources. +s2n-tls is written in C99. The code formatting and indentation should be relatively clear from reading some s2n-tls source files, but there is also an automated "make indent" target that will indent the s2n-tls sources. -There should be no need for comments to explain *what* s2n code is doing; variables and functions should be given clear and human-readable names that make their purpose and intent intuitive. Comments explaining *why* we are doing something are encouraged. Often some context setting is necessary; a reference to an RFC, or a reminder of some critical state that is hard to work directly into the immediate code in a natural way. All comments should be written using C syntax `/* */` and **avoid** C++ comments `//` even though C99 compilers allow `//`. +There should be no need for comments to explain *what* s2n-tls code is doing; variables and functions should be given clear and human-readable names that make their purpose and intent intuitive. Comments explaining *why* we are doing something are encouraged. Often some context setting is necessary; a reference to an RFC, or a reminder of some critical state that is hard to work directly into the immediate code in a natural way. All comments should be written using C syntax `/* */` and **avoid** C++ comments `//` even though C99 compilers allow `//`. Every source code file must include a copy of the Apache Software License 2.0, as well as a correct copyright notification. The year of copyright should be the year in which the file was first created. There is also a brief set of other coding conventions: -* s2n uses explicitly sized primitives where possible. E.g. uint8_t, uint32_t. -* In general, s2n uses unsigned ints for sizes, as TLS/SSL do the same. -* Any structures exposed to application authors must be opaque: s2n manages the memory allocation and de-allocation. +* s2n-tls uses explicitly sized primitives where possible. E.g. uint8_t, uint32_t. +* In general, s2n-tls uses unsigned ints for sizes, as TLS/SSL do the same. +* Any structures exposed to application authors must be opaque: s2n-tls manages the memory allocation and de-allocation. * Variables are declared closest to their first point of use, to maximize context around the typing. * Duplication of logic is discouraged * 4 spaces, no tabs @@ -215,26 +215,26 @@ There is also a brief set of other coding conventions: ## Tests -s2n is written in C99, a language which lacks a "standard" testing framework. Although there are some more well used C++ testing frameworks, s2n also targets some embedded platforms on which a C++ compiler is unavailable. +s2n-tls is written in C99, a language which lacks a "standard" testing framework. Although there are some more well used C++ testing frameworks, s2n-tls also targets some embedded platforms on which a C++ compiler is unavailable. -Since testing and test-cases are absolutely mandatory for all s2n functionality, s2n includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/aws/s2n-tls/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. +Since testing and test-cases are absolutely mandatory for all s2n-tls functionality, s2n-tls includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/aws/s2n-tls/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. Unit tests are added as .c files in [tests/unit/](https://github.com/aws/s2n-tls/blob/main/tests/unit/). A simple example to look at is [tests/unit/s2n_stuffer_base64_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_stuffer_base64_test.c). The tests are started with BEGIN_TEST(), and expectations are tested with EXPECT_SUCCESS and EXPECT_EQUAL before exiting with an END_TEST call. The test framework will take care of compiling and executing the tests and indicates success or failure with green or red text in the console. -In addition to fully covering functionality in the correct cases, s2n tests are also expected to include adversarial or "negative" test cases. For example, the tests performed on record encryption validate that s2n is tamper resistant by attempting to actually tamper with records. Similarly, we validate that our memory handling routines cannot be over-filled by attempting to over-fill them. +In addition to fully covering functionality in the correct cases, s2n-tls tests are also expected to include adversarial or "negative" test cases. For example, the tests performed on record encryption validate that s2n-tls is tamper resistant by attempting to actually tamper with records. Similarly, we validate that our memory handling routines cannot be over-filled by attempting to over-fill them. -To avoid adding unneeded code to the production build of s2n, there is also a small test library defined at [tests/testlib/](https://github.com/aws/s2n-tls/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. +To avoid adding unneeded code to the production build of s2n-tls, there is also a small test library defined at [tests/testlib/](https://github.com/aws/s2n-tls/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. Unit tests are run automatically with `make`. To run a subset of the unit tests, set the `UNIT_TESTS` environment variable with the unit test name(s). For example: ``` UNIT_TESTS=s2n_hash_test make ``` -## A tour of s2n memory handling: blobs and stuffers +## A tour of s2n-tls memory handling: blobs and stuffers -C has a history of issues around memory and buffer handling. To avoid problems in this area, s2n does not use C string functions or standard buffer manipulation patterns. Instead memory regions are tracked explicitly, with `s2n_blob` structures, and buffers are re-oriented as streams with `s2n_stuffer` structures. +C has a history of issues around memory and buffer handling. To avoid problems in this area, s2n-tls does not use C string functions or standard buffer manipulation patterns. Instead memory regions are tracked explicitly, with `s2n_blob` structures, and buffers are re-oriented as streams with `s2n_stuffer` structures. ### s2n_blob: keeping track of memory ranges @@ -247,12 +247,12 @@ struct s2n_blob { }; ``` -Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n prevents the memory regions from being swapped to disk and from showing up in core files (where supported). +Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n-tls prevents the memory regions from being swapped to disk and from showing up in core files (where supported). ### s2n_stuffer: a streaming buffer -The stuffer data structure included in s2n is intended to handle all protocol level -input and output to memory buffers and is the real work-horse of s2n. At its core +The stuffer data structure included in s2n-tls is intended to handle all protocol level +input and output to memory buffers and is the real work-horse of s2n-tls . At its core a stuffer is a blob and two cursors: ```c @@ -266,7 +266,7 @@ struct s2n_stuffer { This layout that makes it possible to implement a stream: -![Stuffer layout](images/s2n_stuffer_layout.png "s2n stuffer internal layout") +![Stuffer layout](images/s2n_stuffer_layout.png "s2n-tls stuffer internal layout") All access to/from the stuffer goes "through" s2n_stuffer_ functions. For example, we can write with **s2n_stuffer_write()**, and when we do the write cursor is incremented to the new position. We can read with **s2n_stuffer_read()**, and of course we can only read data as far as the write cursor (which is always at or ahead of the read cursor). To protect user data, when we read data out of the stuffer, we wipe the copy of the data within the local stuffer memory. We also ensure that it's only possible to read as much data as is in the stuffer. @@ -299,7 +299,7 @@ GUARD(s2n_stuffer_read_uint16(in, &record_size)); This pattern should make it very clear what the message format is, where the contents are being stored, and that we're handling things in a safe way. -There are times when we must interact with C functions from other libraries; for example, when handling encryption and decryption. In these cases, it is usually necessary to provide access to "raw" pointers into stuffers. s2n provides two functions for this: +There are times when we must interact with C functions from other libraries; for example, when handling encryption and decryption. In these cases, it is usually necessary to provide access to "raw" pointers into stuffers. s2n-tls provides two functions for this: ```c void *s2n_stuffer_raw_write(struct s2n_stuffer *stuffer, uint32_t data_len); @@ -356,7 +356,7 @@ GUARD(s2n_stuffer_wipe(&in)); Every connection is associated with an s2n_connection structure. The details of this structure are opaque to applications, but internally it is where all of the TLS state is managed. To make sense of what is going on, it is necessary to understand how the TLS protocol works at the record and handshake layers. -When a TLS connection is being started, the first communication consists of handshake messages. The client sends the first message (a client hello), and then the server replies (with a server hello), and so on. Because a server must wait for a client and vice versa, this phase of a TLS connection is not full-duplex. To save on memory, s2n uses a single stuffer for both incoming and outgoing handshake messages and it is located as s2n_connection->handshake.io (which is a growable stuffer). +When a TLS connection is being started, the first communication consists of handshake messages. The client sends the first message (a client hello), and then the server replies (with a server hello), and so on. Because a server must wait for a client and vice versa, this phase of a TLS connection is not full-duplex. To save on memory, s2n-tls uses a single stuffer for both incoming and outgoing handshake messages and it is located as s2n_connection->handshake.io (which is a growable stuffer). Borrowing another trick from functional programming, the state machine for handling handshake messages is implemented using a table of function pointers, located in [tls/s2n_handshake_io.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_handshake_io.c). @@ -380,13 +380,13 @@ static struct s2n_handshake_action state_machine[] = { }; ``` -The 'writer' field indicates whether we expect a Client or a Server to write a particular message type (or 'B' for both in the case of an application data message, but we haven't gotten to that yet). If s2n is acting as a server, then it attempts to read client messages, if it's acting as a client it will try to write it. To perform either operation it calls the relevant function pointer. This way the state machine can be very short and simple: write a handshake message out when we have one pending, and in the other direction read in data until we have a fully-buffered handshake message before then calling the relevant message parsing function. +The 'writer' field indicates whether we expect a Client or a Server to write a particular message type (or 'B' for both in the case of an application data message, but we haven't gotten to that yet). If s2n-tls is acting as a server, then it attempts to read client messages, if it's acting as a client it will try to write it. To perform either operation it calls the relevant function pointer. This way the state machine can be very short and simple: write a handshake message out when we have one pending, and in the other direction read in data until we have a fully-buffered handshake message before then calling the relevant message parsing function. One detail we've skipped over so far is that handshake messages are encapsulated by an additional record layer within the TLS protocol. As we've already seen, TLS records are fairly simple: just a 5-byte header indicating the message type (Handshake, application data, and alerts), protocol version, and record size. The remainder of the record is data and may or may not be encrypted. What isn't so simple is that TLS allows 'inner' messages, like Handshake message, to be fragmented across several records, and for a single record to contain multiple messages. -![TLS layers](images/s2n_tls_layers.png "s2n TLS layers") +![TLS layers](images/s2n_tls_layers.png "s2n-tls TLS layers") -In the outbound direction, s2n never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. +In the outbound direction, s2n-tls never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. To perform all of this, the s2n_connection structure has a few more internal stuffers: @@ -397,9 +397,9 @@ struct s2n_stuffer out; struct s2n_stuffer alert_in; ``` -'header_in' is a small 5-byte stuffer, which is used to read in a record header. Once that stuffer is full, and the size of the next record is determined (from that header), inward data is directed to the 'in' stuffer. The 'out' stuffer is for data that we are writing out; like an encrypted TLS record. 'alert_in' is for any TLS alert message that s2n receives from its peer. s2n treats all alerts as fatal, but we buffer the full alert message so that reason can be logged. +'header_in' is a small 5-byte stuffer, which is used to read in a record header. Once that stuffer is full, and the size of the next record is determined (from that header), inward data is directed to the 'in' stuffer. The 'out' stuffer is for data that we are writing out; like an encrypted TLS record. 'alert_in' is for any TLS alert message that s2n-tls receives from its peer. s2n-tls treats all alerts as fatal, but we buffer the full alert message so that reason can be logged. -When past the handshake phase, s2n supports full-duplex I/O. Separate threads or event handlers are free to call s2n_send and s2n_recv on the same connection. Because either a read or a write may cause a connection to be closed, there are two additional stuffers for storing outbound alert messages: +When past the handshake phase, s2n-tls supports full-duplex I/O. Separate threads or event handlers are free to call s2n_send and s2n_recv on the same connection. Because either a read or a write may cause a connection to be closed, there are two additional stuffers for storing outbound alert messages: ```c struct s2n_stuffer reader_alert_out; @@ -415,19 +415,19 @@ sig_atomic_t closed; 'closing' is an atomic, but even if it were not it can only be changed from 0 to 1, so an over-write is harmless. Every time a TLS record is fully-written, s2n_send() checks to see if closing is set to 1. If it is then the reader or writer alert message will be sent (writer takes priority, if both are present) and the connection will be closed. Once the closed is 1, no more I/O may be sent or received on the connection. -## s2n and entropy +## s2n-tls and entropy -s2n provides two deterministic random number generators to every thread. **s2n_get_public_random_data()** should be used to generate any data that is exposed in a public context including nonces, initialization vectors, and randomized timing values. **s2n_get_private_random_data()** should be used for data which must be kept secret. Additionally s2n over-rides libcrypto's entropy generation with **s2n_get_private_random_data()**. +s2n-tls provides two deterministic random number generators to every thread. **s2n_get_public_random_data()** should be used to generate any data that is exposed in a public context including nonces, initialization vectors, and randomized timing values. **s2n_get_private_random_data()** should be used for data which must be kept secret. Additionally s2n-tls over-rides libcrypto's entropy generation with **s2n_get_private_random_data()**. -## Contributing to s2n +## Contributing to s2n-tls -We are happy to accept contributions to s2n. We suggest the following general procedure: +We are happy to accept contributions to s2n-tls . We suggest the following general procedure: -* Please read all of the documentation available in the s2n "docs/" directory. This development guide along with the usage guide should give a good flavor for what the goals of s2n are and whether they line up with your idea for a contribution +* Please read all of the documentation available in the s2n-tls "docs/" directory. This development guide along with the usage guide should give a good flavor for what the goals of s2n-tls are and whether they line up with your idea for a contribution * If you have an idea for a significant contribution, it is worth first cutting an issue and discussing the change. Get feedback on the API design, or what the feature might require, before writing code. * If you discover a security critical bug, please report it via http://aws.amazon.com/security/vulnerability-reporting/ and **do not** create a public issue. -* Create a git fork of the s2n repository and prepare your changes locally within your fork. -* When you're ready, and when all tests are passing, create a pull request to the master awslabs s2n repository. -* All changes to s2n go through code review and legal review. All submissions and contributions are made under the terms of the Apache Software License 2.0. For larger contributions, we may ask you to sign a contributor license agreement. -* s2n undergoes periodic government and commercial security analyses, including code audits and penetration tests. To participate in these analyses, we may ask you to sign a Non-Disclosure Agreement. +* Create a git fork of the s2n-tls repository and prepare your changes locally within your fork. +* When you're ready, and when all tests are passing, create a pull request to the master awslabs s2n-tls repository. +* All changes to s2n-tls go through code review and legal review. All submissions and contributions are made under the terms of the Apache Software License 2.0. For larger contributions, we may ask you to sign a contributor license agreement. +* s2n-tls undergoes periodic government and commercial security analyses, including code audits and penetration tests. To participate in these analyses, we may ask you to sign a Non-Disclosure Agreement. diff --git a/docs/READING-LIST.md b/docs/READING-LIST.md index 4f714171175..f31e8463071 100644 --- a/docs/READING-LIST.md +++ b/docs/READING-LIST.md @@ -1,4 +1,4 @@ -# Useful Reading list for s2n +# Useful Reading list for s2n-tls ## Books diff --git a/docs/STATE-MACHINE.md b/docs/STATE-MACHINE.md index 1f1df81509f..b0a91ef985f 100644 --- a/docs/STATE-MACHINE.md +++ b/docs/STATE-MACHINE.md @@ -1,4 +1,4 @@ -# s2n state machine graphs +# s2n-tls state machine graphs ## TLS 1.2 State Machine diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index fea382c9f13..fa66ccd7ffe 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -1,16 +1,16 @@ -# Using s2n +# Using s2n-tls -s2n is a C library, and is built using Make. To clone the latest -copy of s2n from git use: +s2n-tls is a C library, and is built using Make. To clone the latest +copy of s2n-tls from git use: ```shell git clone https://github.com/aws/s2n-tls.git -cd s2n +cd s2n-tls ``` -## Building s2n with existing libcrypto +## Building s2n-tls with existing libcrypto ### make Instructions -To build s2n with an existing libcrypto installation, store its root folder in the +To build s2n-tls with an existing libcrypto installation, store its root folder in the `LIBCRYPTO_ROOT` environment variable. ```shell # /usr/local/ssl/lib should contain libcrypto.a @@ -28,7 +28,7 @@ the default installation on your machine will be used. (Optional): Set the CMake variable `BUILD_SHARED_LIBS=ON` to build shared libraries. The default is static. -We recommend an out-of-source build. Suppose you have a directory `s2n` which contains the s2n source code. At the same level +We recommend an out-of-source build. Suppose you have a directory `s2n` which contains the s2n-tls source code. At the same level we can create a directory called `s2n-build` For example, we can build and install shared libs using ninja as our build system, and the system libcrypto implementation. @@ -36,7 +36,7 @@ For example, we can build and install shared libs using ninja as our build syste ````shell mkdir s2n-build cd s2n-build -cmake ../s2n -DBUILD_SHARED_LIBS=ON -GNinja +cmake ../s2n-tls -DBUILD_SHARED_LIBS=ON -GNinja ninja ninja test sudo ninja install @@ -47,7 +47,7 @@ For another example, we can prepare an Xcode project using static libs using a l ````shell mkdir s2n-build cd s2n-build -cmake ../s2n -DCMAKE_INSTALL_PREFIX=$HOME/s2n-user/builds/libcrypto-impl -G "Xcode" +cmake ../s2n-tls -DCMAKE_INSTALL_PREFIX=$HOME/s2n-user/builds/libcrypto-impl -G "Xcode" # now open the project in Xcode and build from there, or use the Xcode CLI ```` @@ -56,14 +56,14 @@ Or, for unix style vanilla builds: ````shell mkdir s2n-build cd s2n-build -cmake ../s2n +cmake ../s2n-build make make test sudo make install ```` -### Consuming s2n via. CMake -s2n ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n in your project is: +### Consuming s2n-tls via. CMake +s2n-tls ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n-tls in your project is: ````shell find_package(s2n) @@ -74,12 +74,12 @@ target_link_libraries(yourExecutableOrLibrary AWS::s2n) ```` And when invoking CMake for your project, do one of two things: - 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n build. + 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n-tls build. 2. If you have globally installed s2n, do nothing, it will automatically be found. -## Building s2n with OpenSSL-1.1.1 +## Building s2n-tls with OpenSSL-1.1.1 -To build s2n with OpenSSL-1.1.1, do the following: +To build s2n-tls with OpenSSL-1.1.1, do the following: ```shell # We keep the build artifacts in the -build directory @@ -100,7 +100,7 @@ cd `tar ztf openssl-1.1.1-latest.tar.gz | head -n1 | cut -f1 -d/` make make install -# Build s2n +# Build s2n-tls cd ../../ make ``` @@ -115,9 +115,9 @@ setarch i386 ./config -fPIC no-shared \ --prefix=`pwd`/../../libcrypto-root/ ``` -## Building s2n with OpenSSL-1.0.2 +## Building s2n-tls with OpenSSL-1.0.2 -To build s2n with OpenSSL-1.0.2, do the following: +To build s2n-tls with OpenSSL-1.0.2, do the following: ```shell # We keep the build artifacts in the -build directory @@ -139,16 +139,16 @@ make depend make make install -# Build s2n +# Build s2n-tls cd ../../ make ``` **Mac Users:** please replace "./config" with "./Configure darwin64-x86_64-cc". -## Building s2n with LibreSSL +## Building s2n-tls with LibreSSL -To build s2n with LibreSSL, do the following: +To build s2n-tls with LibreSSL, do the following: ```shell # We keep the build artifacts in the -build directory @@ -163,17 +163,17 @@ cd libressl-x.y.z ./configure --prefix=`pwd`/../../libcrypto-root/ make CFLAGS=-fPIC install -# Build s2n +# Build s2n-tls cd ../../ make ``` -once built, static and dynamic libraries for s2n will be available in the lib/ +once built, static and dynamic libraries for s2n-tls will be available in the lib/ directory. -## Building s2n with BoringSSL +## Building s2n-tls with BoringSSL -To build s2n with BoringSSL, you must check out a copy of the BoringSSL +To build s2n-tls with BoringSSL, you must check out a copy of the BoringSSL directly via git. This procedure has been tested with fb68d6c901b98ffe15b8890d00bc819bf44c5f01 of BoringSSL. @@ -196,18 +196,18 @@ mkdir ../../../libcrypto-root/lib/ cp crypto/libcrypto.a ../../../libcrypto-root/lib/ cp -r ../include/ ../../../libcrypto-root/include -# Build s2n +# Build s2n-tls cd ../../../ make ``` -once built, static and dynamic libraries for s2n will be available in the lib/ +once built, static and dynamic libraries for s2n-tls will be available in the lib/ directory. ## mlock() and system limits -Internally s2n uses mlock() to prevent memory from being swapped to disk. The -s2n build tests may fail in some environments where the default limit on locked +Internally s2n-tls uses mlock() to prevent memory from being swapped to disk. The +s2n-tls build tests may fail in some environments where the default limit on locked memory is too low. To check this limit, run: ```shell @@ -217,23 +217,23 @@ ulimit -l to raise the limit, consult the documentation for your platform. ### Disabling mlock() -To disable s2n's mlock behavior, run your application with the `S2N_DONT_MLOCK` environment variable set. -s2n also reads this for unit tests. Try `S2N_DONT_MLOCK=1 make` if you're having mlock failures during unit tests. +To disable s2n-tls's mlock behavior, run your application with the `S2N_DONT_MLOCK` environment variable set. +s2n-tls also reads this for unit tests. Try `S2N_DONT_MLOCK=1 make` if you're having mlock failures during unit tests. -# s2n API +# s2n-tls API -The API exposed by s2n is the set of functions and declarations that +The API exposed by s2n-tls is the set of functions and declarations that are in the "s2n.h" header file. Any functions and declarations that are in the "s2n.h" file -are intended to be stable (API and ABI) within major version numbers of s2n releases. Other functions -and structures used in s2n internally can not be considered stable and their parameters, names, and +are intended to be stable (API and ABI) within major version numbers of s2n-tls releases. Other functions +and structures used in s2n-tls internally can not be considered stable and their parameters, names, and sizes may change. -At this time (Summer 2015), there has been no numbered release of s2n and all APIs are subject to change based +At this time (Summer 2015), there has been no numbered release of s2n-tls and all APIs are subject to change based on the feedback and preferences of early adopters. ## Preprocessor macros -s2n defines five preprocessor macros that are used to determine what +s2n-tls defines five preprocessor macros that are used to determine what version of SSL/TLS is in use on a connection. ```c @@ -245,12 +245,12 @@ version of SSL/TLS is in use on a connection. ``` These correspond to SSL2.0, SSL3.0, TLS1.0, TLS1.1 and TLS1.2 respectively. -Note that s2n does not support SSL2.0 for sending and receiving encrypted data, +Note that s2n-tls does not support SSL2.0 for sending and receiving encrypted data, but does accept SSL2.0 hello messages. ## Enums -s2n defines the following enum types: +s2n-tls defines the following enum types: ### s2n_error_type @@ -267,7 +267,7 @@ typedef enum { } s2n_error_type; ``` -***s2n_error_type*** is used to help applications determine why an s2n function failed. +***s2n_error_type*** is used to help applications determine why an s2n-tls function failed. This enum is optimized for use in C switch statements. Each value in the enum represents an error "category". See [Error Handling](#error-handling) for more detail. @@ -286,8 +286,8 @@ typedef enum { S2N_NOT_BLOCKED, S2N_BLOCKED_ON_READ, S2N_BLOCKED_ON_WRITE } s2n_ ``` **s2n_blocked_status** is used in non-blocking mode to indicate in which -direction s2n became blocked on I/O before it returned control to the caller. -This allows an application to avoid retrying s2n operations until I/O is +direction s2n-tls became blocked on I/O before it returned control to the caller. +This allows an application to avoid retrying s2n-tls operations until I/O is possible in that direction. ### s2n_blinding @@ -296,9 +296,9 @@ possible in that direction. typedef enum { S2N_BUILT_IN_BLINDING, S2N_SELF_SERVICE_BLINDING } s2n_blinding; ``` -**s2n_blinding** is used to opt-out of s2n's built-in blinding. Blinding is a +**s2n_blinding** is used to opt-out of s2n-tls's built-in blinding. Blinding is a mitigation against timing side-channels which in some cases can leak information -about encrypted data. By default s2n will cause a thread to sleep between 10 and +about encrypted data. By default s2n-tls will cause a thread to sleep between 10 and 30 seconds whenever tampering is detected. Setting the **S2N_SELF_SERVICE_BLINDING** option with **s2n_connection_set_blinding** @@ -324,13 +324,13 @@ supported status request type is OCSP, **S2N_STATUS_REQUEST_OCSP**. typedef enum { S2N_CERT_AUTH_NONE, S2N_CERT_AUTH_REQUIRED, S2N_CERT_AUTH_OPTIONAL } s2n_cert_auth_type; ``` **s2n_cert_auth_type** is used to declare what type of client certificiate authentication to use. -Currently the default for s2n is for neither the server side or the client side to use Client (aka Mutual) authentication. +Currently the default for s2n-tls is for neither the server side or the client side to use Client (aka Mutual) authentication. ## Opaque structures -s2n defines several opaque structures that are used for managed objects. Because +s2n-tls defines several opaque structures that are used for managed objects. Because these structures are opaque, they can only be safely referenced indirectly through -pointers and their sizes may change with future versions of s2n. +pointers and their sizes may change with future versions of s2n-tls. ```c struct s2n_config; @@ -347,7 +347,7 @@ struct s2n_rsa_public_key; struct s2n_cert_public_key; ``` -**s2n_rsa_public_key** and **s2n_cert_public_key** can be used by consumers of s2n to get and set public keys through other API calls. +**s2n_rsa_public_key** and **s2n_cert_public_key** can be used by consumers of s2n-tls to get and set public keys through other API calls. ## Error handling @@ -358,14 +358,14 @@ const char *s2n_strerror_debug(int error, const char *lang); const char *s2n_strerror_name(int error); ```` -s2n functions that return 'int' return 0 to indicate success and -1 to indicate -failure. s2n functions that return pointer types return NULL in the case of -failure. When an s2n function returns a failure, s2n_errno will be set to a value +s2n-tls functions that return 'int' return 0 to indicate success and -1 to indicate +failure. s2n-tls functions that return pointer types return NULL in the case of +failure. When an s2n-tls function returns a failure, s2n_errno will be set to a value corresponding to the error. This error value can be translated into a string explaining the error in English by calling s2n_strerror(s2n_errno, "EN"). A string containing human readable error name, can be generated with `s2n_strerror_name`. A string containing internal debug information, including filename and line number, can be generated with `s2n_strerror_debug`. -This string is useful to include when reporting issues to the s2n development team. +This string is useful to include when reporting issues to the s2n-tls development team. Example: @@ -378,11 +378,11 @@ if (s2n_config_set_cipher_preferences(config, prefs) < 0) { **NOTE**: To avoid possible confusion, s2n_errno should be cleared after processing an error: `s2n_errno = S2N_ERR_T_OK` -When using s2n outside of `C`, the address of the thread-local `s2n_errno` may be obtained by calling the `int *s2n_errno_location()` function. -This will ensure that the same TLS mechanisms are used with which s2n was compiled. +When using s2n-tls outside of `C`, the address of the thread-local `s2n_errno` may be obtained by calling the `int *s2n_errno_location()` function. +This will ensure that the same TLS mechanisms are used with which s2n-tls was compiled. ### Stacktraces -s2n has an mechanism to capture stacktraces when errors occur. +s2n-tls has an mechanism to capture stacktraces when errors occur. This mechanism is off by default, but can be enabled in code by calling `s2n_stack_traces_enabled_set()`. It can be enabled globally by setting the environment variable `S2N_PRINT_STACKTRACE=1`. Note that enabling stacktraces this can significantly slow down unit tests, and can cause failures on unit-tests (such as `s2n_cbc_verify`) that measure the timing of events. @@ -399,7 +399,7 @@ int s2n_get_stacktrace(char*** trace, int* trace_size); ### Error categories -s2n organizes errors into different "types" to allow applications to do logic on error values without catching all possibilities. +s2n-tls organizes errors into different "types" to allow applications to do logic on error values without catching all possibilities. Applications using non-blocking I/O should check error type to determine if the I/O operation failed because it would block or for some other error. To retrieve the type for a given error use `s2n_error_get_type()`. Applications should perform any error handling logic using these high level types: @@ -410,7 +410,7 @@ S2N_ERR_T_CLOSED, /* EOF */ S2N_ERR_T_BLOCKED, /* Underlying I/O operation would block */ S2N_ERR_T_ALERT, /* Incoming Alert */ S2N_ERR_T_PROTO, /* Failure in some part of the TLS protocol. Ex: CBC verification failure */ -S2N_ERR_T_INTERNAL, /* Error internal to s2n. A precondition could have failed. */ +S2N_ERR_T_INTERNAL, /* Error internal to s2n-tls. A precondition could have failed. */ S2N_ERR_T_USAGE /* User input error. Ex: Providing an invalid cipher preference version */ ``` @@ -451,8 +451,8 @@ if (s2n_recv(conn, &blocked) < 0) { unsigned long s2n_get_openssl_version(); ``` -**s2n_get_openssl_version** returns the version number of OpenSSL that s2n was compiled with. It can be used by -applications to validate at runtime that the versions of s2n and Openssl that they have loaded are correct. +**s2n_get_openssl_version** returns the version number of OpenSSL that s2n-tls was compiled with. It can be used by +applications to validate at runtime that the versions of s2n-tls and Openssl that they have loaded are correct. ### s2n\_init @@ -461,9 +461,9 @@ applications to validate at runtime that the versions of s2n and Openssl that th int s2n_init(); ``` -**s2n_init** initializes the s2n library and should be called once in your application, -before any other s2n functions are called. Failure to call s2n_init() will result -in errors from other s2n functions. +**s2n_init** initializes the s2n-tls library and should be called once in your application, +before any other s2n-tls functions are called. Failure to call s2n_init() will result +in errors from other s2n-tls functions. ### s2n\_cleanup @@ -471,9 +471,9 @@ in errors from other s2n functions. int s2n_cleanup(); ``` -**s2n_cleanup** cleans up any internal resources used by s2n. This function should be +**s2n_cleanup** cleans up any internal resources used by s2n-tls. This function should be called from each thread or process that is created subsequent to calling **s2n_init** -when that thread or process is done calling other s2n functions. +when that thread or process is done calling other s2n-tls functions. ## Configuration-oriented functions @@ -529,15 +529,15 @@ The following chart maps the security policy version to protocol version and cip | "20190802" | | X | X | X | X | X | X | | X | | | | X | | "20200207" | | X | X | X | X | X | X | | X | | | | | -The "default" and "default_tls13" version is special in that it will be updated with future s2n changes and ciphersuites and protocol versions may be added and removed, or their internal order of preference might change. Numbered versions are fixed and will never change. +The "default" and "default_tls13" version is special in that it will be updated with future s2n-tls changes and ciphersuites and protocol versions may be added and removed, or their internal order of preference might change. Numbered versions are fixed and will never change. -"20160411" follows the same general preference order as "default". The main difference is it has a CBC cipher suite at the top. This is to accommodate certain Java clients that have poor GCM implementations. Users of s2n who have found GCM to be hurting performance for their clients should consider this version. +"20160411" follows the same general preference order as "default". The main difference is it has a CBC cipher suite at the top. This is to accommodate certain Java clients that have poor GCM implementations. Users of s2n-tls who have found GCM to be hurting performance for their clients should consider this version. -"20170405" is a FIPS compliant cipher suite preference list based on approved algorithms in the [FIPS 140-2 Annex A](http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf). Similarly to "20160411", this preference list has CBC cipher suites at the top to accommodate certain Java clients. Users of s2n who plan to enable FIPS mode should consider this version. +"20170405" is a FIPS compliant cipher suite preference list based on approved algorithms in the [FIPS 140-2 Annex A](http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf). Similarly to "20160411", this preference list has CBC cipher suites at the top to accommodate certain Java clients. Users of s2n-tls who plan to enable FIPS mode should consider this version. -s2n does not expose an API to control the order of preference for each ciphersuite or protocol version. s2n follows the following order: +s2n-tls does not expose an API to control the order of preference for each ciphersuite or protocol version. s2n-tls follows the following order: -*NOTE*: All ChaCha20-Poly1305 cipher suites will not be available if s2n is not built with an Openssl 1.1.1 libcrypto. The +*NOTE*: All ChaCha20-Poly1305 cipher suites will not be available if s2n-tls is not built with an Openssl 1.1.1 libcrypto. The underlying encrypt/decrypt functions are not available in older versions. 1. Always prefer the highest protocol version supported @@ -637,14 +637,14 @@ int s2n_config_set_cert_chain_and_key_defaults(struct s2n_config *config, **s2n_config_set_cert_chain_and_key_defaults** explicitly sets certificate chain and private key pairs to be used as defaults for each auth method (key type). A "default" certificate is used when there is not an SNI match with any other configured certificate. Only one certificate can be set as the default per auth method (one RSA default, one ECDSA default, etc.). All previous default certificates will be cleared and re-set when this API is called. This API is called for a specific **s2n_config** object. -S2N will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n will clear defaults and no longer attempt to automatically choose any default certificates. +S2N will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates. ### s2n\_cert\_tiebreak\_callback ```c typedef struct s2n_cert_chain_and_key* (*s2n_cert_tiebreak_callback) (struct s2n_cert_chain_and_key *cert1, struct s2n_cert_chain_and_key *cert2, uint8_t *name, uint32_t name_len); ``` -**s2n_cert_tiebreak_callback** is invoked if s2n cannot resolve a conflict between two certificates with the same domain name. This function is invoked while certificates are added to an **s2n_config**. +**s2n_cert_tiebreak_callback** is invoked if s2n-tls cannot resolve a conflict between two certificates with the same domain name. This function is invoked while certificates are added to an **s2n_config**. Currently, the only builtin resolution for domain name conflicts is certificate type(RSA, ECDSA, etc). The callback should return a pointer to the **s2n_cert_chain_and_key** that should be used for dns name **name**. If NULL is returned, the first certificate will be used. Typically an application will use properties like trust and expiry to implement tiebreaking. @@ -843,14 +843,14 @@ that will be called after ClientHello was parsed. typedef int s2n_client_hello_fn(struct s2n_connection *conn, void *ctx); ``` -The callback function take as an input s2n connection, which received +The callback function take as an input s2n-tls connection, which received ClientHello and context provided in **s2n_config_set_client_hello_cb**. The callback can get any ClientHello information from the connection and use **s2n_connection_set_config** call to change the config of the connection. If any of the properties of the connection were changed based on server_name extension the callback must return 1, otherwise the callback can return 0 -to continue handshake in s2n or it can return negative value to make s2n +to continue handshake in s2n-tls or it can return negative value to make s2n-tls terminate handshake early with fatal handshake failure alert. ### s2n\_config\_set\_alert\_behavior @@ -858,8 +858,8 @@ terminate handshake early with fatal handshake failure alert. int s2n_config_set_alert_behavior(struct s2n_config *config, s2n_alert_behavior alert_behavior); ``` Sets whether or not a connection should terminate on receiving a WARNING alert from its peer. `alert_behavior` can take the following values: -- `S2N_ALERT_FAIL_ON_WARNINGS` - default behavior: s2n will terminate the connection if its peer sends a WARNING alert. -- `S2N_ALERT_IGNORE_WARNINGS` - with the exception of `close_notify` s2n will ignore all WARNING alerts and keep communicating with its peer. +- `S2N_ALERT_FAIL_ON_WARNINGS` - default behavior: s2n-tls will terminate the connection if its peer sends a WARNING alert. +- `S2N_ALERT_IGNORE_WARNINGS` - with the exception of `close_notify` s2n-tls will ignore all WARNING alerts and keep communicating with its peer. This setting is ignored in TLS1.3. TLS1.3 terminates a connection for all alerts except user_canceled. @@ -923,7 +923,7 @@ Client Auth Related API's are not recommended for normal users. Use of these API 1. Using these API's requires users to: Complete full x509 parsing and hostname validation in the application layer 2. Application knowledge of TLS code points for certificate types -3. Application dependency on libcrypto to give a libcrypto RSA struct back to s2n +3. Application dependency on libcrypto to give a libcrypto RSA struct back to s2n-tls ### s2n\_config\_set\_client\_auth\_type and s2n\_connection\_set\_client\_auth\_type ```c @@ -946,7 +946,7 @@ set the public keys found in the Certificate into **public_key_out**. ## Session Caching related calls -s2n includes support for resuming from cached SSL/TLS session, provided +s2n-tls includes support for resuming from cached SSL/TLS session, provided the caller sets (and implements) three callback functions. ### s2n\_config\_set\_cache\_store\_callback @@ -1008,7 +1008,7 @@ int s2n_config_send_max_fragment_length(struct s2n_config *config, uint8_t mfl_c **s2n_config_send_max_fragment_length** allows the caller to set a TLS Maximum Fragment Length extension that will be used to fragment outgoing messages. -s2n currently does not reject fragments larger than the configured maximum when +s2n-tls currently does not reject fragments larger than the configured maximum when in server mode. The TLS negotiated maximum fragment length overrides the preference set by the **s2n_connection_prefer_throughput** and **s2n_connection_prefer_low_latency**. @@ -1030,7 +1030,7 @@ request and continue TLS handshake with default maximum fragment length of 8k by struct s2n_connection * s2n_connection_new(s2n_mode mode); ``` -**s2n_connection_new** creates a new connection object. Each s2n SSL/TLS +**s2n_connection_new** creates a new connection object. Each s2n-tls SSL/TLS connection uses one of these objects. These connection objects can be operated on by up to two threads at a time, one sender and one receiver, but neither sending nor receiving are atomic, so if these objects are being called by @@ -1081,8 +1081,8 @@ int s2n_connection_set_write_fd(struct s2n_connection *conn, int writefd); ``` -**s2n_connection_set_fd** sets the file-descriptor for an s2n connection. This -file-descriptor should be active and connected. s2n also supports setting the +**s2n_connection_set_fd** sets the file-descriptor for an s2n-tls connection. This +file-descriptor should be active and connected. s2n-tls also supports setting the read and write file-descriptors to different values (for pipes or other unusual types of I/O). @@ -1147,7 +1147,7 @@ name the client is using. int s2n_connection_set_blinding(struct s2n_connection *conn, s2n_blinding blinding); ``` -**s2n_connection_set_blinding** can be used to configure s2n to either use +**s2n_connection_set_blinding** can be used to configure s2n-tls to either use built-in blinding (set blinding to S2N_BUILT_IN_BLINDING) or self-service blinding (set blinding to S2N_SELF_SERVICE_BLINDING). @@ -1169,7 +1169,7 @@ int s2n_connection_set_dynamic_record_threshold(struct s2n_connection *conn, uin ``` **s2n_connection_prefer_throughput** and **s2n_connection_prefer_low_latency** -change the behavior of s2n when sending data to prefer either throughput +change the behavior of s2n-tls when sending data to prefer either throughput or low latency. Connections prefering low latency will be encrypted using small record sizes that can be decrypted sooner by the recipient. Connections prefering throughput will use large record sizes that minimize overhead. @@ -1189,7 +1189,7 @@ uint64_t s2n_connection_get_wire_bytes_out(struct s2n_connection *conn); ``` **s2n_connection_get_wire_bytes_in** and **s2n_connection_get_wire_bytes_out** -return the number of bytes transmitted by s2n "on the wire", in and out +return the number of bytes transmitted by s2n-tls "on the wire", in and out respectively. ### s2n\_connection\_get\_protocol\_version @@ -1205,7 +1205,7 @@ int s2n_connection_get_actual_protocol_version(struct s2n_connection *conn); number supported by the client, **s2n_connection_get_server_protocol_version** returns the protocol version number supported by the server and **s2n_connection_get_actual_protocol_version** returns the protocol version -number actually used by s2n for the connection. **s2n_connection_get_client_hello_version** +number actually used by s2n-tls for the connection. **s2n_connection_get_client_hello_version** returns the protocol version used to send the initial client hello message. Each version number value corresponds to the macros defined as **S2N_SSLv2**, @@ -1351,7 +1351,7 @@ int s2n_connection_get_alert(struct s2n_connection *conn); ``` If a connection was shut down by the peer, **s2n_connection_get_alert** returns -the TLS alert code that caused a connection to be shut down. s2n considers all +the TLS alert code that caused a connection to be shut down. s2n-tls considers all TLS alerts fatal and shuts down a connection whenever one is received. ### s2n\_connection\_get\_cipher @@ -1361,7 +1361,7 @@ const char * s2n_connection_get_cipher(struct s2n_connection *conn); ``` **s2n_connection_get_cipher** returns a string indicating the cipher suite -negotiated by s2n for a connection in Openssl format, e.g. "ECDHE-RSA-AES128-GCM-SHA256". +negotiated by s2n-tls for a connection in Openssl format, e.g. "ECDHE-RSA-AES128-GCM-SHA256". ### s2n\_connection\_get\_curve @@ -1382,7 +1382,7 @@ Return the certificate that was used during the TLS handshake. - If **conn** is a server connection, the certificate selected will depend on the ServerName sent by the client and supported ciphers. - If **conn** is a client connection, the certificate sent in response to a CertificateRequest - message is returned. Currently s2n supports loading only one certificate in client mode. Note that + message is returned. Currently s2n-tls supports loading only one certificate in client mode. Note that not all TLS endpoints will request a certificate. This function returns NULL if the certificate selection phase of the handshake has not completed @@ -1451,7 +1451,7 @@ this will allow for gradual and linear transition of a key from encrypt-decrypt ### Asynchronous private key operations related calls -When s2n is used in non-blocking mode, this set of functions allows user +When s2n-tls is used in non-blocking mode, this set of functions allows user to move execution of CPU-heavy private key operations out of the main event loop, preventing **s2n_negotiate** blocking the loop for a few milliseconds each time the private key operation needs to be performed. @@ -1566,15 +1566,15 @@ of sensitive data. ## I/O functions -s2n supports both blocking and non-blocking I/O. To use s2n in non-blocking +s2n-tls supports both blocking and non-blocking I/O. To use s2n-tls in non-blocking mode, set the underlying file descriptors as non-blocking (i.e. with -**fcntl**). In blocking mode, each s2n I/O function will not return until it is -complete. In non-blocking mode an s2n I/O function may return while there is +**fcntl**). In blocking mode, each s2n-tls I/O function will not return until it is +complete. In non-blocking mode an s2n-tls I/O function may return while there is still I/O pending. In this case the value of the **blocked** parameter will be set to either **S2N_BLOCKED_ON_READ** or **S2N_BLOCKED_ON_WRITE**, depending on the -direction in which s2n is blocked. +direction in which s2n-tls is blocked. -s2n I/O functions should be called repeatedly until the **blocked** parameter is +s2n-tls I/O functions should be called repeatedly until the **blocked** parameter is **S2N_NOT_BLOCKED**. ### s2n\_negotiate @@ -1698,7 +1698,7 @@ int s2n_connection_set_recv_ctx(struct s2n_connection *conn, void *ctx); int s2n_connection_set_send_ctx(struct s2n_connection *conn, void *ctx); ``` -s2n also provides an I/O abstraction layer in the event the application would +s2n-tls also provides an I/O abstraction layer in the event the application would like to keep control over I/O operations. **s2n_connection_set_recv_cb** and **s2n_connection_set_send_cb** may be used to send or receive data with callbacks defined by the user. These may be blocking or nonblocking. @@ -1745,20 +1745,20 @@ extern int s2n_mem_set_callbacks(s2n_mem_init_callback mem_init_callback, s2n_me ``` -**s2n_mem_set_callbacks** allows the caller to over-ride s2n's internal memory +**s2n_mem_set_callbacks** allows the caller to over-ride s2n-tls's internal memory handling functions. To work correctly, **s2n_mem_set_callbacks** must be called before **s2n_init**. **s2n_mem_init_callback** should be a function that will -be called when s2n is initialized. **s2n_mem_cleanup_callback** will be called +be called when s2n-tls is initialized. **s2n_mem_cleanup_callback** will be called when **s2n_cleanup** is executed. **s2n_mem_malloc_callback** should be a function that can allocate at least **requested** bytes of memory and store the location of that memory in **\*ptr**, and the size of the allocated data in **\*allocated**. The function may choose to allocate more memory than was requested. -s2n will consider all allocated memory available for use, and will attempt to +s2n-tls will consider all allocated memory available for use, and will attempt to free all allocated memory when able. **s2n_mem_free_callback** should be a function that can free memory. # Examples -To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory +To understand the API it may be easiest to see examples in action. s2n-tls's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory includes an example client (s2nc) and server (s2nd). From bdb6365ab6cd41342749fb916ac9313c0a25e0bb Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Fri, 19 Feb 2021 11:05:54 -0800 Subject: [PATCH 04/23] Update docs/DEVELOPMENT-GUIDE.md Co-authored-by: Tejeswini Sundaram <40477596+ttjsu-aws@users.noreply.github.com> --- docs/DEVELOPMENT-GUIDE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md index aa19b2940fd..0d3a0014c46 100644 --- a/docs/DEVELOPMENT-GUIDE.md +++ b/docs/DEVELOPMENT-GUIDE.md @@ -1,4 +1,4 @@ -c Development guide for s2n-tls +# Development guide for s2n-tls If you are curious about the internals of s2n-tls, or interested in contributing to s2n-tls, this document is for you. If instead you are interested in using s2n-tls in an application @@ -430,4 +430,3 @@ We are happy to accept contributions to s2n-tls . We suggest the following gener * When you're ready, and when all tests are passing, create a pull request to the master awslabs s2n-tls repository. * All changes to s2n-tls go through code review and legal review. All submissions and contributions are made under the terms of the Apache Software License 2.0. For larger contributions, we may ask you to sign a contributor license agreement. * s2n-tls undergoes periodic government and commercial security analyses, including code audits and penetration tests. To participate in these analyses, we may ask you to sign a Non-Disclosure Agreement. - From d1b4e0fc5846a6413982bb075013fa98f9d9f4db Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Fri, 19 Feb 2021 11:26:46 -0800 Subject: [PATCH 05/23] Update README.md Co-authored-by: Tejeswini Sundaram <40477596+ttjsu-aws@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 258f3ca72f1..cf9190e8e27 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 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. [![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/) -[![Apache 2 License](https://img.shields.io/github/license/aws/s2n-ls.svg)](http://aws.amazon.com/apache-2-0/) +[![Apache 2 License](https://img.shields.io/github/license/aws/s2n-tls.svg)](http://aws.amazon.com/apache-2-0/) [![C99](https://img.shields.io/badge/language-C99-blue.svg)](http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf) [![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/aws/s2n-tls.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/aws/s2n-tls/context:cpp) [![codecov](https://codecov.io/gh/aws/s2n-tls/branch/main/graph/badge.svg)](https://codecov.io/gh/aws/s2n-tls) From 96a56068be6bc4d15e778fa4b0d27d6b65b5356c Mon Sep 17 00:00:00 2001 From: Doug Chapman Date: Fri, 19 Feb 2021 11:31:01 -0800 Subject: [PATCH 06/23] Update USEAGE-GUIDE --- docs/USAGE-GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index fa66ccd7ffe..fbeb24149df 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -66,11 +66,11 @@ sudo make install s2n-tls ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n-tls in your project is: ````shell -find_package(s2n) +find_package(s2n-tls) .... -target_link_libraries(yourExecutableOrLibrary AWS::s2n) +target_link_libraries(yourExecutableOrLibrary AWS::s2n-tls) ```` And when invoking CMake for your project, do one of two things: From 2e47dfe5169d707f4f75aa52bc5b9d253ac617a2 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:22:35 -0800 Subject: [PATCH 07/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cf9190e8e27..07cc1ad4060 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ Internally s2n-tls takes a systematic approach to data protection and includes s ##### 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, 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. +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 From 0d1640f1225cbcefa3988ba5fe98b231aa50b1d5 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:22:48 -0800 Subject: [PATCH 08/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 07cc1ad4060..ed077543b20 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ AWS Security via our [vulnerability reporting page](http://aws.amazon.com/securi If you package or distribute s2n, 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, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). +If you are interested in contributing to s2n-tls, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). ## Language Bindings for s2n-tls See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n-tls that we're aware of. From f8d0a713cc77dd18edcbe5084eb7b4f44ea5f7da Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:22:57 -0800 Subject: [PATCH 09/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ed077543b20..e2e1dfbebfd 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ s2n-tls is written in C, but makes light use of standard C library functions and If you discover a potential security issue in s2n-tls we ask that you notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. -If you package or distribute s2n, 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. +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](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). From 649fc89ab9a1776a8d403b194600cebb7d659302 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:23:28 -0800 Subject: [PATCH 10/23] Update docs/USAGE-GUIDE.md Co-authored-by: Cameron Bytheway --- docs/USAGE-GUIDE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index fbeb24149df..4e83b118ce6 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -75,7 +75,7 @@ target_link_libraries(yourExecutableOrLibrary AWS::s2n-tls) And when invoking CMake for your project, do one of two things: 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n-tls build. - 2. If you have globally installed s2n, do nothing, it will automatically be found. + 2. If you have globally installed s2n-tls, do nothing, it will automatically be found. ## Building s2n-tls with OpenSSL-1.1.1 @@ -1761,4 +1761,3 @@ function that can free memory. To understand the API it may be easiest to see examples in action. s2n-tls's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory includes an example client (s2nc) and server (s2nd). - From d4ddaf6e03491d6dc8f20d1e62645b6dd67774ac Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:23:40 -0800 Subject: [PATCH 11/23] Update docs/USAGE-GUIDE.md Co-authored-by: Cameron Bytheway --- docs/USAGE-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index 4e83b118ce6..47dc7cf6e0e 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -637,7 +637,7 @@ int s2n_config_set_cert_chain_and_key_defaults(struct s2n_config *config, **s2n_config_set_cert_chain_and_key_defaults** explicitly sets certificate chain and private key pairs to be used as defaults for each auth method (key type). A "default" certificate is used when there is not an SNI match with any other configured certificate. Only one certificate can be set as the default per auth method (one RSA default, one ECDSA default, etc.). All previous default certificates will be cleared and re-set when this API is called. This API is called for a specific **s2n_config** object. -S2N will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates. +s2n-tls will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates. ### s2n\_cert\_tiebreak\_callback ```c From ae1bebbeda3832aec222605be73e9791b1eb6d89 Mon Sep 17 00:00:00 2001 From: Doug Chapman Date: Thu, 18 Feb 2021 12:26:40 -0800 Subject: [PATCH 12/23] Org change to aws --- README.md | 22 +++++++++++----------- codebuild/codebuild.config | 2 +- codebuild/common.config | 4 ++-- codebuild/integ_codebuild.config | 10 +++++----- docs/DEVELOPMENT-GUIDE.md | 24 ++++++++++++------------ docs/USAGE-GUIDE.md | 4 ++-- 6 files changed, 33 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index cdca230e20c..6c898aff2c6 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ s2n 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. -[![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/awslabs/s2n/) -[![Apache 2 License](https://img.shields.io/github/license/awslabs/s2n.svg)](http://aws.amazon.com/apache-2-0/) +[![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/) +[![Apache 2 License](https://img.shields.io/github/license/aws/s2n-ls.svg)](http://aws.amazon.com/apache-2-0/) [![C99](https://img.shields.io/badge/language-C99-blue.svg)](http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf) -[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/awslabs/s2n.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/awslabs/s2n/context:cpp) -[![codecov](https://codecov.io/gh/awslabs/s2n/branch/main/graph/badge.svg)](https://codecov.io/gh/awslabs/s2n) -[![Github forks](https://img.shields.io/github/forks/awslabs/s2n.svg)](https://github.com/awslabs/s2n/network) -[![Github stars](https://img.shields.io/github/stars/awslabs/s2n.svg)](https://github.com/awslabs/s2n/stargazers) -[![Join the chat at https://gitter.im/awslabs/s2n](https://badges.gitter.im/awslabs/s2n.svg)](https://gitter.im/awslabs/s2n?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/aws/s2n-tls.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/aws/s2n-tls/context:cpp) +[![codecov](https://codecov.io/gh/aws/s2n-tls/branch/main/graph/badge.svg)](https://codecov.io/gh/aws/s2n-tls) +[![Github forks](https://img.shields.io/github/forks/aws/s2n-tls.svg)](https://github.com/aws/s2n-tls/network) +[![Github stars](https://img.shields.io/github/stars/aws/s2n-tls.svg)](https://github.com/aws/s2n-tls/stargazers) +[![Join the chat at https://gitter.im/aws/s2n-tls](https://badges.gitter.im/aws/s2n-tls.svg)](https://gitter.im/aws/s2n-tls?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ## Quickstart for Ubuntu 1. Fork s2n on GitHub @@ -50,7 +50,7 @@ CTEST_PARALLEL_LEVEL=5 ninja test ``` ## Have a Question? -If you have any questions about Submitting PR's, Opening Issues, s2n API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/awslabs/s2n +If you have any questions about Submitting PR's, Opening Issues, s2n API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/aws/s2n-tls Otherwise, if you think you might have found a security impacting issue, please instead follow [our Security Notification Process.](#security-issue-notifications) @@ -81,7 +81,7 @@ int bytes_written; bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked); ``` -For details on building the s2n library and how to use s2n in an application you are developing, see the [API Reference](https://github.com/awslabs/s2n/blob/main/docs/USAGE-GUIDE.md). +For details on building the s2n library and how to use s2n in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). ## s2n features @@ -145,7 +145,7 @@ AWS Security via our [vulnerability reporting page](http://aws.amazon.com/securi If you package or distribute s2n, or use s2n as part of a large multi-user service, you may be eligible for pre-notification of future s2n releases. Please contact s2n-pre-notification@amazon.com. ## Contributing to s2n -If you are interested in contributing to s2n, please see our [development guide](https://github.com/awslabs/s2n/blob/main/docs/DEVELOPMENT-GUIDE.md). +If you are interested in contributing to s2n, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). ## Language Bindings for s2n -See our [language bindings list](https://github.com/awslabs/s2n/blob/main/docs/BINDINGS.md) for language bindings for s2n that we're aware of. +See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n that we're aware of. diff --git a/codebuild/codebuild.config b/codebuild/codebuild.config index 956d18b8e4d..e39499879f3 100644 --- a/codebuild/codebuild.config +++ b/codebuild/codebuild.config @@ -88,7 +88,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_2XLARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_sidetrail.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: diff --git a/codebuild/common.config b/codebuild/common.config index fb67335c647..855367987bf 100644 --- a/codebuild/common.config +++ b/codebuild/common.config @@ -15,7 +15,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_2XLARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -26,7 +26,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: diff --git a/codebuild/integ_codebuild.config b/codebuild/integ_codebuild.config index 40765ad1868..c81bb2ab9b6 100644 --- a/codebuild/integ_codebuild.config +++ b/codebuild/integ_codebuild.config @@ -11,7 +11,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl102.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -23,7 +23,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_boringlibre.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -36,7 +36,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl111.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -49,7 +49,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl102.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: @@ -62,7 +62,7 @@ env_type: LINUX_CONTAINER compute_type: BUILD_GENERAL1_LARGE timeout_in_min: 90 buildspec: codebuild/spec/buildspec_ubuntu_integ_openssl102_asanvalgrind.yml -source_location: https://github.com/awslabs/s2n.git +source_location: https://github.com/aws/s2n-tls.git source_type : GITHUB source_clonedepth: 1 source_version: diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md index 0755286d044..05f8e0ec59a 100644 --- a/docs/DEVELOPMENT-GUIDE.md +++ b/docs/DEVELOPMENT-GUIDE.md @@ -2,7 +2,7 @@ If you are curious about the internals of s2n, or interested in contributing to s2n, this document is for you. If instead you are interested in using s2n in an application -that you are developing, please see the accompanying [Usage Guide](https://github.com/awslabs/s2n/blob/main/docs/USAGE-GUIDE.md). +that you are developing, please see the accompanying [Usage Guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). ## s2n's development principles @@ -91,7 +91,7 @@ benefit is that functions can read quite declaratively. In the case of message parsers, the function contents can read almost like schemas of the message being parsed. -A good example file for message parsing to look at is [tls/s2n_server_finished.c](https://github.com/awslabs/s2n/blob/main/tls/s2n_server_finished.c). +A good example file for message parsing to look at is [tls/s2n_server_finished.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_server_finished.c). From reading the file it should be reasonably clear that a server finished message consists just of S2N_TLS_FINISHED_LEN number of bytes, what the next state is and so on. @@ -113,7 +113,7 @@ if (s2n_result_is_error(s2n_do_something(with_something_else))) { } ``` -is so common that [utils/s2n_safety.h](https://github.com/awslabs/s2n/blob/main/utils/s2n_safety.h) provides several macros for working with fallible functions. Notable macros include; +is so common that [utils/s2n_safety.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_safety.h) provides several macros for working with fallible functions. Notable macros include; ```c /** @@ -130,7 +130,7 @@ is so common that [utils/s2n_safety.h](https://github.com/awslabs/s2n/blob/main/ These macros should be used when calling functions you expect to succeed. Primarily these macros help save two lines that repeatedly clutter files, and secondarily they are very useful when developing and debugging code as it is easy to redefine the macro to implement a simple backtrace (even a simple printf will suffice, but a breakpoint is more usual). If a function does fail, it should use the `BAIL(errno)` macro provided for surfacing the error to an application. -New error translations, and their human-readable translations can be defined in [error/s2n_errno.h](https://github.com/awslabs/s2n/blob/main/error/s2n_errno.h) and [error/s2n_errno.c](https://github.com/awslabs/s2n/blob/main/error/s2n_errno.c). When called, e.g.: +New error translations, and their human-readable translations can be defined in [error/s2n_errno.h](https://github.com/aws/s2n-tls/blob/main/error/s2n_errno.h) and [error/s2n_errno.c](https://github.com/aws/s2n-tls/blob/main/error/s2n_errno.c). When called, e.g.: ```c BAIL(S2N_ERR_BAD_MESSAGE); @@ -140,7 +140,7 @@ the macro will set s2n_errno correctly, as well as some useful debug strings, an ### Safety checking -[utils/s2n_safety.h](https://github.com/awslabs/s2n/blob/main/utils/s2n_safety.h) provides several more convenience macros intended to make safety and bounds checking easier. There are checked versions of memcpy (`CHECKED_MEMCPY`) and memset (`CHECKED_MEMSET`), as well as predicate testers like `ENSURE`, `ENSURE_GTE`, `ENSURE_INCLUSIVE_RANGE`, `ENSURE_EXCLUSIVE_RANGE` for performing simple comparisons in a systematic, error-handled, way. +[utils/s2n_safety.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_safety.h) provides several more convenience macros intended to make safety and bounds checking easier. There are checked versions of memcpy (`CHECKED_MEMCPY`) and memset (`CHECKED_MEMSET`), as well as predicate testers like `ENSURE`, `ENSURE_GTE`, `ENSURE_INCLUSIVE_RANGE`, `ENSURE_EXCLUSIVE_RANGE` for performing simple comparisons in a systematic, error-handled, way. *Note*: In general, C preprocessor Macros with embedded control flow are a bad idea, but `GUARD`, `ENSURE`, and `BAIL` are so thoroughly used throughout s2n that it should be a clear and idiomatic pattern, almost forming a small domain specific language. @@ -167,7 +167,7 @@ As discussed below, s2n rarely allocates resources, and so has nothing to clean Branches can be a source of cognitive load, as they ask the reader to follow a path of thinking, while also remembering that there is another path to be explored. When branches are nested, they can often lead to impossible to grasp combinatorial explosions. s2n tries to systematically reduce the number of branches used in the code in several ways. -Firstly, there are almost no ifdef calls in s2n. Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/awslabs/s2n/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. +Firstly, there are almost no ifdef calls in s2n. Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. Secondly, s2n generally branches in the case of failure, rather than success. So instead of creating a nest of if's: @@ -217,15 +217,15 @@ There is also a brief set of other coding conventions: s2n is written in C99, a language which lacks a "standard" testing framework. Although there are some more well used C++ testing frameworks, s2n also targets some embedded platforms on which a C++ compiler is unavailable. -Since testing and test-cases are absolutely mandatory for all s2n functionality, s2n includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/awslabs/s2n/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. +Since testing and test-cases are absolutely mandatory for all s2n functionality, s2n includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/aws/s2n-tls/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. -Unit tests are added as .c files in [tests/unit/](https://github.com/awslabs/s2n/blob/main/tests/unit/). A simple example to look at is [tests/unit/s2n_stuffer_base64_test.c](https://github.com/awslabs/s2n/blob/main/tests/unit/s2n_stuffer_base64_test.c). The tests are started with BEGIN_TEST(), and expectations are tested with EXPECT_SUCCESS and EXPECT_EQUAL before exiting with an END_TEST call. +Unit tests are added as .c files in [tests/unit/](https://github.com/aws/s2n-tls/blob/main/tests/unit/). A simple example to look at is [tests/unit/s2n_stuffer_base64_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_stuffer_base64_test.c). The tests are started with BEGIN_TEST(), and expectations are tested with EXPECT_SUCCESS and EXPECT_EQUAL before exiting with an END_TEST call. The test framework will take care of compiling and executing the tests and indicates success or failure with green or red text in the console. In addition to fully covering functionality in the correct cases, s2n tests are also expected to include adversarial or "negative" test cases. For example, the tests performed on record encryption validate that s2n is tamper resistant by attempting to actually tamper with records. Similarly, we validate that our memory handling routines cannot be over-filled by attempting to over-fill them. -To avoid adding unneeded code to the production build of s2n, there is also a small test library defined at [tests/testlib/](https://github.com/awslabs/s2n/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. +To avoid adding unneeded code to the production build of s2n, there is also a small test library defined at [tests/testlib/](https://github.com/aws/s2n-tls/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. Unit tests are run automatically with `make`. To run a subset of the unit tests, set the `UNIT_TESTS` environment variable with the unit test name(s). For example: ``` @@ -247,7 +247,7 @@ struct s2n_blob { }; ``` -Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/awslabs/s2n/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n prevents the memory regions from being swapped to disk and from showing up in core files (where supported). +Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n prevents the memory regions from being swapped to disk and from showing up in core files (where supported). ### s2n_stuffer: a streaming buffer @@ -358,7 +358,7 @@ Every connection is associated with an s2n_connection structure. The details of When a TLS connection is being started, the first communication consists of handshake messages. The client sends the first message (a client hello), and then the server replies (with a server hello), and so on. Because a server must wait for a client and vice versa, this phase of a TLS connection is not full-duplex. To save on memory, s2n uses a single stuffer for both incoming and outgoing handshake messages and it is located as s2n_connection->handshake.io (which is a growable stuffer). -Borrowing another trick from functional programming, the state machine for handling handshake messages is implemented using a table of function pointers, located in [tls/s2n_handshake_io.c](https://github.com/awslabs/s2n/blob/main/tls/s2n_handshake_io.c). +Borrowing another trick from functional programming, the state machine for handling handshake messages is implemented using a table of function pointers, located in [tls/s2n_handshake_io.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_handshake_io.c). ```c static struct s2n_handshake_action state_machine[] = { @@ -386,7 +386,7 @@ One detail we've skipped over so far is that handshake messages are encapsulated ![TLS layers](images/s2n_tls_layers.png "s2n TLS layers") -In the outbound direction, s2n never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/awslabs/s2n/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. +In the outbound direction, s2n never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. To perform all of this, the s2n_connection structure has a few more internal stuffers: diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index 84fb3dfe07f..fea382c9f13 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -4,7 +4,7 @@ s2n is a C library, and is built using Make. To clone the latest copy of s2n from git use: ```shell -git clone https://github.com/awslabs/s2n.git +git clone https://github.com/aws/s2n-tls.git cd s2n ``` @@ -1759,6 +1759,6 @@ function that can free memory. # Examples -To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/awslabs/s2n/blob/main/bin/) directory +To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory includes an example client (s2nc) and server (s2nd). From c93d7f56b3c0e02a8bdcb80755e5ad8e2f287c9b Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Thu, 18 Feb 2021 12:57:42 -0800 Subject: [PATCH 13/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c898aff2c6..b3b0893eee2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ s2n -s2n 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 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. [![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/) [![Apache 2 License](https://img.shields.io/github/license/aws/s2n-ls.svg)](http://aws.amazon.com/apache-2-0/) From dcb1182f0661e94751bc9d736324e24b5f1ebe90 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Thu, 18 Feb 2021 12:57:49 -0800 Subject: [PATCH 14/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 68 ++++++------- docs/BINDINGS.md | 6 +- docs/DEVELOPMENT-GUIDE.md | 120 +++++++++++------------ docs/READING-LIST.md | 2 +- docs/STATE-MACHINE.md | 2 +- docs/USAGE-GUIDE.md | 198 +++++++++++++++++++------------------- 6 files changed, 198 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index b3b0893eee2..258f3ca72f1 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be [![Join the chat at https://gitter.im/aws/s2n-tls](https://badges.gitter.im/aws/s2n-tls.svg)](https://gitter.im/aws/s2n-tls?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ## Quickstart for Ubuntu -1. Fork s2n on GitHub +1. Fork s2n-tls on GitHub 2. Run the following commands on Ubuntu. ``` -git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n.git -cd s2n +git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n-tls.git +cd s2n-tls # Pick an "env" line from the codebuild/codebuild.config file and run it, in this case choose the openssl-1.1.1 with GCC 9 build S2N_LIBCRYPTO=openssl-1.1.1 BUILD_S2N=true TESTS=integration GCC_VERSION=9 @@ -36,27 +36,27 @@ An example of building on OSX: ```sh brew install ninja cmake -git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n.git -mkdir s2n_build -cd s2n_build +git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n-tls.git +mkdir s2n_tls_build +cd s2n_tls_build # Build with debug symbols and a specific OpenSSL version cmake -GNinja \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_PREFIX_PATH=/usr/local/Cellar/openssl@1.1/1.1.1g \ - ../s2n + ../s2n-tls ninja -j6 CTEST_PARALLEL_LEVEL=5 ninja test ``` ## Have a Question? -If you have any questions about Submitting PR's, Opening Issues, s2n API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/aws/s2n-tls +If you have any questions about Submitting PR's, Opening Issues, s2n-tls API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/aws/s2n-tls Otherwise, if you think you might have found a security impacting issue, please instead follow [our Security Notification Process.](#security-issue-notifications) -## Using s2n +## Using s2n-tls -The s2n I/O APIs are designed to be intuitive to developers familiar with the widely-used POSIX I/O APIs, and s2n supports blocking, non-blocking, and full-duplex I/O. Additionally there are no locks or mutexes within s2n. +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. ```c /* Create a server mode connection handle */ @@ -81,71 +81,71 @@ int bytes_written; bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked); ``` -For details on building the s2n library and how to use s2n in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). +For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). -## s2n features +## s2n-tls features -s2n implements SSLv3, TLS1.0, TLS1.1, and TLS1.2. For encryption, s2n supports 128-bit and 256-bit AES, in the CBC and GCM modes, ChaCha20, 3DES, and RC4. For forward secrecy, s2n supports both DHE and ECDHE. s2n also supports the Server Name Indicator (SNI), Application-Layer Protocol Negotiation (ALPN) and the Online Certificate Status Protocol (OCSP) TLS extensions. SSLv3, RC4, 3DES and DHE are each disabled by default for security reasons. +s2n-tls implements SSLv3, TLS1.0, TLS1.1, and TLS1.2. 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 the 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 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. +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. ```c -/* Use the latest s2n "default" set of ciphersuite and protocol preferences */ +/* 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 safety mechanisms +## s2n-tls safety mechanisms -Internally s2n takes a systematic approach to data protection and includes several mechanisms designed to improve safety. +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 is about 6,000 lines of code. s2n's code is also structured and written with a focus on reviewability. All s2n code is subject to code review, and we plan to complete security evaluations of s2n on an annual basis. +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, including one by a commercial security vendor. s2n 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 issue tracker. +To date there have been two external code-level reviews of s2n, 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 is subject to regular static analysis, fuzz-testing, and penetration testing. Several penetration tests have occurred, including two by commercial vendors. +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 includes positive and negative unit tests and end-to-end test cases. +s2n-tls includes positive and negative unit tests and end-to-end test cases. ##### Erase on read -s2n encrypts or erases plaintext data as quickly as possible. For example, decrypted data buffers are erased as they are read by the application. +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 uses operating system features to protect data from being swapped to disk or appearing in core dumps. +s2n-tls uses operating system features to protect data from being swapped to disk or appearing in core dumps. ##### Minimalist feature adoption -s2n 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. +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 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. +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 has been structured so that different encryption libraries may be used. Today s2n supports OpenSSL, LibreSSL, BoringSSL, and the Apple Common Crypto framework to perform the underlying cryptographic operations. +s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports OpenSSL, LibreSSL, BoringSSL, and the Apple Common Crypto framework to perform the underlying cryptographic operations. ##### Timing blinding -s2n includes structured support for blinding time-based side-channels that may leak sensitive data. For example, if s2n fails to parse a TLS record or handshake message, s2n 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. +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 uses simple tables to drive the TLS/SSL state machines, making it difficult for invalid out-of-order states to arise. +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 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. +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 we ask that you notify +If you discover a potential security issue in s2n-tls we ask that you notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. -If you package or distribute s2n, or use s2n as part of a large multi-user service, you may be eligible for pre-notification of future s2n releases. Please contact s2n-pre-notification@amazon.com. +If you package or distribute s2n, 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 +## Contributing to s2n-tls If you are interested in contributing to s2n, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). -## Language Bindings for s2n -See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n that we're aware of. +## Language Bindings for s2n-tls +See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n-tls that we're aware of. diff --git a/docs/BINDINGS.md b/docs/BINDINGS.md index 8455427d434..c8c39089ee5 100644 --- a/docs/BINDINGS.md +++ b/docs/BINDINGS.md @@ -1,8 +1,8 @@ -# Language Bindings for s2n +# Language Bindings for s2n-tls -The following are language bindings to s2n that we're aware of. They are not a part of the s2n project. +The following are language bindings to s2n-tls that we're aware of. They are not a part of the s2n-tls project. -Let us know if you know of a language binding to s2n that's not listed below. +Let us know if you know of a language binding to s2n-tls that's not listed below. ## Lua diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md index 05f8e0ec59a..aa19b2940fd 100644 --- a/docs/DEVELOPMENT-GUIDE.md +++ b/docs/DEVELOPMENT-GUIDE.md @@ -1,25 +1,25 @@ -# Development guide for s2n +c Development guide for s2n-tls -If you are curious about the internals of s2n, or interested in contributing to -s2n, this document is for you. If instead you are interested in using s2n in an application +If you are curious about the internals of s2n-tls, or interested in contributing to +s2n-tls, this document is for you. If instead you are interested in using s2n-tls in an application that you are developing, please see the accompanying [Usage Guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md). -## s2n's development principles +## s2n-tls's development principles -Before getting into the detail of how s2n works internally, it's worth covering -s2n's development principles. These principles guide and inform many of the design +Before getting into the detail of how s2n-tls works internally, it's worth covering +s2n-tls's development principles. These principles guide and inform many of the design decisions we'll go through. We're always open to new principles, if you can think of better ones and make a case for them. #### Development principles * **Maintain an excellent TLS/SSL implementation**
Although it's hidden "*under the hood*", TLS/SSL is the direct interface with customers and end-users. Good performance and security are critical to a positive experience. -* **Protect user data and keys**
Above all else, s2n must ensure that user data and private keys are being handled correctly and carefully. Security is often a matter of trade-offs and costs; we should always strive to increase the costs for attackers whenever the tradeoffs are acceptable to users. +* **Protect user data and keys**
Above all else, s2n-tls must ensure that user data and private keys are being handled correctly and carefully. Security is often a matter of trade-offs and costs; we should always strive to increase the costs for attackers whenever the tradeoffs are acceptable to users. * **Stay simple**
Write as little code as necessary, omit rarely used optional features and support as few modes of operation as possible. We will also promote and encourage changes that reduce the size of our code base. -* **Write clear readable code with a light cognitive load**
s2n's code must be concise, easy to follow and legible to a proficient C programmer. Our code should be organized in a way that divides the implementation up into small units of work, with the entire context necessary at hand. We should also minimize the number of branches in our code, the depth of our call stacks, and the number of members in our structures. +* **Write clear readable code with a light cognitive load**
s2n-tls's code must be concise, easy to follow and legible to a proficient C programmer. Our code should be organized in a way that divides the implementation up into small units of work, with the entire context necessary at hand. We should also minimize the number of branches in our code, the depth of our call stacks, and the number of members in our structures. * **Defend in depth and systematically**
Great care and attention to detail is required to write good code, but we also use automation and mechanistic processes to protect against human error. -* **Be easy to use and maintain sane defaults**
It should be low effort, even for a novice developer, to use s2n in a safe way. We also shouldn't "*pass the buck*" and place the burden of subtle or complicated TLS-specific decision making upon application authors and system administrators. +* **Be easy to use and maintain sane defaults**
It should be low effort, even for a novice developer, to use s2n-tls in a safe way. We also shouldn't "*pass the buck*" and place the burden of subtle or complicated TLS-specific decision making upon application authors and system administrators. * **Provide great performance and responsiveness**
TLS/SSL is rapidly becoming ubiquitous. Even small inefficiencies and overhead can become significant when multiplied by billions of users and quintillions of sessions. -* **Stay paranoid**
s2n operates in a security critical space. Even with the most precautionary development methods it is impossible to guarantee the absence of defects. A subtle one-byte error on a single line may still cause problems. +* **Stay paranoid**
s2n-tls operates in a security critical space. Even with the most precautionary development methods it is impossible to guarantee the absence of defects. A subtle one-byte error on a single line may still cause problems. * **Make data-driven decisions**
Opinions can differ on security best practices, sometimes in contradictory ways. Where possible, we are guided by facts and measurable data. #### Priorities @@ -33,7 +33,7 @@ When weighing up difficult implementation trade-offs our ordered set of prioriti #### Commit and code-review policy -s2n is review-then-commit for code changes, and commit-then-review for +s2n-tls is review-then-commit for code changes, and commit-then-review for documentation changes. Code additions are made by pull requests, no author may merge their own pull request on code. Changes to documentation, including code comments, may be made more freely. @@ -41,19 +41,19 @@ comments, may be made more freely. ## Coding style and conventions Per our development principles, an important goal is to reduce the cognitive load required to -read, review and extend s2n. Although s2n is written in C, s2n adopts several +read, review and extend s2n-tls . Although s2n-tls is written in C, s2n-tls adopts several patterns more common to functional programming. Though they are used in a way that is idiomatic and shouldn't feel completely alien in C. ### High level function design -The first convention is that's s2n's functions are generally quite small, no +The first convention is that's s2n-tls's functions are generally quite small, no more than a page or two at most and commonly just a few lines. Functions have a clear input and output and are in that sense "pure" functions; for example handling a particular TLS handshake message type takes the message as input, and the output is connection state. ```c -/* An idiomatic s2n function generally has: +/* An idiomatic s2n-tls function generally has: * * An s2n_result return value. This is used to signal success or error. * An input, often a struct. @@ -62,16 +62,16 @@ as input, and the output is connection state. S2N_RESULT s2n_do_something(struct *some_input, struct *some_output); ``` -s2n functions also operate in a message passing style. For example, +s2n-tls functions also operate in a message passing style. For example, a simplified version of the flow when handling a TLS client finished message might looks like this: -![s2n message passing](images/s2n_lambda.png "s2n message passing") +![s2n-tls message passing](images/s2n_lambda.png "s2n-tls message passing") each function handles a clear, well-defined piece of work, before passing on responsibility to the next function. -The second convention of s2n's functions is that functions are +The second convention of s2n-tls's functions is that functions are split into two kinds: those that handle control flow and coordinate other functions, and those that parse messages. For example, in the above diagram, it might appear that the functions are calling each other directly @@ -103,9 +103,9 @@ one place. ### Error handling and Macros -As may also be clear from the above examples, s2n has some conventions for how errors are handled. Firstly, s2n functions should always return `S2N_RESULT_ERROR` or `NULL` on error, and `S2N_RESULT_OK` or a valid pointer on success. s2n also includes a thread local variable: s2n_errno, for indicating the cause of the error. This follows the convention set by libc (with errno), getaddrinfo (gai_errno), net-snmp (snmp_errno), and countless other libraries. +As may also be clear from the above examples, s2n-tls has some conventions for how errors are handled. Firstly, s2n-tls functions should always return `S2N_RESULT_ERROR` or `NULL` on error, and `S2N_RESULT_OK` or a valid pointer on success. s2n-tls also includes a thread local variable: s2n_errno, for indicating the cause of the error. This follows the convention set by libc (with errno), getaddrinfo (gai_errno), net-snmp (snmp_errno), and countless other libraries. -In s2n, we **always** check return values. Because of that, the coding pattern: +In s2n-tls, we **always** check return values. Because of that, the coding pattern: ```c if (s2n_result_is_error(s2n_do_something(with_something_else))) { @@ -142,10 +142,10 @@ the macro will set s2n_errno correctly, as well as some useful debug strings, an [utils/s2n_safety.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_safety.h) provides several more convenience macros intended to make safety and bounds checking easier. There are checked versions of memcpy (`CHECKED_MEMCPY`) and memset (`CHECKED_MEMSET`), as well as predicate testers like `ENSURE`, `ENSURE_GTE`, `ENSURE_INCLUSIVE_RANGE`, `ENSURE_EXCLUSIVE_RANGE` for performing simple comparisons in a systematic, error-handled, way. -*Note*: In general, C preprocessor Macros with embedded control flow are a bad idea, but `GUARD`, `ENSURE`, and `BAIL` are so thoroughly used throughout s2n that it should be a clear and idiomatic pattern, almost forming a small domain specific language. +*Note*: In general, C preprocessor Macros with embedded control flow are a bad idea, but `GUARD`, `ENSURE`, and `BAIL` are so thoroughly used throughout s2n-tls that it should be a clear and idiomatic pattern, almost forming a small domain specific language. ### Cleanup on Error -As discussed below, s2n rarely allocates resources, and so has nothing to clean up on error. For cases where functions do allocate resources which must be cleaned up, s2n offers two macros: +As discussed below, s2n-tls rarely allocates resources, and so has nothing to clean up on error. For cases where functions do allocate resources which must be cleaned up, s2n-tls offers two macros: ```c /** @@ -165,11 +165,11 @@ As discussed below, s2n rarely allocates resources, and so has nothing to clean ### Control flow and the state machine -Branches can be a source of cognitive load, as they ask the reader to follow a path of thinking, while also remembering that there is another path to be explored. When branches are nested, they can often lead to impossible to grasp combinatorial explosions. s2n tries to systematically reduce the number of branches used in the code in several ways. +Branches can be a source of cognitive load, as they ask the reader to follow a path of thinking, while also remembering that there is another path to be explored. When branches are nested, they can often lead to impossible to grasp combinatorial explosions. s2n-tls tries to systematically reduce the number of branches used in the code in several ways. -Firstly, there are almost no ifdef calls in s2n. Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. +Firstly, there are almost no ifdef calls in s2n-tls . Ifdefs can be a particularly penalizing source of cognitive load. In addition to being a branch, they also ask the reader to mix state from two different languages (C, and the C preprocessor) and they tend to be associated with ugly rendering in IDEs and code formatters. In the few places where ifdef's are necessary, we use them in a careful way without compromising the integrity of the function. [tls/s2n_config.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_config.c) is a good example. Rather than mixing the Apple and non-Apple implementations and cluttering one function with several ifdefs, there is a complete implementation of the timer functionality for each platform. Within the POSIX implementation, an ifdef and define are used to use the most precise clock type, but in a way that does not compromise readability. -Secondly, s2n generally branches in the case of failure, rather than success. So instead of creating a nest of if's: +Secondly, s2n-tls generally branches in the case of failure, rather than success. So instead of creating a nest of if's: ```c if (s2n_foo() == 0) { @@ -185,29 +185,29 @@ GUARD(s2n_bar()); GUARD(s2n_baz()); ``` -This pattern leads to a linear control flow, where the main body of a function describes everything that happens in a regular, "*happy*" case. Any deviation is usually a fatal error and we exit the function. This is safe because s2n rarely allocates resources, and so has nothing to clean up on error. +This pattern leads to a linear control flow, where the main body of a function describes everything that happens in a regular, "*happy*" case. Any deviation is usually a fatal error and we exit the function. This is safe because s2n-tls rarely allocates resources, and so has nothing to clean up on error. -This pattern also leads to extremely few "else" clauses in the s2n code base. Within s2n, else clauses should be treated with suspicion and examined for potential eradication. Where an else clause is necessary, we try to ensure that the first if block is the most likely case. This aids readability, and also results in a more efficient compiled instruction pipeline (although good CPU branch prediction will rapidly correct any mis-ordering). +This pattern also leads to extremely few "else" clauses in the s2n-tls code base. Within s2n-tls, else clauses should be treated with suspicion and examined for potential eradication. Where an else clause is necessary, we try to ensure that the first if block is the most likely case. This aids readability, and also results in a more efficient compiled instruction pipeline (although good CPU branch prediction will rapidly correct any mis-ordering). -For branches on small enumerated types, s2n generally favors switch statements: though switch statements taking up more than about 25 lines of code are discouraged, and a "default:" block is mandatory. +For branches on small enumerated types, s2n-tls generally favors switch statements: though switch statements taking up more than about 25 lines of code are discouraged, and a "default:" block is mandatory. -Another technique for complexity avoidance is that the core TLS state machine within s2n does not use branches and instead uses a table of function pointers (another technique borrowed from functional programming) to dispatch data to the correct handler. This is covered in more detail later in this document. +Another technique for complexity avoidance is that the core TLS state machine within s2n-tls does not use branches and instead uses a table of function pointers (another technique borrowed from functional programming) to dispatch data to the correct handler. This is covered in more detail later in this document. -Lastly, s2n studiously avoids locks. s2n is designed to be thread-safe, but does so by using atomic data types in the small number of well-isolated variables that may be accessed by multiple threads. +Lastly, s2n-tls studiously avoids locks. s2n-tls is designed to be thread-safe, but does so by using atomic data types in the small number of well-isolated variables that may be accessed by multiple threads. ### Code formatting and commenting -s2n is written in C99. The code formatting and indentation should be relatively clear from reading some s2n source files, but there is also an automated "make indent" target that will indent the s2n sources. +s2n-tls is written in C99. The code formatting and indentation should be relatively clear from reading some s2n-tls source files, but there is also an automated "make indent" target that will indent the s2n-tls sources. -There should be no need for comments to explain *what* s2n code is doing; variables and functions should be given clear and human-readable names that make their purpose and intent intuitive. Comments explaining *why* we are doing something are encouraged. Often some context setting is necessary; a reference to an RFC, or a reminder of some critical state that is hard to work directly into the immediate code in a natural way. All comments should be written using C syntax `/* */` and **avoid** C++ comments `//` even though C99 compilers allow `//`. +There should be no need for comments to explain *what* s2n-tls code is doing; variables and functions should be given clear and human-readable names that make their purpose and intent intuitive. Comments explaining *why* we are doing something are encouraged. Often some context setting is necessary; a reference to an RFC, or a reminder of some critical state that is hard to work directly into the immediate code in a natural way. All comments should be written using C syntax `/* */` and **avoid** C++ comments `//` even though C99 compilers allow `//`. Every source code file must include a copy of the Apache Software License 2.0, as well as a correct copyright notification. The year of copyright should be the year in which the file was first created. There is also a brief set of other coding conventions: -* s2n uses explicitly sized primitives where possible. E.g. uint8_t, uint32_t. -* In general, s2n uses unsigned ints for sizes, as TLS/SSL do the same. -* Any structures exposed to application authors must be opaque: s2n manages the memory allocation and de-allocation. +* s2n-tls uses explicitly sized primitives where possible. E.g. uint8_t, uint32_t. +* In general, s2n-tls uses unsigned ints for sizes, as TLS/SSL do the same. +* Any structures exposed to application authors must be opaque: s2n-tls manages the memory allocation and de-allocation. * Variables are declared closest to their first point of use, to maximize context around the typing. * Duplication of logic is discouraged * 4 spaces, no tabs @@ -215,26 +215,26 @@ There is also a brief set of other coding conventions: ## Tests -s2n is written in C99, a language which lacks a "standard" testing framework. Although there are some more well used C++ testing frameworks, s2n also targets some embedded platforms on which a C++ compiler is unavailable. +s2n-tls is written in C99, a language which lacks a "standard" testing framework. Although there are some more well used C++ testing frameworks, s2n-tls also targets some embedded platforms on which a C++ compiler is unavailable. -Since testing and test-cases are absolutely mandatory for all s2n functionality, s2n includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/aws/s2n-tls/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. +Since testing and test-cases are absolutely mandatory for all s2n-tls functionality, s2n-tls includes its own small testing framework, defined in [tests/s2n_test.h](https://github.com/aws/s2n-tls/blob/main/tests/s2n_test.h). The framework consists of 15 macros that allow you to start a test suite, which is a normal C application with a main() function, and to validate various expectations. Unit tests are added as .c files in [tests/unit/](https://github.com/aws/s2n-tls/blob/main/tests/unit/). A simple example to look at is [tests/unit/s2n_stuffer_base64_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_stuffer_base64_test.c). The tests are started with BEGIN_TEST(), and expectations are tested with EXPECT_SUCCESS and EXPECT_EQUAL before exiting with an END_TEST call. The test framework will take care of compiling and executing the tests and indicates success or failure with green or red text in the console. -In addition to fully covering functionality in the correct cases, s2n tests are also expected to include adversarial or "negative" test cases. For example, the tests performed on record encryption validate that s2n is tamper resistant by attempting to actually tamper with records. Similarly, we validate that our memory handling routines cannot be over-filled by attempting to over-fill them. +In addition to fully covering functionality in the correct cases, s2n-tls tests are also expected to include adversarial or "negative" test cases. For example, the tests performed on record encryption validate that s2n-tls is tamper resistant by attempting to actually tamper with records. Similarly, we validate that our memory handling routines cannot be over-filled by attempting to over-fill them. -To avoid adding unneeded code to the production build of s2n, there is also a small test library defined at [tests/testlib/](https://github.com/aws/s2n-tls/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. +To avoid adding unneeded code to the production build of s2n-tls, there is also a small test library defined at [tests/testlib/](https://github.com/aws/s2n-tls/blob/main/tests/testlib/) which includes routines useful for test cases. For example, there is a hex parser and emitter, which is useful for defining network data in test cases, but not needed in production. Unit tests are run automatically with `make`. To run a subset of the unit tests, set the `UNIT_TESTS` environment variable with the unit test name(s). For example: ``` UNIT_TESTS=s2n_hash_test make ``` -## A tour of s2n memory handling: blobs and stuffers +## A tour of s2n-tls memory handling: blobs and stuffers -C has a history of issues around memory and buffer handling. To avoid problems in this area, s2n does not use C string functions or standard buffer manipulation patterns. Instead memory regions are tracked explicitly, with `s2n_blob` structures, and buffers are re-oriented as streams with `s2n_stuffer` structures. +C has a history of issues around memory and buffer handling. To avoid problems in this area, s2n-tls does not use C string functions or standard buffer manipulation patterns. Instead memory regions are tracked explicitly, with `s2n_blob` structures, and buffers are re-oriented as streams with `s2n_stuffer` structures. ### s2n_blob: keeping track of memory ranges @@ -247,12 +247,12 @@ struct s2n_blob { }; ``` -Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n prevents the memory regions from being swapped to disk and from showing up in core files (where supported). +Functions that handle memory ranges are expected to at least use blobs (stuffers are better though, as we'll see). A blob can be initialized with an existing memory buffer using **s2n_blob_init**, but [utils/s2n_mem.h](https://github.com/aws/s2n-tls/blob/main/utils/s2n_mem.h) also defines routines for dynamically allocated blobs. For handling user data, we prefer the latter, as s2n-tls prevents the memory regions from being swapped to disk and from showing up in core files (where supported). ### s2n_stuffer: a streaming buffer -The stuffer data structure included in s2n is intended to handle all protocol level -input and output to memory buffers and is the real work-horse of s2n. At its core +The stuffer data structure included in s2n-tls is intended to handle all protocol level +input and output to memory buffers and is the real work-horse of s2n-tls . At its core a stuffer is a blob and two cursors: ```c @@ -266,7 +266,7 @@ struct s2n_stuffer { This layout that makes it possible to implement a stream: -![Stuffer layout](images/s2n_stuffer_layout.png "s2n stuffer internal layout") +![Stuffer layout](images/s2n_stuffer_layout.png "s2n-tls stuffer internal layout") All access to/from the stuffer goes "through" s2n_stuffer_ functions. For example, we can write with **s2n_stuffer_write()**, and when we do the write cursor is incremented to the new position. We can read with **s2n_stuffer_read()**, and of course we can only read data as far as the write cursor (which is always at or ahead of the read cursor). To protect user data, when we read data out of the stuffer, we wipe the copy of the data within the local stuffer memory. We also ensure that it's only possible to read as much data as is in the stuffer. @@ -299,7 +299,7 @@ GUARD(s2n_stuffer_read_uint16(in, &record_size)); This pattern should make it very clear what the message format is, where the contents are being stored, and that we're handling things in a safe way. -There are times when we must interact with C functions from other libraries; for example, when handling encryption and decryption. In these cases, it is usually necessary to provide access to "raw" pointers into stuffers. s2n provides two functions for this: +There are times when we must interact with C functions from other libraries; for example, when handling encryption and decryption. In these cases, it is usually necessary to provide access to "raw" pointers into stuffers. s2n-tls provides two functions for this: ```c void *s2n_stuffer_raw_write(struct s2n_stuffer *stuffer, uint32_t data_len); @@ -356,7 +356,7 @@ GUARD(s2n_stuffer_wipe(&in)); Every connection is associated with an s2n_connection structure. The details of this structure are opaque to applications, but internally it is where all of the TLS state is managed. To make sense of what is going on, it is necessary to understand how the TLS protocol works at the record and handshake layers. -When a TLS connection is being started, the first communication consists of handshake messages. The client sends the first message (a client hello), and then the server replies (with a server hello), and so on. Because a server must wait for a client and vice versa, this phase of a TLS connection is not full-duplex. To save on memory, s2n uses a single stuffer for both incoming and outgoing handshake messages and it is located as s2n_connection->handshake.io (which is a growable stuffer). +When a TLS connection is being started, the first communication consists of handshake messages. The client sends the first message (a client hello), and then the server replies (with a server hello), and so on. Because a server must wait for a client and vice versa, this phase of a TLS connection is not full-duplex. To save on memory, s2n-tls uses a single stuffer for both incoming and outgoing handshake messages and it is located as s2n_connection->handshake.io (which is a growable stuffer). Borrowing another trick from functional programming, the state machine for handling handshake messages is implemented using a table of function pointers, located in [tls/s2n_handshake_io.c](https://github.com/aws/s2n-tls/blob/main/tls/s2n_handshake_io.c). @@ -380,13 +380,13 @@ static struct s2n_handshake_action state_machine[] = { }; ``` -The 'writer' field indicates whether we expect a Client or a Server to write a particular message type (or 'B' for both in the case of an application data message, but we haven't gotten to that yet). If s2n is acting as a server, then it attempts to read client messages, if it's acting as a client it will try to write it. To perform either operation it calls the relevant function pointer. This way the state machine can be very short and simple: write a handshake message out when we have one pending, and in the other direction read in data until we have a fully-buffered handshake message before then calling the relevant message parsing function. +The 'writer' field indicates whether we expect a Client or a Server to write a particular message type (or 'B' for both in the case of an application data message, but we haven't gotten to that yet). If s2n-tls is acting as a server, then it attempts to read client messages, if it's acting as a client it will try to write it. To perform either operation it calls the relevant function pointer. This way the state machine can be very short and simple: write a handshake message out when we have one pending, and in the other direction read in data until we have a fully-buffered handshake message before then calling the relevant message parsing function. One detail we've skipped over so far is that handshake messages are encapsulated by an additional record layer within the TLS protocol. As we've already seen, TLS records are fairly simple: just a 5-byte header indicating the message type (Handshake, application data, and alerts), protocol version, and record size. The remainder of the record is data and may or may not be encrypted. What isn't so simple is that TLS allows 'inner' messages, like Handshake message, to be fragmented across several records, and for a single record to contain multiple messages. -![TLS layers](images/s2n_tls_layers.png "s2n TLS layers") +![TLS layers](images/s2n_tls_layers.png "s2n-tls TLS layers") -In the outbound direction, s2n never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. +In the outbound direction, s2n-tls never coalesces multiple messages into a single record, so writing a handshake message is a simple matter of fragmenting the handshake message if necessary and writing the records. In the inbound direction, the small state machine in s2n_handshake_io.c takes care of any fragmentation and coalescing. See [tests/unit/s2n_fragmentation_coalescing_test.c](https://github.com/aws/s2n-tls/blob/main/tests/unit/s2n_fragmentation_coalescing_test.c) for our test cases covering the logic too. To perform all of this, the s2n_connection structure has a few more internal stuffers: @@ -397,9 +397,9 @@ struct s2n_stuffer out; struct s2n_stuffer alert_in; ``` -'header_in' is a small 5-byte stuffer, which is used to read in a record header. Once that stuffer is full, and the size of the next record is determined (from that header), inward data is directed to the 'in' stuffer. The 'out' stuffer is for data that we are writing out; like an encrypted TLS record. 'alert_in' is for any TLS alert message that s2n receives from its peer. s2n treats all alerts as fatal, but we buffer the full alert message so that reason can be logged. +'header_in' is a small 5-byte stuffer, which is used to read in a record header. Once that stuffer is full, and the size of the next record is determined (from that header), inward data is directed to the 'in' stuffer. The 'out' stuffer is for data that we are writing out; like an encrypted TLS record. 'alert_in' is for any TLS alert message that s2n-tls receives from its peer. s2n-tls treats all alerts as fatal, but we buffer the full alert message so that reason can be logged. -When past the handshake phase, s2n supports full-duplex I/O. Separate threads or event handlers are free to call s2n_send and s2n_recv on the same connection. Because either a read or a write may cause a connection to be closed, there are two additional stuffers for storing outbound alert messages: +When past the handshake phase, s2n-tls supports full-duplex I/O. Separate threads or event handlers are free to call s2n_send and s2n_recv on the same connection. Because either a read or a write may cause a connection to be closed, there are two additional stuffers for storing outbound alert messages: ```c struct s2n_stuffer reader_alert_out; @@ -415,19 +415,19 @@ sig_atomic_t closed; 'closing' is an atomic, but even if it were not it can only be changed from 0 to 1, so an over-write is harmless. Every time a TLS record is fully-written, s2n_send() checks to see if closing is set to 1. If it is then the reader or writer alert message will be sent (writer takes priority, if both are present) and the connection will be closed. Once the closed is 1, no more I/O may be sent or received on the connection. -## s2n and entropy +## s2n-tls and entropy -s2n provides two deterministic random number generators to every thread. **s2n_get_public_random_data()** should be used to generate any data that is exposed in a public context including nonces, initialization vectors, and randomized timing values. **s2n_get_private_random_data()** should be used for data which must be kept secret. Additionally s2n over-rides libcrypto's entropy generation with **s2n_get_private_random_data()**. +s2n-tls provides two deterministic random number generators to every thread. **s2n_get_public_random_data()** should be used to generate any data that is exposed in a public context including nonces, initialization vectors, and randomized timing values. **s2n_get_private_random_data()** should be used for data which must be kept secret. Additionally s2n-tls over-rides libcrypto's entropy generation with **s2n_get_private_random_data()**. -## Contributing to s2n +## Contributing to s2n-tls -We are happy to accept contributions to s2n. We suggest the following general procedure: +We are happy to accept contributions to s2n-tls . We suggest the following general procedure: -* Please read all of the documentation available in the s2n "docs/" directory. This development guide along with the usage guide should give a good flavor for what the goals of s2n are and whether they line up with your idea for a contribution +* Please read all of the documentation available in the s2n-tls "docs/" directory. This development guide along with the usage guide should give a good flavor for what the goals of s2n-tls are and whether they line up with your idea for a contribution * If you have an idea for a significant contribution, it is worth first cutting an issue and discussing the change. Get feedback on the API design, or what the feature might require, before writing code. * If you discover a security critical bug, please report it via http://aws.amazon.com/security/vulnerability-reporting/ and **do not** create a public issue. -* Create a git fork of the s2n repository and prepare your changes locally within your fork. -* When you're ready, and when all tests are passing, create a pull request to the master awslabs s2n repository. -* All changes to s2n go through code review and legal review. All submissions and contributions are made under the terms of the Apache Software License 2.0. For larger contributions, we may ask you to sign a contributor license agreement. -* s2n undergoes periodic government and commercial security analyses, including code audits and penetration tests. To participate in these analyses, we may ask you to sign a Non-Disclosure Agreement. +* Create a git fork of the s2n-tls repository and prepare your changes locally within your fork. +* When you're ready, and when all tests are passing, create a pull request to the master awslabs s2n-tls repository. +* All changes to s2n-tls go through code review and legal review. All submissions and contributions are made under the terms of the Apache Software License 2.0. For larger contributions, we may ask you to sign a contributor license agreement. +* s2n-tls undergoes periodic government and commercial security analyses, including code audits and penetration tests. To participate in these analyses, we may ask you to sign a Non-Disclosure Agreement. diff --git a/docs/READING-LIST.md b/docs/READING-LIST.md index 4f714171175..f31e8463071 100644 --- a/docs/READING-LIST.md +++ b/docs/READING-LIST.md @@ -1,4 +1,4 @@ -# Useful Reading list for s2n +# Useful Reading list for s2n-tls ## Books diff --git a/docs/STATE-MACHINE.md b/docs/STATE-MACHINE.md index 1f1df81509f..b0a91ef985f 100644 --- a/docs/STATE-MACHINE.md +++ b/docs/STATE-MACHINE.md @@ -1,4 +1,4 @@ -# s2n state machine graphs +# s2n-tls state machine graphs ## TLS 1.2 State Machine diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index fea382c9f13..fa66ccd7ffe 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -1,16 +1,16 @@ -# Using s2n +# Using s2n-tls -s2n is a C library, and is built using Make. To clone the latest -copy of s2n from git use: +s2n-tls is a C library, and is built using Make. To clone the latest +copy of s2n-tls from git use: ```shell git clone https://github.com/aws/s2n-tls.git -cd s2n +cd s2n-tls ``` -## Building s2n with existing libcrypto +## Building s2n-tls with existing libcrypto ### make Instructions -To build s2n with an existing libcrypto installation, store its root folder in the +To build s2n-tls with an existing libcrypto installation, store its root folder in the `LIBCRYPTO_ROOT` environment variable. ```shell # /usr/local/ssl/lib should contain libcrypto.a @@ -28,7 +28,7 @@ the default installation on your machine will be used. (Optional): Set the CMake variable `BUILD_SHARED_LIBS=ON` to build shared libraries. The default is static. -We recommend an out-of-source build. Suppose you have a directory `s2n` which contains the s2n source code. At the same level +We recommend an out-of-source build. Suppose you have a directory `s2n` which contains the s2n-tls source code. At the same level we can create a directory called `s2n-build` For example, we can build and install shared libs using ninja as our build system, and the system libcrypto implementation. @@ -36,7 +36,7 @@ For example, we can build and install shared libs using ninja as our build syste ````shell mkdir s2n-build cd s2n-build -cmake ../s2n -DBUILD_SHARED_LIBS=ON -GNinja +cmake ../s2n-tls -DBUILD_SHARED_LIBS=ON -GNinja ninja ninja test sudo ninja install @@ -47,7 +47,7 @@ For another example, we can prepare an Xcode project using static libs using a l ````shell mkdir s2n-build cd s2n-build -cmake ../s2n -DCMAKE_INSTALL_PREFIX=$HOME/s2n-user/builds/libcrypto-impl -G "Xcode" +cmake ../s2n-tls -DCMAKE_INSTALL_PREFIX=$HOME/s2n-user/builds/libcrypto-impl -G "Xcode" # now open the project in Xcode and build from there, or use the Xcode CLI ```` @@ -56,14 +56,14 @@ Or, for unix style vanilla builds: ````shell mkdir s2n-build cd s2n-build -cmake ../s2n +cmake ../s2n-build make make test sudo make install ```` -### Consuming s2n via. CMake -s2n ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n in your project is: +### Consuming s2n-tls via. CMake +s2n-tls ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n-tls in your project is: ````shell find_package(s2n) @@ -74,12 +74,12 @@ target_link_libraries(yourExecutableOrLibrary AWS::s2n) ```` And when invoking CMake for your project, do one of two things: - 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n build. + 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n-tls build. 2. If you have globally installed s2n, do nothing, it will automatically be found. -## Building s2n with OpenSSL-1.1.1 +## Building s2n-tls with OpenSSL-1.1.1 -To build s2n with OpenSSL-1.1.1, do the following: +To build s2n-tls with OpenSSL-1.1.1, do the following: ```shell # We keep the build artifacts in the -build directory @@ -100,7 +100,7 @@ cd `tar ztf openssl-1.1.1-latest.tar.gz | head -n1 | cut -f1 -d/` make make install -# Build s2n +# Build s2n-tls cd ../../ make ``` @@ -115,9 +115,9 @@ setarch i386 ./config -fPIC no-shared \ --prefix=`pwd`/../../libcrypto-root/ ``` -## Building s2n with OpenSSL-1.0.2 +## Building s2n-tls with OpenSSL-1.0.2 -To build s2n with OpenSSL-1.0.2, do the following: +To build s2n-tls with OpenSSL-1.0.2, do the following: ```shell # We keep the build artifacts in the -build directory @@ -139,16 +139,16 @@ make depend make make install -# Build s2n +# Build s2n-tls cd ../../ make ``` **Mac Users:** please replace "./config" with "./Configure darwin64-x86_64-cc". -## Building s2n with LibreSSL +## Building s2n-tls with LibreSSL -To build s2n with LibreSSL, do the following: +To build s2n-tls with LibreSSL, do the following: ```shell # We keep the build artifacts in the -build directory @@ -163,17 +163,17 @@ cd libressl-x.y.z ./configure --prefix=`pwd`/../../libcrypto-root/ make CFLAGS=-fPIC install -# Build s2n +# Build s2n-tls cd ../../ make ``` -once built, static and dynamic libraries for s2n will be available in the lib/ +once built, static and dynamic libraries for s2n-tls will be available in the lib/ directory. -## Building s2n with BoringSSL +## Building s2n-tls with BoringSSL -To build s2n with BoringSSL, you must check out a copy of the BoringSSL +To build s2n-tls with BoringSSL, you must check out a copy of the BoringSSL directly via git. This procedure has been tested with fb68d6c901b98ffe15b8890d00bc819bf44c5f01 of BoringSSL. @@ -196,18 +196,18 @@ mkdir ../../../libcrypto-root/lib/ cp crypto/libcrypto.a ../../../libcrypto-root/lib/ cp -r ../include/ ../../../libcrypto-root/include -# Build s2n +# Build s2n-tls cd ../../../ make ``` -once built, static and dynamic libraries for s2n will be available in the lib/ +once built, static and dynamic libraries for s2n-tls will be available in the lib/ directory. ## mlock() and system limits -Internally s2n uses mlock() to prevent memory from being swapped to disk. The -s2n build tests may fail in some environments where the default limit on locked +Internally s2n-tls uses mlock() to prevent memory from being swapped to disk. The +s2n-tls build tests may fail in some environments where the default limit on locked memory is too low. To check this limit, run: ```shell @@ -217,23 +217,23 @@ ulimit -l to raise the limit, consult the documentation for your platform. ### Disabling mlock() -To disable s2n's mlock behavior, run your application with the `S2N_DONT_MLOCK` environment variable set. -s2n also reads this for unit tests. Try `S2N_DONT_MLOCK=1 make` if you're having mlock failures during unit tests. +To disable s2n-tls's mlock behavior, run your application with the `S2N_DONT_MLOCK` environment variable set. +s2n-tls also reads this for unit tests. Try `S2N_DONT_MLOCK=1 make` if you're having mlock failures during unit tests. -# s2n API +# s2n-tls API -The API exposed by s2n is the set of functions and declarations that +The API exposed by s2n-tls is the set of functions and declarations that are in the "s2n.h" header file. Any functions and declarations that are in the "s2n.h" file -are intended to be stable (API and ABI) within major version numbers of s2n releases. Other functions -and structures used in s2n internally can not be considered stable and their parameters, names, and +are intended to be stable (API and ABI) within major version numbers of s2n-tls releases. Other functions +and structures used in s2n-tls internally can not be considered stable and their parameters, names, and sizes may change. -At this time (Summer 2015), there has been no numbered release of s2n and all APIs are subject to change based +At this time (Summer 2015), there has been no numbered release of s2n-tls and all APIs are subject to change based on the feedback and preferences of early adopters. ## Preprocessor macros -s2n defines five preprocessor macros that are used to determine what +s2n-tls defines five preprocessor macros that are used to determine what version of SSL/TLS is in use on a connection. ```c @@ -245,12 +245,12 @@ version of SSL/TLS is in use on a connection. ``` These correspond to SSL2.0, SSL3.0, TLS1.0, TLS1.1 and TLS1.2 respectively. -Note that s2n does not support SSL2.0 for sending and receiving encrypted data, +Note that s2n-tls does not support SSL2.0 for sending and receiving encrypted data, but does accept SSL2.0 hello messages. ## Enums -s2n defines the following enum types: +s2n-tls defines the following enum types: ### s2n_error_type @@ -267,7 +267,7 @@ typedef enum { } s2n_error_type; ``` -***s2n_error_type*** is used to help applications determine why an s2n function failed. +***s2n_error_type*** is used to help applications determine why an s2n-tls function failed. This enum is optimized for use in C switch statements. Each value in the enum represents an error "category". See [Error Handling](#error-handling) for more detail. @@ -286,8 +286,8 @@ typedef enum { S2N_NOT_BLOCKED, S2N_BLOCKED_ON_READ, S2N_BLOCKED_ON_WRITE } s2n_ ``` **s2n_blocked_status** is used in non-blocking mode to indicate in which -direction s2n became blocked on I/O before it returned control to the caller. -This allows an application to avoid retrying s2n operations until I/O is +direction s2n-tls became blocked on I/O before it returned control to the caller. +This allows an application to avoid retrying s2n-tls operations until I/O is possible in that direction. ### s2n_blinding @@ -296,9 +296,9 @@ possible in that direction. typedef enum { S2N_BUILT_IN_BLINDING, S2N_SELF_SERVICE_BLINDING } s2n_blinding; ``` -**s2n_blinding** is used to opt-out of s2n's built-in blinding. Blinding is a +**s2n_blinding** is used to opt-out of s2n-tls's built-in blinding. Blinding is a mitigation against timing side-channels which in some cases can leak information -about encrypted data. By default s2n will cause a thread to sleep between 10 and +about encrypted data. By default s2n-tls will cause a thread to sleep between 10 and 30 seconds whenever tampering is detected. Setting the **S2N_SELF_SERVICE_BLINDING** option with **s2n_connection_set_blinding** @@ -324,13 +324,13 @@ supported status request type is OCSP, **S2N_STATUS_REQUEST_OCSP**. typedef enum { S2N_CERT_AUTH_NONE, S2N_CERT_AUTH_REQUIRED, S2N_CERT_AUTH_OPTIONAL } s2n_cert_auth_type; ``` **s2n_cert_auth_type** is used to declare what type of client certificiate authentication to use. -Currently the default for s2n is for neither the server side or the client side to use Client (aka Mutual) authentication. +Currently the default for s2n-tls is for neither the server side or the client side to use Client (aka Mutual) authentication. ## Opaque structures -s2n defines several opaque structures that are used for managed objects. Because +s2n-tls defines several opaque structures that are used for managed objects. Because these structures are opaque, they can only be safely referenced indirectly through -pointers and their sizes may change with future versions of s2n. +pointers and their sizes may change with future versions of s2n-tls. ```c struct s2n_config; @@ -347,7 +347,7 @@ struct s2n_rsa_public_key; struct s2n_cert_public_key; ``` -**s2n_rsa_public_key** and **s2n_cert_public_key** can be used by consumers of s2n to get and set public keys through other API calls. +**s2n_rsa_public_key** and **s2n_cert_public_key** can be used by consumers of s2n-tls to get and set public keys through other API calls. ## Error handling @@ -358,14 +358,14 @@ const char *s2n_strerror_debug(int error, const char *lang); const char *s2n_strerror_name(int error); ```` -s2n functions that return 'int' return 0 to indicate success and -1 to indicate -failure. s2n functions that return pointer types return NULL in the case of -failure. When an s2n function returns a failure, s2n_errno will be set to a value +s2n-tls functions that return 'int' return 0 to indicate success and -1 to indicate +failure. s2n-tls functions that return pointer types return NULL in the case of +failure. When an s2n-tls function returns a failure, s2n_errno will be set to a value corresponding to the error. This error value can be translated into a string explaining the error in English by calling s2n_strerror(s2n_errno, "EN"). A string containing human readable error name, can be generated with `s2n_strerror_name`. A string containing internal debug information, including filename and line number, can be generated with `s2n_strerror_debug`. -This string is useful to include when reporting issues to the s2n development team. +This string is useful to include when reporting issues to the s2n-tls development team. Example: @@ -378,11 +378,11 @@ if (s2n_config_set_cipher_preferences(config, prefs) < 0) { **NOTE**: To avoid possible confusion, s2n_errno should be cleared after processing an error: `s2n_errno = S2N_ERR_T_OK` -When using s2n outside of `C`, the address of the thread-local `s2n_errno` may be obtained by calling the `int *s2n_errno_location()` function. -This will ensure that the same TLS mechanisms are used with which s2n was compiled. +When using s2n-tls outside of `C`, the address of the thread-local `s2n_errno` may be obtained by calling the `int *s2n_errno_location()` function. +This will ensure that the same TLS mechanisms are used with which s2n-tls was compiled. ### Stacktraces -s2n has an mechanism to capture stacktraces when errors occur. +s2n-tls has an mechanism to capture stacktraces when errors occur. This mechanism is off by default, but can be enabled in code by calling `s2n_stack_traces_enabled_set()`. It can be enabled globally by setting the environment variable `S2N_PRINT_STACKTRACE=1`. Note that enabling stacktraces this can significantly slow down unit tests, and can cause failures on unit-tests (such as `s2n_cbc_verify`) that measure the timing of events. @@ -399,7 +399,7 @@ int s2n_get_stacktrace(char*** trace, int* trace_size); ### Error categories -s2n organizes errors into different "types" to allow applications to do logic on error values without catching all possibilities. +s2n-tls organizes errors into different "types" to allow applications to do logic on error values without catching all possibilities. Applications using non-blocking I/O should check error type to determine if the I/O operation failed because it would block or for some other error. To retrieve the type for a given error use `s2n_error_get_type()`. Applications should perform any error handling logic using these high level types: @@ -410,7 +410,7 @@ S2N_ERR_T_CLOSED, /* EOF */ S2N_ERR_T_BLOCKED, /* Underlying I/O operation would block */ S2N_ERR_T_ALERT, /* Incoming Alert */ S2N_ERR_T_PROTO, /* Failure in some part of the TLS protocol. Ex: CBC verification failure */ -S2N_ERR_T_INTERNAL, /* Error internal to s2n. A precondition could have failed. */ +S2N_ERR_T_INTERNAL, /* Error internal to s2n-tls. A precondition could have failed. */ S2N_ERR_T_USAGE /* User input error. Ex: Providing an invalid cipher preference version */ ``` @@ -451,8 +451,8 @@ if (s2n_recv(conn, &blocked) < 0) { unsigned long s2n_get_openssl_version(); ``` -**s2n_get_openssl_version** returns the version number of OpenSSL that s2n was compiled with. It can be used by -applications to validate at runtime that the versions of s2n and Openssl that they have loaded are correct. +**s2n_get_openssl_version** returns the version number of OpenSSL that s2n-tls was compiled with. It can be used by +applications to validate at runtime that the versions of s2n-tls and Openssl that they have loaded are correct. ### s2n\_init @@ -461,9 +461,9 @@ applications to validate at runtime that the versions of s2n and Openssl that th int s2n_init(); ``` -**s2n_init** initializes the s2n library and should be called once in your application, -before any other s2n functions are called. Failure to call s2n_init() will result -in errors from other s2n functions. +**s2n_init** initializes the s2n-tls library and should be called once in your application, +before any other s2n-tls functions are called. Failure to call s2n_init() will result +in errors from other s2n-tls functions. ### s2n\_cleanup @@ -471,9 +471,9 @@ in errors from other s2n functions. int s2n_cleanup(); ``` -**s2n_cleanup** cleans up any internal resources used by s2n. This function should be +**s2n_cleanup** cleans up any internal resources used by s2n-tls. This function should be called from each thread or process that is created subsequent to calling **s2n_init** -when that thread or process is done calling other s2n functions. +when that thread or process is done calling other s2n-tls functions. ## Configuration-oriented functions @@ -529,15 +529,15 @@ The following chart maps the security policy version to protocol version and cip | "20190802" | | X | X | X | X | X | X | | X | | | | X | | "20200207" | | X | X | X | X | X | X | | X | | | | | -The "default" and "default_tls13" version is special in that it will be updated with future s2n changes and ciphersuites and protocol versions may be added and removed, or their internal order of preference might change. Numbered versions are fixed and will never change. +The "default" and "default_tls13" version is special in that it will be updated with future s2n-tls changes and ciphersuites and protocol versions may be added and removed, or their internal order of preference might change. Numbered versions are fixed and will never change. -"20160411" follows the same general preference order as "default". The main difference is it has a CBC cipher suite at the top. This is to accommodate certain Java clients that have poor GCM implementations. Users of s2n who have found GCM to be hurting performance for their clients should consider this version. +"20160411" follows the same general preference order as "default". The main difference is it has a CBC cipher suite at the top. This is to accommodate certain Java clients that have poor GCM implementations. Users of s2n-tls who have found GCM to be hurting performance for their clients should consider this version. -"20170405" is a FIPS compliant cipher suite preference list based on approved algorithms in the [FIPS 140-2 Annex A](http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf). Similarly to "20160411", this preference list has CBC cipher suites at the top to accommodate certain Java clients. Users of s2n who plan to enable FIPS mode should consider this version. +"20170405" is a FIPS compliant cipher suite preference list based on approved algorithms in the [FIPS 140-2 Annex A](http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf). Similarly to "20160411", this preference list has CBC cipher suites at the top to accommodate certain Java clients. Users of s2n-tls who plan to enable FIPS mode should consider this version. -s2n does not expose an API to control the order of preference for each ciphersuite or protocol version. s2n follows the following order: +s2n-tls does not expose an API to control the order of preference for each ciphersuite or protocol version. s2n-tls follows the following order: -*NOTE*: All ChaCha20-Poly1305 cipher suites will not be available if s2n is not built with an Openssl 1.1.1 libcrypto. The +*NOTE*: All ChaCha20-Poly1305 cipher suites will not be available if s2n-tls is not built with an Openssl 1.1.1 libcrypto. The underlying encrypt/decrypt functions are not available in older versions. 1. Always prefer the highest protocol version supported @@ -637,14 +637,14 @@ int s2n_config_set_cert_chain_and_key_defaults(struct s2n_config *config, **s2n_config_set_cert_chain_and_key_defaults** explicitly sets certificate chain and private key pairs to be used as defaults for each auth method (key type). A "default" certificate is used when there is not an SNI match with any other configured certificate. Only one certificate can be set as the default per auth method (one RSA default, one ECDSA default, etc.). All previous default certificates will be cleared and re-set when this API is called. This API is called for a specific **s2n_config** object. -S2N will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n will clear defaults and no longer attempt to automatically choose any default certificates. +S2N will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates. ### s2n\_cert\_tiebreak\_callback ```c typedef struct s2n_cert_chain_and_key* (*s2n_cert_tiebreak_callback) (struct s2n_cert_chain_and_key *cert1, struct s2n_cert_chain_and_key *cert2, uint8_t *name, uint32_t name_len); ``` -**s2n_cert_tiebreak_callback** is invoked if s2n cannot resolve a conflict between two certificates with the same domain name. This function is invoked while certificates are added to an **s2n_config**. +**s2n_cert_tiebreak_callback** is invoked if s2n-tls cannot resolve a conflict between two certificates with the same domain name. This function is invoked while certificates are added to an **s2n_config**. Currently, the only builtin resolution for domain name conflicts is certificate type(RSA, ECDSA, etc). The callback should return a pointer to the **s2n_cert_chain_and_key** that should be used for dns name **name**. If NULL is returned, the first certificate will be used. Typically an application will use properties like trust and expiry to implement tiebreaking. @@ -843,14 +843,14 @@ that will be called after ClientHello was parsed. typedef int s2n_client_hello_fn(struct s2n_connection *conn, void *ctx); ``` -The callback function take as an input s2n connection, which received +The callback function take as an input s2n-tls connection, which received ClientHello and context provided in **s2n_config_set_client_hello_cb**. The callback can get any ClientHello information from the connection and use **s2n_connection_set_config** call to change the config of the connection. If any of the properties of the connection were changed based on server_name extension the callback must return 1, otherwise the callback can return 0 -to continue handshake in s2n or it can return negative value to make s2n +to continue handshake in s2n-tls or it can return negative value to make s2n-tls terminate handshake early with fatal handshake failure alert. ### s2n\_config\_set\_alert\_behavior @@ -858,8 +858,8 @@ terminate handshake early with fatal handshake failure alert. int s2n_config_set_alert_behavior(struct s2n_config *config, s2n_alert_behavior alert_behavior); ``` Sets whether or not a connection should terminate on receiving a WARNING alert from its peer. `alert_behavior` can take the following values: -- `S2N_ALERT_FAIL_ON_WARNINGS` - default behavior: s2n will terminate the connection if its peer sends a WARNING alert. -- `S2N_ALERT_IGNORE_WARNINGS` - with the exception of `close_notify` s2n will ignore all WARNING alerts and keep communicating with its peer. +- `S2N_ALERT_FAIL_ON_WARNINGS` - default behavior: s2n-tls will terminate the connection if its peer sends a WARNING alert. +- `S2N_ALERT_IGNORE_WARNINGS` - with the exception of `close_notify` s2n-tls will ignore all WARNING alerts and keep communicating with its peer. This setting is ignored in TLS1.3. TLS1.3 terminates a connection for all alerts except user_canceled. @@ -923,7 +923,7 @@ Client Auth Related API's are not recommended for normal users. Use of these API 1. Using these API's requires users to: Complete full x509 parsing and hostname validation in the application layer 2. Application knowledge of TLS code points for certificate types -3. Application dependency on libcrypto to give a libcrypto RSA struct back to s2n +3. Application dependency on libcrypto to give a libcrypto RSA struct back to s2n-tls ### s2n\_config\_set\_client\_auth\_type and s2n\_connection\_set\_client\_auth\_type ```c @@ -946,7 +946,7 @@ set the public keys found in the Certificate into **public_key_out**. ## Session Caching related calls -s2n includes support for resuming from cached SSL/TLS session, provided +s2n-tls includes support for resuming from cached SSL/TLS session, provided the caller sets (and implements) three callback functions. ### s2n\_config\_set\_cache\_store\_callback @@ -1008,7 +1008,7 @@ int s2n_config_send_max_fragment_length(struct s2n_config *config, uint8_t mfl_c **s2n_config_send_max_fragment_length** allows the caller to set a TLS Maximum Fragment Length extension that will be used to fragment outgoing messages. -s2n currently does not reject fragments larger than the configured maximum when +s2n-tls currently does not reject fragments larger than the configured maximum when in server mode. The TLS negotiated maximum fragment length overrides the preference set by the **s2n_connection_prefer_throughput** and **s2n_connection_prefer_low_latency**. @@ -1030,7 +1030,7 @@ request and continue TLS handshake with default maximum fragment length of 8k by struct s2n_connection * s2n_connection_new(s2n_mode mode); ``` -**s2n_connection_new** creates a new connection object. Each s2n SSL/TLS +**s2n_connection_new** creates a new connection object. Each s2n-tls SSL/TLS connection uses one of these objects. These connection objects can be operated on by up to two threads at a time, one sender and one receiver, but neither sending nor receiving are atomic, so if these objects are being called by @@ -1081,8 +1081,8 @@ int s2n_connection_set_write_fd(struct s2n_connection *conn, int writefd); ``` -**s2n_connection_set_fd** sets the file-descriptor for an s2n connection. This -file-descriptor should be active and connected. s2n also supports setting the +**s2n_connection_set_fd** sets the file-descriptor for an s2n-tls connection. This +file-descriptor should be active and connected. s2n-tls also supports setting the read and write file-descriptors to different values (for pipes or other unusual types of I/O). @@ -1147,7 +1147,7 @@ name the client is using. int s2n_connection_set_blinding(struct s2n_connection *conn, s2n_blinding blinding); ``` -**s2n_connection_set_blinding** can be used to configure s2n to either use +**s2n_connection_set_blinding** can be used to configure s2n-tls to either use built-in blinding (set blinding to S2N_BUILT_IN_BLINDING) or self-service blinding (set blinding to S2N_SELF_SERVICE_BLINDING). @@ -1169,7 +1169,7 @@ int s2n_connection_set_dynamic_record_threshold(struct s2n_connection *conn, uin ``` **s2n_connection_prefer_throughput** and **s2n_connection_prefer_low_latency** -change the behavior of s2n when sending data to prefer either throughput +change the behavior of s2n-tls when sending data to prefer either throughput or low latency. Connections prefering low latency will be encrypted using small record sizes that can be decrypted sooner by the recipient. Connections prefering throughput will use large record sizes that minimize overhead. @@ -1189,7 +1189,7 @@ uint64_t s2n_connection_get_wire_bytes_out(struct s2n_connection *conn); ``` **s2n_connection_get_wire_bytes_in** and **s2n_connection_get_wire_bytes_out** -return the number of bytes transmitted by s2n "on the wire", in and out +return the number of bytes transmitted by s2n-tls "on the wire", in and out respectively. ### s2n\_connection\_get\_protocol\_version @@ -1205,7 +1205,7 @@ int s2n_connection_get_actual_protocol_version(struct s2n_connection *conn); number supported by the client, **s2n_connection_get_server_protocol_version** returns the protocol version number supported by the server and **s2n_connection_get_actual_protocol_version** returns the protocol version -number actually used by s2n for the connection. **s2n_connection_get_client_hello_version** +number actually used by s2n-tls for the connection. **s2n_connection_get_client_hello_version** returns the protocol version used to send the initial client hello message. Each version number value corresponds to the macros defined as **S2N_SSLv2**, @@ -1351,7 +1351,7 @@ int s2n_connection_get_alert(struct s2n_connection *conn); ``` If a connection was shut down by the peer, **s2n_connection_get_alert** returns -the TLS alert code that caused a connection to be shut down. s2n considers all +the TLS alert code that caused a connection to be shut down. s2n-tls considers all TLS alerts fatal and shuts down a connection whenever one is received. ### s2n\_connection\_get\_cipher @@ -1361,7 +1361,7 @@ const char * s2n_connection_get_cipher(struct s2n_connection *conn); ``` **s2n_connection_get_cipher** returns a string indicating the cipher suite -negotiated by s2n for a connection in Openssl format, e.g. "ECDHE-RSA-AES128-GCM-SHA256". +negotiated by s2n-tls for a connection in Openssl format, e.g. "ECDHE-RSA-AES128-GCM-SHA256". ### s2n\_connection\_get\_curve @@ -1382,7 +1382,7 @@ Return the certificate that was used during the TLS handshake. - If **conn** is a server connection, the certificate selected will depend on the ServerName sent by the client and supported ciphers. - If **conn** is a client connection, the certificate sent in response to a CertificateRequest - message is returned. Currently s2n supports loading only one certificate in client mode. Note that + message is returned. Currently s2n-tls supports loading only one certificate in client mode. Note that not all TLS endpoints will request a certificate. This function returns NULL if the certificate selection phase of the handshake has not completed @@ -1451,7 +1451,7 @@ this will allow for gradual and linear transition of a key from encrypt-decrypt ### Asynchronous private key operations related calls -When s2n is used in non-blocking mode, this set of functions allows user +When s2n-tls is used in non-blocking mode, this set of functions allows user to move execution of CPU-heavy private key operations out of the main event loop, preventing **s2n_negotiate** blocking the loop for a few milliseconds each time the private key operation needs to be performed. @@ -1566,15 +1566,15 @@ of sensitive data. ## I/O functions -s2n supports both blocking and non-blocking I/O. To use s2n in non-blocking +s2n-tls supports both blocking and non-blocking I/O. To use s2n-tls in non-blocking mode, set the underlying file descriptors as non-blocking (i.e. with -**fcntl**). In blocking mode, each s2n I/O function will not return until it is -complete. In non-blocking mode an s2n I/O function may return while there is +**fcntl**). In blocking mode, each s2n-tls I/O function will not return until it is +complete. In non-blocking mode an s2n-tls I/O function may return while there is still I/O pending. In this case the value of the **blocked** parameter will be set to either **S2N_BLOCKED_ON_READ** or **S2N_BLOCKED_ON_WRITE**, depending on the -direction in which s2n is blocked. +direction in which s2n-tls is blocked. -s2n I/O functions should be called repeatedly until the **blocked** parameter is +s2n-tls I/O functions should be called repeatedly until the **blocked** parameter is **S2N_NOT_BLOCKED**. ### s2n\_negotiate @@ -1698,7 +1698,7 @@ int s2n_connection_set_recv_ctx(struct s2n_connection *conn, void *ctx); int s2n_connection_set_send_ctx(struct s2n_connection *conn, void *ctx); ``` -s2n also provides an I/O abstraction layer in the event the application would +s2n-tls also provides an I/O abstraction layer in the event the application would like to keep control over I/O operations. **s2n_connection_set_recv_cb** and **s2n_connection_set_send_cb** may be used to send or receive data with callbacks defined by the user. These may be blocking or nonblocking. @@ -1745,20 +1745,20 @@ extern int s2n_mem_set_callbacks(s2n_mem_init_callback mem_init_callback, s2n_me ``` -**s2n_mem_set_callbacks** allows the caller to over-ride s2n's internal memory +**s2n_mem_set_callbacks** allows the caller to over-ride s2n-tls's internal memory handling functions. To work correctly, **s2n_mem_set_callbacks** must be called before **s2n_init**. **s2n_mem_init_callback** should be a function that will -be called when s2n is initialized. **s2n_mem_cleanup_callback** will be called +be called when s2n-tls is initialized. **s2n_mem_cleanup_callback** will be called when **s2n_cleanup** is executed. **s2n_mem_malloc_callback** should be a function that can allocate at least **requested** bytes of memory and store the location of that memory in **\*ptr**, and the size of the allocated data in **\*allocated**. The function may choose to allocate more memory than was requested. -s2n will consider all allocated memory available for use, and will attempt to +s2n-tls will consider all allocated memory available for use, and will attempt to free all allocated memory when able. **s2n_mem_free_callback** should be a function that can free memory. # Examples -To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory +To understand the API it may be easiest to see examples in action. s2n-tls's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory includes an example client (s2nc) and server (s2nd). From 863be9b2462988025ff2177869fb9e1a02ca0e2f Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Fri, 19 Feb 2021 11:05:54 -0800 Subject: [PATCH 15/23] Update docs/DEVELOPMENT-GUIDE.md Co-authored-by: Tejeswini Sundaram <40477596+ttjsu-aws@users.noreply.github.com> --- docs/DEVELOPMENT-GUIDE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md index aa19b2940fd..0d3a0014c46 100644 --- a/docs/DEVELOPMENT-GUIDE.md +++ b/docs/DEVELOPMENT-GUIDE.md @@ -1,4 +1,4 @@ -c Development guide for s2n-tls +# Development guide for s2n-tls If you are curious about the internals of s2n-tls, or interested in contributing to s2n-tls, this document is for you. If instead you are interested in using s2n-tls in an application @@ -430,4 +430,3 @@ We are happy to accept contributions to s2n-tls . We suggest the following gener * When you're ready, and when all tests are passing, create a pull request to the master awslabs s2n-tls repository. * All changes to s2n-tls go through code review and legal review. All submissions and contributions are made under the terms of the Apache Software License 2.0. For larger contributions, we may ask you to sign a contributor license agreement. * s2n-tls undergoes periodic government and commercial security analyses, including code audits and penetration tests. To participate in these analyses, we may ask you to sign a Non-Disclosure Agreement. - From 98d8386b51cd62be19d56ed20c29207c86757618 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Fri, 19 Feb 2021 11:26:46 -0800 Subject: [PATCH 16/23] Update README.md Co-authored-by: Tejeswini Sundaram <40477596+ttjsu-aws@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 258f3ca72f1..cf9190e8e27 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 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. [![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/) -[![Apache 2 License](https://img.shields.io/github/license/aws/s2n-ls.svg)](http://aws.amazon.com/apache-2-0/) +[![Apache 2 License](https://img.shields.io/github/license/aws/s2n-tls.svg)](http://aws.amazon.com/apache-2-0/) [![C99](https://img.shields.io/badge/language-C99-blue.svg)](http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf) [![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/aws/s2n-tls.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/aws/s2n-tls/context:cpp) [![codecov](https://codecov.io/gh/aws/s2n-tls/branch/main/graph/badge.svg)](https://codecov.io/gh/aws/s2n-tls) From 3c77b19e3a1beec97f1bba2302329dad62957649 Mon Sep 17 00:00:00 2001 From: Doug Chapman Date: Fri, 19 Feb 2021 11:31:01 -0800 Subject: [PATCH 17/23] Update USEAGE-GUIDE --- docs/USAGE-GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index fa66ccd7ffe..fbeb24149df 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -66,11 +66,11 @@ sudo make install s2n-tls ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n-tls in your project is: ````shell -find_package(s2n) +find_package(s2n-tls) .... -target_link_libraries(yourExecutableOrLibrary AWS::s2n) +target_link_libraries(yourExecutableOrLibrary AWS::s2n-tls) ```` And when invoking CMake for your project, do one of two things: From 103717729cc72e0a5023fc4d76772ed9b5937180 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:22:35 -0800 Subject: [PATCH 18/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cf9190e8e27..07cc1ad4060 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ Internally s2n-tls takes a systematic approach to data protection and includes s ##### 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, 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. +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 From fffd5566f11b1f606273461c64a82590db8418fc Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:22:48 -0800 Subject: [PATCH 19/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 07cc1ad4060..ed077543b20 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ AWS Security via our [vulnerability reporting page](http://aws.amazon.com/securi If you package or distribute s2n, 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, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). +If you are interested in contributing to s2n-tls, please see our [development guide](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). ## Language Bindings for s2n-tls See our [language bindings list](https://github.com/aws/s2n-tls/blob/main/docs/BINDINGS.md) for language bindings for s2n-tls that we're aware of. From c38cfd34b1109f054cd422984b658dfa8172f6b8 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:22:57 -0800 Subject: [PATCH 20/23] Update README.md Co-authored-by: Cameron Bytheway --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ed077543b20..e2e1dfbebfd 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ s2n-tls is written in C, but makes light use of standard C library functions and If you discover a potential security issue in s2n-tls we ask that you notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. -If you package or distribute s2n, 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. +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](https://github.com/aws/s2n-tls/blob/main/docs/DEVELOPMENT-GUIDE.md). From 0f349de7759f3eb47f93c49766a396638ebc6550 Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:23:28 -0800 Subject: [PATCH 21/23] Update docs/USAGE-GUIDE.md Co-authored-by: Cameron Bytheway --- docs/USAGE-GUIDE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index fbeb24149df..4e83b118ce6 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -75,7 +75,7 @@ target_link_libraries(yourExecutableOrLibrary AWS::s2n-tls) And when invoking CMake for your project, do one of two things: 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n-tls build. - 2. If you have globally installed s2n, do nothing, it will automatically be found. + 2. If you have globally installed s2n-tls, do nothing, it will automatically be found. ## Building s2n-tls with OpenSSL-1.1.1 @@ -1761,4 +1761,3 @@ function that can free memory. To understand the API it may be easiest to see examples in action. s2n-tls's [bin/](https://github.com/aws/s2n-tls/blob/main/bin/) directory includes an example client (s2nc) and server (s2nd). - From 84a47e8f9b3ba8035a0548771de0af8ce11ebdbe Mon Sep 17 00:00:00 2001 From: DougCh <54039637+dougch@users.noreply.github.com> Date: Wed, 24 Feb 2021 12:23:40 -0800 Subject: [PATCH 22/23] Update docs/USAGE-GUIDE.md Co-authored-by: Cameron Bytheway --- docs/USAGE-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index 4e83b118ce6..47dc7cf6e0e 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -637,7 +637,7 @@ int s2n_config_set_cert_chain_and_key_defaults(struct s2n_config *config, **s2n_config_set_cert_chain_and_key_defaults** explicitly sets certificate chain and private key pairs to be used as defaults for each auth method (key type). A "default" certificate is used when there is not an SNI match with any other configured certificate. Only one certificate can be set as the default per auth method (one RSA default, one ECDSA default, etc.). All previous default certificates will be cleared and re-set when this API is called. This API is called for a specific **s2n_config** object. -S2N will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates. +s2n-tls will attempt to automatically choose default certificates for each auth method (key type) based on the order that **s2n_cert_chain_and_key** are added to the **s2n_config** using one of the APIs listed above. **s2n_config_set_cert_chain_and_key_defaults** can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates. ### s2n\_cert\_tiebreak\_callback ```c From 44380a6da575edf743fbda80ae0bc55f6da38fea Mon Sep 17 00:00:00 2001 From: Doug Chapman Date: Tue, 2 Mar 2021 17:16:45 -0800 Subject: [PATCH 23/23] doc: S2N renamed --- docs/USAGE-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md index 47dc7cf6e0e..d126cc01e0b 100644 --- a/docs/USAGE-GUIDE.md +++ b/docs/USAGE-GUIDE.md @@ -1685,7 +1685,7 @@ do { uint32_t s2n_peek(struct s2n_connection *conn); ``` -**s2n_peek** allows users of S2N to peek inside the data buffer of an S2N connection to see if there more data to be read without actually reading it. This is useful when using select() on the underlying S2N file descriptor with a message based application layer protocol. As a single call to s2n_recv may read all data off the underlying file descriptor, select() will be unable to tell you there if there is more application data ready for processing already loaded into the S2N buffer. s2n_peek can then be used to determine if s2n_recv needs to be called before more data comes in on the raw fd. +**s2n_peek** allows users of s2n-tls to peek inside the data buffer of an s2n-tls connection to see if there more data to be read without actually reading it. This is useful when using select() on the underlying s2n-tls file descriptor with a message based application layer protocol. As a single call to s2n_recv may read all data off the underlying file descriptor, select() will be unable to tell you there if there is more application data ready for processing already loaded into the s2n-tls buffer. s2n_peek can then be used to determine if s2n_recv needs to be called before more data comes in on the raw fd.