From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/ssl/doc/src/ssl.xml | 728 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 728 insertions(+) create mode 100644 lib/ssl/doc/src/ssl.xml (limited to 'lib/ssl/doc/src/ssl.xml') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml new file mode 100644 index 0000000000..9b780b14ce --- /dev/null +++ b/lib/ssl/doc/src/ssl.xml @@ -0,0 +1,728 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ssl + Peter Högfeldt + Peter Högfeldt + + Peter Högfeldt + + 2003-03-25 + D + ssl.sgml +
+ ssl + Interface Functions for Secure Socket Layer + +

This module contains interface functions to the Secure Socket Layer.

+ + +
+ General + +

There is a new implementation of ssl available in + this module but until it is 100 % complete, so that it can replace + the old implementation in all aspects it will be + described here new ssl API

+ +

The reader is advised to also read the ssl(6) manual page + describing the SSL application. +

+ +

It is strongly advised to seed the random generator after + the ssl application has been started (see seed/1 + below), and before any connections are established. Although + the port program interfacing to the ssl libraries does a + "random" seeding of its own in order to make everything work + properly, that seeding is by no means random for the world + since it has a constant value which is known to everyone + reading the source code of the port program.

+ +
+ +
+ Common data types +

The following datatypes are used in the functions below: +

+ + +

options() = [option()]

+ + +

option() = socketoption() | ssloption()

+ + +

socketoption() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} | {backlog, integer()} | {ip, ipaddress()} | {port, integer()}

+ + +

ssloption() = {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()}

+ + +

packettype() (see inet(3))

+ + +

activetype() (see inet(3))

+ + +

reason() = atom() | {atom(), string()}

+ + +

bytes() = [byte()]

+ + +

string() = [byte()]

+ + +

byte() = 0 | 1 | 2 | ... | 255

+ + +

code() = 0 | 1 | 2

+ + +

depth() = byte()

+ + +

address() = hostname() | ipstring() | ipaddress()

+ + +

ipaddress() = ipstring() | iptuple()

+ + +

hostname() = string()

+ + +

ipstring() = string()

+ + +

iptuple() = {byte(), byte(), byte(), byte()}

+ + +

sslsocket()

+ + +

protocol() = sslv2 | sslv3 | tlsv1

+ + +

+ + +

The socket option {backlog, integer()} is for + listen/2 only, and the option {port, integer()} + is for connect/3/4 only. +

+

The following socket options are set by default: {mode, list}, {packet, 0}, {header, 0}, {nodelay, false}, {active, true}, {backlog, 5}, + {ip, {0,0,0,0}}, and {port, 0}. +

+

Note that the options {mode, binary} and binary + are equivalent. Similarly {mode, list} and the absence of + option binary are equivalent. +

+

The ssl options are for setting specific SSL parameters as follows: +

+ + +

{verify, code()} Specifies type of verification: + 0 = do not verify peer; 1 = verify peer, 2 = verify peer, + fail if no peer certificate. The default value is 0. +

+ + +

{depth, depth()} Specifies the maximum + verification depth, i.e. how far in a chain of certificates + the verification process can proceed before the verification + is considered to fail. +

+

Peer certificate = 0, CA certificate = 1, higher level CA + certificate = 2, etc. The value 2 thus means that a chain + can at most contain peer cert, CA cert, next CA cert, and an + additional CA cert. +

+

The default value is 1. +

+ + +

{certfile, path()} Path to a file containing the + user's certificate. + chain of PEM encoded certificates.

+ + +

{keyfile, path()} Path to file containing user's + private PEM encoded key.

+ + +

{password, string()} String containing the user's + password. Only used if the private keyfile is password protected.

+ + +

{cacertfile, path()} Path to file containing PEM encoded + CA certificates (trusted certificates used for verifying a peer + certificate).

+ + +

{ciphers, string()} String of ciphers as a colon + separated list of ciphers. The function ciphers/0 can + be used to find all available ciphers.

