Add support to free/allocate SSL buffers
authorTodd Short <tshort@akamai.com>
Fri, 13 Jan 2017 16:00:26 +0000 (11:00 -0500)
committerRich Salz <rsalz@openssl.org>
Wed, 26 Jul 2017 15:42:17 +0000 (11:42 -0400)
OpenSSL already has the feature of SSL_MODE_RELEASE_BUFFERS that can
be set to release the read or write buffers when data has finished
reading or writing. OpenSSL will automatically re-allocate the buffers
as needed. This can be quite aggressive in terms of memory allocation.

This provides a manual mechanism. SSL_free_buffers() will free
the data buffers if there's no pending data. SSL_alloc_buffers()
will realloc them; but this function is not strictly necessary, as it's
still done automatically in the state machine.

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2240)

doc/man3/SSL_alloc_buffers.pod [new file with mode: 0644]
include/openssl/ssl.h
ssl/ssl_lib.c
test/build.info
test/recipes/90-test_sslbuffers.t [new file with mode: 0644]
test/sslbuffertest.c [new file with mode: 0644]
util/libssl.num

diff --git a/doc/man3/SSL_alloc_buffers.pod b/doc/man3/SSL_alloc_buffers.pod
new file mode 100644 (file)
index 0000000..de33efb
--- /dev/null
@@ -0,0 +1,67 @@
+=pod
+
+=head1 NAME
+
+SSL_free_buffers, SSL_alloc_buffers - manage SSL structure buffers
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_free_buffers(SSL *ssl);
+ int SSL_alloc_buffers(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_free_buffers() frees the read and write buffers of the given B<ssl>.
+SSL_alloc_buffers() allocates the read and write buffers of the given B<ssl>.
+
+The B<SSL_MODE_RELEASE_BUFFERS> mode releases read or write buffers whenever
+the buffers have been drained. These functions allow applications to manually
+control when buffers are freed and allocated.
+
+After freeing the buffers, the buffers are automatically reallocted upon a
+new read or write. The SSL_alloc_buffers() does not need to be called, but
+can be used to make sure the buffers are pre-allocated. This can be used to
+avoid allocation during data processing or with CRYPTO_set_mem_functions()
+to control where and how buffers are allocated.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0 (Failure)
+
+The SSL_free_buffers() function returns 0 when there is pending data to be
+read or written. The SSL_alloc_buffers() function returns 0 when there is
+an allocation failure.
+
+=item 1 (Success)
+
+The SSL_free_buffers() function returns 1 if the buffers have been freed. This
+value is also returned if the buffers had been freed before calling
+SSL_free_buffers().
+The SSL_alloc_buffers() function returns 1 if the buffers have been allocated.
+This valus is also returned if the buffers had been allocated before calling
+SSL_alloc_buffers().
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_free(3)>, L<SSL_clear(3)>,
+L<SSL_new(3)>, L<SSL_CTX_set_mode(3)>,
+L<CRYPTO_set_mem_functions>
+
+=head1 COPYRIGHT
+
+Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
index 5dd210d..c634937 100644 (file)
@@ -442,8 +442,7 @@ typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx);
 # define SSL_MODE_NO_AUTO_CHAIN 0x00000008U
 /*
  * Save RAM by releasing read and write buffers when they're empty. (SSL3 and
- * TLS only.) "Released" buffers are put onto a free-list in the context or
- * just freed (depending on the context's setting for freelist_max_len).
+ * TLS only.) Released buffers are freed.
  */
 # define SSL_MODE_RELEASE_BUFFERS 0x00000010U
 /*
@@ -2238,6 +2237,9 @@ int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
 __owur const struct openssl_ssl_test_functions *SSL_test_functions(void);
 # endif
 
+__owur int SSL_free_buffers(SSL *ssl);
+__owur int SSL_alloc_buffers(SSL *ssl);
+
 extern const char SSL_version_str[];
 
 int ERR_load_SSL_strings(void);
index be15daa..74767f6 100644 (file)
@@ -4778,6 +4778,22 @@ int SSL_early_get0_ext(SSL *s, unsigned int type, const unsigned char **out,
     return 0;
 }
 
+int SSL_free_buffers(SSL *ssl)
+{
+    RECORD_LAYER *rl = &ssl->rlayer;
+
+    if (RECORD_LAYER_read_pending(rl) || RECORD_LAYER_write_pending(rl))
+        return 0;
+
+    RECORD_LAYER_release(rl);
+    return 1;
+}
+
+int SSL_alloc_buffers(SSL *ssl)
+{
+    return ssl3_setup_buffers(ssl);
+}
+
 void SSL_CTX_set_keylog_callback(SSL_CTX *ctx, SSL_CTX_keylog_cb_func cb)
 {
     ctx->keylog_callback = cb;
index 3d5b15e..a92ff18 100644 (file)
@@ -43,7 +43,7 @@ INCLUDE_MAIN___test_libtestutil_OLB = /INCLUDE=MAIN
           bioprinttest sslapitest dtlstest sslcorrupttest bio_enc_test \
           pkey_meth_test uitest cipherbytes_test asn1_encode_test \
           x509_time_test x509_dup_cert_test x509_check_cert_pkey_test \
-          recordlentest drbgtest \
+          recordlentest drbgtest sslbuffertest \
           time_offset_test pemtest ssl_cert_table_internal_test ciphername_test
 
   SOURCE[aborttest]=aborttest.c
@@ -437,6 +437,10 @@ INCLUDE_MAIN___test_libtestutil_OLB = /INCLUDE=MAIN
     INCLUDE[tls13secretstest]=.. ../include
     DEPEND[tls13secretstest]=../libcrypto ../libssl libtestutil.a
   ENDIF
+
+  SOURCE[sslbuffertest]=sslbuffertest.c ssltestlib.c
+  INCLUDE[sslbuffertest]=../include
+  DEPEND[sslbuffertest]=../libcrypto ../libssl libtestutil.a
 ENDIF
 
 {-
diff --git a/test/recipes/90-test_sslbuffers.t b/test/recipes/90-test_sslbuffers.t
new file mode 100644 (file)
index 0000000..934eef9
--- /dev/null
@@ -0,0 +1,21 @@
+#! /usr/bin/env perl
+# Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+#
+# Licensed under the OpenSSL license (the "License").  You may not use
+# this file except in compliance with the License.  You can obtain a copy
+# in the file LICENSE in the source distribution or at
+# https://www.openssl.org/source/license.html
+
+
+use OpenSSL::Test::Utils;
+use OpenSSL::Test qw/:DEFAULT srctop_file/;
+
+setup("test_sslbuffers");
+
+plan skip_all => "No suitable TLS/SSL protocol is supported by this OpenSSL build"
+    if alldisabled(available_protocols("tls"));
+
+plan tests => 1;
+
+ok(run(test(["sslbuffertest", srctop_file("apps", "server.pem"),
+             srctop_file("apps", "server.pem")])), "running sslbuffertest");
diff --git a/test/sslbuffertest.c b/test/sslbuffertest.c
new file mode 100644 (file)
index 0000000..72cb987
--- /dev/null
@@ -0,0 +1,180 @@
+/*
+ * Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+ *
+ * Licensed under the OpenSSL licenses, (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * https://www.openssl.org/source/license.html
+ * or in the file LICENSE in the source distribution.
+ */
+
+#include <string.h>
+#include <openssl/ssl.h>
+#include <openssl/bio.h>
+#include <openssl/err.h>
+
+#include "../ssl/packet_locl.h"
+
+#include "ssltestlib.h"
+#include "testutil.h"
+
+struct async_ctrs {
+    unsigned int rctr;
+    unsigned int wctr;
+};
+
+static SSL_CTX *serverctx = NULL;
+static SSL_CTX *clientctx = NULL;
+
+#define MAX_ATTEMPTS    100
+
+
+/*
+ * There are 9 passes in the tests
+ * 0 = control test
+ * tests during writes
+ * 1 = free buffers
+ * 2 = + allocate buffers after free
+ * 3 = + allocate buffers again
+ * 4 = + free buffers after allocation
+ * tests during reads
+ * 5 = + free buffers
+ * 6 = + free buffers again
+ * 7 = + allocate buffers after free
+ * 8 = + free buffers after allocation
+ */
+static int test_func(int test)
+{
+    int result = 0;
+    SSL *serverssl = NULL, *clientssl = NULL;
+    int ret;
+    size_t i, j;
+    const char testdata[] = "Test data";
+    char buf[sizeof(testdata)];
+
+    if (!TEST_true(create_ssl_objects(serverctx, clientctx, &serverssl, &clientssl,
+                                      NULL, NULL))) {
+        TEST_error("Test %d failed: Create SSL objects failed\n", test);
+        goto end;
+    }
+
+    if (!TEST_true(create_ssl_connection(serverssl, clientssl, SSL_ERROR_NONE))) {
+        TEST_error("Test %d failed: Create SSL connection failed\n", test);
+        goto end;
+    }
+
+    /*
+     * Send and receive some test data. Do the whole thing twice to ensure
+     * we hit at least one async event in both reading and writing
+     */
+    for (j = 0; j < 2; j++) {
+        int len;
+
+        /*
+
+         * Write some test data. It should never take more than 2 attempts
+         * (the first one might be a retryable fail).
+         */
+        for (ret = -1, i = 0, len = 0; len != sizeof(testdata) && i < 2;
+             i++) {
+            /* test == 0 mean to free/allocate = control */
+            if (test >= 1 && !TEST_true(SSL_free_buffers(clientssl)))
+                goto end;
+            if (test >= 2 && !TEST_true(SSL_alloc_buffers(clientssl)))
+                goto end;
+            /* allocate a second time */
+            if (test >= 3 && !TEST_true(SSL_alloc_buffers(clientssl)))
+                goto end;
+            if (test >= 4 && !TEST_true(SSL_free_buffers(clientssl)))
+                goto end;
+
+            ret = SSL_write(clientssl, testdata + len,
+                            sizeof(testdata) - len);
+            if (ret > 0) {
+                len += ret;
+            } else {
+                int ssl_error = SSL_get_error(clientssl, ret);
+
+                if (ssl_error == SSL_ERROR_SYSCALL ||
+                    ssl_error == SSL_ERROR_SSL) {
+                    TEST_error("Test %d failed: Failed to write app data\n", test);
+                    goto end;
+                }
+            }
+        }
+        if (!TEST_size_t_eq(len, sizeof(testdata)))
+            goto end;
+        /*
+         * Now read the test data. It may take more attemps here because
+         * it could fail once for each byte read, including all overhead
+         * bytes from the record header/padding etc.
+         */
+        for (ret = -1, i = 0, len = 0; len != sizeof(testdata) &&
+                 i < MAX_ATTEMPTS; i++)
+        {
+            if (test >= 5 && !TEST_true(SSL_free_buffers(serverssl)))
+                goto end;
+            /* free a second time */
+            if (test >= 6 && !TEST_true(SSL_free_buffers(serverssl)))
+                goto end;
+            if (test >= 7 && !TEST_true(SSL_alloc_buffers(serverssl)))
+                goto end;
+            if (test >= 8 && !TEST_true(SSL_free_buffers(serverssl)))
+                goto end;
+
+            ret = SSL_read(serverssl, buf + len, sizeof(buf) - len);
+            if (ret > 0) {
+                len += ret;
+            } else {
+                int ssl_error = SSL_get_error(serverssl, ret);
+
+                if (ssl_error == SSL_ERROR_SYSCALL ||
+                    ssl_error == SSL_ERROR_SSL) {
+                    TEST_error("Test %d failed: Failed to read app data\n", test);
+                    goto end;
+                }
+            }
+        }
+        if (!TEST_mem_eq(buf, len, testdata, sizeof(testdata)))
+            goto end;
+    }
+
+    result = 1;
+ end:
+    if (!result)
+        ERR_print_errors_fp(stderr);
+
+    SSL_free(clientssl);
+    SSL_free(serverssl);
+
+    return result;
+}
+
+int test_main(int argc, char *argv[])
+{
+    int testresult = EXIT_FAILURE;
+
+    CRYPTO_set_mem_debug(1);
+    CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON);
+
+    if (argc != 3) {
+        TEST_error("Invalid argument count\n");
+        goto end;
+    }
+
+    if (!create_ssl_ctx_pair(TLS_server_method(), TLS_client_method(),
+                             &serverctx, &clientctx, argv[1], argv[2])) {
+        TEST_error("Failed to create SSL_CTX pair\n");
+        goto end;
+    }
+
+    ADD_ALL_TESTS(test_func, 9);
+
+    testresult = run_tests(argv[0]);
+
+ end:
+    SSL_CTX_free(clientctx);
+    SSL_CTX_free(serverctx);
+
+    return testresult;
+}
index 26a225c..6a93ecb 100644 (file)
@@ -460,3 +460,5 @@ SSL_SESSION_set1_master_key             460 1_1_1   EXIST::FUNCTION:
 SSL_SESSION_set_cipher                  461    1_1_1   EXIST::FUNCTION:
 SSL_SESSION_set_protocol_version        462    1_1_1   EXIST::FUNCTION:
 OPENSSL_cipher_name                     463    1_1_1   EXIST::FUNCTION:
+SSL_alloc_buffers                       464    1_1_1   EXIST::FUNCTION:
+SSL_free_buffers                        465    1_1_1   EXIST::FUNCTION: