← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/ssl/doc/src/ssl.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/ssl/doc/src/ssl.xml
1
 
<?xml version="1.0" encoding="latin1" ?>
 
1
<?xml version="1.0" encoding="iso-8859-1" ?>
2
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
3
3
 
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>1999</year><year>2009</year>
 
7
      <year>1999</year><year>2011</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
13
13
      compliance with the License. You should have received a copy of the
14
14
      Erlang Public License along with this software. If not, it can be
15
15
      retrieved online at http://www.erlang.org/.
16
 
    
 
16
 
17
17
      Software distributed under the License is distributed on an "AS IS"
18
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
      the License for the specific language governing rights and limitations
20
20
      under the License.
21
 
    
 
21
 
22
22
    </legalnotice>
23
 
 
24
23
    <title>ssl</title>
25
 
    <prepared>Peter H&ouml;gfeldt</prepared>
26
 
    <responsible>Peter H&ouml;gfeldt</responsible>
27
 
    <docno></docno>
28
 
    <approved>Peter H&ouml;gfeldt</approved>
29
 
    <checked></checked>
30
 
    <date>2003-03-25</date>
31
 
    <rev>D</rev>
32
 
    <file>ssl.sgml</file>
 
24
    <file>ssl.xml</file>
33
25
  </header>
34
26
  <module>ssl</module>
35
27
  <modulesummary>Interface Functions for Secure Socket Layer</modulesummary>
36
28
  <description>
37
 
    <p>This module contains interface functions to the Secure Socket Layer.</p>
 
29
    <p>This module contains interface functions to the Secure Socket
 
30
      Layer. 
 
31
    </p>
38
32
  </description>
39
 
 
 
33
  
 
34
  <section>
 
35
    <title>SSL</title>
 
36
 
 
37
    <list type="bulleted">
 
38
      <item>ssl requires the crypto an public_key applications.</item>
 
39
      <item>Supported SSL/TLS-versions are SSL-3.0 and TLS-1.0 </item>
 
40
      <item>For security reasons sslv2 is not supported.</item>
 
41
      <item>Ephemeral Diffie-Hellman cipher suites are supported
 
42
      but not Diffie Hellman Certificates cipher suites.</item>
 
43
      <item>Export cipher suites are not supported as the
 
44
      U.S. lifted its export restrictions in early 2000.</item>
 
45
      <item>CRL and policy certificate
 
46
            extensions are not supported yet. </item>
 
47
    </list>
 
48
 
 
49
  </section>
 
50
  
 
51
  <section>
 
52
    <title>COMMON DATA TYPES</title>
 
53
    <p>The following data types are used in the functions below:
 
54
    </p>
 
55
 
 
56
    <p><c>boolean() = true | false</c></p> 
 
57
    
 
58
    <p><c>property() = atom()</c></p>
 
59
    
 
60
    <p><c>option() = socketoption() | ssloption() | transportoption()</c></p>
 
61
 
 
62
     <p><c>socketoption() = [{property(), term()}] - defaults to
 
63
      [{mode,list},{packet, 0},{header, 0},{active, true}].
 
64
    </c></p>
 
65
 
 
66
    <p>For valid options
 
67
      see <seealso marker="kernel:inet">inet(3) </seealso> and
 
68
      <seealso marker="kernel:gen_tcp">gen_tcp(3) </seealso>.
 
69
    </p>
 
70
    
 
71
    <p> <c>ssloption() = {verify, verify_type()} |
 
72
      {verify_fun, {fun(), term()}} |
 
73
      {fail_if_no_peer_cert, boolean()}
 
74
      {depth, integer()} |
 
75
      {cert, der_encoded()}| {certfile, path()} |
 
76
      {key, der_encoded()} | {keyfile, path()} | {password, string()} |
 
77
      {cacerts, [der_encoded()]} | {cacertfile, path()} |
 
78
      |{dh, der_encoded()} | {dhfile, path()} | {ciphers, ciphers()} |
 
79
      {ssl_imp, ssl_imp()} | {reuse_sessions, boolean()} | {reuse_session, fun()} 
 
80
    </c></p>
 
81
 
 
82
    <p><c>transportoption() = {CallbackModule, DataTag, ClosedTag}
 
83
        - defaults to {gen_tcp, tcp, tcp_closed}. Ssl may be
 
84
        run over any reliable transport protocol that has
 
85
        an equivalent API to gen_tcp's.</c></p>
 
86
    
 
87
    <p><c>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; CallbackModule =
 
88
        atom()</c>
 
89
    </p> <p><c>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; DataTag =
 
90
        atom() - tag used in socket data message.</c></p>
 
91
    <p><c>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ClosedTag = atom() - tag used in
 
92
    socket close message.</c></p>
 
93
 
 
94
    <p><c>verify_type() = verify_none | verify_peer</c></p>
 
95
    
 
96
    <p><c>path() = string() - representing a file path.</c></p>
 
97
 
 
98
    <p><c>der_encoded() = binary() -Asn1 DER encoded entity as an erlang binary.</c></p>
 
99
    
 
100
    <p><c>host() = hostname() | ipaddress()</c></p>
 
101
        
 
102
    <p><c>hostname() = string()</c></p>
 
103
    
 
104
    <p><c>
 
105
      ip_address() = {N1,N2,N3,N4}  % IPv4
 
106
      | {K1,K2,K3,K4,K5,K6,K7,K8}  % IPv6    </c></p>
 
107
 
 
108
    <p><c>sslsocket() - opaque to the user. </c></p>
 
109
    
 
110
    <p><c>protocol() = sslv3 | tlsv1 </c></p>
 
111
    
 
112
    <p><c>ciphers() = [ciphersuite()] | string() (according to old API)</c></p>
 
113
    
 
114
    <p><c>ciphersuite() =
 
115
      {key_exchange(), cipher(), hash()}</c></p>
 
116
    
 
117
    <p><c>key_exchange() =  rsa | dhe_dss | dhe_rsa | dh_anon
 
118
    </c></p>
 
119
 
 
120
   <p><c>cipher() = rc4_128 | des_cbc | '3des_ede_cbc'
 
121
      | aes_128_cbc | aes_256_cbc </c></p>
 
122
 
 
123
   <p> <c>hash() = md5 | sha
 
124
    </c></p>
 
125
 
 
126
    <p><c>ssl_imp() = new | old - default is new.</c></p>
 
127
    
 
128
  </section>
 
129
 
 
130
  <section>
 
131
    <title>SSL OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT</title>
 
132
 
 
133
    <p>Options described here are options that are have the same
 
134
    meaning in the client and the server.
 
135
    </p>
 
136
    
 
137
    <taglist>
 
138
 
 
139
      <tag>{cert, der_encoded()}</tag>
 
140
      <item> The DER encoded users certificate. If this option
 
141
      is supplied it will override the certfile option.</item>
 
142
      
 
143
      <tag>{certfile, path()}</tag>
 
144
      <item>Path to a file containing the user's certificate.</item>
 
145
      
 
146
      <tag>{key, der_encoded()}</tag>
 
147
      <item> The DER encoded users private key. If this option
 
148
      is supplied it will override the keyfile option.</item>
 
149
      
 
150
      <tag>{keyfile, path()}</tag>
 
151
      <item>Path to file containing user's
 
152
      private PEM encoded key. As PEM-files may contain several
 
153
      entries this option defaults to the same file as given by
 
154
      certfile option.</item>
 
155
 
 
156
      <tag>{password, string()}</tag>
 