+ + +

The type sslsocket() is opaque to the user. +

+

The owner of a socket is the one that created it by a call to + transport_accept/[1,2], connect/[3,4], + or listen/2. +

+

When a socket is in active mode (the default), data from the + socket is delivered to the owner of the socket in the form of + messages: +

+ + +

{ssl, Socket, Data}

+ + +

{ssl_closed, Socket}

+ + +

{ssl_error, Socket, Reason}

+ + +

A Timeout argument specifies a timeout in milliseconds. The + default value for a Timeout argument is infinity. +

+

Functions listed below may return the value {error, closed}, which only indicates that the SSL socket is + considered closed for the operation in question. It is for + instance possible to have {error, closed} returned from + an call to send/2, and a subsequent call to recv/3 + returning {ok, Data}. +

+

Hence a return value of {error, closed} must not be + interpreted as if the socket was completely closed. On the + contrary, in order to free all resources occupied by an SSL + socket, close/1 must be called, or else the process owning + the socket has to terminate. +

+

For each SSL socket there is an Erlang process representing the + socket. When a socket is opened, that process links to the + calling client process. Implementations that want to detect + abnormal exits from the socket process by receiving {'EXIT', Pid, Reason} messages, should use the function pid/1 + to retrieve the process identifier from the socket, in order to + be able to match exit messages properly.

+
+ + + ciphers() -> {ok, string()} | {error, enotstarted} + Get supported ciphers. + +

Returns a string consisting of colon separated cipher + designations that are supported by the current SSL library + implementation. +

+

The SSL application has to be started to return the string + of ciphers.

+ + + + close(Socket) -> ok | {error, Reason} + Close a socket returned by transport_accept/[1,2], connect/3/4, or listen/2. + + Socket = sslsocket() + + +

Closes a socket returned by transport_accept/[1,2], + connect/[3,4], or listen/2

+ + + + connect(Address, Port, Options) -> {ok, Socket} | {error, Reason} + connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason} + Connect to Portat Address. + + Address = address() + Port = integer() + Options = [connect_option()] + connect_option() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} | {ip, ipaddress()} | {port, integer()} | {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()} + Timeout = integer() + Socket = sslsocket() + + +

Connects to Port at Address. If the optional + Timeout argument is specified, and a connection could not + be established within the given time, {error, timeout} is + returned. The default value for Timeout is infinity. +

+

The ip and port options are for binding to a + particular local address and port, respectively.

+ + + + connection_info(Socket) -> {ok, {Protocol, Cipher}} | {error, Reason} + Get current protocol version and cipher. + + Socket = sslsocket() + Protocol = protocol() + Cipher = string() + + +

Gets the chosen protocol version and cipher for an established + connection (accepted och connected).

+ + + + controlling_process(Socket, NewOwner) -> ok | {error, Reason} + Assign a new controlling process to the socket. + + Socket = sslsocket() + NewOwner = pid() + + +

Assigns a new controlling process to Socket. A controlling + process is the owner of a socket, and receives all messages from + the socket.

+ + + + format_error(ErrorCode) -> string() + Return an error string. + + ErrorCode = term() + + +

Returns a diagnostic string describing an error.

+ + + + getopts(Socket, OptionsTags) -> {ok, Options} | {error, Reason} + Get options set for socket + + Socket = sslsocket() + OptionTags = [optiontag()]() + + +

Returns the options the tags of which are OptionTags for + for the socket Socket.

+ + + + listen(Port, Options) -> {ok, ListenSocket} | {error, Reason} + Set up a socket to listen on a port on the local host. + + Port = integer() + Options = [listen_option()] + listen_option() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {active, activetype()} | {backlog, integer()} | {ip, ipaddress()} | {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()} + ListenSocket = sslsocket() + + +

Sets up a socket to listen on port Port at the local host. + If Port is zero, listen/2 picks an available port + number (use port/1 to retrieve it). +

+

