aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc/src/ssl.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssl/doc/src/ssl.xml')
-rw-r--r--lib/ssl/doc/src/ssl.xml103
1 files changed, 64 insertions, 39 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 1d74faf1b3..ffee4bd1af 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
- <year>1999</year><year>2013</year>
+ <year>1999</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -184,12 +184,6 @@
<item> The DER encoded trusted certificates. If this option
is supplied it will override the cacertfile option.</item>
- <tag>{cacertfile, path()}</tag>
- <item>Path to file containing PEM encoded
- CA certificates (trusted certificates used for verifying a peer
- certificate). May be omitted if you do not want to verify
- the peer.</item>
-
<tag>{ciphers, ciphers()}</tag>
<item>The cipher suites that should be supported. The function
<c>cipher_suites/0</c> can be used to find all ciphers that are
@@ -354,7 +348,13 @@ fun(srp, Username :: string(), UserState :: term()) ->
<item>Specifies if client should try to reuse sessions
when possible.
</item>
-
+
+ <tag>{cacertfile, path()}</tag>
+ <item>The path to a file containing PEM encoded CA certificates. The CA
+ certificates are used during server authentication and when building the
+ client certificate chain.
+ </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>
@@ -403,7 +403,17 @@ fun(srp, Username :: string(), UserState :: term()) ->
meaning in the server than in the client.</p>
<taglist>
-
+
+ <tag>{cacertfile, path()}</tag>
+ <item>The path to a file containing PEM encoded CA
+ certificates. The CA certificates are used to build the server
+ certificate chain, and for client authentication. Also the CAs
+ are used in the list of acceptable client CAs passed to the
+ client when a certificate is requested. May be omitted if there
+ is no need to verify the client and if there are not any
+ intermediate CAs for the server certificate.
+ </item>
+
<tag>{dh, der_encoded()}</tag>
<item>The DER encoded Diffie Hellman parameters. If this option
is supplied it will override the dhfile option.
@@ -460,6 +470,10 @@ fun(srp, Username :: string(), UserState :: term()) ->
</item>
<tag>{log_alert, boolean()}</tag>
<item>If false, error reports will not be displayed.</item>
+ <tag>{honor_cipher_order, boolean()}</tag>
+ <item>If true, use the server's preference for cipher selection. If false
+ (the default), use the client's preference.
+ </item>
</taglist>
</section>
@@ -754,39 +768,45 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>ssl_accept(ListenSocket) -> </name>
- <name>ssl_accept(ListenSocket, Timeout) -> ok | {error, Reason}</name>
- <fsummary>Perform server-side SSL handshake</fsummary>
+ <name>ssl_accept(Socket) -> </name>
+ <name>ssl_accept(Socket, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Perform server-side SSL/TLS handshake</fsummary>
<type>
- <v>ListenSocket = sslsocket()</v>
+ <v>Socket = sslsocket()</v>
<v>Timeout = integer()</v>
<v>Reason = term()</v>
</type>
<desc>
- <p>The <c>ssl_accept</c> function establish the SSL connection
- on the server side. It should be called directly after
- <c>transport_accept</c>, in the spawned server-loop.</p>
+ <p> Performs the SSL/TLS server-side handshake <c>Socket</c> is a socket as returned
+ by <seealso
+ marker="#transport_accept-2">ssl:transport_accept/[1,2]</seealso>
+ </p>
</desc>
</func>
<func>
- <name>ssl_accept(ListenSocket, SslOptions) -> </name>
- <name>ssl_accept(ListenSocket, SslOptions, Timeout) -> {ok, Socket} | {error, Reason}</name>
- <fsummary>Perform server-side SSL handshake</fsummary>
+ <name>ssl_accept(Socket, SslOptions) -> </name>
+ <name>ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
+ <fsummary>Perform server-side SSL/TLS handshake</fsummary>
<type>
- <v>ListenSocket = socket()</v>
+ <v>Socket = socket() | sslsocket() </v>
<v>SslOptions = ssloptions()</v>
<v>Timeout = integer()</v>
<v>Reason = term()</v>
</type>
<desc>
- <p> Upgrades a gen_tcp, or
- equivalent, socket to an ssl socket i.e. performs the
- ssl server-side handshake.</p>
+ <p> If <c>Socket</c> is a socket() - upgrades a gen_tcp, or equivalent, socket to an ssl socket
+ i.e. performs the SSL/TLS server-side handshake and returns the ssl socket.
+ </p>
+
<warning><p>Note that the listen socket should be in {active, false} mode
before telling the client that the server is ready to upgrade
- and calling this function, otherwise the upgrade may
+ by calling this function, otherwise the upgrade may
or may not succeed depending on timing.</p></warning>
+
+ <p> If <c>Socket</c> is an sslsocket() - provides additional SSL/TLS options to those specified in <seealso
+ marker="#listen-2">ssl:listen/2 </seealso> and then performs the SSL/TLS handshake.
+ </p>
</desc>
</func>
@@ -828,33 +848,38 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>transport_accept(Socket) -></name>
- <name>transport_accept(Socket, Timeout) ->
+ <name>transport_accept(ListenSocket) -></name>
+ <name>transport_accept(ListenSocket, Timeout) ->
{ok, NewSocket} | {error, Reason}</name>
<fsummary>Accept an incoming connection and
prepare for <c>ssl_accept</c></fsummary>
<type>
- <v>Socket = NewSocket = sslsocket()</v>
+ <v>ListenSocket = NewSocket = sslsocket()</v>
<v>Timeout = integer()</v>
<v>Reason = reason()</v>
</type>
<desc>
<p>Accepts an incoming connection request on a listen socket.
- <c>ListenSocket</c> must be a socket returned from
- <c>listen/2</c>. The socket returned should be passed to
- <c>ssl_accept</c> to complete ssl handshaking and
- establishing the connection.</p>
+ <c>ListenSocket</c> must be a socket returned from
+ <seealso
+ marker="#listen-2"> ssl:listen/2</seealso>.
+ The socket returned should be passed to
+ <seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso>
+ to complete handshaking i.e
+ establishing the SSL/TLS connection.</p>
<warning>
- <p>The socket returned can only be used with <c>ssl_accept</c>,
- no traffic can be sent or received before that call.</p>
+ <p>The socket returned can only be used with
+ <seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso>
+ no traffic can be sent or received before that call.</p>
</warning>
<p>The accepted socket inherits the options set for
- <c>ListenSocket</c> in <c>listen/2</c>.</p>
+ <c>ListenSocket</c> in <seealso
+ marker="#listen-2"> ssl:listen/2</seealso>.</p>
<p>The default
- value for <c>Timeout</c> is <c>infinity</c>. If
- <c>Timeout</c> is specified, and no connection is accepted
- within the given time, <c>{error, timeout}</c> is
- returned.</p>
+ value for <c>Timeout</c> is <c>infinity</c>. If
+ <c>Timeout</c> is specified, and no connection is accepted
+ within the given time, <c>{error, timeout}</c> is
+ returned.</p>
</desc>
</func>