Ubuntu Feisty 7.04 manual page repository

Ubuntu is a free computer operating system based on the Linux kernel. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

Provided by: erlang-manpages_11.b.2-1_all

 

NAME

        ssl - Interface Functions for Secure Socket Layer
 

DESCRIPTION

        This module contains interface functions to the Secure Socket Layer.
ssl(6) manual page describing
        the SSL application.
 
    Warning:
        It is strongly advised to seed  the  random  generator  after  the  ssl
        application has been started (see seed/1 below), and before any connec‐
        tions are established. Although the port program interfacing to the ssl
        libraries  does  a  "random" seeding of its own in order to make every‐
        thing 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.
        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()}
 
inet(3))
 
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.  Simi‐
        larly {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  certifi‐
            cate. 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 certifi‐
            cate = 2, etc. The value 2 thus means that a chain can at most con‐
            tain 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 certifi‐
            cate. 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  cer‐
            tificates  (trusted certificates used for verifying a peer certifi‐
            cate).
 
          * {ciphers, string()} String of ciphers as a colon separated list  of
            ciphers.  The  function  ciphers/0 can be used to find all availabe
            ciphers.
 
        The type sslsocket() is opaque to the user.
 
        The owner of a socket is the one that created it by a call to accept/1,
        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 pro‐
        cess. Implementations that want  to  detect  abnormal  exits  from  the
        socket  process by receiving {’EXIT’, Pid, Reason} messages, should use
        the function pid/1 to retreive the process identifier from the  socket,
        in order to be able to match exit messages properly.
 

EXPORTS

        accept(ListenSocket) -> {ok, Socket} | {error, Reason}
        accept(ListenSocket, Timeout) -> {ok, Socket} | {error, Reason}
 
               Types  ListenSocket = Socket = sslsocket()
                      Timeout = integer()
 
               Accepts  an incoming connection request on a listen socket. Lis‐
               tenSocket must be a socket returned from listen/2.
 
               The accepted socket inherits the options set for ListenSocket in
               listen/2.
 
               The  default value for Timeout is infinity. If Timeout is speci‐
               fied, and no connection  is  accepted  within  the  given  time,
               {error, timeout} is returned.
 
        ciphers() -> {ok, string()} | {error, enotstarted}
 
               Returns  a string constisting of colon separated cipher designa‐
               tions that are supported by the current SSL library  implementa‐
               tion.
 
               The  SSL  application  has to be started to return the string of
               ciphers.
 
        close(Socket) -> ok | {error, Reason}
 
               Types  Socket = sslsocket()
 
               Closes a socket returned by 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, Rea     
        son}
 
               Types  Address = address()
                      Port = integer()
                      Options = [connect_option()]
                      connect_option() = {mode, list} | {mode, binary} | binary
                      |  {packet,  packettype()} | {header, integer()} | {node‐
                      lay, boolean()} | {active,  activetype()}  |  {ip,  ipad‐
                      dress()} | {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}
 
               Types  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}
 
               Types  Socket = sslsocket()
                      NewOwner = pid()
 
               Assigns  a new controlling process to Socket. A controlling pro‐
               cess is the owner of a socket, and receives  all  messages  from
               the socket.
 
        format_error(ErrorCode) -> string()
 
               Types  ErrorCode = term()
 
               Returns a diagnostic string describing an error.
 
        getopts(Socket, OptionsTags) -> {ok, Options} | {error, Reason}
 
               Types  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}
 
               Types  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 retreive 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, enoop‐
               tions} is returned.
 
               The  returned  ListenSocket  can  only  be  used  in  calls   to
               accept/1/2.
 
        peercert(Socket) ->
        peercert(Socket, Opts) -> {ok, Cert} | {ok, Subject} | {error, Reason}
 
               Types  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}
 
               Types  Socket = sslsocket()
                      Address = ipaddress()
                      Port = integer()
 
               Returns the address and port number of the peer.
 
        pid(Socket) -> pid()
 
               Types  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}
 
               Types  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}
 
               Types  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  ran‐
               dom  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}
 
               Types  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}
 
               Types  Socket = sslsocket()
                      Options = [socketoption]()
 
               Sets options according to Options for the socket Socket.
 
        sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}
 
               Types  Socket = sslsocket()
                      Address = ipaddress()
                      Port = integer()
 
               Returns the local address and port number of the socket  Socket.
 
        version() -> {ok, {SSLVsn, CompVsn, LibVsn}}
 
               Types  SSLVsn = CompVsn = LibVsn = string()()
 
               Returns  the  SSL application version (SSLVsn), the library ver‐
               sion used when compiling the SSL application port program  (Com‐
               pVsn),  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  ver‐
              sion 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.
inet(3)
 

AUTHOR

        Peter Högfeldt - support@erlang.ericsson.se
 

Sections

What does Ubuntu mean?
Ubuntu is an African word meaning 'Humanity to others', or 'I am what I am because of who we all are'. The Ubuntu distribution brings the spirit of Ubuntu to the software world.