Convert libssl manpages from pod to mdoc(7).

libcrypto has not been started yet.

ok schwarze@ miod@

1 files changed, 1317 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/ssl.3 b/src/lib/libssl/doc/ssl.3
new file mode 100644
index 0000000000..901e1fdfc1
--- /dev/null
+++ b/src/lib/libssl/doc/ssl.3
@@ -0,0 +1,1317 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL 3
+.Os
+.Sh NAME
+.Nm SSL
+.Nd OpenSSL SSL/TLS library
+.Sh SYNOPSIS
+.Sh DESCRIPTION
+The OpenSSL
+.Nm ssl
+library implements the Secure Sockets Layer (SSL v2/v3) and
+Transport Layer Security (TLS v1) protocols.
+It provides a rich API which is documented here.
+.Pp
+At first the library must be initialized; see
+.Xr SSL_library_init 3 .
+.Pp
+Then an
+.Vt SSL_CTX
+object is created as a framework to establish TLS/SSL enabled connections (see
+.Xr SSL_CTX_new 3 ) .
+Various options regarding certificates, algorithms, etc., can be set in this
+object.
+.Pp
+When a network connection has been created, it can be assigned to an
+.Vt SSL
+object.
+After the
+.Vt SSL
+object has been created using
+.Xr SSL_new 3 ,
+.Xr SSL_set_fd 3
+or
+.Xr SSL_set_bio 3
+can be used to associate the network connection with the object.
+.Pp
+Then the TLS/SSL handshake is performed using
+.Xr SSL_accept 3
+or
+.Xr SSL_connect 3
+respectively.
+.Xr SSL_read 3
+and
+.Xr SSL_write 3
+are used to read and write data on the TLS/SSL connection.
+.Xr SSL_shutdown 3
+can be used to shut down the TLS/SSL connection.
+.Sh DATA STRUCTURES
+Currently the OpenSSL
+.Nm ssl
+library functions deals with the following data structures:
+.Bl -tag -width Ds
+.It Vt SSL_METHOD No (SSL Method)
+That's a dispatch structure describing the internal
+.Nm ssl
+library methods/functions which implement the various protocol versions
+(SSLv1, SSLv2 and TLSv1).
+It's needed to create an
+.Vt SSL_CTX .
+.It Vt SSL_CIPHER No (SSL Cipher)
+This structure holds the algorithm information for a particular cipher which
+is a core part of the SSL/TLS protocol.
+The available ciphers are configured on an
+.Vt SSL_CTX
+basis and the actually used ones are then part of the
+.Vt SSL_SESSION .
+.It Vt SSL_CTX No (SSL Context)
+That's the global context structure which is created by a server or client
+once per program lifetime and which holds mainly default values for the
+.Vt SSL
+structures which are later created for the connections.
+.It Vt SSL_SESSION No (SSL Session)
+This is a structure containing the current TLS/SSL session details for a
+connection:
+.Vt SSL_CIPHER Ns s, client and server certificates, keys, etc.
+.It Vt SSL No (SSL Connection)
+That's the main SSL/TLS structure which is created by a server or client per
+established connection.
+This actually is the core structure in the SSL API.
+Under run-time the application usually deals with this structure which has
+links to mostly all other structures.
+.El
+.Sh HEADER FILES
+Currently the OpenSSL
+.Nm ssl
+library provides the following C header files containing the prototypes for the
+data structures and functions:
+.Bl -tag -width Ds
+.It Pa ssl.h
+That's the common header file for the SSL/TLS API.
+Include it into your program to make the API of the
+.Nm ssl
+library available.
+It internally includes both more private SSL headers and headers from the
+.Em crypto
+library.
+Whenever you need hardcore details on the internals of the SSL API, look inside
+this header file.
+.It Pa ssl2.h
+That's the sub header file dealing with the SSLv2 protocol only.
+.Bf Em
+ Usually you don't have to include it explicitly because it's already included
+by
+.Pa ssl.h .
+.Ef
+.It Pa ssl3.h
+That's the sub header file dealing with the SSLv3 protocol only.
+.Bf Em
+Usually you don't have to include it explicitly because it's already included
+by
+.Pa ssl.h .
+.Ef
+.It Pa ssl23.h
+That's the sub header file dealing with the combined use of the SSLv2 and SSLv3
+protocols.
+.Bf Em
+Usually you don't have to include it explicitly because it's already included
+by
+.Pa ssl.h .
+.Ef
+.It Pa tls1.h
+That's the sub header file dealing with the TLSv1 protocol only.
+.Bf Em
+Usually you don't have to include it explicitly because it's already included
+by
+.Pa ssl.h .
+.Ef
+.El
+.Sh API FUNCTIONS
+The functions that the OpenSSL
+.Nm ssl
+library exports are documented below:
+.Ss DEALING WITH PROTOCOL METHODS
+Here we document the various API functions which deal with the SSL/TLS protocol
+methods defined in
+.Vt SSL_METHOD
+structures.
+.Bl -tag -width Ds
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSLv2_client_method void
+.Xc
+Constructor for the SSLv2
+.Vt SSL_METHOD
+structure for a dedicated client.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSLv2_server_method void
+.Xc
+Constructor for the SSLv2
+.Vt SSL_METHOD
+structure for a dedicated server.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSLv2_method void
+.Xc
+Constructor for the SSLv2
+.Vt SSL_METHOD
+structure for combined client and server.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSLv3_client_method void
+.Xc
+Constructor for the SSLv3
+.Vt SSL_METHOD
+structure for a dedicated client.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSLv3_server_method void
+.Xc
+Constructor for the SSLv3
+.Vt SSL_METHOD
+structure for a dedicated server.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSLv3_method void
+.Xc
+Constructor for the SSLv3
+.Vt SSL_METHOD
+structure for combined client and server.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn TLSv1_client_method void
+.Xc
+Constructor for the TLSv1
+.Vt SSL_METHOD
+structure for a dedicated client.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn TLSv1_server_method void
+.Xc
+Constructor for the TLSv1
+.Vt SSL_METHOD
+structure for a dedicated server.
+.It Xo
+.Ft const SSL_METHOD *
+.Fn TLSv1_method void
+.Xc
+Constructor for the TLSv1
+.Vt SSL_METHOD
+structure for combined client and server.
+.El
+.Ss DEALING WITH CIPHERS
+Here we document the various API functions which deal with the SSL/TLS ciphers
+defined in
+.Vt SSL_CIPHER
+structures.
+.Bl -tag -width Ds
+.It Xo
+.Ft char *
+.Fn SSL_CIPHER_description "SSL_CIPHER *cipher" "char *buf" "int len"
+.Xc
+Write a string to
+.Fa buf
+(with a maximum size of
+.Fa len )
+containing a human readable description of
+.Fa cipher .
+Returns
+.Fa buf .
+.It Xo
+.Ft int
+.Fn SSL_CIPHER_get_bits "SSL_CIPHER *cipher" "int *alg_bits"
+.Xc
+Determine the number of bits in
+.Fa cipher .
+Because of export crippled ciphers there are two bits:
+the bits the algorithm supports in general (stored to
+.Fa alg_bits )
+and the bits which are actually used (the return value).
+.It Xo
+.Ft const char *
+.Fn SSL_CIPHER_get_name "SSL_CIPHER *cipher"
+.Xc
+Return the internal name of
+.Fa cipher
+as a string.
+These are the various strings defined by the
+.Dv SSL2_TXT_xxx ,
+.Dv SSL3_TXT_xxx
+and
+.Dv TLS1_TXT_xxx
+definitions in the header files.
+.It Xo
+.Ft char *
+.Fn SSL_CIPHER_get_version "SSL_CIPHER *cipher"
+.Xc
+Returns a string like
+Qq TLSv1/SSLv3
+or
+Qq SSLv2
+which indicates the SSL/TLS protocol version to which
+.Fa cipher
+belongs (i.e., where it was defined in the specification the first time).
+.El
+.Ss DEALING WITH PROTOCOL CONTEXTS
+Here we document the various API functions which deal with the SSL/TLS
+protocol context defined in the
+.Vt SSL_CTX
+structure.
+.Bl -tag -width Ds
+.It Xo
+.Ft int
+.Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *x"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_add_extra_chain_cert "SSL_CTX *ctx" "X509 *x509"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_add_session "SSL_CTX *ctx" "SSL_SESSION *c"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_ctrl "SSL_CTX *ctx" "int cmd" "long larg" "char *parg"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_flush_sessions "SSL_CTX *s" "long t"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_free "SSL_CTX *a"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_CTX_get_app_data "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft X509_STORE *
+.Fn SSL_CTX_get_cert_store "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft STACK *
+.Fn SSL_CTX_get_client_CA_list "const SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))"
+.Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_CTX_get_ex_data "const SSL_CTX *s" "int idx"
+.Xc
+.It Xo
+.Ft int
+.Fo SSL_CTX_get_ex_new_index
+.Fa "long argl"
+.Fa "void *argp"
+.Fa "CRYPTO_EX_new *new_func"
+.Fa "CRYPTO_EX_dup *dup_func"
+.Fa "CRYPTO_EX_free *free_func"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fo "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))"
+.Fa "SSL *ssl"
+.Fa "int cb"
+.Fa "int ret"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_get_quiet_shutdown "const SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_get_session_cache_mode "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_get_timeout "const SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fo "(*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))"
+.Fa "int ok"
+.Fa "X509_STORE_CTX *ctx"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_get_verify_mode "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_load_verify_locations "SSL_CTX *ctx" "char *CAfile" "char *CApath"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_need_tmp_RSA "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft SSL_CTX *
+.Fn SSL_CTX_new "const SSL_METHOD *meth"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_remove_session "SSL_CTX *ctx" "SSL_SESSION *c"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_accept "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_accept_good "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_accept_renegotiate "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_cache_full "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_cb_hits "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_connect "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_connect_good "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_connect_renegotiate "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_get_cache_size "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft SSL_SESSION *
+.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))"
+.Fa "SSL *ssl"
+.Fa "unsigned char *data"
+.Fa "int len"
+.Fa "int *copy"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" "SSL *ssl" "SSL_SESSION *sess"
+.Xc
+.It Xo
+.Ft void
+.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))"
+.Fa "SSL_CTX *ctx"
+.Fa "SSL_SESSION *sess"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_hits "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_misses "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_number "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_sess_set_cache_size "SSL_CTX *ctx" "long t"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_sess_set_get_cb
+.Fa "SSL_CTX *ctx"
+.Fa "SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_sess_set_new_cb
+.Fa "SSL_CTX *ctx"
+.Fa "int (*cb)(SSL *ssl, SSL_SESSION *sess)"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_sess_set_remove_cb
+.Fa "SSL_CTX *ctx"
+.Fa "void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_sess_timeouts "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft LHASH *
+.Fn SSL_CTX_sessions "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_app_data "SSL_CTX *ctx" "void *arg"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_cert_store "SSL_CTX *ctx" "X509_STORE *cs"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_cert_verify_cb "SSL_CTX *ctx" "int (*cb)()" "char *arg"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "char *str"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK *list"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_set_client_cert_cb
+.Fa "SSL_CTX *ctx"
+.Fa "int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_default_read_ahead "SSL_CTX *ctx" "int m"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_set_default_verify_paths "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_set_ex_data "SSL_CTX *s" "int idx" "char *arg"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_set_info_callback
+.Fa "SSL_CTX *ctx"
+.Fa "void (*cb)(SSL *ssl, int cb, int ret)"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_set_msg_callback
+.Fa "SSL_CTX *ctx"
+.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, \
+size_t len, SSL *ssl, void *arg)"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_msg_callback_arg "SSL_CTX *ctx" "void *arg"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_options "SSL_CTX *ctx" "unsigned long op"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_quiet_shutdown "SSL_CTX *ctx" "int mode"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_session_cache_mode "SSL_CTX *ctx" "int mode"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_set_ssl_version "SSL_CTX *ctx" "const SSL_METHOD *meth"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_timeout "SSL_CTX *ctx" "long t"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_set_tmp_dh "SSL_CTX* ctx" "DH *dh"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_set_tmp_dh_callback "SSL_CTX *ctx" "DH *(*cb)(void)"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa"
+.Xc
+.It Xo
+.Fn SSL_CTX_set_tmp_rsa_callback
+.Xc
+.Ft long
+.Fo SSL_CTX_set_tmp_rsa_callback
+.Fa "SSL_CTX *ctx"
+.Fa "RSA *(*cb)(SSL *ssl, int export, int keylength)"
+.Fc
+.Pp
+Sets the callback which will be called when a temporary private key is
+required.
+The
+.Fa export
+flag will be set if the reason for needing a temp key is that an export
+ciphersuite is in use, in which case,
+.Fa keylength
+will contain the required keylength in bits.
+.\" XXX using what?
+Generate a key of appropriate size (using ???) and return it.
+.It Xo
+.Fn SSL_set_tmp_rsa_callback
+.Xc
+.Ft long
+.Fo SSL_set_tmp_rsa_callback
+.Fa "SSL *ssl"
+.Fa "RSA *(*cb)(SSL *ssl, int export, int keylength)"
+.Fc
+.Pp
+The same as
+.Fn SSL_CTX_set_tmp_rsa_callback ,
+except it operates on an
+.Vt SSL
+session instead of a context.
+.It Xo
+.Ft void
+.Fn SSL_CTX_set_verify "SSL_CTX *ctx" "int mode" "int (*cb)(void)"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey"
+.Xc
+.It Xo
+.Ft int
+.Fo SSL_CTX_use_PrivateKey_ASN1
+.Fa "int type"
+.Fa "SSL_CTX *ctx"
+.Fa "unsigned char *d"
+.Fa "long len"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "char *file" "int type"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "char *file" "int type"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "char *file" "int type"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_set_psk_client_callback
+.Fa "SSL_CTX *ctx"
+.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \
+unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_CTX_use_psk_identity_hint "SSL_CTX *ctx" "const char *hint"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_CTX_set_psk_server_callback
+.Fa "SSL_CTX *ctx"
+.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, \
+unsigned char *psk, int max_psk_len)"
+.Fc
+.Xc
+.El
+.Ss DEALING WITH SESSIONS
+Here we document the various API functions which deal with the SSL/TLS sessions
+defined in the
+.Vt SSL_SESSION
+structures.
+.Bl -tag -width Ds
+.It Xo
+.Ft int
+.Fn SSL_SESSION_cmp "const SSL_SESSION *a" "const SSL_SESSION *b"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_SESSION_free "SSL_SESSION *ss"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_SESSION_get_app_data "SSL_SESSION *s"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_SESSION_get_ex_data "const SSL_SESSION *s" "int idx"
+.Xc
+.It Xo
+.Ft int
+.Fo SSL_SESSION_get_ex_new_index
+.Fa "long argl"
+.Fa "char *argp"
+.Fa "int (*new_func)(void)"
+.Fa "int (*dup_func)(void), void (*free_func)(void)"
+.Fc
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_SESSION_get_time "const SSL_SESSION *s"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_SESSION_get_timeout "const SSL_SESSION *s"
+.Xc
+.It Xo
+.Ft unsigned long
+.Fn SSL_SESSION_hash "const SSL_SESSION *a"
+.Xc
+.It Xo
+.Ft SSL_SESSION *
+.Fn SSL_SESSION_new void
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_SESSION_print "BIO *bp" "const SSL_SESSION *x"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_SESSION_print_fp "FILE *fp" "const SSL_SESSION *x"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_SESSION_set_app_data "SSL_SESSION *s" "char *a"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_SESSION_set_ex_data "SSL_SESSION *s" "int idx" "char *arg"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_SESSION_set_time "SSL_SESSION *s" "long t"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_SESSION_set_timeout "SSL_SESSION *s" "long t"
+.Xc
+.El
+.Ss DEALING WITH CONNECTIONS
+Here we document the various API functions which deal with the SSL/TLS
+connection defined in the
+.Vt SSL
+structure.
+.Bl -tag -width Ds
+.It Xo
+.Ft int
+.Fn SSL_accept "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_add_dir_cert_subjects_to_stack "STACK *stack" "const char *dir"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_add_file_cert_subjects_to_stack "STACK *stack" "const char *file"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_add_client_CA "SSL *ssl" "X509 *x"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_alert_desc_string "int value"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_alert_desc_string_long "int value"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_alert_type_string "int value"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_alert_type_string_long "int value"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_check_private_key "const SSL *ssl"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_clear "SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_clear_num_renegotiations "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_connect "SSL *ssl"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_copy_session_id "SSL *t" "const SSL *f"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_ctrl "SSL *ssl" "int cmd" "long larg" "char *parg"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_do_handshake "SSL *ssl"
+.Xc
+.It Xo
+.Ft SSL *
+.Fn SSL_dup "SSL *ssl"
+.Xc
+.It Xo
+.Ft STACK *
+.Fn SSL_dup_CA_list "STACK *sk"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_free "SSL *ssl"
+.Xc
+.It Xo
+.Ft SSL_CTX *
+.Fn SSL_get_SSL_CTX "const SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_app_data "SSL *ssl"
+.Xc
+.It Xo
+.Ft X509 *
+.Fn SSL_get_certificate "const SSL *ssl"
+.Xc
+.It Xo
+.Ft const char *
+.Fn SSL_get_cipher "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_cipher_bits "const SSL *ssl" "int *alg_bits"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_cipher_list "const SSL *ssl" "int n"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_cipher_name "const SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_cipher_version "const SSL *ssl"
+.Xc
+.It Xo
+.Ft STACK *
+.Fn SSL_get_ciphers "const SSL *ssl"
+.Xc
+.It Xo
+.Ft STACK *
+.Fn SSL_get_client_CA_list "const SSL *ssl"
+.Xc
+.It Xo
+.Ft SSL_CIPHER *
+.Fn SSL_get_current_cipher "SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_get_default_timeout "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_error "const SSL *ssl" "int i"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_ex_data "const SSL *ssl" "int idx"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_ex_data_X509_STORE_CTX_idx void
+.Xc
+.It Xo
+.Ft int
+.Fo SSL_get_ex_new_index
+.Fa "long argl"
+.Fa "char *argp"
+.Fa "int (*new_func)(void)"
+.Fa "int (*dup_func)(void)"
+.Fa "void (*free_func)(void)"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_fd "const SSL *ssl"
+.Xc
+.It Xo
+.Ft void
+.Fn "(*SSL_get_info_callback(const SSL *ssl))"
+.Xc
+.It Xo
+.Ft STACK *
+.Fn SSL_get_peer_cert_chain "const SSL *ssl"
+.Xc
+.It Xo
+.Ft X509 *
+.Fn SSL_get_peer_certificate "const SSL *ssl"
+.Xc
+.It Xo
+.Ft EVP_PKEY *
+.Fn SSL_get_privatekey "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_quiet_shutdown "const SSL *ssl"
+.Xc
+.It Xo
+.Ft BIO *
+.Fn SSL_get_rbio "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_read_ahead "const SSL *ssl"
+.Xc
+.It Xo
+.Ft SSL_SESSION *
+.Fn SSL_get_session "const SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_shared_ciphers "const SSL *ssl" "char *buf" "int len"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_shutdown "const SSL *ssl"
+.Xc
+.It Xo
+.Ft const SSL_METHOD *
+.Fn SSL_get_ssl_method "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_state "const SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_get_time "const SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_get_timeout "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn "(*SSL_get_verify_callback(const SSL *ssl))" int "X509_STORE_CTX *"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_get_verify_mode "const SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_get_verify_result "const SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_get_version "const SSL *ssl"
+.Xc
+.It Xo
+.Ft BIO *
+.Fn SSL_get_wbio "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_in_accept_init "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_in_before "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_in_connect_init "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_in_init "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_is_init_finished "SSL *ssl"
+.Xc
+.It Xo
+.Ft STACK *
+.Fn SSL_load_client_CA_file "char *file"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_load_error_strings "void"
+.Xc
+.It Xo
+.Ft SSL *
+.Fn SSL_new "SSL_CTX *ctx"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_num_renegotiations "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_peek "SSL *ssl" "void *buf" "int num"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_pending "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_read "SSL *ssl" "void *buf" "int num"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_renegotiate "SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_rstate_string "SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_rstate_string_long "SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_session_reused "SSL *ssl"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_accept_state "SSL *ssl"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_app_data "SSL *ssl" "char *arg"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_bio "SSL *ssl" "BIO *rbio" "BIO *wbio"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_cipher_list "SSL *ssl" "char *str"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_client_CA_list "SSL *ssl" "STACK *list"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_connect_state "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_ex_data "SSL *ssl" "int idx" "char *arg"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_fd "SSL *ssl" "int fd"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_info_callback "SSL *ssl" "void (*cb)(void)"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_set_msg_callback
+.Fa "SSL *ctx"
+.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, \
+size_t len, SSL *ssl, void *arg)"
+.Fc
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_msg_callback_arg "SSL *ctx" "void *arg"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_options "SSL *ssl" "unsigned long op"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_quiet_shutdown "SSL *ssl" "int mode"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_read_ahead "SSL *ssl" "int yes"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_rfd "SSL *ssl" "int fd"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_session "SSL *ssl" "SSL_SESSION *session"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_shutdown "SSL *ssl" "int mode"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_ssl_method "SSL *ssl" "const SSL_METHOD *meth"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_time "SSL *ssl" "long t"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_timeout "SSL *ssl" "long t"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_verify "SSL *ssl" "int mode" "int (*callback)(void)"
+.Xc
+.It Xo
+.Ft void
+.Fn SSL_set_verify_result "SSL *ssl" "long arg"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_set_wfd "SSL *ssl" "int fd"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_shutdown "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_state "const SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_state_string "const SSL *ssl"
+.Xc
+.It Xo
+.Ft char *
+.Fn SSL_state_string_long "const SSL *ssl"
+.Xc
+.It Xo
+.Ft long
+.Fn SSL_total_renegotiations "SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_PrivateKey_ASN1 "int type" "SSL *ssl" "unsigned char *d" "long len"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_PrivateKey_file "SSL *ssl" "char *file" "int type"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "char *file" "int type"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_certificate "SSL *ssl" "X509 *x"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_certificate_ASN1 "SSL *ssl" "int len" "unsigned char *d"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_certificate_file "SSL *ssl" "char *file" "int type"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_version "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_want "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_want_nothing "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_want_read "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_want_write "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_want_x509_lookup "const SSL *ssl"
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_set_psk_client_callback
+.Fa "SSL *ssl"
+.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \
+unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)"
+.Fc
+.Xc
+.It Xo
+.Ft int
+.Fn SSL_use_psk_identity_hint "SSL *ssl" "const char *hint"
+.Xc
+.It Xo
+.Ft void
+.Fo SSL_set_psk_server_callback
+.Fa "SSL *ssl"
+.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, \
+unsigned char *psk, int max_psk_len)"
+.Fc
+.Xc
+.It Xo
+.Ft const char *
+.Fn SSL_get_psk_identity_hint "SSL *ssl"
+.Xc
+.It Xo
+.Ft const char *
+.Fn SSL_get_psk_identity "SSL *ssl"
+.Xc
+.El
+.Sh SEE ALSO
+.Xr openssl 1 ,
+.Xr crypto 3 ,
+.Xr d2i_SSL_SESSION 3 ,
+.Xr SSL_accept 3 ,
+.Xr SSL_alert_type_string 3 ,
+.Xr SSL_CIPHER_get_name 3 ,
+.Xr SSL_clear 3 ,
+.Xr SSL_COMP_add_compression_method 3 ,
+.Xr SSL_connect 3 ,
+.Xr SSL_CTX_add_extra_chain_cert 3 ,
+.Xr SSL_CTX_add_session 3 ,
+.Xr SSL_CTX_ctrl 3 ,
+.Xr SSL_CTX_flush_sessions 3 ,
+.Xr SSL_CTX_get_ex_new_index 3 ,
+.Xr SSL_CTX_get_verify_mode 3 ,
+.Xr SSL_CTX_load_verify_locations 3 ,
+.Xr SSL_CTX_new 3 ,
+.Xr SSL_CTX_sess_number 3 ,
+.Xr SSL_CTX_sess_set_cache_size 3 ,
+.Xr SSL_CTX_sess_set_get_cb 3 ,
+.Xr SSL_CTX_sessions 3 ,
+.Xr SSL_CTX_set_cert_store 3 ,
+.Xr SSL_CTX_set_cert_verify_callback 3 ,
+.Xr SSL_CTX_set_cipher_list 3 ,
+.Xr SSL_CTX_set_client_CA_list 3 ,
+.Xr SSL_CTX_set_client_cert_cb 3 ,
+.Xr SSL_CTX_set_default_passwd_cb 3 ,
+.Xr SSL_CTX_set_generate_session_id 3 ,
+.Xr SSL_CTX_set_info_callback 3 ,
+.Xr SSL_CTX_set_max_cert_list 3 ,
+.Xr SSL_CTX_set_mode 3 ,
+.Xr SSL_CTX_set_msg_callback 3 ,
+.Xr SSL_CTX_set_options 3 ,
+.Xr SSL_CTX_set_psk_client_callback 3 ,
+.Xr SSL_CTX_set_quiet_shutdown 3 ,
+.Xr SSL_CTX_set_session_cache_mode 3 ,
+.Xr SSL_CTX_set_session_id_context 3 ,
+.Xr SSL_CTX_set_ssl_version 3 ,
+.Xr SSL_CTX_set_timeout 3 ,
+.Xr SSL_CTX_set_tmp_dh_callback 3 ,
+.Xr SSL_CTX_set_tmp_rsa_callback 3 ,
+.Xr SSL_CTX_set_verify 3 ,
+.Xr SSL_CTX_use_certificate 3 ,
+.Xr SSL_CTX_use_psk_identity_hint 3 ,
+.Xr SSL_do_handshake 3 ,
+.Xr SSL_get_ciphers 3 ,
+.Xr SSL_get_client_CA_list 3 ,
+.Xr SSL_get_default_timeout 3 ,
+.Xr SSL_get_error 3 ,
+.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 ,
+.Xr SSL_get_ex_new_index 3 ,
+.Xr SSL_get_fd 3 ,
+.Xr SSL_get_peer_cert_chain 3 ,
+.Xr SSL_get_psk_identity 3 ,
+.Xr SSL_get_rbio 3 ,
+.Xr SSL_get_session 3 ,
+.Xr SSL_get_SSL_CTX 3 ,
+.Xr SSL_get_verify_result 3 ,
+.Xr SSL_get_version 3 ,
+.Xr SSL_library_init 3 ,
+.Xr SSL_load_client_CA_file 3 ,
+.Xr SSL_new 3 ,
+.Xr SSL_pending 3 ,
+.Xr SSL_read 3 ,
+.Xr SSL_rstate_string 3 ,
+.Xr SSL_SESSION_free 3 ,
+.Xr SSL_SESSION_get_ex_new_index 3 ,
+.Xr SSL_SESSION_get_time 3 ,
+.Xr SSL_session_reused 3 ,
+.Xr SSL_set_bio 3 ,
+.Xr SSL_set_connect_state 3 ,
+.Xr SSL_set_fd 3 ,
+.Xr SSL_set_session 3 ,
+.Xr SSL_set_shutdown 3 ,
+.Xr SSL_shutdown 3 ,
+.Xr SSL_state_string 3 ,
+.Xr SSL_want 3 ,
+.Xr SSL_write 3
+.Sh HISTORY
+The
+.Xr ssl 3
+document appeared in OpenSSL 0.9.2.