path: root/lib/libssl/man/SSL_CTX_use_certificate.3

.\"
.\"	$OpenBSD: SSL_CTX_use_certificate.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
.\"
.Dd $Mdocdate: November 5 2016 $
.Dt SSL_CTX_USE_CERTIFICATE 3
.Os
.Sh NAME
.Nm SSL_CTX_use_certificate ,
.Nm SSL_CTX_use_certificate_ASN1 ,
.Nm SSL_CTX_use_certificate_file ,
.Nm SSL_use_certificate ,
.Nm SSL_use_certificate_ASN1 ,
.Nm SSL_use_certificate_file ,
.Nm SSL_CTX_use_certificate_chain_file ,
.Nm SSL_CTX_use_certificate_chain_mem ,
.Nm SSL_CTX_use_PrivateKey ,
.Nm SSL_CTX_use_PrivateKey_ASN1 ,
.Nm SSL_CTX_use_PrivateKey_file ,
.Nm SSL_CTX_use_RSAPrivateKey ,
.Nm SSL_CTX_use_RSAPrivateKey_ASN1 ,
.Nm SSL_CTX_use_RSAPrivateKey_file ,
.Nm SSL_use_PrivateKey_file ,
.Nm SSL_use_PrivateKey_ASN1 ,
.Nm SSL_use_PrivateKey ,
.Nm SSL_use_RSAPrivateKey ,
.Nm SSL_use_RSAPrivateKey_ASN1 ,
.Nm SSL_use_RSAPrivateKey_file ,
.Nm SSL_CTX_check_private_key ,
.Nm SSL_check_private_key
.Nd load certificate and key data
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft int
.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x"
.Ft int
.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d"
.Ft int
.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "const char *file" "int type"
.Ft int
.Fn SSL_use_certificate "SSL *ssl" "X509 *x"
.Ft int
.Fn SSL_use_certificate_ASN1 "SSL *ssl" "unsigned char *d" "int len"
.Ft int
.Fn SSL_use_certificate_file "SSL *ssl" "const char *file" "int type"
.Ft int
.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file"
.Ft int
.Fn SSL_CTX_use_certificate_chain_mem "SSL_CTX *ctx" "void *buf" "int len"
.Ft int
.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey"
.Ft int
.Fo SSL_CTX_use_PrivateKey_ASN1
.Fa "int pk" "SSL_CTX *ctx" "unsigned char *d" "long len"
.Fc
.Ft int
.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "const char *file" "int type"
.Ft int
.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa"
.Ft int
.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len"
.Ft int
.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "const char *file" "int type"
.Ft int
.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey"
.Ft int
.Fn SSL_use_PrivateKey_ASN1 "int pk" "SSL *ssl" "unsigned char *d" "long len"
.Ft int
.Fn SSL_use_PrivateKey_file "SSL *ssl" "const char *file" "int type"
.Ft int
.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa"
.Ft int
.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len"
.Ft int
.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "const char *file" "int type"
.Ft int
.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx"
.Ft int
.Fn SSL_check_private_key "const SSL *ssl"
.Sh DESCRIPTION
These functions load the certificates and private keys into the
.Vt SSL_CTX
or
.Vt SSL
object, respectively.
.Pp
The
.Fn SSL_CTX_*
class of functions loads the certificates and keys into the
.Vt SSL_CTX
object
.Fa ctx .
The information is passed to
.Vt SSL
objects
.Fa ssl
created from
.Fa ctx
with
.Xr SSL_new 3
by copying, so that changes applied to
.Fa ctx
do not propagate to already existing
.Vt SSL
objects.
.Pp
The
.Fn SSL_*
class of functions only loads certificates and keys into a specific
.Vt SSL
object.
The specific information is kept when
.Xr SSL_clear 3
is called for this
.Vt SSL
object.
.Pp
.Fn SSL_CTX_use_certificate
loads the certificate
.Fa x
into
.Fa ctx ;
.Fn SSL_use_certificate
loads
.Fa x
into
.Fa ssl .
The rest of the certificates needed to form the complete certificate chain can
be specified using the
.Xr SSL_CTX_add_extra_chain_cert 3
function.
.Pp
.Fn SSL_CTX_use_certificate_ASN1
loads the ASN1 encoded certificate from the memory location
.Fa d
(with length
.Fa len )
into
.Fa ctx ;
.Fn SSL_use_certificate_ASN1
loads the ASN1 encoded certificate into
.Fa ssl .
.Pp
.Fn SSL_CTX_use_certificate_file
loads the first certificate stored in
.Fa file
into
.Fa ctx .
The formatting
.Fa type
of the certificate must be specified from the known types
.Dv SSL_FILETYPE_PEM
and
.Dv SSL_FILETYPE_ASN1 .
.Fn SSL_use_certificate_file
loads the certificate from
.Fa file
into
.Fa ssl .
See the
.Sx NOTES
section on why
.Fn SSL_CTX_use_certificate_chain_file
should be preferred.
.Pp
The
.Fn SSL_CTX_use_certificate_chain*
functions load a certificate chain into
.Fa ctx .
The certificates must be in PEM format and must be sorted starting with the
subject's certificate (actual client or server certificate),
followed by intermediate CA certificates if applicable,
and ending at the highest level (root) CA.
There is no corresponding function working on a single
.Vt SSL
object.
.Pp
.Fn SSL_CTX_use_PrivateKey
adds
.Fa pkey
as private key to
.Fa ctx .
.Fn SSL_CTX_use_RSAPrivateKey
adds the private key
.Fa rsa
of type RSA to
.Fa ctx .
.Fn SSL_use_PrivateKey
adds
.Fa pkey
as private key to
.Fa ssl ;
.Fn SSL_use_RSAPrivateKey
adds
.Fa rsa
as private key of type RSA to
.Fa ssl .
If a certificate has already been set and the private does not belong to the
certificate, an error is returned.
To change a certificate private key pair,
the new certificate needs to be set with
.Fn SSL_use_certificate
or
.Fn SSL_CTX_use_certificate
before setting the private key with
.Fn SSL_CTX_use_PrivateKey
or
.Fn SSL_use_PrivateKey .
.Pp
.Fn SSL_CTX_use_PrivateKey_ASN1
adds the private key of type
.Fa pk
stored at memory location
.Fa d
(length
.Fa len )
to
.Fa ctx .
.Fn SSL_CTX_use_RSAPrivateKey_ASN1
adds the private key of type RSA stored at memory location
.Fa d
(length
.Fa len )
to
.Fa ctx .
.Fn SSL_use_PrivateKey_ASN1
and
.Fn SSL_use_RSAPrivateKey_ASN1
add the private key to
.Fa ssl .
.Pp
.Fn SSL_CTX_use_PrivateKey_file
adds the first private key found in
.Fa file
to
.Fa ctx .
The formatting
.Fa type
of the certificate must be specified from the known types
.Dv SSL_FILETYPE_PEM
and
.Dv SSL_FILETYPE_ASN1 .
.Fn SSL_CTX_use_RSAPrivateKey_file
adds the first private RSA key found in
.Fa file
to
.Fa ctx .
.Fn SSL_use_PrivateKey_file
adds the first private key found in
.Fa file
to
.Fa ssl ;
.Fn SSL_use_RSAPrivateKey_file
adds the first private RSA key found to
.Fa ssl .
.Pp
.Fn SSL_CTX_check_private_key
checks the consistency of a private key with the corresponding certificate
loaded into
.Fa ctx .
If more than one key/certificate pair (RSA/DSA) is installed,
the last item installed will be checked.
If, e.g., the last item was a RSA certificate or key,
the RSA key/certificate pair will be checked.
.Fn SSL_check_private_key
performs the same check for
.Fa ssl .
If no key/certificate was explicitly added for this
.Fa ssl ,
the last item added into
.Fa ctx
will be checked.
.Sh 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
.Xr SSL_CTX_set_cipher_list 3 .
.Pp
When reading certificates and private keys from file, files of type
.Dv SSL_FILETYPE_ASN1
(also known as
.Em DER ,
binary encoding) can only contain one certificate or private key; consequently,
.Fn SSL_CTX_use_certificate_chain_file
is only applicable to PEM formatting.
Files of type
.Dv SSL_FILETYPE_PEM
can contain more than one item.
.Pp
.Fn 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
.Xr 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 it is not intended to use both type of certificate at the same time,
it is recommended to use the
.Fn SSL_CTX_use_certificate_chain_file
instead of the
.Fn SSL_CTX_use_certificate_file
function in order to allow the use of complete certificate chains even when no
trusted CA storage is used or when the CA issuing the certificate shall not be
added to the trusted CA storage.
.Pp
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
.Xr SSL_CTX_load_verify_locations 3 ) .
.Pp
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
.Xr 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.)
.Sh RETURN VALUES
On success, the functions return 1.
Otherwise check out the error stack to find out the reason.
.Sh SEE ALSO
.Xr ssl 3 ,
.Xr SSL_clear 3 ,
.Xr SSL_CTX_add_extra_chain_cert 3 ,
.Xr SSL_CTX_load_verify_locations 3 ,
.Xr SSL_CTX_set_cipher_list 3 ,
.Xr SSL_CTX_set_client_cert_cb 3 ,
.Xr SSL_CTX_set_default_passwd_cb 3 ,
.Xr SSL_new 3
.Sh HISTORY
Support for DER encoded private keys
.Pq Dv SSL_FILETYPE_ASN1
in
.Fn SSL_CTX_use_PrivateKey_file
and
.Fn SSL_use_PrivateKey_file
was added in 0.9.8.