generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add manual pages for certficate/key loading and friends.

Browse Source
This commit is contained in:
Lutz Jänicke 2000-12-08 14:29:13 +00:00
parent c5e48d8b01
commit 66ebbb6a56
6 changed files with 253 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/ssl/SSL_CTX_add_extra_chain_cert.pod Normal file
View File

@ -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

10
doc/ssl/SSL_CTX_load_verify_locations.pod
View File

@ -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

4
doc/ssl/SSL_CTX_set_cipher_list.pod
View File

@ -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

70
doc/ssl/SSL_CTX_set_default_passwd_cb.pod Normal file
View File

@ -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

131
doc/ssl/SSL_CTX_use_certificate.pod Normal file
View File

@ -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

5
doc/ssl/ssl.pod
View File

@ -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)>,