Add manual pages for certficate/key loading and friends.

6 files changed, 253 insertions, 5 deletions

diff --git a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
new file mode 100644
index 0000000000..21a9db0e2a
--- /dev/null
+++ b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
@@ -0,0 +1,38 @@
+=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
diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod
index 8e11606dad..0e2d2179c8 100644
--- a/doc/ssl/SSL_CTX_load_verify_locations.pod
+++ b/doc/ssl/SSL_CTX_load_verify_locations.pod
@@ -63,7 +63,10 @@ no other certificates for the same parameters will be searched in case of
 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
 
@@ -113,6 +116,9 @@ The operation succeeded.
 
 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
diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod
index 272d6b3de2..9a29eeeb95 100644
--- a/doc/ssl/SSL_CTX_set_cipher_list.pod
+++ b/doc/ssl/SSL_CTX_set_cipher_list.pod
@@ -2,8 +2,7 @@
 
 =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
 
@@ -47,6 +46,7 @@ could be selected and 0 on complete failure.
 =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
diff --git a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
new file mode 100644
index 0000000000..a5343a1cf3
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
@@ -0,0 +1,70 @@
+=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
diff --git a/doc/ssl/SSL_CTX_use_certificate.pod b/doc/ssl/SSL_CTX_use_certificate.pod
new file mode 100644
index 0000000000..0357c1de3b
--- /dev/null
+++ b/doc/ssl/SSL_CTX_use_certificate.pod
@@ -0,0 +1,131 @@
+=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
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 87f698fba9..5f55cb6804 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -650,12 +650,15 @@ L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>,
 L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>,
 L<SSL_connect(3)|SSL_connect(3)>,
 L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
 L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
 L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
 L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
-L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
 L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>,
 L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
 L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
 L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
 L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(3)>,