This module contains interface functions to the Secure Socket Layer.
The following data types are used in the functions below:
For valid options
see
Options described here are options that are have the same meaning in the client and the server.
The verification fun should be defined as:
fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
{extension, #'Extension'{}}, InitialUserState :: term()) ->
{valid, UserState :: term()} | {valid_peer, UserState :: term()} |
{fail, Reason :: term()} | {unknown, UserState :: term()}.
The verify fun will be called during the X509-path
validation when an error or an extension unknown to the ssl
application is encountered. Additionally it will be called
when a certificate is considered valid by the path validation
to allow access to each certificate in the path to the user
application. Note that it will differentiate between the
peer certificate and CA certificates by using valid_peer or
valid as the second argument to the verify fun. See
If the verify callback fun returns {fail, Reason}, the verification process is immediately stopped and an alert is sent to the peer and the TLS/SSL handshake is terminated. If the verify callback fun returns {valid, UserState}, the verification process is continued. If the verify callback fun always returns {valid, UserState}, the TLS/SSL handshake will not be terminated with respect to verification failures and the connection will be established. If called with an extension unknown to the user application the return value {unknown, UserState} should be used.
The default verify_fun option in verify_peer mode:
{fun(_,{bad_cert, _} = Reason, _) ->
{fail, Reason};
(_,{extension, _}, UserState) ->
{unknown, UserState};
(_, valid, UserState) ->
{valid, UserState};
(_, valid_peer, UserState) ->
{valid, UserState}
end, []}
The default verify_fun option in verify_none mode:
{fun(_,{bad_cert, _}, UserState) ->
{valid, UserState};
(_,{extension, _}, UserState) ->
{unknown, UserState};
(_, valid, UserState) ->
{valid, UserState};
(_, valid_peer, UserState) ->
{valid, UserState}
end, []}
Possible path validation errors:
{bad_cert, cert_expired}, {bad_cert, invalid_issuer}, {bad_cert, invalid_signature}, {bad_cert, unknown_ca},{bad_cert, selfsigned_peer}, {bad_cert, name_not_permitted}, {bad_cert, missing_basic_constraint}, {bad_cert, invalid_key_usage}
Options described here are client specific or has a slightly different meaning in the client than in the server.
Indicates the client will try to perform Next Protocol Negotiation.
If precedence is server the negaotiated protocol will be the first protocol that appears on the server advertised list that is also on the clients preference list.
If the precedence is client the negaotiated protocol will be the first protocol that appears on the clients preference list that is also on the server advertised list.
If the client does not support any of the servers advertised protocols or the server does not advertise any protocols the client will fallback to the first protocol in its list or if a default is supplied it will fallback to that instead. If the server does not support next protocol renegotiation the connection will be aborted if no default protocol is supplied.
Options described here are server specific or has a slightly different meaning in the server than in the client.
When an ssl socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of messages:
A
Returns a list of supported cipher suites. cipher_suites() is equivalent to cipher_suites(erlang). Type openssl is provided for backwards compatibility with old ssl that used openssl.
Upgrades a gen_tcp, or equivalent, connected socket to an ssl socket i.e. performs the client-side ssl handshake.
Opens an ssl connection to Host, Port.
Close an ssl connection.
Assigns a new controlling process to the ssl-socket. A controlling process is the owner of an ssl-socket, and receives all messages from the socket.
Returns the negotiated protocol version and cipher suite.
Presents the error returned by an ssl function as a printable string.
Get the value of the specified socket options.
Creates an ssl listen socket.
The peer certificate is returned as a DER encoded binary.
The certificate can be decoded with
Returns the address and port number of the peer.
This function receives a packet from a socket in passive
mode. A closed socket is indicated by a return value
The
The optional
Use the pseudo random function (PRF) of a TLS session to generate
additional key material. It either takes user generated values for
This function can only be used with TLS connections,
Initiates a new handshake. A notable return value is
Writes
A notable return value is
Sets options according to
Immediately close a socket in one or two directions.
To be able to handle that the peer has done a shutdown on
the write side, the
The
Upgrades a gen_tcp, or equivalent, socket to an ssl socket i.e. performs the ssl server-side handshake.
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 or may not succeed depending on timing.
Returns the local address and port number of the socket
Starts the Ssl application. Default type
is temporary.
Stops the Ssl application.
Accepts an incoming connection request on a listen socket.
The socket returned can only be used with
The accepted socket inherits the options set for
The default
value for
Returns version information relevant for the ssl application.
Returns the Next Protocol negotiated.