157
      <item>String containing the user's password.
 
158
        Only used if the private keyfile is password protected.
 
159
      </item>
 
160
 
 
161
      <tag>{cacerts, [der_encoded()]}</tag>
 
162
      <item> The DER encoded trusted certificates. If this option
 
163
      is supplied it will override the cacertfile option.</item>
 
164
 
 
165
      <tag>{cacertfile, path()}</tag>
 
166
      <item>Path to file containing PEM encoded
 
167
      CA certificates (trusted certificates used for verifying a peer
 
168
      certificate). May be omitted if you do not want to verify
 
169
      the peer.</item>
 
170
 
 
171
      <tag>{ciphers, ciphers()}</tag>
 
172
      <item>The cipher suites that should be supported. The function
 
173
      <c>cipher_suites/0</c> can be used to find all available
 
174
      ciphers. Additionally some anonymous cipher suites ({dh_anon,
 
175
      rc4_128, md5}, {dh_anon, des_cbc, sha}, {dh_anon,
 
176
      '3des_ede_cbc', sha}, {dh_anon, aes_128_cbc, sha}, {dh_anon,
 
177
      aes_256_cbc, sha}) are supported for testing purposes and will
 
178
      only work if explicitly enabled by this option and they are supported/enabled
 
179
      by the peer also.
 
180
      </item>
 
181
 
 
182
      <tag>{ssl_imp, ssl_imp()}</tag>
 
183
      <item>Specify which ssl implementation you want to use. Defaults to
 
184
      new.
 
185
      </item>
 
186
 
 
187
      <tag>{secure_renegotiate, boolean()}</tag>
 
188
      <item>Specifies if to reject renegotiation attempt that does
 
189
      not live up to RFC 5746. By default secure_renegotiate is
 
190
      set to false i.e. secure renegotiation will be used if possible
 
191
      but it will fallback to unsecure renegotiation if the peer
 
192
      does not support RFC 5746.
 
193
      </item>
 
194
 
 
195
      <tag>{depth, integer()}</tag>
 
196
      <item>Specifies the maximum
 
197
      verification depth, i.e. how far in a chain of certificates the
 
198
      verification process can proceed before the verification is
 
199
      considered to fail. Peer certificate = 0, CA certificate = 1,
 
200
      higher level CA certificate = 2, etc.  The value 2 thus means
 
201
      that a chain can at most contain peer cert, CA cert, next CA
 
202
      cert, and an additional CA cert. The default value is 1.
 
203
      </item>
 
204
 
 
205
      <tag>{verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}}</tag>
 
206
      <item>
 
207
        <p>The verification fun should be defined as:</p>
 
208
 
 
209
        <code>
 
210
fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
 