The listen queue size defaults to 5. If a different value is + wanted, the option {backlog, Size} should be added to the + list of options. +

+

An empty Options list is considered an error, and + {error, enooptions} is returned. +

+

The returned ListenSocket can only be used in calls to + transport_accept/[1,2].

+ + + + peercert(Socket) -> + peercert(Socket, Opts) -> {ok, Cert} | {ok, Subject} | {error, Reason} + Return the peer certificate. + + Socket = sslsocket() + Opts = [pkix | ssl | subject]() + Cert = term()() + Subject = term()() + + +

peercert(Cert) is equivalent to peercert(Cert, []). +

+

The form of the returned certificate depends on the + options. +

+

If the options list is empty the certificate is returned as + a DER encoded binary. +

+

The options pkix and ssl implies that the + certificate is returned as a parsed ASN.1 structure in the + form of an Erlang term. +

+

The ssl option gives a more elaborate return + structure, with more explicit information. In particular + object identifiers are replaced by atoms. +

+

The options pkix, and ssl are mutually + exclusive. +

+

The option subject implies that only the subject's + distinguished name part of the peer certificate is returned. + It can only be used together with the option pkix or + the option ssl.

+ + + + peername(Socket) -> {ok, {Address, Port}} | {error, Reason} + Return peer address and port. + + Socket = sslsocket() + Address = ipaddress() + Port = integer() + + +

Returns the address and port number of the peer.

+ + + + pid(Socket) -> pid() + Return the pid of the socket process. + + Socket = sslsocket() + + +

Returns the pid of the socket process. The returned pid should + only be used for receiving exit messages.

+ + + + recv(Socket, Length) -> {ok, Data} | {error, Reason} + recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason} + Receive data on socket. + + Socket = sslsocket() + Length = integer() >= 0 + Timeout = integer() + Data = bytes() | binary() + + +

Receives data on socket Socket when the socket is in + passive mode, i.e. when the option {active, false} + has been specified. +

+

A notable return value is {error, closed} which + indicates that the socket is closed. +

+

A positive value of the Length argument is only + valid when the socket is in raw mode (option {packet, 0} is set, and the option binary is not + set); otherwise it should be set to 0, whence all available + bytes are returned. +

+

If the optional Timeout parameter is specified, and + no data was available within the given time, {error, timeout} is returned. The default value for + Timeout is infinity.

+ + + + seed(Data) -> ok | {error, Reason} + Seed the ssl random generator. + + Data = iolist() | binary() + + +

Seeds the ssl random generator. +

+

It is strongly advised to seed the random generator after + the ssl application has been started, and before any + connections are established. Although the port program + interfacing to the OpenSSL libraries does a "random" seeding + of its own in order to make everything work properly, that + seeding is by no means random for the world since it has a + constant value which is known to everyone reading the source + code of the seeding. +

+

A notable return value is {error, edata}} indicating that + Data was not a binary nor an iolist.

+ + + + send(Socket, Data) -> ok | {error, Reason} + Write data to a socket. + + Socket = sslsocket() + Data = iolist() | binary() + + +

Writes Data to Socket.

+

A notable return value is {error, closed} indicating that + the socket is closed.

+ + + + setopts(Socket, Options) -> ok | {error, Reason} + Set socket options. + + Socket = sslsocket() + Options = [socketoption]() + + +

Sets options according to Options for the socket + Socket.

+ + + + ssl_accept(Socket) -> ok | {error, Reason} + ssl_accept(Socket, Timeout) -> ok | {error, Reason} + Perform server-side SSL handshake and key exchange + + Socket = sslsocket() + Timeout = integer() + Reason = atom() + + +

The ssl_accept function establish the SSL connection + on the server side. It should be called directly after + transport_accept, in the spawned server-loop.

+

Note that the ssl connection is not complete until ssl_accept + has returned true, and if an error is returned, the socket + is unavailable and for instance close/1 will crash.

