Ssl

# Module Ssl

    module Ssl: sig .. end

Functions for making encrypted communications using the Secure Socket Layer (SSL). These are mostly bindings to the openssl library.
Author(s): Samuel Mimram

# Exceptions and errors

`type ``ssl_error =`

`|` | `Error_none` | `(*` | No error happened. This is never raised and should disappear in future versions. | `*)`
`|` | `Error_ssl`
`|` | `Error_want_read` | `(*` | The operation did not complete; the same TLS/SSL I/O function should be called again later. | `*)`
`|` | `Error_want_write` | `(*` | The operation did not complete; the same TLS/SSL I/O function should be called again later. | `*)`
`|` | `Error_want_x509_lookup` | `(*` | The operation did not complete because an application callback set by `set_client_cert_cb` has asked to be called again. The TLS/SSL I/O function should be called again later. Details depend on the application. | `*)`
`|` | `Error_syscall` | `(*` | Some I/O error occurred. The OpenSSL error queue may contain more information on the error. | `*)`
`|` | `Error_zero_return` | `(*` | The TLS/SSL connection has been closed. If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned only if a closure alert has occurred in the protocol, i.e. if the connection has been closed cleanly. Note that in this case `Error_zero_return` does not necessarily indicate that the underlying transport has been closed. | `*)`
`|` | `Error_want_connect` | `(*` | The operation did not complete; the same TLS/SSL I/O function should be called again later. | `*)`
`|` | `Error_want_accept` | `(*` | The operation did not complete; the same TLS/SSL I/O function should be called again later. | `*)`

An ssl error has occured (see SSL_get_error(3ssl) for details).

    exception Method_error

The SSL method could not be initalized.

    exception Context_error

    exception Certificate_error

The SSL server certificate could not be initialized.

    exception Private_key_error

The SSL server private key could not be intialized.

    exception Unmatching_keys

The SSL private key does not match the certificate public key.

    exception Invalid_socket

The given socket is invalid.

    exception Handler_error

The SSL handler could not be initialized.

    exception Connection_error of ssl_error

The connection could not be made with the SSL service.

    exception Accept_error of ssl_error

Failed to accept an SSL connection.

    exception Read_error of ssl_error

An error occured while reading data.

    exception Write_error of ssl_error

An error occured while writing data.
`type ``verify_error =`