211
             {extension, #'Extension'{}}, InitialUserState :: term()) ->
 
212
        {valid, UserState :: term()} | {valid_peer, UserState :: term()} |
 
213
        {fail, Reason :: term()} | {unknown, UserState :: term()}.
 
214
        </code>
 
215
 
 
216
        <p>The verify fun will be called during the X509-path
 
217
        validation when an error or an extension unknown to the ssl
 
218
        application is encountered. Additionally it will be called
 
219
        when a certificate is considered valid by the path validation
 
220
        to allow access to each certificate in the path to the user
 
221
        application. Note that the it will differentiate between the
 
222
        peer certificate and CA certificates by using valid_peer or
 
223
        valid as the second argument to the verify fun.  See <seealso
 
224
        marker="public_key:cert_records">the public_key User's
 
225
        Guide</seealso> for definition of #'OTPCertificate'{} and
 
226
        #'Extension'{}.</p>
 
227
 
 
228
        <p>If the verify callback fun returns {fail, Reason}, the
 
229
        verification process is immediately stopped and an alert is
 
230
        sent to the peer and the TLS/SSL handshake is terminated. If
 
231
        the verify callback fun returns {valid, UserState}, the
 
232
        verification process is continued.  If the verify callback fun
 
233
        always returns {valid, UserState}, the TLS/SSL handshake will
 
234
        not be terminated with respect to verification failures and
 
235
        the connection will be established. If called with an
 
236
        extension unknown to the user application the return value
 
237
        {unknown, UserState} should be used.</p>
 
238
 
 
239
        <p>The default verify_fun option in verify_peer mode:</p>
 
240
 
 
241
      <code>
 
242
{fun(_,{bad_cert, _} = Reason, _) ->
 
243
         {fail, Reason};
 
244
    (_,{extension, _}, UserState) ->
 
245
         {unknown, UserState};
 
246
    (_, valid, UserState) ->
 
247
         {valid, UserState};
 
248
    (_, valid_peer, UserState) ->
 
249
         {valid, UserState}
 
250
 end, []}
 
251
      </code>
 
252
 
 
253
      <p>The default verify_fun option in verify_none mode:</p>
 
254
 
 
255
       <code>
 
256
{fun(_,{bad_cert, _}, UserState) ->
 
257
         {valid, UserState};
 
258
    (_,{extension, _}, UserState) ->
 
259
         {unknown, UserState};
 
260
    (_, valid, UserState) ->
 
261
         {valid, UserState};
 
262
    (_, valid_peer, UserState) ->
 
263
         {valid, UserState}
 
264
 end, []}
 
265
      </code>
 
266
 
 
267
<p>Possible path validation errors: </p>
 
268
 
 
269
<p> {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, {bad_cert, invalid_signature}, {bad_cert, unknown_ca}, {bad_cert, name_not_permitted}, {bad_cert, missing_basic_constraint}, {bad_cert, invalid_key_usage}</p>
 
270
      </item>
 
271
 
 
272
      <tag>{hibernate_after, integer()|undefined}</tag>
 
273
      <item>When an integer-value is specified, the <code>ssl_connection</code>
 
274
            will go into hibernation after the specified number of milliseconds
 
275
            of inactivity, thus reducing its memory footprint. When
 
276
            <code>undefined</code> is specified (this is the default), the process
 
277
            will never go into hibernation.
 
278
      </item>
 
279
    </taglist>
 
280
 
 
281
  </section>
 
282
 
 
283
   <section>
 
284
    <title>SSL OPTION DESCRIPTIONS - CLIENT SIDE</title>
 
285
 
 
286
    <p>Options described here are client specific or has a slightly different
 
287
    meaning in the client than in the server.</p>
 
288
 
 
289
    <taglist>
 
290
      <tag>{verify, verify_type()}</tag>
 
291
      <item> In verify_none mode the default behavior will be to
 
292
      allow all x509-path validation errors. See also the verify_fun
 
293
      option.
 
294
      </item>
 
295
      <tag>{reuse_sessions, boolean()}</tag>
 
296
      <item>Specifies if client should try to reuse sessions
 
297
      when possible.
 
298
      </item>
 
299
 
 
300
    </taglist>
 
301
  </section>
 
302
 
 
303
  <section>
 
304
    <title>SSL OPTION DESCRIPTIONS - SERVER SIDE</title>
 
305
 
 
306
    <p>Options described here are server specific or has a slightly different
 
307
    meaning in the server than in the client.</p>
 
308
 
 
309
    <taglist>
 
310
 
 
311
      <tag>{dh, der_encoded()}</tag>
 
312
      <item>The DER encoded Diffie Hellman parameters. If this option
 
313
      is supplied it will override the dhfile option.
 
314
      </item>
 
315
 
 
316
      <tag>{dhfile, path()}</tag>
 
317
      <item>Path to file containing PEM encoded Diffie Hellman parameters,
 
318
      for the server to use if a cipher suite using Diffie Hellman key exchange
 
319
      is negotiated. If not specified default parameters will be used.
 
320
      </item>
 
321
 
 
322
      <tag>{verify, verify_type()}</tag>
 
323
      <item>Servers only do the x509-path validation in verify_peer
 
324
      mode, as it then will send a certificate request to the client
 
325
      (this message is not sent if the verify option is verify_none)
 
326
      and you may then also want to specify the option
 
327
      fail_if_no_peer_cert.
 
328
      </item>
 
329
 
 
330
      <tag>{fail_if_no_peer_cert, boolean()}</tag>
 
331
      <item>Used together with {verify, verify_peer} by a ssl server.
 
332
      If set to true, the server will fail if the client does not have
 
333
      a certificate to send, i.e. sends a empty certificate, if set to
 
334
      false it will only fail if the client sends a invalid
 
335
      certificate (an empty certificate is considered valid).
 
336
      </item>
 
337
 
 
338
      <tag>{reuse_sessions, boolean()}</tag>
 
339
      <item>Specifies if the server should agree to reuse sessions
 
340
      when the clients request to do so. See also the reuse_session
 
341
      option.
 
342
      </item>
 
343
 
 
344
      <tag>{reuse_session, fun(SuggestedSessionId,
 
345
      PeerCert, Compression, CipherSuite) -> boolean()}</tag>
 
346
      <item>Enables the ssl server to have a local policy
 
347
      for deciding if a session should be reused or not,
 
348
      only meaning full if <c>reuse_sessions</c> is set to true.
 
349
      SuggestedSessionId is a binary(),  PeerCert is a DER encoded
 
350
      certificate, Compression is an enumeration integer
 
351
      and CipherSuite of type ciphersuite().      
 
352
      </item>
 
353
 
 
354
    </taglist>
 
355
  </section>
 
356
  
40
357
  <section>
41
358
    <title>General</title>
42
 
 
43
 
    <p>There is a new implementation of ssl available in 
44
 
    this module but until it is 100 % complete, so that it can replace
45
 
    the old implementation in all aspects it will be
46
 
    described here <seealso marker="new_ssl"> new ssl API </seealso></p>
47
 
    
48
 
    <p>The reader is advised to also read the <c>ssl(6)</c> manual page
49
 
      describing the SSL application.
50
 
      </p>
51
 
    <warning>
52
 
      <p>It is strongly advised to seed the random generator after
53
 
        the ssl application has been started (see <c>seed/1</c>
54
 
        below), and before any connections are established. Although
55
 
        the port program interfacing to the ssl libraries does a
56
 
        "random" seeding of its own in order to make everything work
57
 
        properly, that seeding is by no means random for the world
58
 
        since it has a constant value which is known to everyone
59
 
        reading the source code of the port program.</p>
60
 
    </warning>
61
 
  </section>
62
 
 
63
 
  <section>
64
 
    <title>Common data types</title>
65
 
    <p>The following datatypes are used in the functions below:
66
 
      </p>
67
 
    <list type="bulleted">
68
 
      <item>
69
 
        <p><c>options() = [option()]</c></p>
70
 
      </item>
71
 
      <item>
72
 
        <p><c>option() = socketoption() | ssloption()</c></p>
73
 
      </item>
74
 
      <item>
75
 
        <p><c>socketoption() = {mode, list} | {mode, binary} |  binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} |  {backlog, integer()} | {ip, ipaddress()} | {port, integer()}</c></p>
76
 
      </item>
77
 
      <item>
78
 
        <p><c>ssloption() = {verify, code()} | {depth, depth()} |  {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()}</c></p>
79
 
      </item>
80
 
      <item>
81
 
        <p><c>packettype()</c>  (see inet(3))</p>
82
 
      </item>
83
 
      <item>
84
 
        <p><c>activetype()</c>  (see inet(3))</p>
85
 
      </item>
86
 
      <item>
87
 
        <p><c>reason() = atom() | {atom(), string()}</c></p>
88
 
      </item>
89
 
      <item>
90
 
        <p><c>bytes() = [byte()]</c></p>
91
 
      </item>
92
 
      <item>
93
 
        <p><c>string() = [byte()]</c></p>
94
 
      </item>
95
 
      <item>
96
 
        <p><c>byte() = 0 | 1 | 2 | ... | 255</c></p>
97
 
      </item>
98
 
      <item>
99
 
        <p><c>code() = 0 | 1 | 2</c></p>
100
 
      </item>
101
 
      <item>
102
 
        <p><c>depth() = byte()</c></p>
103
 
      </item>
104
 
      <item>
105
 
        <p><c>address() = hostname() | ipstring() | ipaddress()</c></p>
106
 
      </item>
107
 
      <item>
108
 
        <p><c>ipaddress() = ipstring() | iptuple()</c></p>
109
 
      </item>
110
 
      <item>
111
 
        <p><c>hostname() = string()</c></p>
112
 
      </item>
113
 
      <item>
114
 
        <p><c>ipstring() = string()</c></p>
115
 
      </item>
116
 
      <item>
117
 
        <p><c>iptuple() = {byte(), byte(), byte(), byte()}</c></p>
118
 
      </item>
119
 
      <item>
120
 
        <p><c>sslsocket()</c></p>
121
 
      </item>
122
 
      <item>
123
 
        <p><c>protocol() = sslv2 | sslv3 | tlsv1</c></p>
124
 
      </item>
125
 
      <item>
126
 
        <p><c></c></p>
127
 
      </item>
128
 
    </list>
129
 
    <p>The socket option <c>{backlog, integer()}</c> is for
130
 
      <c>listen/2</c> only, and the option <c>{port, integer()}</c>
131
 
      is for <c>connect/3/4</c> only. 
132
 
      </p>
133
 
    <p>The following socket options are set by default: <c>{mode, list}</c>, <c>{packet, 0}</c>, <c>{header, 0}</c>, <c>{nodelay, false}</c>, <c>{active, true}</c>, <c>{backlog, 5}</c>,
134
 
      <c>{ip, {0,0,0,0}}</c>, and <c>{port, 0}</c>.
135
 
      </p>
136
 
    <p>Note that the options <c>{mode, binary}</c> and <c>binary</c>
137
 
      are equivalent. Similarly <c>{mode, list}</c> and the absence of
138
 
      option <c>binary</c> are equivalent. 
139
 
      </p>
140
 
    <p>The ssl options are for setting specific SSL parameters as follows:
141
 
      </p>
142
 
    <list type="bulleted">
143
 
      <item>
144
 
        <p><c>{verify, code()}</c> Specifies type of verification:
145
 
          0 = do not verify peer; 1 = verify peer, 2 = verify peer,
146
 
          fail if no peer certificate.  The default value is 0.
147
 
          </p>
148
 
      </item>
149
 
      <item>
150
 
        <p><c>{depth, depth()}</c> Specifies the maximum
151
 
          verification depth, i.e. how far in a chain of certificates
152
 
          the verification process can proceed before the verification
153
 
          is considered to fail. 
154
 
          </p>
155
 
        <p>Peer certificate = 0, CA certificate = 1, higher level CA
156
 
          certificate = 2, etc.  The value 2 thus means that a chain
157
 
          can at most contain peer cert, CA cert, next CA cert, and an
158
 
          additional CA cert.
159
 
          </p>
160
 
        <p>The default value is 1.
161
 
          </p>
162
 
      </item>
163
 
      <item>
164
 
        <p><c>{certfile, path()}</c> Path to a file containing the
165
 
          user's certificate.
166
 
          chain of PEM encoded certificates.</p>
167
 
      </item>
168
 
      <item>
169
 
        <p><c>{keyfile, path()}</c> Path to file containing user's
170
 
          private PEM encoded key.</p>
171
 
      </item>
172
 
      <item>
173
 
        <p><c>{password, string()}</c> String containing the user's
174
 
          password. Only used if the private keyfile is password protected.</p>
175
 
      </item>
176
 
      <item>
177
 
        <p><c>{cacertfile, path()}</c> Path to file containing PEM encoded
178
 
          CA certificates (trusted certificates used for verifying a peer
179
 
          certificate).</p>
180
 
      </item>
181
 
      <item>
182
 
        <p><c>{ciphers, string()}</c> String of ciphers as a colon
183
 
          separated list of ciphers. The function <c>ciphers/0</c> can
184
 
          be used to find all available ciphers.</p>
185
 
      </item>
186
 
    </list>
187
 
    <p>The type <c>sslsocket()</c> is opaque to the user.
188
 
      </p>
189
 
    <p>The owner of a socket is the one that created it by a call to
190
 
      <c>transport_accept/[1,2]</c>,  <c>connect/[3,4]</c>,
191
 
      or <c>listen/2</c>.
192
 
      </p>
193
 
    <p>When a socket is in active mode (the default), data from the
 
359
      
 
360
    <p>When a ssl socket is in active mode (the default), data from the
194
361
      socket is delivered to the owner of the socket in the form of
195
362
      messages:
196
 
      </p>
 
363
    </p>
197
364
    <list type="bulleted">
198
 
      <item>
199
 
        <p><c>{ssl, Socket, Data}</c></p>
200
 
      </item>
201
 
      <item>
202
 
        <p><c>{ssl_closed, Socket}</c></p>
203
 
      </item>
204
 
      <item>
205
 
        <p><c>{ssl_error, Socket, Reason}</c></p>
 
365
      <item>{ssl, Socket, Data}
 
366
      </item>
 
367
      <item>{ssl_closed, Socket}
 
368
      </item>
 
369
      <item>
 
370
        {ssl_error, Socket, Reason}
206
371
      </item>
207
372
    </list>
 
373
    
208
374
    <p>A <c>Timeout</c> argument specifies a timeout in milliseconds. The 
209
375
      default value for a <c>Timeout</c> argument is <c>infinity</c>.
210
 
      </p>
211
 
    <p>Functions listed below may return the value <c>{error, closed}</c>, which only indicates that the SSL socket is
212
 
      considered closed for the operation in question. It is for
213
 
      instance possible to have <c>{error, closed}</c> returned from
214
 
      an call to <c>send/2</c>, and a subsequent call to <c>recv/3</c>
215
 
      returning <c>{ok, Data}</c>.
216
 
      </p>
217
 
    <p>Hence a return value of <c>{error, closed}</c> must not be
218
 
      interpreted as if the socket was completely closed. On the
219
 
      contrary, in order to free all resources occupied by an SSL
220
 
      socket, <c>close/1</c> must be called, or else the process owning
221
 
      the socket has to terminate.
222
 
      </p>
223
 
    <p>For each SSL socket there is an Erlang process representing the
224
 
      socket.  When a socket is opened, that process links to the
225
 
      calling client process.  Implementations that want to detect
226
 
      abnormal exits from the socket process by receiving <c>{'EXIT', Pid, Reason}</c> messages, should use the function <c>pid/1</c>
227
 
      to retrieve the process identifier from the socket, in order to
228
 
      be able to match exit messages properly.</p>
 
376
    </p>
229
377
  </section>
 
378
  
230
379
  <funcs>
231
380
    <func>
232
 
      <name>ciphers() -> {ok, string()} | {error, enotstarted}</name>
233
 
      <fsummary>Get supported ciphers.</fsummary>
234
 
      <desc>
235
 
        <p>Returns a string consisting of colon separated cipher
236
 
          designations that are supported by the current SSL library
237
 
          implementation.
238
 
          </p>
239
 
        <p>The SSL application has to be started to return the string
240
 
          of ciphers.</p>
241
 
      </desc>
242
 
    </func>
243
 
    <func>
244
 
      <name>close(Socket) -> ok | {error, Reason}</name>
245
 
      <fsummary>Close a socket returned by <c>transport_accept/[1,2]</c>, <c>connect/3/4</c>, or <c>listen/2</c>.</fsummary>
246
 
      <type>
247
 
        <v>Socket = sslsocket()</v>
248
 
      </type>
249
 
      <desc>
250
 
        <p>Closes a socket returned by <c>transport_accept/[1,2]</c>,
251
 
        <c>connect/[3,4]</c>, or <c>listen/2</c></p>
252
 
      </desc>
253
 
    </func>
254
 
    <func>
255
 
      <name>connect(Address, Port, Options) -> {ok, Socket} | {error, Reason}</name>
256
 
      <name>connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason}</name>
