Module `Ssl`Source

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

author Samuel Mimram

OpenSSL version

Sourcetype version = {

major : int;
(*
major version
*)
minor : int;
(*
minor version
*)
patch : int;
(*
patch number
*)

}

in version prior to 3.0, details are dropped: 1.1.1n = 1.1.1f

Sourceval native_library_version : version

Exceptions and errors

Sourcetype ssl_error =

| Error_none
(*
No error happened. This is never raised and should disappear in future versions.
*)
| Error_ssl
(*
A non-recoverable, fatal error in the SSL library occurred, usually a protocol error. The OpenSSL error queue contains more information on the error. If this error occurs then no further I/O operations should be performed on the connection and SSL_shutdown() must not be called.
*)
| 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.
*)
| Error_want_async
(*
The operation did not complete because an asynchronous engine is still processing data. The TLS/SSL I/O function should be called again later. The function must be called from the same thread that the original call was made from.
*)
| Error_want_async_job
(*
The asynchronous job could not be started because there were no async jobs available in the pool. The application should retry the operation after a currently executing asynchronous operation for the current thread has completed.
*)
| Error_want_client_hello_cb
(*
The operation did not complete because an application callback set by SSL_CTX_set_client_hello_cb() has asked to be called again. The TLS/SSL I/O function should be called again later. Details depend on the application.
*)
| Error_want_retry_verify
(*
See https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_verify.html
*)

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

Source

type bigarray =
  (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

Sourceexception Method_error

The SSL method could not be initialized.

Sourceexception Context_error

Sourceexception Cipher_error

Sourceexception Diffie_hellman_error

Sourceexception Ec_curve_error

Sourceexception Certificate_error of string

The SSL server certificate could not be initialized.

Sourceexception Private_key_error of string

The SSL server private key could not be initialized.

Sourceexception Unmatching_keys

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

Sourceexception Invalid_socket

The given socket is invalid.

Sourceexception Handler_error

The SSL handler could not be initialized.

Sourceexception Connection_error of ssl_error

The connection could not be made with the SSL service.

Sourceexception Accept_error of ssl_error

Failed to accept an SSL connection.

Sourceexception Read_error of ssl_error

An error occurred while reading data.

Sourceexception Write_error of ssl_error

An error occurred while writing data.

Sourceexception Flush_error of bool

An error occurred while flushing a socket. Flush_error true means that the operation should be retried.

Sourcetype 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?

Sourceexception Verify_error of verify_error

An error occurred while verifying the certificate.

Communication

Sourceval 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 achieved by calling Ssl_threads.init first.

Sourceval get_error_string : unit -> string

Retrieve a human-readable message that corresponds to the earliest error code from the thread's error queue and removes the entry.

deprecated Use [Ssl.Error.get_error] instead

Sourcemodule Error : sig ... end

Sourcetype protocol =

| SSLv23
(*
accept all possible protocols (SSLv2 if supported by openssl, SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3)
- deprecated SSL 2.0 was deprecated in 2011 by RFC 6176.
*)
| SSLv3
(*
only SSL v3 protocol
- deprecated SSL 3.0 was deprecated in June 2015 by RFC 7568.
*)
| TLSv1
(*
only TLS v1 protocol
- deprecated TLS 1.0 and 1.1 were formally deprecated in RFC8996 in March 2021.
*)
| TLSv1_1
(*
only TLS v1.1 protocol
- deprecated TLS 1.0 and 1.1 were formally deprecated in RFC8996 in March 2021.
*)
| TLSv1_2
(*
only TLS v1.2 protocol
*)
| TLSv1_3
(*
only TLS v1.3 protocol
*)

Protocol used by SSL.

Sourcetype 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).

Sourceval thread_safe : bool ref

Contexts

Sourcetype 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.

Sourcetype context_type =

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

Type of the context to create.

Sourceval create_context : protocol -> context_type -> context

Create a context.

Sourceval set_min_protocol_version : context -> protocol -> unit

set_min_protocol_version ctx proto sets the minimum supported protocol version for ctx to proto.

Sourceval set_max_protocol_version : context -> protocol -> unit

