From: Lutz Jänicke Date: Fri, 8 Dec 2000 14:29:13 +0000 (+0000) Subject: Add manual pages for certficate/key loading and friends. X-Git-Tag: OpenSSL_0_9_6a-beta1~107^2~10 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=66ebbb6a56bc1688fa37878e4feec985b0c260d7;hp=c5e48d8b0143e7f69c6f5bc9ca8e3ba6e4566a78 Add manual pages for certficate/key loading and friends. --- 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 + + long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509) + +=head1 DESCRIPTION + +SSL_CTX_add_extra_chain_cert() adds the certificate B 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. + +=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, +L, +L + +=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/B. +try to fill in missing certificates from B/B, if the +certificate chain was not explicitely specified (see +L, +L. =head1 WARNINGS @@ -113,6 +116,9 @@ The operation succeeded. L, L, -L +L, +L, +L + =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, L, +L, L =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 + + 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 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 +is provided. The pem_passwd_cb must write the password into the provided buffer +B which is of size B. The actual length of the password must +be returned to the calling function. B 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 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 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, +L + +=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 + + 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. The information is passed to SSL objects B +created from B with L by copying, so that +changes applied to B 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 is called for this SSL object. + +SSL_CTX_use_certificate() loads the certificate B into B, +SSL_use_certificate() loads B into B. + +SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from +the memory location B (with length B) into B, +SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B. + +SSL_CTX_use_certificate_file() loads the first certificate stored in B +into B. The formatting B 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 into B. + +SSL_CTX_use_certificate_chain_file() loads a certificate chain from +B into B. 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 as private key to B. +SSL_CTX_use_RSAPrivateKey() adds the private key B of type RSA +to B. SSL_use_PrivateKey() adds B as private key to B; +SSL_use_RSAPrivateKey() adds B as private key of type RSA to B. + +SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B +stored at memory location B (length B) to B. +SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA +stored at memory location B (length B) to B. +SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private +key to B. + +SSL_CTX_use_PrivateKey_file() adds the first private key found in +B to B. The formatting B 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 to B. SSL_use_PrivateKey_file() adds the first private key found +in B to B; SSL_use_RSAPrivateKey_file() adds the first private +RSA key found to B. + +=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. + +When reading certificates and private keys from file, files of type +SSL_FILETYPE_ASN1 (also known as B, 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. +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. + +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. +(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, L, L, +L, +L, +L, +L + +=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, L, L, L, L, L, +L, L, L L, -L +L, +L, L, L, +L, L, L, L, L,