257
 
      <fsummary>Connect to <c>Port</c>at <c>Address</c>.</fsummary>
258
 
      <type>
259
 
        <v>Address = address()</v>
260
 
        <v>Port = integer()</v>
261
 
        <v>Options = [connect_option()]</v>
262
 
        <v>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()}</v>
263
 
        <v>Timeout = integer()</v>
264
 
        <v>Socket = sslsocket()</v>
265
 
      </type>
266
 
      <desc>
267
 
        <p>Connects to <c>Port</c> at <c>Address</c>. If the optional 
268
 
          <c>Timeout</c> argument is specified, and a connection could not
269
 
          be established within the given time, <c>{error, timeout}</c> is
270
 
          returned. The default value for <c>Timeout</c> is <c>infinity</c>.
271
 
          </p>
272
 
        <p>The <c>ip</c> and <c>port</c> options are for binding to a 
273
 
          particular <em>local</em> address and port, respectively.</p>
274
 
      </desc>
275
 
    </func>
276
 
    <func>
277
 
      <name>connection_info(Socket) -> {ok, {Protocol, Cipher}} | {error, Reason}</name>
278
 
      <fsummary>Get current protocol version and cipher.</fsummary>
279
 
      <type>
280
 
        <v>Socket = sslsocket()</v>
281
 
        <v>Protocol = protocol()</v>
282
 
        <v>Cipher = string()</v>
283
 
      </type>
284
 
      <desc>
285
 
        <p>Gets the chosen protocol version and cipher for an established
286
 
          connection (accepted och connected). </p>
287
 
      </desc>
288
 
    </func>
289
 
    <func>
290
 
      <name>controlling_process(Socket, NewOwner) -> ok | {error, Reason}</name>
291
 
      <fsummary>Assign a new controlling process to the socket.</fsummary>
292
 
      <type>
293
 
        <v>Socket = sslsocket()</v>
294
 
        <v>NewOwner = pid()</v>
295
 
      </type>
296
 
      <desc>
297
 
        <p>Assigns a new controlling process to <c>Socket</c>. A controlling
298
 
          process is the owner of a socket, and receives all messages from
299
 
          the socket.</p>
300
 
      </desc>
301
 
    </func>
302
 
    <func>
303
 
      <name>format_error(ErrorCode) -> string()</name>
 
381
      <name>cipher_suites() -></name>
 
382
      <name>cipher_suites(Type) -> ciphers()</name>
 
383
      <fsummary> Returns a list of supported cipher suites</fsummary>
 
384
      <type>
 
