aboutsummaryrefslogtreecommitdiffstats
path: root/doc/ssl
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ssl')
-rw-r--r--doc/ssl/SSL_CTX_set_tlsext_servername_callback.pod62
-rw-r--r--doc/ssl/SSL_export_keying_material.pod61
-rw-r--r--doc/ssl/SSL_set_connect_state.pod2
3 files changed, 124 insertions, 1 deletions
diff --git a/doc/ssl/SSL_CTX_set_tlsext_servername_callback.pod b/doc/ssl/SSL_CTX_set_tlsext_servername_callback.pod
new file mode 100644
index 000000000000..3b0a50956d9b
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_tlsext_servername_callback.pod
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg,
+SSL_get_servername_type, SSL_get_servername - handle server name indication
+(SNI)
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
+ int (*cb)(SSL *, int *, void *));
+ long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
+
+ const char *SSL_get_servername(const SSL *s, const int type);
+ int SSL_get_servername_type(const SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
+used by a server to perform any actions or configuration required based on
+the servername extension received in the incoming connection. When B<cb>
+is NULL, SNI is not used. The B<arg> value is a pointer which is passed to
+the application callback.
+
+SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be
+passed into the callback for this B<SSL_CTX>.
+
+SSL_get_servername() returns a servername extension value of the specified
+type if provided in the Client Hello or NULL.
+
+SSL_get_servername_type() returns the servername type or -1 if no servername
+is present. Currently the only supported type (defined in RFC3546) is
+B<TLSEXT_NAMETYPE_host_name>.
+
+=head1 NOTES
+
+The ALPN and SNI callbacks are both executed during Client Hello processing.
+The servername callback is executed first, followed by the ALPN callback.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_tlsext_servername_callback() and
+SSL_CTX_set_tlsext_servername_arg() both always return 1 indicating success.
+
+=head1 SEE ALSO
+
+L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
+L<SSL_get0_alpn_selected(3)>
+
+=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
diff --git a/doc/ssl/SSL_export_keying_material.pod b/doc/ssl/SSL_export_keying_material.pod
new file mode 100644
index 000000000000..ccb99ec9a8e0
--- /dev/null
+++ b/doc/ssl/SSL_export_keying_material.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+SSL_export_keying_material - obtain keying material for application use
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
+ const char *label, size_t llen,
+ const unsigned char *context,
+ size_t contextlen, int use_context);
+
+=head1 DESCRIPTION
+
+During the creation of a TLS or DTLS connection shared keying material is
+established between the two endpoints. The function SSL_export_keying_material()
+enables an application to use some of this keying material for its own purposes
+in accordance with RFC5705.
+
+An application may need to securely establish the context within which this
+keying material will be used. For example this may include identifiers for the
+application session, application algorithms or parameters, or the lifetime of
+the context. The context value is left to the application but must be the same
+on both sides of the communication.
+
+For a given SSL connection B<s>, B<olen> bytes of data will be written to
+B<out>. The application specific context should be supplied in the location
+pointed to by B<context> and should be B<contextlen> bytes long. Provision of
+a context is optional. If the context should be omitted entirely then
+B<use_context> should be set to 0. Otherwise it should be any other value. If
+B<use_context> is 0 then the values of B<context> and B<contextlen> are ignored.
+Note that a zero length context is treated differently to no context at all, and
+will result in different keying material being returned.
+
+An application specific label should be provided in the location pointed to by
+B<label> and should be B<llen> bytes long. Typically this will be a value from
+the IANA Exporter Label Registry
+(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>).
+Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard
+to be used without registration.
+
+Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and
+above. Attempting to use it in SSLv3 will result in an error.
+
+=head1 RETURN VALUES
+
+SSL_export_keying_material() returns 0 or -1 on failure or 1 on success.
+
+=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
diff --git a/doc/ssl/SSL_set_connect_state.pod b/doc/ssl/SSL_set_connect_state.pod
index d88a057deffa..14facc6a57c9 100644
--- a/doc/ssl/SSL_set_connect_state.pod
+++ b/doc/ssl/SSL_set_connect_state.pod
@@ -25,7 +25,7 @@ it was either assigned a dedicated client method, a dedicated server
method, or a generic method, that can be used for both client and
server connections. (The method might have been changed with
L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> or
-SSL_set_ssl_method().)
+SSL_set_ssl_method(3).)
When beginning a new handshake, the SSL engine must know whether it must
call the connect (client) or accept (server) routines. Even though it may