`|` | `Error_v_unable_to_get_issuer_cert` | `(*` | The issuer certificate could not be found: this occurs if the issuer certificate of an untrusted certificate cannot be found. | `*)`
`|` | `Error_v_unable_to_get_ctl` | `(*` | The CRL of a certificate could not be found. | `*)`
`|` | `Error_v_unable_to_decrypt_cert_signature` | `(*` | The certificate signature could not be decrypted. This means that the actual signature value could not be determined rather than it not matching the expected value, this is only meaningful for RSA keys. | `*)`
`|` | `Error_v_unable_to_decrypt_CRL_signature` | `(*` | The CRL signature could not be decrypted: this means that the actual signature value could not be determined rather than it not matching the expected value. Unused. | `*)`
`|` | `Error_v_unable_to_decode_issuer_public_key` | `(*` | The public key in the certificate SubjectPublicKeyInfo could not be read. | `*)`
`|` | `Error_v_cert_signature_failure` | `(*` | The signature of the certificate is invalid. | `*)`
`|` | `Error_v_CRL_signature_failure` | `(*` | The signature of the certificate is invalid. | `*)`
`|` | `Error_v_cert_not_yet_valid` | `(*` | The certificate is not yet valid: the notBefore date is after the current time. | `*)`
`|` | `Error_v_cert_has_expired` | `(*` | The certificate has expired: that is the notAfter date is before the current time. | `*)`
`|` | `Error_v_CRL_not_yet_valid` | `(*` | The CRL is not yet valid. | `*)`
`|` | `Error_v_CRL_has_expired` | `(*` | The CRL has expired. | `*)`
`|` | `Error_v_error_in_cert_not_before_field` | `(*` | The certificate notBefore field contains an invalid time. | `*)`
`|` | `Error_v_error_in_cert_not_after_field` | `(*` | The certificate notAfter field contains an invalid time. | `*)`
`|` | `Error_v_error_in_CRL_last_update_field` | `(*` | The CRL lastUpdate field contains an invalid time. | `*)`
`|` | `Error_v_error_in_CRL_next_update_field` | `(*` | The CRL nextUpdate field contains an invalid time. | `*)`
`|` | `Error_v_out_of_mem` | `(*` | An error occurred trying to allocate memory. This should never happen. | `*)`
`|` | `Error_v_depth_zero_self_signed_cert` | `(*` | The passed certificate is self signed and the same certificate cannot be found in the list of trusted certificates. | `*)`
`|` | `Error_v_self_signed_cert_in_chain` | `(*` | The certificate chain could be built up using the untrusted certificates but the root could not be found locally. | `*)`
`|` | `Error_v_unable_to_get_issuer_cert_locally` | `(*` | The issuer certificate of a locally looked up certificate could not be found. This normally means the list of trusted certificates is not complete. | `*)`
`|` | `Error_v_unable_to_verify_leaf_signature` | `(*` | No signatures could be verified because the chain contains only one certificate and it is not self signed. | `*)`
`|` | `Error_v_cert_chain_too_long` | `(*` | The certificate chain length is greater than the supplied maximum depth. Unused. | `*)`
`|` | `Error_v_cert_revoked` | `(*` | The certificate has been revoked. | `*)`
`|` | `Error_v_invalid_CA` | `(*` | A CA certificate is invalid. Either it is not a CA or its extensions are not consistent with the supplied purpose. | `*)`
`|` | `Error_v_path_length_exceeded` | `(*` | The basicConstraints pathlength parameter has been exceeded. | `*)`
`|` | `Error_v_invalid_purpose` | `(*` | The supplied certificate cannot be used for the specified purpose. | `*)`
`|` | `Error_v_cert_untrusted` | `(*` | The root CA is not marked as trusted for the specified purpose. | `*)`
`|` | `Error_v_cert_rejected` | `(*` | The root CA is marked to reject the specified purpose. | `*)`
`|` | `Error_v_subject_issuer_mismatch` | `(*` | The current candidate issuer certificate was rejected because its subject name did not match the issuer name of the current certificate. | `*)`
`|` | `Error_v_akid_skid_mismatch` | `(*` | The current candidate issuer certificate was rejected because its subject key identifier was present and did not match the authority key identifier current certificate. | `*)`
`|` | `Error_v_akid_issuer_serial_mismatch` | `(*` | The current candidate issuer certificate was rejected because its issuer name and serial number was present and did not match the authority key identifier of the current certificate. | `*)`
`|` | `Error_v_keyusage_no_certsign` | `(*` | The current candidate issuer certificate was rejected because its keyUsage extension does not permit certificate signing. | `*)`
`|` | `Error_v_application_verification` | `(*` | An application specific error. Unused. | `*)`

Why did the certificate verification fail?

    exception Verify_error of verify_error

An error occured while verifying the certificate.

# Communication

    val init : ?thread_safe:bool -> unit -> unit

Initialize SSL functions. Should be called before calling any other function. The parameter `thread_safe` should be set to true if you use threads in you application (the same effect can achived by calling `Ssl_threads.init` first.

    val get_error_string : unit -> string

Retrieve a human-readable message that corresponds to the last error that occurred.
`type ``protocol =`

`|` | `SSLv23` | `(*` | SSL v3 protocol but can rollback to v2 | `*)`
`|` | `SSLv3` | `(*` | SSL v3 protocol | `*)`
`|` | `TLSv1` | `(*` | TLS v1 protocol | `*)`

Protocol used by SSL.

    type socket

An SSL abstract socket.

## Threads

You should not have to use those functions. They are only here for internal use (they are needed to make the openssl library thread-safe, see the `Ssl_threads` module).

    val thread_safe : bool Pervasives.ref

## Contexts

    type context

A context. A context should be created by a server or client once per program life-time and holds mainly default values for the SSL structures which are later created for the connections.
`type ``context_type =`

`|` | `Client_context` | `(*` | Client connections. | `*)`
`|` | `Server_context` | `(*` | Server connections. | `*)`
`|` | `Both_context` | `(*` | Client and server connections. | `*)`

Type of the context to create.

    val create_context : protocol -> context_type -> context

Create a context.

    val use_certificate : context -> string -> string -> unit

`use_certificate ctx cert privkey` makes the context `ctx` use `cert` as certificate's file name (in PEM format) and `privkey` as private key file name.

    val set_password_callback : context -> (bool -> string) -> unit

Set the callback function called to get passwords for encrypted PEM files. The callback function takes a boolean argument which indicates if it's used for reading/decryption (`false`) or writing/encryption (`true`).

    val set_client_CA_list_from_file : context -> string -> unit

Set the list of CAs sent to the client when requesting a client certificate.
`type ``verify_mode =`

`|` | `Verify_peer`
`|` | `Verify_fail_if_no_peer_cert` | `(*` | Implies `Verify_peer`. | `*)`
`|` | `Verify_client_once` | `(*` | Implies `Verify_peer`. | `*)`

Verification modes (see SSL_CTX_set_verify(3)).

    type verify_callback

A callback function for verification. Warning: this might change in the future.

    val client_verify_callback : verify_callback

Client's verification callback. Warning: this might change in the future.

    val set_verify : context -> verify_mode list -> verify_callback option -> unit

Set the verify mode and callback, see SSL_CTX_set_verify(3). Warning: this might change in the future.

    val set_verify_depth : context -> int -> unit

Set the maximum depth for the certificate chain verification that shall be allowed.

## Ciphers

    type cipher

A cipher. It holds the algorithm information for a particular cipher which are a core part of the SSL/TLS protocol.

    val set_cipher_list : context -> string -> unit

Set the list of available ciphers for a context. See man ciphers(1) for the format of the string.

    val get_cipher : socket -> cipher

Get the cipher used by a socket.

    val get_cipher_description : cipher -> string

Get a description of a cipher.

    val get_cipher_name : cipher -> string

Get the name of a cipher.

    val get_cipher_version : cipher -> string

Get the version of a cipher.

## Certificates

    type certificate

A certificate.

    val read_certificate : string -> certificate

`read_certificate fname` reads the certificate in the file `fname`.

    val write_certificate : string -> certificate -> unit

    val get_certificate : socket -> certificate

Get the certificate used by a socket.

    val get_issuer : certificate -> string

Get the issuer of a certificate.

    val get_subject : certificate -> string

Get the subject of a certificate.

    val load_verify_locations : context -> string -> string -> unit

`load_verify_locations ctxt cafile capath` specifies the locations for the context `ctx`, at which CA certificates for verification purposes are located. `cafile` should be the name of a CA certificates file in PEM format and `capath` should be the name of a directory which contains CA certificates in PEM format. Empty strings can be used in order not to specify on of the parameters (but not both).
Raises `Invalid_argument` if both strings are empty or if one of the files given in arguments could not be found.

    val get_verify_result : socket -> int

Get the verification result.

## Creating, connecting and closing sockets

    val embed_socket : Unix.file_descr -> context -> socket

Embed a Unix socket into an SSL socket.

    val open_connection : protocol -> Unix.sockaddr -> socket

Open an SSL connection.

    val open_connection_with_context : context -> Unix.sockaddr -> socket

Open an SSL connection with the specified context.

    val shutdown_connection : socket -> unit

Close an SSL connection opened with `open_connection`.

    val connect : socket -> unit

Connect an SSL socket.

    val accept : socket -> unit

Accept an SSL connection.

    val flush : socket -> unit

Flush an SSL connection.

    val shutdown : socket -> unit

Close an SSL connection.

## I/O on SSL sockets

    val verify : socket -> unit

Check the result of the verification of the X509 certificate presented by the peer, if any. Raises a `verify_error` on failure.

    val file_descr_of_socket : socket -> Unix.file_descr

Get the file descriptor associated with a socket. It is primarly useful for `select`ing on it; you should not write or read on it.

    val read : socket -> string -> int -> int -> int

`read sock buf off len` receives data from a connected SSL socket.

    val write : socket -> string -> int -> int -> int

`write sock buf off len` sends data over a connected SSL socket.

### High-level communication functions

    val input_string : socket -> string

Input a string on an SSL socket.

    val output_string : socket -> string -> unit

Write a string on an SSL socket.

    val input_char : socket -> char

Input a character on an SSL socket.

    val output_char : socket -> char -> unit

Write a char on an SSL socket.

    val input_int : socket -> int

Input an integer on an SSL socket.

    val output_int : socket -> int -> unit

Write an integer on an SSL socket.