385
        <v>Type = erlang | openssl</v>
 
386
 
 
387
      </type>
 
388
      <desc><p>Returns a list of supported cipher suites.
 
389
        cipher_suites() is equivalent to cipher_suites(erlang).
 
390
        Type openssl is provided for backwards compatibility with
 
391
        old ssl that used openssl.
 
392
        </p>
 
393
    </desc>
 
394
    </func>
 
395
    
 
396
    <func>
 
397
      <name>connect(Socket, SslOptions) -> </name>
 
398
      <name>connect(Socket, SslOptions, Timeout) -> {ok, SslSocket}
 
399
        | {error, Reason}</name>
 
400
      <fsummary> Upgrades a gen_tcp, or
 
401
        equivalent, connected socket to a ssl socket. </fsummary>
 
402
      <type>
 
403
        <v>Socket = socket()</v>
 
404
        <v>SslOptions = [ssloption()]</v>
 
405
        <v>Timeout = integer() | infinity</v>
 
406
        <v>SslSocket = sslsocket()</v>
 
407
        <v>Reason = term()</v>
 
408
      </type>
 
409
      <desc> <p>Upgrades a gen_tcp, or equivalent,
 
410
          connected socket to a ssl socket i.e. performs the
 
411
          client-side ssl handshake.</p>
 
412
    </desc>
 
413
    </func>
 
414
 
 
415
    <func>
 
416
      <name>connect(Host, Port, Options) -></name>
 
417
      <name>connect(Host, Port, Options, Timeout) ->
 
418
          {ok, SslSocket} | {error, Reason}</name>
 
419
      <fsummary>Opens an ssl connection to Host, Port. </fsummary>
 
420
      <type>
 
421
          <v>Host = host()</v>
 
422
          <v>Port = integer()</v>
 
423
          <v>Options = [option()]</v>
 
424
          <v>Timeout = integer() | infinity</v>
 
425
          <v>SslSocket = sslsocket()</v>
 
426
          <v>Reason = term()</v>
 
427
      </type>
 
428
      <desc> <p>Opens an ssl connection to Host, Port.</p> </desc>
 
429
    </func>
 
430
 
 
431
    <func>
 
432
      <name>close(SslSocket) -> ok | {error, Reason}</name>
 
433
      <fsummary>Close a ssl connection</fsummary>
 
434
      <type>
 
435
          <v>SslSocket = sslsocket()</v>
 
436
          <v>Reason = term()</v>
 
437
      </type>
 
438
      <desc><p>Close a ssl connection.</p>
 
439
      </desc>
 
440
    </func>
 
441
 
 
442
    <func>
 
443
      <name>controlling_process(SslSocket, NewOwner) ->
 
444
        ok | {error, Reason}</name>
 
445
      
 
446
        <fsummary>Assigns a new controlling process to the
 
447
        ssl-socket.</fsummary>
 
448
      
 
449
        <type>
 
450
          <v>SslSocket = sslsocket()</v>
 
451
          <v>NewOwner = pid()</v>
 
452
          <v>Reason = term()</v>
 
453
        </type>
 
454
        <desc><p>Assigns a new controlling process to the ssl-socket. A
 
455
      controlling process is the owner of a ssl-socket, and receives
 
456
      all messages from the socket.</p>
 
457
      </desc>
 
458
    </func>
 
459
 
 
460
    <func>
 
461
        <name>connection_info(SslSocket) ->
 
462
          {ok, {ProtocolVersion, CipherSuite}} |  {error, Reason} </name>
 
463
      <fsummary>Returns the negotiated protocol version and cipher suite.
 
464
      </fsummary>
 
465
      <type>
 
466
        <v>CipherSuite = ciphersuite()</v>
 
467
        <v>ProtocolVersion = protocol()</v>
 
468
      </type>
 
469
      <desc><p>Returns the negotiated protocol version and cipher suite.</p> 
 
470
      </desc>
 
471
    </func>
 
472
 
 
473
     <func>
 
474
      <name>format_error(Reason) -> string()</name>
304
475
      <fsummary>Return an error string.</fsummary>
305
476
      <type>
306
 
        <v>ErrorCode = term()</v>
307
 
      </type>
308
 
      <desc>
309
 
        <p>Returns a diagnostic string describing an error.</p>
310
 
      </desc>
311
 
    </func>
312
 
    <func>
313
 
      <name>getopts(Socket, OptionsTags) -> {ok, Options} | {error, Reason}</name>
314
 
      <fsummary>Get options set for socket</fsummary>
315
 
      <type>
316
 
        <v>Socket = sslsocket()</v>
317
 
        <v>OptionTags = [optiontag()]()</v>
318
 
      </type>
319
 
      <desc>
320
 
        <p>Returns the options the tags of which are <c>OptionTags</c> for
321
 
          for the socket <c>Socket</c>. </p>
322
 
      </desc>
323
 
    </func>
324
 
    <func>
325
 
      <name>listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}</name>
326
 
      <fsummary>Set up a socket to listen on a port on the local host.</fsummary>
327
 
      <type>
328
 
        <v>Port = integer()</v>
329
 
        <v>Options = [listen_option()]</v>
330
 
        <v>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()}</v>
331
 
        <v>ListenSocket = sslsocket()</v>
332
 
      </type>
333
 
      <desc>
334
 
        <p>Sets up a socket to listen on port <c>Port</c> at the local host.
335
 
          If <c>Port</c> is zero, <c>listen/2</c> picks an available port
336
 
          number (use <c>port/1</c> to retrieve it).
337
 
          </p>
338
 
        <p>The listen queue size defaults to 5. If a different value is 
339
 
          wanted, the option <c>{backlog, Size}</c> should be added to the 
340
 
          list of options.
341
 
          </p>
342
 
        <p>An empty <c>Options</c> list is considered an error, and
343
 
          <c>{error, enooptions}</c> is returned.
344
 
          </p>
345
 
        <p>The returned <c>ListenSocket</c> can only be used in calls to 
346
 
          <c>transport_accept/[1,2]</c>.</p>
347
 
      </desc>
348
 
    </func>
349
 
    <func>
350
 
      <name>peercert(Socket) -> </name>
351
 
      <name>peercert(Socket, Opts) -> {ok, Cert} | {ok, Subject} |  {error, Reason}</name>
 
477
        <v>Reason = term()</v>
 
478
      </type>
 
479
      <desc>
 
480
        <p>Presents the error returned by an ssl function as a printable string.</p>
 
481
      </desc>
 
482
    </func>
 
483
   
 
484
    <func>
 
485
      <name>getopts(Socket) -> </name>
 
486
      <name>getopts(Socket, OptionNames) ->
 
487
        {ok, [socketoption()]} | {error, Reason}</name>
 
488
      <fsummary>Get the value of the specified options.</fsummary>
 
489
      <type>
 
490
        <v>Socket = sslsocket()</v>
 
491
        <v>OptionNames = [property()]</v>
 
492
      </type>
 
493
      <desc>
 
494
        <p>Get the value of the specified socket options, if no
 
495
          options are specified all options are returned.
 
496
        </p>
 
497
      </desc>
 
498
    </func>
 
499
 
 
500
    <func>
 
501
      <name>listen(Port, Options) ->
 
502
        {ok, ListenSocket} | {error, Reason}</name>
 
503
      <fsummary>Creates a ssl listen socket.</fsummary>
 
504
      <type>
 
505
        <v>Port = integer()</v>
 
506
        <v>Options = options()</v>
 
507
        <v>ListenSocket = sslsocket()</v>
 
