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 |
| |
Error_ssl |
| |
Error_want_read |
| |
Error_want_write |
| |
Error_want_x509_lookup |
| |
Error_syscall |
| |
Error_zero_return |
| |
Error_want_connect |
| |
Error_want_accept |
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 |
| |
Error_v_unable_to_get_ctl |
| |
Error_v_unable_to_decrypt_cert_signature |
| |
Error_v_unable_to_decrypt_CRL_signature |
| |
Error_v_unable_to_decode_issuer_public_key |
| |
Error_v_cert_signature_failure |
| |
Error_v_CRL_signature_failure |
| |
Error_v_cert_not_yet_valid |
| |
Error_v_cert_has_expired |
| |
Error_v_CRL_not_yet_valid |
| |
Error_v_CRL_has_expired |
| |
Error_v_error_in_cert_not_before_field |
| |
Error_v_error_in_cert_not_after_field |
| |
Error_v_error_in_CRL_last_update_field |
| |
Error_v_error_in_CRL_next_update_field |
| |
Error_v_out_of_mem |
| |
Error_v_depth_zero_self_signed_cert |
| |
Error_v_self_signed_cert_in_chain |
| |
Error_v_unable_to_get_issuer_cert_locally |
| |
Error_v_unable_to_verify_leaf_signature |
| |
Error_v_cert_chain_too_long |
| |
Error_v_cert_revoked |
| |
Error_v_invalid_CA |
| |
Error_v_path_length_exceeded |
| |
Error_v_invalid_purpose |
| |
Error_v_cert_untrusted |
| |
Error_v_cert_rejected |
| |
Error_v_subject_issuer_mismatch |
| |
Error_v_akid_skid_mismatch |
| |
Error_v_akid_issuer_serial_mismatch |
| |
Error_v_keyusage_no_certsign |
| |
Error_v_application_verification |
Why did the certificate verification fail?
exception Verify_error of verify_error
An error occured while verifying the certificate.
Communication
val init : unit -> unit
Initialize SSL functions. Should be called before calling any other function.
val get_error_string : unit -> string
Retrieve a human-readable message that corresponds to the last error that occurred.
type
protocol =
| |
SSLv2 |
| |
SSLv23 |
| |
SSLv3 |
| |
TLSv1 |
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 crypto_num_locks : unit -> int
val thread_id_function : (unit -> int) option Pervasives.ref
val thread_locking_function : (int -> bool -> unit) option 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 |
| |
Server_context |
| |
Both_context |
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 |
| |
Verify_client_once |
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 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.