From bfaabab8c130a088d7bd703eb5e57c41fcd1f74f Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Mon, 6 Sep 2010 14:39:09 +0200 Subject: Updated documentation for ssl-4.0.1 --- lib/ssl/doc/src/ssl.xml | 285 +++++++++++++++++++----------- lib/ssl/doc/src/ssl_distribution.xml | 10 +- lib/ssl/doc/src/ssl_protocol.xml | 12 +- lib/ssl/doc/src/ssl_session_cache_api.xml | 20 +-- 4 files changed, 200 insertions(+), 127 deletions(-) diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index def61bcf03..0f3054aec3 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -1,4 +1,4 @@ - + @@ -69,10 +69,13 @@

ssloption() = {verify, verify_type()} | + {verify_fun, {fun(), term()}} | {fail_if_no_peer_cert, boolean()} {depth, integer()} | - {certfile, path()} | {keyfile, path()} | {password, string()} | - {cacertfile, path()} | {dhfile, path()} | {ciphers, ciphers()} | + {cert, der_bin()}| {certfile, path()} | + {key, der_bin()} | {keyfile, path()} | {password, string()} | + {cacerts, [der_bin()]} | {cacertfile, path()} | + |{dh, der_bin()} | {dhfile, path()} | {ciphers, ciphers()} | {ssl_imp, ssl_imp()} | {reuse_sessions, boolean()} | {reuse_session, fun()}

@@ -91,6 +94,8 @@

verify_type() = verify_none | verify_peer

path() = string() - representing a file path.

+ +

der_bin() = binary() -Asn1 DER encoded entity as an erlang binary.

host() = hostname() | ipaddress()

@@ -121,115 +126,52 @@

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

- -
- SSL OPTION DESCRIPTIONS + +
+ SSL OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT + +

Options described here are options that are have the same + meaning in the client and the server. +

