159191Skris 259191Skris=pod 359191Skris 459191Skris=head1 NAME 559191Skris 659191SkrisSSL - OpenSSL SSL/TLS library 759191Skris 859191Skris=head1 SYNOPSIS 959191Skris 1059191Skris=head1 DESCRIPTION 1159191Skris 1259191SkrisThe OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and 1359191SkrisTransport Layer Security (TLS v1) protocols. It provides a rich API which is 1459191Skrisdocumented here. 1559191Skris 1672613SkrisAt first the library must be initialized; see 1772613SkrisL<SSL_library_init(3)|SSL_library_init(3)>. 1859191Skris 1972613SkrisThen an B<SSL_CTX> object is created as a framework to establish 2072613SkrisTLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>). 2172613SkrisVarious options regarding certificates, algorithms etc. can be set 2272613Skrisin this object. 2359191Skris 2472613SkrisWhen a network connection has been created, it can be assigned to an 2572613SkrisB<SSL> object. After the B<SSL> object has been created using 2672613SkrisL<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or 2772613SkrisL<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network 2872613Skrisconnection with the object. 2959191Skris 3072613SkrisThen the TLS/SSL handshake is performed using 3172613SkrisL<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)> 3272613Skrisrespectively. 3372613SkrisL<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used 3472613Skristo read and write data on the TLS/SSL connection. 3572613SkrisL<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the 3672613SkrisTLS/SSL connection. 3759191Skris 3859191Skris=head1 DATA STRUCTURES 3959191Skris 4059191SkrisCurrently the OpenSSL B<ssl> library functions deals with the following data 4159191Skrisstructures: 4259191Skris 4359191Skris=over 4 4459191Skris 4559191Skris=item B<SSL_METHOD> (SSL Method) 4659191Skris 4759191SkrisThat's a dispatch structure describing the internal B<ssl> library 4859191Skrismethods/functions which implement the various protocol versions (SSLv1, SSLv2 4959191Skrisand TLSv1). It's needed to create an B<SSL_CTX>. 5059191Skris 5159191Skris=item B<SSL_CIPHER> (SSL Cipher) 5259191Skris 5359191SkrisThis structure holds the algorithm information for a particular cipher which 5459191Skrisare a core part of the SSL/TLS protocol. The available ciphers are configured 5559191Skrison a B<SSL_CTX> basis and the actually used ones are then part of the 5659191SkrisB<SSL_SESSION>. 5759191Skris 5859191Skris=item B<SSL_CTX> (SSL Context) 5959191Skris 6059191SkrisThat's the global context structure which is created by a server or client 6159191Skrisonce per program life-time and which holds mainly default values for the 6259191SkrisB<SSL> structures which are later created for the connections. 6359191Skris 6459191Skris=item B<SSL_SESSION> (SSL Session) 6559191Skris 6668651SkrisThis is a structure containing the current TLS/SSL session details for a 6759191Skrisconnection: B<SSL_CIPHER>s, client and server certificates, keys, etc. 6859191Skris 6959191Skris=item B<SSL> (SSL Connection) 7059191Skris 7159191SkrisThat's the main SSL/TLS structure which is created by a server or client per 7259191Skrisestablished connection. This actually is the core structure in the SSL API. 7359191SkrisUnder run-time the application usually deals with this structure which has 7459191Skrislinks to mostly all other structures. 7559191Skris 7659191Skris=back 7759191Skris 7872613Skris 7972613Skris=head1 HEADER FILES 8072613Skris 8172613SkrisCurrently the OpenSSL B<ssl> library provides the following C header files 8272613Skriscontaining the prototypes for the data structures and and functions: 8372613Skris 8472613Skris=over 4 8572613Skris 8672613Skris=item B<ssl.h> 8772613Skris 8872613SkrisThat's the common header file for the SSL/TLS API. Include it into your 8972613Skrisprogram to make the API of the B<ssl> library available. It internally 9072613Skrisincludes both more private SSL headers and headers from the B<crypto> library. 9172613SkrisWhenever you need hard-core details on the internals of the SSL API, look 9272613Skrisinside this header file. 9372613Skris 9472613Skris=item B<ssl2.h> 9572613Skris 9672613SkrisThat's the sub header file dealing with the SSLv2 protocol only. 9772613SkrisI<Usually you don't have to include it explicitly because 9872613Skrisit's already included by ssl.h>. 9972613Skris 10072613Skris=item B<ssl3.h> 10172613Skris 10272613SkrisThat's the sub header file dealing with the SSLv3 protocol only. 10372613SkrisI<Usually you don't have to include it explicitly because 10472613Skrisit's already included by ssl.h>. 10572613Skris 10672613Skris=item B<ssl23.h> 10772613Skris 10872613SkrisThat's the sub header file dealing with the combined use of the SSLv2 and 10972613SkrisSSLv3 protocols. 11072613SkrisI<Usually you don't have to include it explicitly because 11172613Skrisit's already included by ssl.h>. 11272613Skris 11372613Skris=item B<tls1.h> 11472613Skris 11572613SkrisThat's the sub header file dealing with the TLSv1 protocol only. 11672613SkrisI<Usually you don't have to include it explicitly because 11772613Skrisit's already included by ssl.h>. 11872613Skris 11972613Skris=back 12072613Skris 12159191Skris=head1 API FUNCTIONS 12259191Skris 12359191SkrisCurrently the OpenSSL B<ssl> library exports 214 API functions. 12459191SkrisThey are documented in the following: 12559191Skris 12659191Skris=head2 DEALING WITH PROTOCOL METHODS 12759191Skris 12859191SkrisHere we document the various API functions which deal with the SSL/TLS 12959191Skrisprotocol methods defined in B<SSL_METHOD> structures. 13059191Skris 13159191Skris=over 4 13259191Skris 133238405Sjkim=item const SSL_METHOD *B<SSLv2_client_method>(void); 13459191Skris 13559191SkrisConstructor for the SSLv2 SSL_METHOD structure for a dedicated client. 13659191Skris 137238405Sjkim=item const SSL_METHOD *B<SSLv2_server_method>(void); 13859191Skris 13959191SkrisConstructor for the SSLv2 SSL_METHOD structure for a dedicated server. 14059191Skris 141238405Sjkim=item const SSL_METHOD *B<SSLv2_method>(void); 14259191Skris 14359191SkrisConstructor for the SSLv2 SSL_METHOD structure for combined client and server. 14459191Skris 145238405Sjkim=item const SSL_METHOD *B<SSLv3_client_method>(void); 14659191Skris 14759191SkrisConstructor for the SSLv3 SSL_METHOD structure for a dedicated client. 14859191Skris 149238405Sjkim=item const SSL_METHOD *B<SSLv3_server_method>(void); 15059191Skris 15159191SkrisConstructor for the SSLv3 SSL_METHOD structure for a dedicated server. 15259191Skris 153238405Sjkim=item const SSL_METHOD *B<SSLv3_method>(void); 15459191Skris 15559191SkrisConstructor for the SSLv3 SSL_METHOD structure for combined client and server. 15659191Skris 157238405Sjkim=item const SSL_METHOD *B<TLSv1_client_method>(void); 15859191Skris 15959191SkrisConstructor for the TLSv1 SSL_METHOD structure for a dedicated client. 16059191Skris 161238405Sjkim=item const SSL_METHOD *B<TLSv1_server_method>(void); 16259191Skris 16359191SkrisConstructor for the TLSv1 SSL_METHOD structure for a dedicated server. 16459191Skris 165238405Sjkim=item const SSL_METHOD *B<TLSv1_method>(void); 16659191Skris 16759191SkrisConstructor for the TLSv1 SSL_METHOD structure for combined client and server. 16859191Skris 16959191Skris=back 17059191Skris 17159191Skris=head2 DEALING WITH CIPHERS 17259191Skris 17359191SkrisHere we document the various API functions which deal with the SSL/TLS 17459191Skrisciphers defined in B<SSL_CIPHER> structures. 17559191Skris 17659191Skris=over 4 17759191Skris 17859191Skris=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len); 17959191Skris 18059191SkrisWrite a string to I<buf> (with a maximum size of I<len>) containing a human 18159191Skrisreadable description of I<cipher>. Returns I<buf>. 18259191Skris 18359191Skris=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits); 18459191Skris 18559191SkrisDetermine the number of bits in I<cipher>. Because of export crippled ciphers 18659191Skristhere are two bits: The bits the algorithm supports in general (stored to 18759191SkrisI<alg_bits>) and the bits which are actually used (the return value). 18859191Skris 18968651Skris=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); 19059191Skris 19159191SkrisReturn the internal name of I<cipher> as a string. These are the various 19259191Skrisstrings defined by the I<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> 19359191Skrisdefinitions in the header files. 19459191Skris 19559191Skris=item char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); 19659191Skris 19759191SkrisReturns a string like "C<TLSv1/SSLv3>" or "C<SSLv2>" which indicates the 19859191SkrisSSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined 19959191Skrisin the specification the first time). 20059191Skris 20159191Skris=back 20259191Skris 20359191Skris=head2 DEALING WITH PROTOCOL CONTEXTS 20459191Skris 20559191SkrisHere we document the various API functions which deal with the SSL/TLS 20659191Skrisprotocol context defined in the B<SSL_CTX> structure. 20759191Skris 20859191Skris=over 4 20959191Skris 21059191Skris=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x); 21159191Skris 21259191Skris=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509); 21359191Skris 21459191Skris=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c); 21559191Skris 216160814Ssimon=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx); 21759191Skris 21859191Skris=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg); 21959191Skris 22059191Skris=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t); 22159191Skris 22259191Skris=item void B<SSL_CTX_free>(SSL_CTX *a); 22359191Skris 22459191Skris=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx); 22559191Skris 22659191Skris=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx); 22759191Skris 228160814Ssimon=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx); 22959191Skris 23059191Skris=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); 23159191Skris 232296341Sdelphij=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx); 233296341Sdelphij 234160814Ssimon=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx); 23559191Skris 23659191Skris=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) 23759191Skris 23859191Skris=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); 23959191Skris 240160814Ssimon=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx); 24159191Skris 242296341Sdelphij=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx); 243296341Sdelphij 24459191Skris=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx); 24559191Skris 246160814Ssimon=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx); 24759191Skris 248160814Ssimon=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); 24959191Skris 25059191Skris=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx); 25159191Skris 25259191Skris=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, char *CAfile, char *CApath); 25359191Skris 25459191Skris=item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx); 25559191Skris 256238405Sjkim=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth); 25759191Skris 25859191Skris=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); 25959191Skris 26059191Skris=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx); 26159191Skris 26259191Skris=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx); 26359191Skris 26459191Skris=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx); 26559191Skris 26659191Skris=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx); 26759191Skris 26859191Skris=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx); 26959191Skris 27059191Skris=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx); 27159191Skris 27259191Skris=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx); 27359191Skris 27459191Skris=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx); 27559191Skris 27659191Skris=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx); 27759191Skris 27859191Skris=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); 27959191Skris 28059191Skris=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); 28159191Skris 28259191Skris=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); 28359191Skris 28459191Skris=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx); 28559191Skris 28659191Skris=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx); 28759191Skris 28859191Skris=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx); 28959191Skris 29059191Skris=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx,t); 29159191Skris 29259191Skris=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); 29359191Skris 29459191Skris=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); 29559191Skris 29659191Skris=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); 29759191Skris 29859191Skris=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx); 29959191Skris 30059191Skris=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx); 30159191Skris 30259191Skris=item void B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg); 30359191Skris 30459191Skris=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); 30559191Skris 30689837Skris=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) 30759191Skris 30859191Skris=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); 30959191Skris 31059191Skris=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list); 31159191Skris 31259191Skris=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); 31359191Skris 31459191Skris=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void)) 31559191Skris 31659191Skris=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m); 31759191Skris 31859191Skris=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx); 31959191Skris 32059191Skris=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg); 32159191Skris 32259191Skris=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); 32359191Skris 324109998Smarkm=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); 325109998Smarkm 326109998Smarkm=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg); 327109998Smarkm 32859191Skris=item void B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op); 32959191Skris 33059191Skris=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode); 33159191Skris 332296341Sdelphij=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m); 333296341Sdelphij 33459191Skris=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); 33559191Skris 336238405Sjkim=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth); 33759191Skris 33859191Skris=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); 33959191Skris 34059191Skris=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh); 34159191Skris 34259191Skris=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void)); 34359191Skris 34459191Skris=item long B<SSL_CTX_set_tmp_rsa>(SSL_CTX *ctx, RSA *rsa); 34559191Skris 34659191Skris=item SSL_CTX_set_tmp_rsa_callback 34759191Skris 34859191SkrisC<long B<SSL_CTX_set_tmp_rsa_callback>(SSL_CTX *B<ctx>, RSA *(*B<cb>)(SSL *B<ssl>, int B<export>, int B<keylength>));> 34959191Skris 35059191SkrisSets the callback which will be called when a temporary private key is 35159191Skrisrequired. The B<C<export>> flag will be set if the reason for needing 35259191Skrisa temp key is that an export ciphersuite is in use, in which case, 35359191SkrisB<C<keylength>> will contain the required keylength in bits. Generate a key of 35459191Skrisappropriate size (using ???) and return it. 35559191Skris 35659191Skris=item SSL_set_tmp_rsa_callback 35759191Skris 35859191Skrislong B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); 35959191Skris 360109998SmarkmThe same as B<SSL_CTX_set_tmp_rsa_callback>, except it operates on an SSL 36159191Skrissession instead of a context. 36259191Skris 36359191Skris=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void)) 36459191Skris 36559191Skris=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey); 36659191Skris 36759191Skris=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len); 36859191Skris 36959191Skris=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, char *file, int type); 37059191Skris 37159191Skris=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa); 37259191Skris 37359191Skris=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len); 37459191Skris 37559191Skris=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, char *file, int type); 37659191Skris 37759191Skris=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x); 37859191Skris 37959191Skris=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d); 38059191Skris 38159191Skris=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type); 38259191Skris 383238405Sjkim=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); 384238405Sjkim 385238405Sjkim=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint); 386238405Sjkim 387238405Sjkim=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); 388238405Sjkim 389238405Sjkim 390238405Sjkim 391238405Sjkim 39259191Skris=back 39359191Skris 39459191Skris=head2 DEALING WITH SESSIONS 39559191Skris 39659191SkrisHere we document the various API functions which deal with the SSL/TLS 39759191Skrissessions defined in the B<SSL_SESSION> structures. 39859191Skris 39959191Skris=over 4 40059191Skris 401160814Ssimon=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b); 40259191Skris 40359191Skris=item void B<SSL_SESSION_free>(SSL_SESSION *ss); 40459191Skris 40559191Skris=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s); 40659191Skris 407160814Ssimon=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx); 40859191Skris 40959191Skris=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) 41059191Skris 411160814Ssimon=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s); 41259191Skris 413160814Ssimon=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s); 41459191Skris 415160814Ssimon=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a); 41659191Skris 41759191Skris=item SSL_SESSION *B<SSL_SESSION_new>(void); 41859191Skris 419160814Ssimon=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x); 42059191Skris 421160814Ssimon=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x); 42259191Skris 42359191Skris=item void B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a); 42459191Skris 42559191Skris=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg); 42659191Skris 42759191Skris=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t); 42859191Skris 42959191Skris=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t); 43059191Skris 43159191Skris=back 43259191Skris 43359191Skris=head2 DEALING WITH CONNECTIONS 43459191Skris 43559191SkrisHere we document the various API functions which deal with the SSL/TLS 43659191Skrisconnection defined in the B<SSL> structure. 43759191Skris 43859191Skris=over 4 43959191Skris 44059191Skris=item int B<SSL_accept>(SSL *ssl); 44159191Skris 44259191Skris=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir); 44359191Skris 44459191Skris=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file); 44559191Skris 44659191Skris=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x); 44759191Skris 44859191Skris=item char *B<SSL_alert_desc_string>(int value); 44959191Skris 45059191Skris=item char *B<SSL_alert_desc_string_long>(int value); 45159191Skris 45259191Skris=item char *B<SSL_alert_type_string>(int value); 45359191Skris 45459191Skris=item char *B<SSL_alert_type_string_long>(int value); 45559191Skris 456160814Ssimon=item int B<SSL_check_private_key>(const SSL *ssl); 45759191Skris 45859191Skris=item void B<SSL_clear>(SSL *ssl); 45959191Skris 46059191Skris=item long B<SSL_clear_num_renegotiations>(SSL *ssl); 46159191Skris 46259191Skris=item int B<SSL_connect>(SSL *ssl); 46359191Skris 464160814Ssimon=item void B<SSL_copy_session_id>(SSL *t, const SSL *f); 46559191Skris 46659191Skris=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg); 46759191Skris 46859191Skris=item int B<SSL_do_handshake>(SSL *ssl); 46959191Skris 47059191Skris=item SSL *B<SSL_dup>(SSL *ssl); 47159191Skris 47259191Skris=item STACK *B<SSL_dup_CA_list>(STACK *sk); 47359191Skris 47459191Skris=item void B<SSL_free>(SSL *ssl); 47559191Skris 476160814Ssimon=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl); 47759191Skris 47859191Skris=item char *B<SSL_get_app_data>(SSL *ssl); 47959191Skris 480160814Ssimon=item X509 *B<SSL_get_certificate>(const SSL *ssl); 48159191Skris 482160814Ssimon=item const char *B<SSL_get_cipher>(const SSL *ssl); 48359191Skris 484160814Ssimon=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits); 48559191Skris 486160814Ssimon=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n); 48759191Skris 488160814Ssimon=item char *B<SSL_get_cipher_name>(const SSL *ssl); 48959191Skris 490160814Ssimon=item char *B<SSL_get_cipher_version>(const SSL *ssl); 49159191Skris 492160814Ssimon=item STACK *B<SSL_get_ciphers>(const SSL *ssl); 49359191Skris 494160814Ssimon=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl); 49559191Skris 49659191Skris=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl); 49759191Skris 498160814Ssimon=item long B<SSL_get_default_timeout>(const SSL *ssl); 49959191Skris 500160814Ssimon=item int B<SSL_get_error>(const SSL *ssl, int i); 50159191Skris 502160814Ssimon=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx); 50359191Skris 50459191Skris=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void); 50559191Skris 50659191Skris=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) 50759191Skris 508160814Ssimon=item int B<SSL_get_fd>(const SSL *ssl); 50959191Skris 510160814Ssimon=item void (*B<SSL_get_info_callback>(const SSL *ssl);)() 51159191Skris 512160814Ssimon=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl); 51359191Skris 514160814Ssimon=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl); 51559191Skris 51659191Skris=item EVP_PKEY *B<SSL_get_privatekey>(SSL *ssl); 51759191Skris 518160814Ssimon=item int B<SSL_get_quiet_shutdown>(const SSL *ssl); 51959191Skris 520160814Ssimon=item BIO *B<SSL_get_rbio>(const SSL *ssl); 52159191Skris 522160814Ssimon=item int B<SSL_get_read_ahead>(const SSL *ssl); 52359191Skris 524160814Ssimon=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl); 52559191Skris 526160814Ssimon=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len); 52759191Skris 528160814Ssimon=item int B<SSL_get_shutdown>(const SSL *ssl); 52959191Skris 530238405Sjkim=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); 53159191Skris 532160814Ssimon=item int B<SSL_get_state>(const SSL *ssl); 53359191Skris 534160814Ssimon=item long B<SSL_get_time>(const SSL *ssl); 53559191Skris 536160814Ssimon=item long B<SSL_get_timeout>(const SSL *ssl); 53759191Skris 538160814Ssimon=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int,X509_STORE_CTX *) 53959191Skris 540160814Ssimon=item int B<SSL_get_verify_mode>(const SSL *ssl); 54159191Skris 542160814Ssimon=item long B<SSL_get_verify_result>(const SSL *ssl); 54359191Skris 544160814Ssimon=item char *B<SSL_get_version>(const SSL *ssl); 54559191Skris 546160814Ssimon=item BIO *B<SSL_get_wbio>(const SSL *ssl); 54759191Skris 54859191Skris=item int B<SSL_in_accept_init>(SSL *ssl); 54959191Skris 55059191Skris=item int B<SSL_in_before>(SSL *ssl); 55159191Skris 55259191Skris=item int B<SSL_in_connect_init>(SSL *ssl); 55359191Skris 55459191Skris=item int B<SSL_in_init>(SSL *ssl); 55559191Skris 55659191Skris=item int B<SSL_is_init_finished>(SSL *ssl); 55759191Skris 55859191Skris=item STACK *B<SSL_load_client_CA_file>(char *file); 55959191Skris 56059191Skris=item void B<SSL_load_error_strings>(void); 56159191Skris 56259191Skris=item SSL *B<SSL_new>(SSL_CTX *ctx); 56359191Skris 56459191Skris=item long B<SSL_num_renegotiations>(SSL *ssl); 56559191Skris 56676866Skris=item int B<SSL_peek>(SSL *ssl, void *buf, int num); 56759191Skris 568160814Ssimon=item int B<SSL_pending>(const SSL *ssl); 56959191Skris 57076866Skris=item int B<SSL_read>(SSL *ssl, void *buf, int num); 57159191Skris 57259191Skris=item int B<SSL_renegotiate>(SSL *ssl); 57359191Skris 57459191Skris=item char *B<SSL_rstate_string>(SSL *ssl); 57559191Skris 57659191Skris=item char *B<SSL_rstate_string_long>(SSL *ssl); 57759191Skris 57859191Skris=item long B<SSL_session_reused>(SSL *ssl); 57959191Skris 58059191Skris=item void B<SSL_set_accept_state>(SSL *ssl); 58159191Skris 58259191Skris=item void B<SSL_set_app_data>(SSL *ssl, char *arg); 58359191Skris 58459191Skris=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio); 58559191Skris 58659191Skris=item int B<SSL_set_cipher_list>(SSL *ssl, char *str); 58759191Skris 58859191Skris=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list); 58959191Skris 59059191Skris=item void B<SSL_set_connect_state>(SSL *ssl); 59159191Skris 59259191Skris=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg); 59359191Skris 59459191Skris=item int B<SSL_set_fd>(SSL *ssl, int fd); 59559191Skris 59659191Skris=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void)) 59759191Skris 598109998Smarkm=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); 599109998Smarkm 600109998Smarkm=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg); 601109998Smarkm 60259191Skris=item void B<SSL_set_options>(SSL *ssl, unsigned long op); 60359191Skris 60459191Skris=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode); 60559191Skris 60659191Skris=item void B<SSL_set_read_ahead>(SSL *ssl, int yes); 60759191Skris 60859191Skris=item int B<SSL_set_rfd>(SSL *ssl, int fd); 60959191Skris 61059191Skris=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session); 61159191Skris 61259191Skris=item void B<SSL_set_shutdown>(SSL *ssl, int mode); 61359191Skris 614238405Sjkim=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth); 61559191Skris 61659191Skris=item void B<SSL_set_time>(SSL *ssl, long t); 61759191Skris 61859191Skris=item void B<SSL_set_timeout>(SSL *ssl, long t); 61959191Skris 62059191Skris=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void)) 62159191Skris 62259191Skris=item void B<SSL_set_verify_result>(SSL *ssl, long arg); 62359191Skris 62459191Skris=item int B<SSL_set_wfd>(SSL *ssl, int fd); 62559191Skris 62659191Skris=item int B<SSL_shutdown>(SSL *ssl); 62759191Skris 628160814Ssimon=item int B<SSL_state>(const SSL *ssl); 62959191Skris 630160814Ssimon=item char *B<SSL_state_string>(const SSL *ssl); 63159191Skris 632160814Ssimon=item char *B<SSL_state_string_long>(const SSL *ssl); 63359191Skris 63459191Skris=item long B<SSL_total_renegotiations>(SSL *ssl); 63559191Skris 63659191Skris=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey); 63759191Skris 63859191Skris=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len); 63959191Skris 64059191Skris=item int B<SSL_use_PrivateKey_file>(SSL *ssl, char *file, int type); 64159191Skris 64259191Skris=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa); 64359191Skris 64459191Skris=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len); 64559191Skris 64659191Skris=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, char *file, int type); 64759191Skris 64859191Skris=item int B<SSL_use_certificate>(SSL *ssl, X509 *x); 64959191Skris 65059191Skris=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d); 65159191Skris 65259191Skris=item int B<SSL_use_certificate_file>(SSL *ssl, char *file, int type); 65359191Skris 654160814Ssimon=item int B<SSL_version>(const SSL *ssl); 65559191Skris 656160814Ssimon=item int B<SSL_want>(const SSL *ssl); 65759191Skris 658160814Ssimon=item int B<SSL_want_nothing>(const SSL *ssl); 65959191Skris 660160814Ssimon=item int B<SSL_want_read>(const SSL *ssl); 66159191Skris 662160814Ssimon=item int B<SSL_want_write>(const SSL *ssl); 66359191Skris 664160814Ssimon=item int B<SSL_want_x509_lookup>(const SSL *ssl); 66559191Skris 66676866Skris=item int B<SSL_write>(SSL *ssl, const void *buf, int num); 66759191Skris 668238405Sjkim=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); 669238405Sjkim 670238405Sjkim=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint); 671238405Sjkim 672238405Sjkim=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); 673238405Sjkim 674238405Sjkim=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl); 675238405Sjkim 676238405Sjkim=item const char *B<SSL_get_psk_identity>(SSL *ssl); 677238405Sjkim 67859191Skris=back 67959191Skris 68059191Skris=head1 SEE ALSO 68159191Skris 68259191SkrisL<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>, 68368651SkrisL<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, 68472613SkrisL<SSL_connect(3)|SSL_connect(3)>, 68572613SkrisL<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>, 68689837SkrisL<SSL_COMP_add_compression_method(3)|SSL_COMP_add_compression_method(3)>, 68772613SkrisL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 68872613SkrisL<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, 68989837SkrisL<SSL_CTX_ctrl(3)|SSL_CTX_ctrl(3)>, 69072613SkrisL<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, 69172613SkrisL<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>, 69272613SkrisL<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, 69372613SkrisL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> 69472613SkrisL<SSL_CTX_new(3)|SSL_CTX_new(3)>, 69576866SkrisL<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, 69672613SkrisL<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, 69772613SkrisL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, 69872613SkrisL<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>, 69989837SkrisL<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>, 70089837SkrisL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, 70189837SkrisL<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 70272613SkrisL<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, 703100928SnectarL<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, 70472613SkrisL<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, 705109998SmarkmL<SSL_CTX_set_generate_session_id(3)|SSL_CTX_set_generate_session_id(3)>, 70689837SkrisL<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>, 707109998SmarkmL<SSL_CTX_set_max_cert_list(3)|SSL_CTX_set_max_cert_list(3)>, 70876866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, 709109998SmarkmL<SSL_CTX_set_msg_callback(3)|SSL_CTX_set_msg_callback(3)>, 71072613SkrisL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, 71189837SkrisL<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, 712296341SdelphijL<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>, 71372613SkrisL<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, 71472613SkrisL<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, 71568651SkrisL<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, 71672613SkrisL<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, 71789837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 71889837SkrisL<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, 71972613SkrisL<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, 72072613SkrisL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, 72189837SkrisL<SSL_alert_type_string(3)|SSL_alert_type_string(3)>, 722100936SnectarL<SSL_do_handshake(3)|SSL_do_handshake(3)>, 72389837SkrisL<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, 72468651SkrisL<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, 72572613SkrisL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 72689837SkrisL<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>, 72772613SkrisL<SSL_get_error(3)|SSL_get_error(3)>, 72872613SkrisL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, 72972613SkrisL<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, 73072613SkrisL<SSL_get_fd(3)|SSL_get_fd(3)>, 73168651SkrisL<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, 73268651SkrisL<SSL_get_rbio(3)|SSL_get_rbio(3)>, 73368651SkrisL<SSL_get_session(3)|SSL_get_session(3)>, 73468651SkrisL<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, 73576866SkrisL<SSL_get_version(3)|SSL_get_version(3)>, 73672613SkrisL<SSL_library_init(3)|SSL_library_init(3)>, 73772613SkrisL<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, 73872613SkrisL<SSL_new(3)|SSL_new(3)>, 73989837SkrisL<SSL_pending(3)|SSL_pending(3)>, 74089837SkrisL<SSL_read(3)|SSL_read(3)>, 74189837SkrisL<SSL_rstate_string(3)|SSL_rstate_string(3)>, 74289837SkrisL<SSL_session_reused(3)|SSL_session_reused(3)>, 74389837SkrisL<SSL_set_bio(3)|SSL_set_bio(3)>, 74476866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 74589837SkrisL<SSL_set_fd(3)|SSL_set_fd(3)>, 74668651SkrisL<SSL_set_session(3)|SSL_set_session(3)>, 74776866SkrisL<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 74889837SkrisL<SSL_shutdown(3)|SSL_shutdown(3)>, 74989837SkrisL<SSL_state_string(3)|SSL_state_string(3)>, 75089837SkrisL<SSL_want(3)|SSL_want(3)>, 75189837SkrisL<SSL_write(3)|SSL_write(3)>, 75272613SkrisL<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 75372613SkrisL<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, 75472613SkrisL<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, 755238405SjkimL<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, 756238405SjkimL<SSL_CTX_set_psk_client_callback(3)|SSL_CTX_set_psk_client_callback(3)>, 757238405SjkimL<SSL_CTX_use_psk_identity_hint(3)|SSL_CTX_use_psk_identity_hint(3)>, 758238405SjkimL<SSL_get_psk_identity(3)|SSL_get_psk_identity(3)> 75959191Skris 76059191Skris=head1 HISTORY 76159191Skris 76259191SkrisThe L<ssl(3)|ssl(3)> document appeared in OpenSSL 0.9.2 76359191Skris 76459191Skris=cut 76559191Skris 766