508
      </type>
 
509
      <desc>
 
510
        <p>Creates a ssl listen socket.</p>
 
511
      </desc>
 
512
    </func>
 
513
 
 
514
    <func>
 
515
      <name>peercert(Socket) -> {ok, Cert} | {error, Reason}</name>
352
516
      <fsummary>Return the peer certificate.</fsummary>
353
 
      <type>
 
517
     <type>
354
518
        <v>Socket = sslsocket()</v>
355
 
        <v>Opts = [pkix | ssl | subject]()</v>
356
 
        <v>Cert = term()()</v>
357
 
        <v>Subject = term()()</v>
 
519
        <v>Cert = binary()</v>
358
520
      </type>
359
521
      <desc>
360
 
        <p><c>peercert(Cert)</c> is equivalent to <c>peercert(Cert, [])</c>.
361
 
          </p>
362
 
        <p>The form of the returned certificate depends on the
363
 
          options.
364
 
          </p>
365
 
        <p>If the options list is empty the certificate is returned as
366
 
          a DER encoded binary.
367
 
          </p>
368
 
        <p>The options <c>pkix</c> and <c>ssl</c> implies that the
369
 
          certificate is returned as a parsed ASN.1 structure in the
370
 
          form of an Erlang term.
371
 
          </p>
372
 
        <p>The <c>ssl</c> option gives a more elaborate return
373
 
          structure, with more explicit information. In particular
374
 
          object identifiers are replaced by atoms.
375
 
          </p>
376
 
        <p>The options <c>pkix</c>, and <c>ssl</c> are mutually
377
 
          exclusive.
378
 
          </p>
379
 
        <p>The option <c>subject</c> implies that only the subject's
380
 
          distinguished name part of the peer certificate is returned.
381
 
          It can only be used together with the option <c>pkix</c> or
382
 
          the option <c>ssl</c>.</p>
 
522
        <p>The peer certificate is returned as a DER encoded binary.
 
523
          The certificate can be decoded with <c>public_key:pkix_decode_cert/2</c>.
 
524
        </p>
383
525
      </desc>
384
526
    </func>
385
527
    <func>
386
 
      <name>peername(Socket) -> {ok, {Address, Port}} | {error, Reason}</name>
 
528
      <name>peername(Socket) -> {ok, {Address, Port}} |
 
529
        {error, Reason}</name>
387
530
      <fsummary>Return peer address and port.</fsummary>
388
531
      <type>
389
532
        <v>Socket = sslsocket()</v>
394
537
        <p>Returns the address and port number of the peer.</p>
395
538
      </desc>
396
539
    </func>
397
 
    <func>
398
 
      <name>pid(Socket) -> pid()</name>
399
 
      <fsummary>Return the pid of the socket process.</fsummary>
400
 
      <type>
401
 
        <v>Socket = sslsocket()</v>
402
 
      </type>
403
 
      <desc>
404
 
        <p>Returns the pid of the socket process. The returned pid should
405
 
          only be used for receiving exit messages.</p>
406
 
      </desc>
407
 
    </func>
408
 
    <func>
409
 
      <name>recv(Socket, Length) -> {ok, Data} | {error, Reason}</name>
410
 
      <name>recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}</name>
411
 
      <fsummary>Receive data on socket.</fsummary>
412
 
      <type>
413
 
        <v>Socket = sslsocket()</v>
414
 
        <v>Length = integer() >= 0</v>
 
540
    
 
541
    <func>
 
542
      <name>recv(Socket, Length) -> </name>
 
543
      <name>recv(Socket, Length, Timeout) -> {ok, Data} | {error,
 
544
        Reason}</name>
 
545
      <fsummary>Receive data on a socket.</fsummary>
 
546
      <type>
 
547
        <v>Socket = sslsocket()</v>
 
548
        <v>Length = integer()</v>
415
549
        <v>Timeout = integer()</v>
416
 
        <v>Data = bytes() | binary()</v>
 
550
        <v>Data = [char()] | binary()</v>
417
551
      </type>
418
552
      <desc>
419
 
        <p>Receives data on socket <c>Socket</c> when the socket is in
420
 
          passive mode, i.e. when the option <c>{active, false}</c>
421
 
          has been specified.
422
 
          </p>
423
 
        <p>A notable return value is <c>{error, closed}</c> which
424
 
          indicates that the socket is closed.
425
 
          </p>
426
 
        <p>A positive value of the <c>Length</c> argument is only
427
 
          valid when the socket is in raw mode (option <c>{packet, 0}</c> is set, and the option <c>binary</c> is <em>not</em>
428
 
          set); otherwise it should be set to 0, whence all available
429
 
          bytes are returned.
430
 
          </p>
431
 
        <p>If the optional <c>Timeout</c> parameter is specified, and
432
 
          no data was available within the given time, <c>{error, timeout}</c> is returned. The default value for
433
 
          <c>Timeout</c> is <c>infinity</c>.</p>
 
553
        <p>This function receives a packet from a socket in passive
 
554
          mode. A closed socket is indicated by a return value
 
555
          <c>{error, closed}</c>.</p>
 
556
        <p>The <c>Length</c> argument is only meaningful when
 
557
          the socket is in <c>raw</c> mode and denotes the number of
 
558
          bytes to read. If <c>Length</c> = 0, all available bytes are
 
559
          returned. If <c>Length</c> &gt; 0, exactly <c>Length</c>
 
560
          bytes are returned, or an error; possibly discarding less
 
561
          than <c>Length</c> bytes of data when the socket gets closed
 
562
          from the other side.</p>
 
563
        <p>The optional <c>Timeout</c> parameter specifies a timeout in
 
564
          milliseconds. The default value is <c>infinity</c>.</p>
434
565
      </desc>
435
566
    </func>
 
567
    
436
568
    <func>
437
 
      <name>seed(Data) -> ok | {error, Reason}</name>
438
 
      <fsummary>Seed the ssl random generator.</fsummary>
 
569
      <name>renegotiate(Socket) -> ok | {error, Reason}</name>
 
570
      <fsummary> Initiates a new handshake.</fsummary>
439
571
      <type>
440
 
        <v>Data = iolist() | binary()</v>
 
572
        <v>Socket = sslsocket()</v>
441
573
      </type>
442
 
      <desc>
443
 
        <p>Seeds the ssl random generator.
444
 
          </p>
445
 
        <p>It is strongly advised to seed the random generator after
446
 
          the ssl application has been started, and before any
447
 
          connections are established. Although the port program
448
 
          interfacing to the OpenSSL libraries does a "random" seeding
449
 
          of its own in order to make everything work properly, that
450
 
          seeding is by no means random for the world since it has a 
451
 
          constant value which is known to everyone reading the source
452
 
          code of the seeding. 
453
 
          </p>
454
 
        <p>A notable return value is <c>{error, edata}}</c> indicating that
455
 
          <c>Data</c> was not a binary nor an iolist.</p>
 
574
      <desc><p>Initiates a new handshake. A notable return value is
 
575
      <c>{error, renegotiation_rejected}</c> indicating that the peer
 
576
      refused to go through with the renegotiation but the connection
 
577
      is still active using the previously negotiated session.</p>
456
578
      </desc>
457
579
    </func>
 
580
    
458
581
    <func>
459
582
      <name>send(Socket, Data) -> ok | {error, Reason}</name>
460
583
      <fsummary>Write data to a socket.</fsummary>
480
603
          <c>Socket</c>. </p>
481
604
      </desc>
482
605
    </func>
 
