aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2015-02-26 18:55:16 +0100
committerZandra Hird <[email protected]>2015-03-17 11:55:53 +0100
commit7cf85926c11d38ce5ebd181f9f98185f359d64a3 (patch)
treee2eef9483f32c5616ebe0c5cf91fcb06e0944d87 /lib/ssl/doc
parente0c0518a14b747cf02a0e5adfbd5b116a189422d (diff)
downloadotp-7cf85926c11d38ce5ebd181f9f98185f359d64a3.tar.gz
otp-7cf85926c11d38ce5ebd181f9f98185f359d64a3.tar.bz2
otp-7cf85926c11d38ce5ebd181f9f98185f359d64a3.zip
ssl: Add TLS-ALPN support
This commit adds support for RFC7301, application-layer protocol negotiation. ALPN is the standard based approach to the NPN extension, and is required for HTTP/2. ALPN lives side by side with NPN and provides an equivalent feature but in this case it is the server that decides what protocol to use, not the client. When both ALPN and NPN are sent by a client, and the server is configured with both ALPN and NPN options, ALPN will always take precedence. This behavior can also be found in the OpenSSL implementation of ALPN. ALPN and NPN share the ssl:negotiated_protocol/1 function for retrieving the negotiated protocol. The previously existing function ssl:negotiated_next_protocol/1 still exists, but has been deprecated and removed from the documentation. The tests against OpenSSL require OpenSSL version 1.0.2+.
Diffstat (limited to 'lib/ssl/doc')
-rw-r--r--lib/ssl/doc/src/ssl.xml38
1 files changed, 33 insertions, 5 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index c9b02d44ec..3581a487a2 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -89,6 +89,8 @@
|{dh, der_encoded()} | {dhfile, path()} | {ciphers, ciphers()} |
{user_lookup_fun, {fun(), term()}}, {psk_identity, string()}, {srp_identity, {string(), string()}} |
{ssl_imp, ssl_imp()} | {reuse_sessions, boolean()} | {reuse_session, fun()}
+ {alpn_advertised_protocols, [binary()]} |
+ {alpn_preferred_protocols, [binary()]} |
{next_protocols_advertised, [binary()]} |
{client_preferred_next_protocols, {client | server, [binary()]} | {client | server, [binary()], binary()}} |
{log_alert, boolean()} | {server_name_indication, hostname() | disable}
@@ -425,7 +427,20 @@ fun(srp, Username :: string(), UserState :: term()) ->
certificates are used during server authentication and when building the
client certificate chain.
</item>
-
+
+ <tag>{alpn_advertised_protocols, [binary()]}</tag>
+ <item>
+ <p>The list of protocols supported by the client to be sent to the
+ server to be used for an Application-Layer Protocol Negotiation (ALPN).
+ If the server supports ALPN then it will choose a protocol from this
+ list; otherwise it will fail the connection with a "no_application_protocol"
+ alert. A server that does not support ALPN will ignore this value.</p>
+
+ <p>The list of protocols must not contain an empty binary.</p>
+
+ <p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p>
+ </item>
+
<tag>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}</tag>
<tag>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}</tag>
<item>
@@ -545,12 +560,25 @@ fun(srp, Username :: string(), UserState :: term()) ->
and CipherSuite is of type ciphersuite().
</item>
+ <tag>{alpn_preferred_protocols, [binary()]}</tag>
+ <item>
+ <p>Indicates the server will try to perform Application-Layer
+ Protocol Negotiation (ALPN).</p>
+
+ <p>The list of protocols is in order of preference. The protocol
+ negotiated will be the first in the list that matches one of the
+ protocols advertised by the client. If no protocol matches, the
+ server will fail the connection with a "no_application_protocol" alert.</p>
+
+ <p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p>
+ </item>
+
<tag>{next_protocols_advertised, Protocols :: [binary()]}</tag>
<item>The list of protocols to send to the client if the client indicates
it supports the Next Protocol extension. The client may select a protocol
that is not on this list. The list of protocols must not contain an empty
binary. If the server negotiates a Next Protocol it can be accessed
- using <c>negotiated_next_protocol/1</c> method.
+ using <c>negotiated_protocol/1</c> function.
</item>
<tag>{psk_identity, string()}</tag>
@@ -1018,15 +1046,15 @@ fun(srp, Username :: string(), UserState :: term()) ->
</desc>
</func>
<func>
- <name>negotiated_next_protocol(Socket) -> {ok, Protocol} | {error, next_protocol_not_negotiated}</name>
- <fsummary>Returns the Next Protocol negotiated.</fsummary>
+ <name>negotiated_protocol(Socket) -> {ok, Protocol} | {error, protocol_not_negotiated}</name>
+ <fsummary>Returns the protocol negotiated through ALPN or NPN extensions.</fsummary>
<type>
<v>Socket = sslsocket()</v>
<v>Protocol = binary()</v>
</type>
<desc>
<p>
- Returns the Next Protocol negotiated.
+ Returns the protocol negotiated through ALPN or NPN extensions.
</p>
</desc>
</func>