- {verify, verify_type()} - If verify_none is specified x509-certificate - path validation errors at the client side - will not automatically cause the connection to fail, as - it will if the verify type is verify_peer. See also - the option verify_fun. - Servers only do the path validation if verify_peer is set to - true, as it then will - send a certificate request to - the client (this message is not sent if the verify option is - verify_none) and you may then also want to specify - the option fail_if_no_peer_cert. - - {fail_if_no_peer_cert, boolean()} - Used together with {verify, verify_peer} by a ssl server. - If set to true, - the server will fail if the client does not have a certificate - to send, e.i sends a empty certificate, if set to false it will - only fail if the client sends a invalid certificate (an empty - certificate is considered valid). - + {cert, der_bin()} + The DER encoded users certificate. If this option + is supplied it will override the certfile option. - {verify_fun, fun(ErrorList) -> boolean()} - Used by the ssl client to determine if - x509-certificate path validations errors are acceptable or - if the connection should fail. Defaults to: - - -fun(ErrorList) -> - case lists:foldl(fun({bad_cert,unknown_ca}, Acc) -> - Acc; - (Other, Acc) -> - [Other | Acc] - end, [], ErrorList) of - [] -> - true; - [_|_] -> - false - end -end - - I.e. by default if the only error found was that the CA-certificate - holder was unknown this will be accepted. - - Possible errors in the error list are: - {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, - {bad_cert, invalid_signature}, {bad_cert, name_not_permitted}, - {bad_cert, unknown_ca}, - {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, - {bad_cert, invalid_signature}, {bad_cert, name_not_permitted}, - {bad_cert, cert_revoked} (not implemented yet), - {bad_cert, unknown_critical_extension} or {bad_cert, term()} - - + {certfile, path()} + Path to a file containing the user's certificate. - {validate_extensions_fun, fun()} - - This options makes it possible to supply a fun to validate - possible application specific certificate extensions - during the certificat path validation. This option - will be better documented onec the public_key API is more - mature. - + {key, der_bin()} + The DER encoded users private key. If this option + is supplied it will override the keyfile option. - {depth, integer()} - 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. Optional for clients but note - that some servers requires that the client can certify - itself. {keyfile, path()} Path to file containing user's private PEM encoded key. As PEM-files may contain several entries this option defaults to the same file as given by certfile option. + {password, string()} String containing the user's password. Only used if the private keyfile is password protected. + + {cacerts, [der_bin()]} + The DER encoded trusted certificates. If this option + is supplied it will override the cacertfile option. + {cacertfile, path()} Path to file containing PEM encoded CA certificates (trusted certificates used for verifying a peer certificate). May be omitted if you do not want to verify the peer. - {dhfile, path()} - Path to file containing PEM encoded Diffie Hellman parameters, - for the server to use if a cipher suite using Diffie Hellman key exchange - is negotiated. If not specified hardcode parameters will be used. - - {ciphers, ciphers()} - The function ciphers_suites/0 can - be used to find all available ciphers. + The cipher suites that should be supported. The function + ciphers_suites/0 can be used to find all available + ciphers. {ssl_imp, ssl_imp()} @@ -237,13 +179,152 @@ end new. + {secure_renegotiate, boolean()} + Specifies if to reject renegotiation attempt that does + not live up to RFC 5746. By default secure_renegotiate is + set to false i.e. secure renegotiation will be used if possible + but it will fallback to unsecure renegotiation if the peer + does not support RFC 5746. + + + {depth, integer()} + 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. + + + {verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}} + +

The verification fun should be defined as:

+ + + fun(OtpCert :: #'OtpCertificate'{}, + Event :: {bad_cert, Reason :: atom()} | + {extension, #'Extension'{}}, InitialUserState :: term()) -> + {valid, UserState :: term()} | {fail, Reason :: term()} | + {unknown, UserState :: term()}. + + +

The verify fun will be called during the X509-path + validation when an error or an extension unknown to the ssl + application is encountered. See + public_key(3) + for definition of #'OtpCertificate'{} and #'Extension'{}.

+ +

If the verify callback fun returns {fail, Reason}, the + verification process is immediately stopped and an alert is + sent to the peer and the TLS/SSL handshake is terminated. If + the verify callback fun returns {valid, UserState}, the + verification process is continued. If the verify callback fun + always returns {valid, UserState}, the TLS/SSL handshake will + not be terminated with respect to verification failures and + the connection will be established. If called with an + extension unknown to the user application the return value + {unknown, UserState} should be used.

+ +

The default verify_fun option in verify_peer mode:

+ + + {fun(_,{bad_cert, _} = Reason, _) -> + {fail, Reason}; + (_,{extension, _}, UserState) -> + {unknown, UserState} + end, []} + + +

The default verify_fun option in verify_none mode:

+ + + {fun(_,{bad_cert, unknown_ca}, UserState) -> + {valid, UserState}; + (_,{bad_cert, _} = Reason, _) -> + {fail, Reason}; + (_,{extension, _}, UserState) -> + {unknown, UserState} + end, []} + + +

Possible path validation errors: + {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}, + {bad_cert, invalid_subject_altname}

+ + + + +
+ +
+ SSL OPTION DESCRIPTIONS - CLIENT SIDE + +

Option described here are client specific or has a slightly different + meaning in the client than in the server.

+ + + {verify, verify_type()} + In verify_none mode the x509-path validation error {bad_cert, unknown_ca} + will automatically be accepted. See also the verify_fun option. + + {reuse_sessions, boolean()} + Specifies if client should try to reuse sessions + when possible. + + + +
+ +
+ SSL OPTION DESCRIPTIONS - SERVER SIDE + +

Option described here are server specific or has a slightly different + meaning in the server than in the client.

+ + + + {dh, der_bin()} + The DER encoded Diffie Hellman parameters. If this option + is supplied it will override the dhfile option. + + + {dhfile, path()} + Path to file containing PEM encoded Diffie Hellman parameters, + for the server to use if a cipher suite using Diffie Hellman key exchange + is negotiated. If not specified default parameters will be used. + + + {verify, verify_type()} + Servers only do the x509-path validation in verify_peer + mode, as it then will send a certificate request to the client + (this message is not sent if the verify option is verify_none) + and you may then also want to specify the option + fail_if_no_peer_cert. + + + {fail_if_no_peer_cert, boolean()} + Used together with {verify, verify_peer} by a ssl server. + If set to true, the server will fail if the client does not have + a certificate to send, i.e. sends a empty certificate, if set to + false it will only fail if the client sends a invalid + certificate (an empty certificate is considered valid). + + {reuse_sessions, boolean()} - Specifies if ssl sessions should be reused - when possible. + Specifies if the server should agree to reuse sessions + when the clients request to do so. See also the reuse_session + option. - {reuse_session, fun(SuggestedSessionId, - PeerCert, Compression, CipherSuite) -> boolean()} + {reuse_session, fun(SuggestedSessionId, + PeerCert, Compression, CipherSuite) -> boolean()} Enables the ssl server to have a local policy for deciding if a session should be reused or not, only meaning full if reuse_sessions is set to true. @@ -252,14 +333,6 @@ end and CipherSuite of type ciphersuite(). - {secure_renegotiate, boolean()} - Specifies if to reject renegotiation attempt that does - not live up to RFC 5746. By default secure_renegotiate is - set to false e.i. secure renegotiation will be used if possible - but it will fallback to unsecure renegotiation if the peer - does not support RFC 5746. - -
@@ -316,7 +389,7 @@ end Reason = term()

Upgrades a gen_tcp, or equivalent, - connected socket to a ssl socket e.i performs the + connected socket to a ssl socket i.e. performs the client-side ssl handshake.

 @@ -559,12 +632,12 @@ end

Upgrades a gen_tcp, or - equivalent, socket to a ssl socket e.i performs the + equivalent, socket to a ssl socket i.e. performs the ssl server-side handshake.

-

Note that the listen socket should be in {active, false} mode +

Note that the listen socket should be in {active, false} mode before telling the client that the server is ready to upgrade and calling this function, otherwise the upgrade may - or may not succeed depending on timing.

+ or may not succeed depending on timing.

 diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml index 4067fb8a22..7bcc12eb5f 100644 --- a/lib/ssl/doc/src/ssl_distribution.xml +++ b/lib/ssl/doc/src/ssl_distribution.xml @@ -1,10 +1,10 @@ - +
- 20002009 + 20002010 Ericsson AB. All Rights Reserved. @@ -36,7 +36,7 @@

Note this documentation is written for the old ssl implementation and - will be updated for the new one once this functionallity is + will be updated for the new one once this functionality is supported by the new implementation.

@@ -55,7 +55,7 @@ all participating Erlang nodes in a distributed system must use this distribution module.

The security depends on how the connections are set up, one can - use key files or certificates to just get a crypted + use key files or certificates to just get a encrypted connection. One can also make the SSL package verify the certificates of other nodes to get additional security. Cookies are however always used as they can be used to @@ -179,7 +179,7 @@ Eshell V5.0 (abort with ^G) certfile can (and usually needs to) be specified as client_certfile and server_certfile. The client_certfile is used when the distribution initiates a - connection to another node and the server_cerfile is used + connection to another node and the server_certfile is used when accepting a connection from a remote node.

The command line argument for specifying the SSL options is named -ssl_dist_opt and should be followed by an even number of diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml index 726b9a4eeb..6936408881 100644 --- a/lib/ssl/doc/src/ssl_protocol.xml +++ b/lib/ssl/doc/src/ssl_protocol.xml @@ -1,10 +1,10 @@ - +

- 20032009 + 20032010 Ericsson AB. All Rights Reserved. @@ -44,7 +44,7 @@
Security overview -

To achive authentication and privacy the client and server will +

To achieve authentication and privacy the client and server will perform a TLS Handshake procedure before transmitting or receiving any data. During the handshake they agree on a protocol version and cryptographic algorithms, they generate shared secrets using public @@ -56,7 +56,7 @@ Data Privacy and Integrity

A symmetric key algorithm has one key only. The key is - used for both encryption and decryption. These algoritms are fast + used for both encryption and decryption. These algorithms are fast compared to public key algorithms (using two keys, a public and a private one) and are therefore typically used for encrypting bulk data. @@ -66,7 +66,7 @@ for each connection and are based on a secret negotiated in the TLS handshake.

-

The TLS handsake protocol and data transfer is run on top of +

The TLS handshake protocol and data transfer is run on top of the TLS Record Protocol that uses a keyed-hash MAC (Message Authenticity Code), or HMAC, to protect the message's data integrity. From the TLS RFC "A Message Authentication Code is a @@ -85,7 +85,7 @@ with the private key of the issuer of the certificate. A chain of trust is build by having the issuer in its turn being certified by an other certificate and so on until you reach the - so called root certificate that is self signed e.i. issued + so called root certificate that is self signed i.e. issued by itself.

Certificates are issued by certification diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml index 7b70c6cf34..e0b07961fb 100644 --- a/lib/ssl/doc/src/ssl_session_cache_api.xml +++ b/lib/ssl/doc/src/ssl_session_cache_api.xml @@ -1,4 +1,4 @@ - + @@ -25,7 +25,7 @@

ssl_session_cache_api Defines the API for the TLS session cache so - that the datastorge scheme can be replaced by + that the data storage scheme can be replaced by defining a new callback module implementing this API.
@@ -56,7 +56,7 @@ Key = key() -

Delets a cache entry. Will only be called from the cache +

Deletes a cache entry. Will only be called from the cache handling process.

@@ -85,10 +85,10 @@ -

Performes possible initializations of the cache and returns +

Performs possible initializations of the cache and returns a reference to it that will be used as parameter to the other api functions. Will be called by the cache handling processes - init function, hence puting the same requierments on it as + init function, hence putting the same requirements on it as a normal process init function.

@@ -96,16 +96,16 @@ lookup(Cache, Key) -> Entry - Looks up a cach entry. + Looks up a cache entry. Cache = cache_ref() Key = key() Entry = session() | undefined -

Looks up a cach entry. Should be callable from any - process. -

+

Looks up a cache entry. Should be callable from any + process. +

@@ -127,7 +127,7 @@ terminate(Cache) -> _ Called by the process that handles the cache when it - is aboute to terminat. + is about to terminate. Cache = term() - as returned by init/0 -- cgit v1.2.3