Add manual pages for certficate/key loading and friends.

=pod

=head1 NAME

SSL_CTX_add_extra_chain_cert - add certificate to chain

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509)

=head1 DESCRIPTION

SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate

chain presented together with the certificate. Several certificates

can be added one after the other.

=head1 NOTES

When constructing the certificate chain, the chain will be formed from

these certificates explicitly specified. If no chain is specified,

the library will try to complete the chain from the available CA

certificates in the trusted CA storage, see

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.

=head1 RETURN VALUES

SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the

error stack to find out the reason for failure otherwise.

=head1 SEE ALSO

L<ssl(3)|ssl(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>

=cut

failure.

When building its own certificate chain, an OpenSSL client/server will

try to fill in missing certificates from B<CAfile>/B<CApath>.

try to fill in missing certificates from B<CAfile>/B<CApath>, if the

certificate chain was not explicitely specified (see

L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>.

=head1 WARNINGS

L<ssl(3)|ssl(3)>,

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,

L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>

L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,

L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>

=cut

=head1 NAME

SSL_CTX_set_cipher_list, SSL_set_cipher_list 

- choose list of available SSL_CIPHERs

SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs

=head1 SYNOPSIS

=head1 SEE ALSO

L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,

L<ciphers(1)|ciphers(1)>

=cut

=pod

=head1 NAME

SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);

 void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);

 int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata);

=head1 DESCRIPTION

SSL_CTX_set_default_passwd_cb() sets the default password callback called

when loading/storing a PEM certificate with encryption.

SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which

will be provided to the password callback on invocation.

The pem_passwd_cb(), which must be provided by the application, hands back the

password to be used during decryption. On invocation a pointer to B<userdata>

is provided. The pem_passwd_cb must write the password into the provided buffer

B<buf> which is of size B<size>. The actual length of the password must

be returned to the calling function. B<rwflag> indicates whether the

callback is used for reading/decryption (rwflag=0) or writing/encryption

(rwflag=1).

=head1 NOTES

When loading or storing private keys, a password might be supplied to

protect the private key. The way this password can be supplied may depend

on the application. If only one private key is handled, it can be practical

to have pem_passwd_cb() handle the password dialog interactively. If several

keys have to be handled, it can be practical to ask for the password once,

then keep it in memory and use it several times. In the last case, the

password could be stored into the B<userdata> storage and the

pem_passwd_cb() only returns the password already stored.

Other items in PEM formatting (certificates) can also be encrypted, it is

however not usual, as certificate information is considered public.

=head1 RETURN VALUES

SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata()

do not provide diagnostic information.

=head1 EXAMPLES

The following example returns the password provided as B<userdata> to the

calling function. The password is considered to be a '\0' terminated

string. If the password does not fit into the buffer, the password is

truncated.

 int pem_passwd_cb(char *buf, int size, int rwflag, void *password)

 {

  strncpy(buf, (char *)(password), size);

  buf[size - 1] = '\0';

  return(strlen(buf));

 }

=head1 SEE ALSO

L<ssl(3)|ssl(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>

=cut

=pod

=head1 NAME

SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file - load certificate and key data

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);

 int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);

 int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);

 int SSL_use_certificate(SSL *ssl, X509 *x);

 int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);

 int SSL_use_certificate_file(SSL *ssl, const char *file, int type);

 int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);

 int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);

 int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,

				 long len);

 int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);

 int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);

 int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);

 int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);

 int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);

 int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);

 int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);

 int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);

 int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);

 int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);

=head1 DESCRIPTION

These functions load the certificates and private keys into the SSL_CTX

or SSL object, respectively.

The SSL_CTX_* class of functions loads the certificates and keys into the

SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>

created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that

changes applied to B<ctx> do not propagate to already existing SSL objects.

The SSL_* class of functions only loads certificates and keys into a

specific SSL object. The specific information is kept, when

L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object.

SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,

SSL_use_certificate() loads B<x> into B<ssl>.

SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from

the memory location B<d> (with length B<len>) into B<ctx>,

SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.

SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>

into B<ctx>. The formatting B<type> of the certificate must be specified

from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.

SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.

SSL_CTX_use_certificate_chain_file() loads a certificate chain from 

B<file> into B<ctx>. The certificates must be in PEM format and must

be sorted starting with the certificate to the highest level (root CA).

There is no corresponding function working on a single SSL object.

SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.

SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA

to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;

SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.

SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>

stored at memory location B<d> (length B<len>) to B<ctx>.

SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA

stored at memory location B<d> (length B<len>) to B<ctx>.

SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private

key to B<ssl>.

SSL_CTX_use_PrivateKey_file() adds the first private key found in

B<file> to B<ctx>. The formatting B<type> of the certificate must be specified

from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.

SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in

B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found

in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private

RSA key found to B<ssl>.

=head1 NOTES

The internal certificate store of OpenSSL can hold two private key/certificate

pairs at a time: one key/certificate of type RSA and one key/certificate

of type DSA. The certificate used depends on the cipher select, see

also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>.

When reading certificates and private keys from file, files of type

SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain

one certificate or private key, consequently 

SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.

Files of type SSL_FILETYPE_PEM can contain more than one item.

SSL_CTX_use_certificate_chain_file() adds the first certificate found

in the file to the certificate store. The other certificates are added

to the store of chain certificates using

L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>.

There exists only one extra chain store, so that the same chain is appended

to both types of certificates, RSA and DSA!

If additional certificates are needed to complete the chain during the

TLS negotiation, CA certificates are additionally looked up in the

locations of trusted CA certificates, see

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.

The private keys loaded from file can be encrypted. In order to successfully

load encrypted keys, a function returning the passphrase must have been

supplied, see

L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>.

(Certificate files might be encrypted as well from the technical point

of view, it however does not make sense as the data in the certificate

is considered public anyway.)

=head1 RETURN VALUES

On success, the functions return 1.

Otherwise check out the error stack to find out the reason.

=head1 SEE ALSO

L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,

L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,

L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,

L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>

=cut