+ + + + sockname(Socket) -> {ok, {Address, Port}} | {error, Reason} + Return the local address and port. + + Socket = sslsocket() + Address = ipaddress() + Port = integer() + + +

Returns the local address and port number of the socket + Socket.

+ + + + transport_accept(Socket) -> {ok, NewSocket} | {error, Reason} + transport_accept(Socket, Timeout) -> {ok, NewSocket} | {error, Reason} + Accept an incoming connection and prepare for ssl_accept + + Socket = NewSocket = sslsocket() + Timeout = integer() + Reason = atom() + + +

Accepts an incoming connection request on a listen socket. + ListenSocket must be a socket returned from listen/2. + The socket returned should be passed to ssl_accept to + complete ssl handshaking and establishing the connection.

+ +

The socket returned can only be used with ssl_accept, + no traffic can be sent or received before that call.

+ +

The accepted socket inherits the options set for ListenSocket + in listen/2.

+

The default value for Timeout is infinity. If + Timeout is specified, and no connection is accepted within + the given time, {error, timeout} is returned.

+ + + + version() -> {ok, {SSLVsn, CompVsn, LibVsn}} + Return the version of SSL. + + SSLVsn = CompVsn = LibVsn = string()() + + +

Returns the SSL application version (SSLVsn), the library + version used when compiling the SSL application port program + (CompVsn), and the actual library version used when + dynamically linking in runtime (LibVsn). +

+

If the SSL application has not been started, CompVsn and + LibVsn are empty strings. +

+ + + + +
+ ERRORS +

The possible error reasons and the corresponding diagnostic strings + returned by format_error/1 are either the same as those defined + in the inet(3) reference manual, or as follows: +

+ + closed + +

Connection closed for the operation in question. +

+ + ebadsocket + +

Connection not found (internal error). +

+ + ebadstate + +

Connection not in connect state (internal error). +

+ + ebrokertype + +

Wrong broker type (internal error). +

+ + ecacertfile + +

Own CA certificate file is invalid. +

+ + ecertfile + +

Own certificate file is invalid. +

+ + echaintoolong + +

The chain of certificates provided by peer is too long. +

+ + ecipher + +

Own list of specified ciphers is invalid. +

+ + ekeyfile + +

Own private key file is invalid. +

+ + ekeymismatch + +

Own private key does not match own certificate. +

+ + enoissuercert + +

Cannot find certificate of issuer of certificate provided + by peer. +

+ + enoservercert + +

Attempt to do accept without having set own certificate. +

+ + enotlistener + +

Attempt to accept on a non-listening socket. +

+ + enoproxysocket + +

No proxy socket found (internal error). +

+ + enooptions + +

The list of options is empty. +

+ + enotstarted + +

The SSL application has not been started. +

+ + eoptions + +

Invalid list of options. +

+ + epeercert + +

Certificate provided by peer is in error. +

+ + epeercertexpired + +

Certificate provided by peer has expired. +

+ + epeercertinvalid + +

Certificate provided by peer is invalid. +

+ + eselfsignedcert + +

Certificate provided by peer is self signed. +

+ + esslaccept + +

Server SSL handshake procedure between client and server failed. +

+ + esslconnect + +

Client SSL handshake procedure between client and server failed. +

+ + esslerrssl + +

SSL protocol failure. Typically because of a fatal alert + from peer. +

+ + ewantconnect + +

Protocol wants to connect, which is not supported in + this version of the SSL application. +

+ + ex509lookup + +

Protocol wants X.509 lookup, which is not supported in + this version of the SSL application. +

+ + {badcall, Call} + +

Call not recognized for current mode (active or passive) and + state of socket. +

+ + {badcast, Cast} + +

Call not recognized for current mode (active or passive) and + state of socket. +

+ + {badinfo, Info} + +

Call not recognized for current mode (active or passive) and + state of socket. +

+ + +
+ +
+ SEE ALSO +

gen_tcp(3), inet(3) +

+
+ + + + -- cgit v1.2.3