1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: 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, SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key data
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
   12:  int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
   13:  int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
   14:  int SSL_use_certificate(SSL *ssl, X509 *x);
   15:  int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
   16:  int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
   17: 
   18:  int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
   19: 
   20:  int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
   21:  int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
   22:                                  long len);
   23:  int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
   24:  int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
   25:  int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
   26:  int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
   27:  int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
   28:  int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);
   29:  int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
   30:  int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
   31:  int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
   32:  int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
   33: 
   34:  int SSL_CTX_check_private_key(const SSL_CTX *ctx);
   35:  int SSL_check_private_key(const SSL *ssl);
   36: 
   37: =head1 DESCRIPTION
   38: 
   39: These functions load the certificates and private keys into the SSL_CTX
   40: or SSL object, respectively.
   41: 
   42: The SSL_CTX_* class of functions loads the certificates and keys into the
   43: SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>
   44: created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that
   45: changes applied to B<ctx> do not propagate to already existing SSL objects.
   46: 
   47: The SSL_* class of functions only loads certificates and keys into a
   48: specific SSL object. The specific information is kept, when
   49: L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object.
   50: 
   51: SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,
   52: SSL_use_certificate() loads B<x> into B<ssl>. The rest of the
   53: certificates needed to form the complete certificate chain can be
   54: specified using the
   55: L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
   56: function.
   57: 
   58: SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
   59: the memory location B<d> (with length B<len>) into B<ctx>,
   60: SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.
   61: 
   62: SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>
   63: into B<ctx>. The formatting B<type> of the certificate must be specified
   64: from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
   65: SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.
   66: See the NOTES section on why SSL_CTX_use_certificate_chain_file()
   67: should be preferred.
   68: 
   69: SSL_CTX_use_certificate_chain_file() loads a certificate chain from 
   70: B<file> into B<ctx>. The certificates must be in PEM format and must
   71: be sorted starting with the subject's certificate (actual client or server
   72: certificate), followed by intermediate CA certificates if applicable, and
   73: ending at the highest level (root) CA.
   74: There is no corresponding function working on a single SSL object.
   75: 
   76: SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.
   77: SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA
   78: to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;
   79: SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.
   80: If a certificate has already been set and the private does not belong
   81: to the certificate an error is returned. To change a certificate, private
   82: key pair the new certificate needs to be set with SSL_use_certificate()
   83: or SSL_CTX_use_certificate() before setting the private key with
   84: SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey(). 
   85: 
   86: 
   87: SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
   88: stored at memory location B<d> (length B<len>) to B<ctx>.
   89: SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA
   90: stored at memory location B<d> (length B<len>) to B<ctx>.
   91: SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private
   92: key to B<ssl>.
   93: 
   94: SSL_CTX_use_PrivateKey_file() adds the first private key found in
   95: B<file> to B<ctx>. The formatting B<type> of the certificate must be specified
   96: from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
   97: SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in
   98: B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found
   99: in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private
  100: RSA key found to B<ssl>.
  101: 
  102: SSL_CTX_check_private_key() checks the consistency of a private key with
  103: the corresponding certificate loaded into B<ctx>. If more than one
  104: key/certificate pair (RSA/DSA) is installed, the last item installed will
  105: be checked. If e.g. the last item was a RSA certificate or key, the RSA
  106: key/certificate pair will be checked. SSL_check_private_key() performs
  107: the same check for B<ssl>. If no key/certificate was explicitly added for
  108: this B<ssl>, the last item added into B<ctx> will be checked.
  109: 
  110: =head1 NOTES
  111:   
  112: The internal certificate store of OpenSSL can hold two private key/certificate
  113: pairs at a time: one key/certificate of type RSA and one key/certificate
  114: of type DSA. The certificate used depends on the cipher select, see
  115: also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>.
  116: 
  117: When reading certificates and private keys from file, files of type
  118: SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain
  119: one certificate or private key, consequently 
  120: SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.
  121: Files of type SSL_FILETYPE_PEM can contain more than one item.
  122: 
  123: SSL_CTX_use_certificate_chain_file() adds the first certificate found
  124: in the file to the certificate store. The other certificates are added
  125: to the store of chain certificates using
  126: L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>.
  127: There exists only one extra chain store, so that the same chain is appended
  128: to both types of certificates, RSA and DSA! If it is not intended to use
  129: both type of certificate at the same time, it is recommended to use the
  130: SSL_CTX_use_certificate_chain_file() instead of the
  131: SSL_CTX_use_certificate_file() function in order to allow the use of
  132: complete certificate chains even when no trusted CA storage is used or
  133: when the CA issuing the certificate shall not be added to the trusted
  134: CA storage.
  135: 
  136: If additional certificates are needed to complete the chain during the
  137: TLS negotiation, CA certificates are additionally looked up in the
  138: locations of trusted CA certificates, see
  139: L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
  140: 
  141: The private keys loaded from file can be encrypted. In order to successfully
  142: load encrypted keys, a function returning the passphrase must have been
  143: supplied, see
  144: L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>.
  145: (Certificate files might be encrypted as well from the technical point
  146: of view, it however does not make sense as the data in the certificate
  147: is considered public anyway.)
  148: 
  149: =head1 RETURN VALUES
  150: 
  151: On success, the functions return 1.
  152: Otherwise check out the error stack to find out the reason.
  153: 
  154: =head1 SEE ALSO
  155: 
  156: L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
  157: L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
  158: L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
  159: L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
  160: L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,
  161: L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
  162: 
  163: =head1 HISTORY
  164: 
  165: Support for DER encoded private keys (SSL_FILETYPE_ASN1) in
  166: SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added
  167: in 0.9.8 .
  168: 
  169: =cut