set_max_protocol_version ctx proto sets the maximum supported protocol version for ctx to proto.

Sourceval get_min_protocol_version : context -> protocol

get_min_protocol_version ctx sets the minimum supported protocol version for ctx to proto.

Sourceval get_max_protocol_version : context -> protocol

get_max_protocol_version ctx proto sets the maximum supported protocol version for ctx to proto.

Sourceval add_extra_chain_cert : context -> string -> unit

Add an additional certificate to the extra chain certificates associated with the ctx. Extra chain certificates will be sent to the peer for verification and are sent in order following the end entity certificate. The value should be contents of the certificate as string in PEM format.

Sourceval add_cert_to_store : context -> string -> unit

Add a certificate to the ctx trust storage. The value should be contents of the certificate as string in PEM format.

Sourceval 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.

Sourceval use_certificate_from_string : context -> string -> string -> unit

Use a certificate whose contents is given as argument (you should use instead use_certificate if you want to read the certificate from a file).

Sourceval 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).

Sourceval set_client_CA_list_from_file : context -> string -> unit

Set the list of CAs sent to the client when requesting a client certificate.

Sourcetype 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)).

Sourcetype verify_callback

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

Sourceval client_verify_callback : verify_callback

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

Sourceval set_client_verify_callback_verbose : bool -> unit

Set verbosity of client_verify_callback

Sourceval 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.

Sourceval set_verify_depth : context -> int -> unit

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

Sourceval set_context_alpn_protos : context -> string list -> unit

Set the list of supported ALPN protocols for negotiation to the context.

Source

val set_context_alpn_select_callback : 
  context ->
  (string list -> string option) ->
  unit

Set the callback to allow server to select the preferred protocol from client's available protocols.

Ciphers

Sourcetype cipher

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

Sourceval disable_protocols : context -> protocol list -> unit

Disable all protocols from the list. * Note that SSLv23 disables both SSLv2 and SSLv3 (as opposed to all the * protocols). *

Sourceval 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.

Sourceval honor_cipher_order : context -> unit

When choosing a cipher, use the server's preferences instead of the client * preferences. When not set, the SSL server will always follow the clients * preferences. When set, the SSLv3/TLSv1 server will choose following its * own preferences. Because of the different protocol, for SSLv2 the server * will send its list of preferences to the client and the client chooses.

Sourceval init_dh_from_file : context -> string -> unit

Init DH parameters from file

Sourceval init_ec_from_named_curve : context -> string -> unit

Init EC curve from curve name

Sourceval get_cipher : socket -> cipher

Get the cipher used by a socket.

Sourceval get_cipher_description : cipher -> string

Get a description of a cipher.

Sourceval get_cipher_name : cipher -> string

Get the name of a cipher.

Sourceval get_cipher_version : cipher -> string

Get the version of a cipher.

Sourceval version : socket -> protocol

Get the version used for the connection. As per the OpenSSL documentation, should only be called after the initial handshake has been completed. Prior to that the results returned from these functions may be unreliable.

raises Failure
if the version is unknown

Certificates

Sourcetype certificate

A certificate.

Sourceval read_certificate : string -> certificate

read_certificate fname reads the certificate in the file fname.

Sourceval write_certificate : string -> certificate -> unit

Sourceval get_certificate : socket -> certificate

Get the certificate used by a socket.

Sourceval get_issuer : certificate -> string

Get the issuer of a certificate.

Sourceval get_subject : certificate -> string

Get the subject of a certificate.

Sourceval get_start_date : certificate -> Unix.tm

Get the start date of a certificate.

Sourceval get_expiration_date : certificate -> Unix.tm

Get the expiration date of a certificate.

Sourceval 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.

Sourceval set_default_verify_paths : context -> bool

Specifies that the default locations from which CA certificates are loaded should be used. Returns true on success.

Sourceval get_verify_result : socket -> int

Get the verification result.

Sourceval get_verify_error_string : int -> string

Get a human readable verification error message for the verification error Its input should be the result of calling get_verify_result.