606
 
483
607
    <func>
484
 
      <name>ssl_accept(Socket) -> ok | {error, Reason}</name>
485
 
      <name>ssl_accept(Socket, Timeout) -> ok | {error, Reason}</name>
486
 
      <fsummary>Perform server-side SSL handshake and key exchange</fsummary>
 
608
      <name>shutdown(Socket, How) -> ok | {error, Reason}</name>
 
609
      <fsummary>Immediately close a socket</fsummary>
487
610
      <type>
488
611
        <v>Socket = sslsocket()</v>
 
612
        <v>How = read | write | read_write</v>
 
613
        <v>Reason = reason()</v>
 
614
      </type>
 
615
      <desc>
 
616
        <p>Immediately close a socket in one or two directions.</p>
 
617
        <p><c>How == write</c> means closing the socket for writing,
 
618
          reading from it is still possible.</p>
 
619
        <p>To be able to handle that the peer has done a shutdown on
 
620
          the write side, the <c>{exit_on_close, false}</c> option
 
621
          is useful.</p>
 
622
      </desc>
 
623
    </func>
 
624
    
 
625
    <func>
 
626
      <name>ssl_accept(ListenSocket) -> </name>
 
627
      <name>ssl_accept(ListenSocket, Timeout) -> ok | {error, Reason}</name>
 
628
      <fsummary>Perform server-side SSL handshake</fsummary>
 
629
      <type>
 
630
        <v>ListenSocket = sslsocket()</v>
489
631
        <v>Timeout = integer()</v>
490
 
        <v>Reason = atom()</v>
 
632
        <v>Reason = term()</v>
491
633
      </type>
492
634
      <desc>
493
635
        <p>The <c>ssl_accept</c> function establish the SSL connection
494
636
          on the server side. It should be called directly after
495
637
          <c>transport_accept</c>, in the spawned server-loop.</p>
496
 
        <p>Note that the ssl connection is not complete until <c>ssl_accept</c>
497
 
          has returned <c>true</c>, and if an error is returned, the socket
498
 
          is unavailable and for instance <c>close/1</c> will crash.</p>
499
 
      </desc>
500
 
    </func>
501
 
    <func>
502
 
      <name>sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}</name>
 
638
      </desc>
 
639
    </func>
 
640
 
 
641
    <func>
 
642
      <name>ssl_accept(ListenSocket, SslOptions) -> </name>
 
643
      <name>ssl_accept(ListenSocket, SslOptions, Timeout) -> {ok, Socket} | {error, Reason}</name>
 
644
      <fsummary>Perform server-side SSL handshake</fsummary>
 
645
      <type>
 
646
        <v>ListenSocket = socket()</v>
 
647
        <v>SslOptions = ssloptions()</v>
 
648
        <v>Timeout = integer()</v>
 
649
        <v>Reason = term()</v>
 
650
      </type>
 
651
      <desc>
 
652
        <p> Upgrades a gen_tcp, or
 
653
          equivalent, socket to a ssl socket i.e. performs the
 
654
        ssl server-side handshake.</p>
 
655
        <p><warning>Note that the listen socket should be in {active, false} mode
 
656
        before telling the client that the server is ready to upgrade
 
657
        and calling this function, otherwise the upgrade may
 
658
        or may not succeed depending on timing.</warning></p>
 
659
      </desc>
 
660
    </func>
 
661
    
 
662
    <func>
 
663
      <name>sockname(Socket) -> {ok, {Address, Port}} |
 
664
        {error, Reason}</name>
503
665
      <fsummary>Return the local address and port.</fsummary>
504
666
      <type>
505
667
        <v>Socket = sslsocket()</v>
511
673
          <c>Socket</c>.</p>
512
674
      </desc>
513
675
    </func>
514
 
    <func>
515
 
      <name>transport_accept(Socket) -> {ok, NewSocket} | {error, Reason}</name>
516
 
      <name>transport_accept(Socket, Timeout) -> {ok, NewSocket} | {error, Reason}</name>
517
 
      <fsummary>Accept an incoming connection and prepare for <c>ssl_accept</c></fsummary>
 
676
    
 
677
    <func>
 
678
      <name>start() -> </name>
 
679
      <name>start(Type) -> ok | {error, Reason}</name>
 
680
      <fsummary>Starts the Ssl application. </fsummary>
 
681
      <type>
 
682
        <v>Type =  permanent | transient | temporary</v>
 
683
      </type>
 
684
      <desc>
 
685
        <p>Starts the Ssl application. Default type
 
686
          is temporary.
 
687
          <seealso marker="kernel:application">application(3)</seealso></p>
 
688
      </desc>
 
689
    </func>
 
690
    <func>
 
691
      <name>stop() -> ok </name>
 
692
      <fsummary>Stops the Ssl application.</fsummary>
 
693
      <desc>
 
694
        <p>Stops the Ssl application.
 
695
          <seealso marker="kernel:application">application(3)</seealso></p>
 
696
      </desc>
 
697
    </func>
 
698
 
 
699
    <func>
 
700
      <name>transport_accept(Socket) -></name>
 
701
      <name>transport_accept(Socket, Timeout) ->
 
702
        {ok, NewSocket} | {error, Reason}</name>
 
703
      <fsummary>Accept an incoming connection and
 
704
        prepare for <c>ssl_accept</c></fsummary>
518
705
      <type>
519
706
        <v>Socket = NewSocket = sslsocket()</v>
520
707
        <v>Timeout = integer()</v>
521
 
        <v>Reason = atom()</v>
 
708
        <v>Reason = reason()</v>
522
709
      </type>
523
710
      <desc>
524
711
        <p>Accepts an incoming connection request on a listen socket.
525
 
          <c>ListenSocket</c> must be a socket returned from <c>listen/2</c>.
526
 
          The socket returned should be passed to <c>ssl_accept</c> to
527
 
          complete ssl handshaking and establishing the connection.</p>
 
712
          <c>ListenSocket</c> must be a socket returned from
 
713
          <c>listen/2</c>.  The socket returned should be passed to
 
714
          <c>ssl_accept</c> to complete ssl handshaking and
 
715
          establishing the connection.</p>
528
716
        <warning>
529
717
          <p>The socket returned can only be used with <c>ssl_accept</c>,
530
718
            no traffic can be sent or received before that call.</p>
531
719
        </warning>
532
 
        <p>The accepted socket inherits the options set for <c>ListenSocket</c>
533
 
          in <c>listen/2</c>.</p>
534
 
        <p>The default value for <c>Timeout</c> is <c>infinity</c>. If 
535
 
          <c>Timeout</c> is specified, and no connection is accepted within
536
 
          the given time, <c>{error, timeout}</c> is returned.</p>
 
720
        <p>The accepted socket inherits the options set for
 
721
          <c>ListenSocket</c> in <c>listen/2</c>.</p>
 
722
        <p>The default
 
723
          value for <c>Timeout</c> is <c>infinity</c>. If
 
724
          <c>Timeout</c> is specified, and no connection is accepted
 
725
          within the given time, <c>{error, timeout}</c> is
 
726
          returned.</p>
537
727
      </desc>
538
728
    </func>
 
729
    
539
730
    <func>
540
 
      <name>version() -> {ok, {SSLVsn, CompVsn, LibVsn}}</name>
541
 
      <fsummary>Return the version of SSL.</fsummary>
 
731
      <name>versions() ->
 
732
        [{SslAppVer, SupportedSslVer, AvailableSslVsn}]</name>
 
