Ssl_ctx_set_cert_verify_callback

SEE ALSO ssl(3), SSLCTXsetverify(3), SSLgetverifyresult(3), SSLCTXloadverifylocations(3) HISTORY Previous to OpenSSL 0.9.7, the arg argument to SSLCTXsetcertverifycallback was ignored, and callback was called simply as int (.callback)(X509STORECTX.) To compile software written for previous versions of OpenSSL, a dummy argument. The library uses SSLCTXsetcertverifycallback in order to override the default certificate verification procedure. If a regular verification callback is set using asio::ssl::stream::setverifycallback, it will be invoked during the first phase of certificate verification, in the same way a default-configured asio::ssl::context would.

Name

ssl - Interface Functions for Secure Socket Layer

Description

This module contains interface functions to the Secure Socket Layer.

Ssl

CallbackModule = atom()

DataTag = atom() - tag used in socket data message.

ClosedTag = atom() - tag used in socket close message.

verify_type() = verify_none verify_peer

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

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

host() = hostname() ipaddress()

hostname() = string()

ip_address() = {N1,N2,N3,N4} % IPv4 {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

sslsocket() - opaque to the user.

protocol() = sslv3 tlsv1

ciphers() = [ciphersuite()] string() (according to old API)

ciphersuite() = {key_exchange(), cipher(), hash()}

key_exchange() = rsa dhe_dss dhe_rsa dh_anon

cipher() = rc4_128 des_cbc '3des_ede_cbc' aes_128_cbc aes_256_cbc

hash() = md5 sha

ssl_imp() = new old - default is new.

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.

{key, der_encoded()}:
The DER encoded users private key. If this option is supplied it will override the keyfile option.
{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 certfileoption.
{password, string()}:
String containing the user's password. Only used if the private keyfile is password protected.
{cacerts, [der_encoded()]}:
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 toverify the peer.
{ciphers, ciphers()}:
The cipher suites that should be supported. The function cipher_suites/0 can be used to find all available ciphers. Additionally some anonymouscipher suites ({dh_anon, rc4_128, md5}, {dh_anon, des_cbc, sha}, {dh_anon, '3des_ede_cbc', sha}, {dh_anon, aes_128_cbc, sha}, {dh_anon, aes_256_cbc, sha}) aresupported for testing purposes and will only work if explicitly enabled by this option and they are supported/enabled by the peer also.
{ssl_imp, ssl_imp()}:
Specify which ssl implementation you want to use. Defaults to 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 renegotiationwill 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 isconsidered 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 containpeer 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:

The verify fun will be called during the X509-path validation when an error or an extension unknown to the ssl application is encountered. Additionally itwill be called when a certificate is considered valid by the path validation to allow access to each certificate in the path to the user application. Note thatit will differentiate between the peer certificate and CA certificates by using valid_peer or valid as the second argument to the verify fun. See thepublic_key User's Guide 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/SSLhandshake is terminated. If the verify callback fun returns {valid, UserState}, the verification process is continued. If the verify callback fun alwaysreturns {valid, UserState}, the TLS/SSL handshake will not be terminated with respect to verification failures and the connection will be established. Ifcalled 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:

The default verify_fun option in verify_none mode:

Possible path validation errors:

{bad_cert, cert_expired}, {bad_cert, invalid_issuer}, {bad_cert, invalid_signature}, {bad_cert, unknown_ca},{bad_cert, selfsigned_peer}, {bad_cert,name_not_permitted}, {bad_cert, missing_basic_constraint}, {bad_cert, invalid_key_usage}

{dh, der_encoded()}:
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. Ifnot 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 theverify 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 an 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 an invalid certificate (an empty certificate is considered valid).
{reuse_sessions, boolean()}:
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()}:
Enables the ssl server to have a local policy for deciding if a session should be reused or not, only meaningful if reuse_sessions is set to true.SuggestedSessionId is a binary(), PeerCert is a DER encoded certificate, Compression is an enumeration integer and CipherSuite is of typeciphersuite().

General

When an ssl socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of messages:

Ssl_ctx_set_cert_verify_callback

peername(Socket) -> {ok, {Address, Port}} {error, Reason}

Types:

Socket = sslsocket()
Address = ipaddress()
Port = integer()

Returns the address and port number of the peer.

recv(Socket, Length) ->
recv(Socket, Length, Timeout) -> {ok, Data} {error, Reason}

Types:

Socket = sslsocket()
Length = integer()
Timeout = integer()
Data = [char()] binary()

This function receives a packet from a socket in passive mode. A closed socket is indicated by a return value {error, closed}.

The Length argument is only meaningful when the socket is in raw mode and denotes the number of bytes to read. If Length = 0, allavailable bytes are returned. If Length > 0, exactly Length bytes are returned, or an error; possibly discarding less than Length bytesof data when the socket gets closed from the other side.

The optional Timeout parameter specifies a timeout in milliseconds. The default value is infinity.

renegotiate(Socket) -> ok {error, Reason}

Types:

Socket = sslsocket()

Initiates a new handshake. A notable return value is {error, renegotiation_rejected} indicating that the peer refused to go through with therenegotiation but the connection is still active using the previously negotiated session.

send(Socket, Data) -> ok {error, Reason}

Types:

Socket = sslsocket()
Data = iodata()

Writes Data to Socket.

A notable return value is {error, closed} indicating that the socket is closed.

setopts(Socket, Options) -> ok {error, Reason}

Types:

Socket = sslsocket()
Options = [socketoption]()

Sets options according to Options for the socket Socket.

shutdown(Socket, How) -> ok {error, Reason}

Types:

Socket = sslsocket()
How = read write read_write
Reason = reason()

Immediately close a socket in one or two directions.

How write means closing the socket for writing, reading from it is still possible.

To be able to handle that the peer has done a shutdown on the write side, the {exit_on_close, false} option is useful.

ssl_accept(ListenSocket) ->
ssl_accept(ListenSocket, Timeout) -> ok {error, Reason}

Types:

ListenSocket = sslsocket()
Timeout = integer()
Reason = term()

The ssl_accept function establish the SSL connection on the server side. It should be called directly after transport_accept, in the spawnedserver-loop.

ssl_accept(ListenSocket, SslOptions) ->
ssl_accept(ListenSocket, SslOptions, Timeout) -> {ok, Socket} {error, Reason}

Types:

ListenSocket = socket()
SslOptions = ssloptions()
Timeout = integer()
Reason = term()

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

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

sockname(Socket) -> {ok, {Address, Port}} {error, Reason}

Types:

Socket = sslsocket()
Address = ipaddress()
Port = integer()

Returns the local address and port number of the socket Socket.

start() ->
start(Type) -> ok {error, Reason}

Types:

Type = permanent transient temporary

Starts the Ssl application. Default type is temporary. application(3)

stop() -> ok

Stops the Ssl application. application(3)

transport_accept(Socket) ->
transport_accept(Socket, Timeout) -> {ok, NewSocket} {error, Reason}

Types:

Socket = NewSocket = sslsocket()
Timeout = integer()
Reason = reason()

Accepts an incoming connection request on a listen socket. ListenSocket must be a socket returned from listen/2. The socket returned should bepassed to ssl_accept to complete ssl handshaking and establishing the connection.

Warning:
The socket returned can only be used with ssl_accept, no traffic can be sent or received before that call.

The accepted socket inherits the options set for ListenSocket in listen/2.

The default value for Timeout is infinity. If Timeout is specified, and no connection is accepted within the given time, {error,timeout} is returned.

versions() -> [{SslAppVer, SupportedSslVer, AvailableSslVsn}]

Types:

SslAppVer = string()
SupportedSslVer = [protocol()]
AvailableSslVsn = [protocol()]

Returns version information relevant for the ssl application.

See Also

inet(3) and gen_tcp(3)

Referenced By

bio_s_bio(3),ciphers(1),d2i_ssl_session(3),http(3),httpc(3),httpd(3),mailx(1),openssl(1),ssl_accept(3),ssl_alert_type_string(3),ssl_cipher_get_name(3),ssl_clear(3),ssl_comp_add_compression_method(3),ssl_connect(3),ssl_ctx_add_extra_chain_cert(3),ssl_ctx_add_session(3),ssl_ctx_ctrl(3),ssl_ctx_flush_sessions(3),ssl_ctx_free(3),ssl_ctx_get_verify_mode(3),ssl_ctx_load_verify_locations(3),ssl_ctx_new(3),ssl_ctx_sess_number(3),ssl_ctx_sess_set_cache_size(3),ssl_ctx_sess_set_get_cb(3),ssl_ctx_sessions(3),ssl_ctx_set_cert_store(3),ssl_ctx_set_cert_verify_callback(3),ssl_ctx_set_cipher_list(3),ssl_ctx_set_client_ca_list(3),ssl_ctx_set_client_cert_cb(3),ssl_ctx_set_default_passwd_cb(3),ssl_ctx_set_ex_data(3),ssl_ctx_set_info_callback(3),ssl_ctx_set_mode(3),ssl_ctx_set_options(3),ssl_ctx_set_quiet_shutdown(3),ssl_ctx_set_session_cache_mode(3),ssl_ctx_set_session_id_context(3),ssl_ctx_set_ssl_version(3),ssl_ctx_set_timeout(3),ssl_ctx_set_tmp_dh_callback(3),ssl_ctx_set_tmp_rsa_callback(3),ssl_ctx_set_verify(3),ssl_ctx_use_certificate(3),ssl_do_handshake(3),ssl_free(3),ssl_get_ciphers(3),ssl_get_client_ca_list(3),ssl_get_current_cipher(3),ssl_get_default_timeout(3),ssl_get_error(3),ssl_get_ex_data_x509_store_ctx_idx

Node Ctx

(3),ssl_get_ex_new_index(3),ssl_get_fd(3),ssl_get_peer_cert_chain(3),ssl_get_peer_certificate(3),ssl_get_rbio(3),ssl_get_session(3),ssl_get_ssl_ctx(3),ssl_get_verify_result(3),ssl_get_version(3),ssl_load_client_ca_file(3),ssl_new(3),ssl_pending(3),ssl_read(3),ssl_rstate_string_long(3),ssl_session_free(3),Ssl_ctx_set_cert_verify_callback vs ssl_ctx_set_verifyssl_session_get_time(3),

Js Ctx

ssl_session_reused(3),ssl_session_set_ex_data(3),ssl_set_bio(3),ssl_set_connect_state(3),ssl_set_fd(3),ssl_set_generate_session_id(3),ssl_set_max_cert_list(3),ssl_set_msg_callback(3),ssl_set_session(3),ssl_set_shutdown(3),ssl_set_verify_result(3),ssl_shutdown(3),ssl_state_string(3),ssl_want_x509_lookup(3),ssl_write(3),ssleay_add_ssl_algorithms

Ctx

(3),

Ssl_ctx_set_cert_verify_callback Example

yapet(1)