Sourceval digest : [ `SHA1 | `SHA256 | `SHA384 ] -> certificate -> string

Get the digest of the certificate as a binary string, using the SHA1, SHA256 or SHA384 hashing algorithm.

Creating, connecting, closing and configuring sockets

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

Embed a Unix socket into an SSL socket.

Sourceval set_client_SNI_hostname : socket -> string -> unit

Set the hostname the client is attempting to connect to using the Server * Name Indication (SNI) TLS extension.

Sourceval set_alpn_protos : socket -> string list -> unit

Set the list of supported ALPN protocols for negotiation to the connection.

Sourceval get_negotiated_alpn_protocol : socket -> string option

Get the negotiated protocol from the connection.

Sourceval 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.

Sourcetype x509_check_flag =

| Always_check_subject
| No_wildcards
| No_partial_wildcards
| Multi_label_wildcards
| Single_label_subdomains

Flags to specify how a certificate is matched against a given host name

Sourceval set_hostflags : socket -> x509_check_flag list -> unit

Sourceval set_host : socket -> string -> unit

Sourceval set_ip : socket -> string -> unit

Set the expected ip address to be verified. Ip address is dotted decimal quad for IPv4 and colon-separated hexadecimal for IPv6. The condensed "::" notation is supported for IPv6 addresses.

Sourceval file_descr_of_socket : socket -> Unix.file_descr

Get the file descriptor associated with a socket. It is primarily useful for selecting on it; you should not write or read on it.

I/O on SSL sockets

The main SSL communication functions that can block if sockets are in blocking mode. This set of functions releases the OCaml runtime lock, which can require extra copying of application data. The module Runtime_lock provided below lifts this limitation by never releasing the OCaml runtime lock.

Sourceval connect : socket -> unit

Connect an SSL socket.

Sourceval accept : socket -> unit

Accept an SSL connection.

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

Open an SSL connection.

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

Open an SSL connection with the specified context.

Sourceval close_notify : socket -> bool

Send close notify to the peer. This is SSL_shutdown(3). * returns true if shutdown is finished, false in case close_notify * needs to be called a second time.

Sourceval shutdown_connection : socket -> unit

Close an SSL connection opened with open_connection.

Sourceval shutdown : socket -> unit

Close a SSL connection. * Send close notify to the peer and wait for close notify from peer.

Sourceval flush : socket -> unit

Flush an SSL connection.

Sourceval read : socket -> Bytes.t -> int -> int -> int

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

Sourceval read_into_bigarray : socket -> bigarray -> int -> int -> int

read_into_bigarray sock ba off len receives data from a connected SSL socket. This function releases the runtime while the read takes place.

Sourceval write : socket -> Bytes.t -> int -> int -> int

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

Sourceval write_substring : socket -> string -> int -> int -> int

write_substring sock str off len sends data over a connected SSL socket.

Sourceval write_bigarray : socket -> bigarray -> int -> int -> int

write_bigarray sock ba off len sends data over a connected SSL socket. This function releases the runtime while the read takes place.

High-level communication functions

Sourceval input_string : socket -> string

Input a string on an SSL socket.

Sourceval output_string : socket -> string -> unit

Write a string on an SSL socket.

Sourceval input_char : socket -> char

Input a character on an SSL socket.

Sourceval output_char : socket -> char -> unit

Write a char on an SSL socket.

Sourceval input_int : socket -> int

Input an integer on an SSL socket.

Sourceval output_int : socket -> int -> unit

Write an integer on an SSL socket.

Sourcemodule Runtime_lock : sig ... end

Runtime_lock is an equivalent, signature compatible, equivalent to the Ssl module, with one difference: the OCaml runtime lock isn't released before calling the underlying SSL primitives. Multiple systhreads cannot, therefore, run concurrently.

Sourceval read_into_bigarray_blocking : socket -> bigarray -> int -> int -> int

This function is deprecated. Use Runtime_lock.read_into_bigarray instead.

deprecated Use [Runtime_lock.read_into_bigarray] instead

Sourceval write_bigarray_blocking : socket -> bigarray -> int -> int -> int

This function is deprecated. Use Runtime_lock.write_bigarray instead.

deprecated Use [Runtime_lock.write_bigarray] instead

package ssl

Module SslSource