From 64a3651b3ece1a1e3195f20e37247f929d179f61 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 14 Sep 2011 10:57:17 +0200 Subject: Remove old ssl implementation and deprecated function ssl:peercert/1 --- lib/ssl/doc/src/Makefile | 4 +- lib/ssl/doc/src/old_ssl.xml | 709 -------------------------------------------- lib/ssl/doc/src/refman.xml | 5 +- lib/ssl/doc/src/ssl.xml | 8 +- 4 files changed, 7 insertions(+), 719 deletions(-) delete mode 100644 lib/ssl/doc/src/old_ssl.xml (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile index 3119d37af0..5d808d6727 100644 --- a/lib/ssl/doc/src/Makefile +++ b/lib/ssl/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1999-2010. All Rights Reserved. +# Copyright Ericsson AB 1999-2011. 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 @@ -37,7 +37,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = refman.xml -XML_REF3_FILES = ssl.xml old_ssl.xml ssl_session_cache_api.xml +XML_REF3_FILES = ssl.xml ssl_session_cache_api.xml XML_REF6_FILES = ssl_app.xml XML_PART_FILES = release_notes.xml usersguide.xml diff --git a/lib/ssl/doc/src/old_ssl.xml b/lib/ssl/doc/src/old_ssl.xml deleted file mode 100644 index 0d2e1afdbd..0000000000 --- a/lib/ssl/doc/src/old_ssl.xml +++ /dev/null @@ -1,709 +0,0 @@ - - - - -
- - 19992010 - 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 - old_ssl.xml -
- old_ssl - Interface Functions for Secure Socket Layer - -

This module contains interface functions to the Secure Socket Layer.

- - -
- General - -

This manual page describes functions that are defined - in the ssl module and represents the old ssl implementation - that coexists with the new one until it has been - totally phased out.

- -

The old implementation can be - accessed by providing the option {ssl_imp, old} to the - ssl:connect and ssl:listen functions.

- -

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) -> {ok, Cert} | {error, Reason} - Return the peer certificate. - - Socket = sslsocket() - Cert = binary()() - Subject = term()() - - -

Returns the DER encoded peer certificate, the certificate can be decoded with - public_key:pkix_decode_cert/2. -

- - - - 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) public_key(3)

-
- - - - diff --git a/lib/ssl/doc/src/refman.xml b/lib/ssl/doc/src/refman.xml index 68f84660f3..011819e82b 100644 --- a/lib/ssl/doc/src/refman.xml +++ b/lib/ssl/doc/src/refman.xml @@ -1,10 +1,10 @@ - +
- 19992010 + 19992011 Ericsson AB. All Rights Reserved. @@ -45,7 +45,6 @@ - diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 0c4c8796be..66d2644b76 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -121,8 +121,6 @@

hash() = md5 | sha

-

ssl_imp() = new | old - default is new.

-
@@ -177,9 +175,9 @@ by the peer also. - {ssl_imp, ssl_imp()} - Specify which ssl implementation you want to use. Defaults to - new. + {ssl_imp, new | old} + No longer has any meaning as the old implementation has + been removed, it will be ignored. {secure_renegotiate, boolean()} -- cgit v1.2.3