From 34ef4b8d5feff3b0cc76573d769e482c420673ba Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 5 Jan 2018 11:55:58 +0100 Subject: ssl: Add new API functions --- lib/ssl/doc/src/ssl.xml | 133 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 6 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 8c1b1541c7..029f29cdb3 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -197,6 +197,18 @@ | sect193r1 | sect193r2 | secp192k1 | secp192r1 | sect163k1 | sect163r1 | sect163r2 | secp160k1 | secp160r1 | secp160r2

+ hello_extensions() = +

#{renegotiation_info => + signature_algs => [{hash(), ecsda| rsa| dsa}] | undefined + alpn => binary() | undefined, + next_protocol_negotiation, + srp => string() | undefined, + ec_point_formats , + elliptic_curves = [oid] | undefined + sni = string()} + }

 + + @@ -211,8 +223,16 @@ {protocol, tls | dtls}

Choose TLS or DTLS protocol for the transport layer security. Defaults to tls Introduced in OTP 20, DTLS support is considered - experimental in this release. DTLS over other transports than UDP are not yet supported.

 - + experimental in this release. Other transports than UDP are not yet supported.

+ + {handshake, hello | full} +

Defaults to full. If hello is specified the handshake will + pause after the hello message and give the user a possibility make decisions + based on hello extensions before continuing or aborting the handshake by calling + handshake_continue/3 or + handshake_cancel/1 +

+ {cert, public_key:der_encoded()}

The DER-encoded users certificate. If this option is supplied, it overrides option certfile.

 @@ -919,15 +939,16 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Socket, SslOptions) -> - connect(Socket, SslOptions, Timeout) -> {ok, TLSSocket} + connect(Socket, SslOptions, Timeout) -> {ok, TLSSocket} | {ok, TLSSocket, Ext} | {error, Reason} Upgrades a gen_tcp, or equivalent, connected socket to an TLS socket. Socket = socket() - SslOptions = [ssl_option()] + SslOptions = [{handshake, hello| full} | ssl_option()] Timeout = integer() | infinity TLSSocket = sslsocket() + Ext = hello_extensions() Reason = term()

Upgrades a gen_tcp, or equivalent, @@ -938,14 +959,25 @@ fun(srp, Username :: string(), UserState :: term()) -> the option server_name_indication shall also be specified, if it is not no Server Name Indication extension will be sent, and public_key:pkix_verify_hostname/2 - will be called with the IP-address of the connection as ReferenceID, which is proably not what you want.

+ will be called with the IP-address of the connection as ReferenceID, which is proably not what you want.

+ + +

If the option {handshake, hello} is used the + handshake is paused after receiving the server hello message + and the success response is {ok, TLSSocket, Ext} + instead of {ok, TLSSocket}. Thereafter the handshake is continued or + canceled by calling + handshake_continue/3 or handshake_cancel/1. +

+ connect(Host, Port, Options) -> connect(Host, Port, Options, Timeout) -> - {ok, SslSocket} | {error, Reason} + {ok, SslSocket}| {ok, TLSSocket, Ext} | {error, Reason} Opens an TLS/DTLS connection to Host, Port. Host = host() @@ -972,6 +1004,16 @@ fun(srp, Username :: string(), UserState :: term()) -> dns_id will be assumed with a fallback to ip if that fails.

According to good practices certificates should not use IP-addresses as "server names". It would be very surprising if this happen outside a closed network.

+ + +

If the option {handshake, hello} is used the + handshake is paused after receiving the server hello message + and the success response is {ok, TLSSocket, Ext} + instead of {ok, TLSSocket}. Thereafter the handshake is continued or + canceled by calling + handshake_continue/3 or handshake_cancel/1. +

@@ -1112,6 +1154,85 @@ fun(srp, Username :: string(), UserState :: term()) -> + + handshake(Socket) -> + handshake(Socket, Timeout) -> {ok, Socket} | {error, Reason} + Performs server-side SSL/TLS handshake. + + Socket = sslsocket() + Timeout = integer() + Reason = term() + + +

Performs the SSL/TLS/DTLS server-side handshake.

+

Socket is a socket as returned by + ssl:transport_accept/[1,2]. +

+ + + + + handshake(Socket, SslOptions) -> + handshake(Socket, SslOptions, Timeout) -> {ok, Socket} | {ok, Socket, Ext} | {error, Reason} + Performs server-side SSL/TLS/DTLS handshake. + + Socket = socket() | sslsocket() + Ext = hello_extensions() + SslOptions = [{handshake, hello| full} | ssl_option()] + Timeout = integer() + Reason = term() + + +

If Socket is a ordinary socket(): upgrades a gen_tcp, + or equivalent, socket to an SSL socket, that is, performs + the SSL/TLS server-side handshake and returns the SSL socket.

+ +

The Socket shall be in passive mode ({active, + false}) before calling this function or the handshake can fail + due to a race condition.

 + +

If Socket is an sslsocket(): provides extra SSL/TLS/DTLS + options to those specified in + ssl:listen/2 and then performs + the SSL/TLS/DTLS handshake.

+ +

+ If option {handshake, hello} is specified the handshake is + paused after receiving the client hello message and the + sucess response is {ok, TLSSocket, Ext} instead of {ok, + TLSSocket}. Thereafter the handshake is continued or + canceled by calling + handshake_continue/3 or handshake_cancel/1. +

+ + + + + handshake_cancel(Socket) -> ok + Cancel handshake with a fatal alert + + Socket = sslsocket() + + +

Cancel the handshake with a fatal USER_CANCELED alert.

+ + + + + handshake_continue(Socket, SSLOptions, Timeout) -> {ok, Socket} | {error, Reason} + Continue the SSL/TLS handshake. + + Socket = sslsocket() + SslOptions = [ssl_option()] + Timeout = integer() + Reason = term() + + +

Continue the SSL/TLS handshake possiby with new, additional or changed options.

+ + + listen(Port, Options) -> {ok, ListenSocket} | {error, Reason} -- cgit v1.2.3