Documentation working session.

api/s2n.h

@@ -142,6 +142,8 @@ extern int *s2n_errno_location(void);
  * the 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.
+ *
+ * See the [Error Handling](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#error-handling) section for how the errors should be interpreted. 
  */
 typedef enum {
   /** No error */
@@ -190,6 +192,13 @@ struct s2n_connection;
  * prior to 1.1.x. This allows applications or languages that also init OpenSSL to interoperate
  * with S2N.
  *
+ * @warn This function must be called BEFORE s2n_init() to have any effect. It will return an error
+ * if s2n is already initialized.
+ *
+ * @note If you disable this and are using a version of OpenSSL/libcrypto < 1.1.x, you will
+ * be responsible for library init and cleanup (specifically `OPENSSL_add_all_algorithms()`
+ * or `OPENSSL_crypto_init()`, and EVP_* APIs will not be usable unless the library is initialized.
+ *
  * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
  */
 S2N_API
@@ -199,6 +208,12 @@ extern int s2n_crypto_disable_init(void);
  * Prevents S2N from installing an atexit handler, which allows safe shutdown of S2N from within a
  * re-entrant shared library
  *
+ * @warn This function must be called BEFORE s2n_init() to have any effect. It will return an error
+ * if s2n is already initialized.
+ *
+ * @note This will cause `s2n_cleanup` to do complete cleanup of s2n-tls when called from the main
+ * thread (the thread `s2n_init` was called from).
+ *
  * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
  */
 S2N_API
@@ -1741,6 +1756,18 @@ extern int s2n_negotiate(struct s2n_connection *conn, s2n_blocked_status *blocke
  * @note Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active. 
  * @note Unlike OpenSSL, repeated calls to s2n_send() should not duplicate the original parameters, but should 
  * update `buf` and `size` per the indication of size written. For example;
+ * ```c
+ * s2n_blocked_status blocked;
+ * int written = 0;
+ * char data[10]; 
+ * do {
+ *     int w = s2n_send(conn, data + written, 10 - written, &blocked);
+ *     if (w < 0) {
+ *         break;
+ *     }
+ *     written += w;
+ * } while (blocked != S2N_NOT_BLOCKED);
+ * ```
  *
  * @param conn A pointer to the s2n_connection object
  * @param buf A pointer to a buffer that s2n will write data from
@@ -1772,6 +1799,22 @@ extern ssize_t s2n_sendv(struct s2n_connection *conn, const struct iovec *bufs,
  *
  * @note Unlike OpenSSL, repeated calls to s2n_sendv_with_offset() should not duplicate the original parameters, but should update `bufs` and `count` per the indication of size written. For example;
  * 
+ * ```c
+ * s2n_blocked_status blocked;
+ * int written = 0;
+ * char data[10]; 
+ * struct iovec iov[1];
+ * iov[0].iov_base = data;
+ * iov[0].iov_len = 10;
+ * do {
+ *     int w = s2n_sendv_with_offset(conn, iov, 1, written, &blocked);
+ *     if (w < 0) {
+ *         break;
+ *     }
+ *     written += w;
+ * } while (blocked != S2N_NOT_BLOCKED);
+ * ```
+ *
  * @param conn A pointer to the s2n_connection object
  * @param bufs A pointer to a vector of buffers that s2n will write data from.
  * @param count The number of buffers in `bufs`
@@ -1787,6 +1830,18 @@ extern ssize_t s2n_sendv_with_offset(struct s2n_connection *conn, const struct i
  * connection. 
  * 
  * @note Unlike OpenSSL, repeated calls to `s2n_recv` should not duplicate the original parameters, but should update `buf` and `size` per the indication of size read. For example;
+ * ```c
+ * s2n_blocked_status blocked;
+ * int bytes_read = 0;
+ * char data[10];
+ * do {
+ *     int r = s2n_recv(conn, data + bytes_read, 10 - bytes_read, &blocked);
+ *     if (r < 0) {
+ *         break;
+ *     }
+ *     bytes_read += r;
+ * } while (blocked != S2N_NOT_BLOCKED);
+ * ```
  *
  * @param conn A pointer to the s2n_connection object
  * @param buf A pointer to a buffer that s2n will place read data into.
@@ -2695,6 +2750,13 @@ extern int s2n_connection_client_cert_used(struct s2n_connection *conn);
 /**
  * A function that provides a human readable string of the cipher suite that was chosen
  * for a connection.
+ *
+ * @warning The string "TLS_NULL_WITH_NULL_NULL" is returned before the TLS handshake has been performed.
+ * This does not mean that the ciphersuite "TLS_NULL_WITH_NULL_NULL" will be used by the connection,
+ * it is merely being used as a placeholder.
+ *
+ * @note This function is only accurate after the TLS handshake.
+ *
  * @param conn A pointer to the connection
  * @returns A string indicating the cipher suite negotiated by s2n in OpenSSL format.
  */

crypto/s2n_libcrypto.h

@@ -0,0 +1,20 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+#pragma once
+
+#include "utils/s2n_result.h"
+
+S2N_RESULT s2n_libcrypto_validate_runtime(void);