733
      <fsummary>Returns version information relevant for the
 
734
        ssl application.</fsummary>
542
735
      <type>
543
 
        <v>SSLVsn = CompVsn = LibVsn = string()()</v>
 
736
        <v>SslAppVer = string()</v>
 
737
        <v>SupportedSslVer = [protocol()]</v>
 
738
        <v>AvailableSslVsn = [protocol()]</v>
544
739
      </type>
545
740
      <desc>
546
 
        <p>Returns the SSL application version (<c>SSLVsn</c>), the library
547
 
          version used when compiling the SSL application port program
548
 
          (<c>CompVsn</c>), and the actual library version used when
549
 
          dynamically linking in runtime (<c>LibVsn</c>).
550
 
          </p>
551
 
        <p>If the SSL application has not been started, <c>CompVsn</c> and
552
 
          <c>LibVsn</c> are empty strings.
553
 
          </p>
 
741
        <p>
 
742
          Returns version information relevant for the
 
743
          ssl application.</p>
554
744
      </desc>
555
745
    </func>
556
 
  </funcs>
557
 
 
558
 
  <section>
559
 
    <title>ERRORS</title>
560
 
    <p>The possible error reasons and the corresponding diagnostic strings 
561
 
      returned by <c>format_error/1</c> are either the same as those defined
562
 
      in the <c>inet(3)</c> reference manual, or as follows:
563
 
      </p>
564
 
    <taglist>
565
 
      <tag><c>closed</c></tag>
566
 
      <item>
567
 
        <p>Connection closed for the operation in question.
568
 
          </p>
569
 
      </item>
570
 
      <tag><c>ebadsocket</c></tag>
571
 
      <item>
572
 
        <p>Connection not found (internal error).
573
 
          </p>
574
 
      </item>
575
 
      <tag><c>ebadstate</c></tag>
576
 
      <item>
577
 
        <p>Connection not in connect state (internal error).
578
 
          </p>
579
 
      </item>
580
 
      <tag><c>ebrokertype</c></tag>
581
 
      <item>
582
 
        <p>Wrong broker type (internal error).
583
 
          </p>
584
 
      </item>
585
 
      <tag><c>ecacertfile</c></tag>
586
 
      <item>
587
 
        <p>Own CA certificate file is invalid.
588
 
          </p>
589
 
      </item>
590
 
      <tag><c>ecertfile</c></tag>
591
 
      <item>
592
 
        <p>Own certificate file is invalid.
593
 
          </p>
594
 
      </item>
595
 
      <tag><c>echaintoolong</c></tag>
596
 
      <item>
597
 
        <p>The chain of certificates provided by peer is too long.
598
 
          </p>
599
 
      </item>
600
 
      <tag><c>ecipher</c></tag>
601
 
      <item>
602
 
        <p>Own list of specified ciphers is invalid.
603
 
          </p>
604
 
      </item>
605
 
      <tag><c>ekeyfile</c></tag>
606
 
      <item>
607
 
        <p>Own private key file is invalid.
608
 
          </p>
609
 
      </item>
610
 
      <tag><c>ekeymismatch</c></tag>
611
 
      <item>
612
 
        <p>Own private key does not match own certificate.
613
 
          </p>
614
 
      </item>
615
 
      <tag><c>enoissuercert</c></tag>
616
 
      <item>
617
 
        <p>Cannot find certificate of issuer of certificate provided
618
 
          by peer.
619
 
          </p>
620
 
      </item>
621
 
      <tag><c>enoservercert</c></tag>
622
 
      <item>
623
 
        <p>Attempt to do accept without having set own certificate.
624
 
          </p>
625
 
      </item>
626
 
      <tag><c>enotlistener</c></tag>
627
 
      <item>
628
 
        <p>Attempt to accept on a non-listening socket.
629
 
          </p>
630
 
      </item>
631
 
      <tag><c>enoproxysocket</c></tag>
632
 
      <item>
633
 
        <p>No proxy socket found (internal error).
634
 
          </p>
635
 
      </item>
636
 
      <tag><c>enooptions</c></tag>
637
 
      <item>
638
 
        <p>The list of options is empty.
639
 
          </p>
640
 
      </item>
641
 
      <tag><c>enotstarted</c></tag>
642
 
      <item>
643
 
        <p>The SSL application has not been started.
644
 
          </p>
645
 
      </item>
646
 
      <tag><c>eoptions</c></tag>
647
 
      <item>
648
 
        <p>Invalid list of options.
649
 
          </p>
650
 
      </item>
651
 
      <tag><c>epeercert</c></tag>
652
 
      <item>
653
 
        <p>Certificate provided by peer is in error.
654
 
          </p>
655
 
      </item>
656
 
      <tag><c>epeercertexpired</c></tag>
657
 
      <item>
658
 
        <p>Certificate provided by peer has expired.
659
 
          </p>
660
 
      </item>
661
 
      <tag><c>epeercertinvalid</c></tag>
662
 
      <item>
663
 
        <p>Certificate provided by peer is invalid.
664
 
          </p>
665
 
      </item>
666
 
      <tag><c>eselfsignedcert</c></tag>
667
 
      <item>
668
 
        <p>Certificate provided by peer is self signed.
669
 
          </p>
670
 
      </item>
671
 
      <tag><c>esslaccept</c></tag>
672
 
      <item>
673
 
        <p>Server SSL handshake procedure between client and server failed.
674
 
          </p>
675
 
      </item>
676
 
      <tag><c>esslconnect</c></tag>
677
 
      <item>
678
 
        <p>Client SSL handshake procedure between client and server failed.
679
 
          </p>
680
 
      </item>
681
 
      <tag><c>esslerrssl</c></tag>
682
 
      <item>
683
 
        <p>SSL protocol failure. Typically because of a fatal alert 
684
 
          from peer.
685
 
          </p>
686
 
      </item>
687
 
      <tag><c>ewantconnect</c></tag>
688
 
      <item>
689
 
        <p>Protocol wants to connect, which is not supported in
690
 
          this version of the SSL application.
691
 
          </p>
692
 
      </item>
693
 
      <tag><c>ex509lookup</c></tag>
694
 
      <item>
695
 
        <p>Protocol wants X.509 lookup, which is not supported in
696
 
          this version of the SSL application.
697
 
          </p>
698
 
      </item>
699
 
      <tag><c>{badcall, Call}</c></tag>
700
 
      <item>
701
 
        <p>Call not recognized for current mode (active or passive) and
702
 
          state of socket.
703
 
          </p>
704
 
      </item>
705
 
      <tag><c>{badcast, Cast}</c></tag>
706
 
      <item>
707
 
        <p>Call not recognized for current mode (active or passive) and
708
 
          state of socket. 
709
 
          </p>
710
 
      </item>
711
 
      <tag><c>{badinfo, Info}</c></tag>
712
 
      <item>
713
 
        <p>Call not recognized for current mode (active or passive) and
714
 
          state of socket.
715
 
          </p>
716
 
      </item>
717
 
    </taglist>
718
 
  </section>
719
 
 
 
746
  </funcs> 
 
747
      
720
748
  <section>
721
749
    <title>SEE ALSO</title>
722
 
    <p>gen_tcp(3), inet(3)
723
 
      </p>
 
750
    <p><seealso marker="kernel:inet">inet(3) </seealso> and 
 
751
      <seealso marker="kernel:gen_tcp">gen_tcp(3) </seealso>
 
752
    </p>
724
753
  </section>
725
 
  
 
754
 
726
755
</erlref>
727
756
 
728