OSSL_CMP_CTX_set1_expected_sender,
OSSL_CMP_CTX_set0_trustedStore,
OSSL_CMP_CTX_get0_trustedStore,
-OSSL_CMP_CTX_set1_untrusted_certs,
-OSSL_CMP_CTX_get0_untrusted_certs,
-OSSL_CMP_CTX_set1_clCert,
+OSSL_CMP_CTX_set1_untrusted,
+OSSL_CMP_CTX_get0_untrusted,
+OSSL_CMP_CTX_set1_cert,
+OSSL_CMP_CTX_build_cert_chain,
OSSL_CMP_CTX_set1_pkey,
OSSL_CMP_CTX_set1_referenceValue,
OSSL_CMP_CTX_set1_secretValue,
OSSL_CMP_CTX_set1_p10CSR,
OSSL_CMP_CTX_push0_genm_ITAV,
OSSL_CMP_certConf_cb_t,
+OSSL_CMP_certConf_cb,
OSSL_CMP_CTX_set_certConf_cb,
OSSL_CMP_CTX_set_certConf_cb_arg,
OSSL_CMP_CTX_get_certConf_cb_arg,
OSSL_CMP_CTX_get0_statusString,
OSSL_CMP_CTX_get_failInfoCode,
OSSL_CMP_CTX_get0_newCert,
+OSSL_CMP_CTX_get1_newChain,
OSSL_CMP_CTX_get1_caPubs,
OSSL_CMP_CTX_get1_extraCertsIn,
OSSL_CMP_CTX_set1_transactionID,
#include <openssl/cmp.h>
- OSSL_CMP_CTX *OSSL_CMP_CTX_new(void);
+ OSSL_CMP_CTX *OSSL_CMP_CTX_new(OSSL_LIB_CTX *libctx, const char *propq);
void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val);
/* logging and error reporting: */
int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb);
#define OSSL_CMP_CTX_set_log_verbosity(ctx, level)
- void OSSL_CMP_CTX_print_errors(OSSL_CMP_CTX *ctx);
+ void OSSL_CMP_CTX_print_errors(const OSSL_CMP_CTX *ctx);
/* message transfer: */
int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);
const X509_NAME *name);
int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store);
X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx);
- int OSSL_CMP_CTX_set1_untrusted_certs(OSSL_CMP_CTX *ctx,
- STACK_OF(X509) *certs);
- STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted_certs(const OSSL_CMP_CTX *ctx);
+ int OSSL_CMP_CTX_set1_untrusted(OSSL_CMP_CTX *ctx, STACK_OF(X509) *certs);
+ STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted(const OSSL_CMP_CTX *ctx);
/* client authentication: */
- int OSSL_CMP_CTX_set1_clCert(OSSL_CMP_CTX *ctx, X509 *cert);
+ int OSSL_CMP_CTX_set1_cert(OSSL_CMP_CTX *ctx, X509 *cert);
+ int OSSL_CMP_CTX_build_cert_chain(OSSL_CMP_CTX *ctx, X509_STORE *own_trusted,
+ STACK_OF(X509) *candidates);
int OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey);
int OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx,
const unsigned char *ref, int len);
/* certificate confirmation: */
typedef int (*OSSL_CMP_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert,
int fail_info, const char **txt);
+ int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info,
+ const char **text);
int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_certConf_cb_t cb);
int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx);
+ STACK_OF(X509) *OSSL_CMP_CTX_get1_newChain(const OSSL_CMP_CTX *ctx);
STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx);
STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx);
This is the context API for using CMP (Certificate Management Protocol) with
OpenSSL.
-OSSL_CMP_CTX_new() allocates and initializes an OSSL_CMP_CTX structure to
-default values, e.g., proof-of-possession method is set to POPOSigningKey.
+OSSL_CMP_CTX_new() allocates an B<OSSL_CMP_CTX> structure associated with
+the library context I<libctx> and property query string I<propq>,
+both of which may be NULL to select the defaults.
+It initializes the remaining fields to their default values - for instance,
+the logging verbosity is set to OSSL_CMP_LOG_INFO,
+the message timeout is set to 120 seconds,
+and the proof-of-possession method is set to OSSL_CRMF_POPO_SIGNATURE.
OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure.
-OSSL_CMP_CTX_reinit() prepares the given B<ctx> for a further transaction by
+OSSL_CMP_CTX_reinit() prepares the given I<ctx> for a further transaction by
clearing the internal CMP transaction (aka session) status, PKIStatusInfo,
-and any previous results (newCert, caPubs, and extraCertsIn)
+and any previous results (newCert, newChain, caPubs, and extraCertsIn)
from the last executed transaction.
All other field values (i.e., CMP options) are retained for potential re-use.
=item B<OSSL_CMP_OPT_DIGEST_ALGNID>
- The digest algorithm NID to be used in RFC 4210's MSG_SIG_ALG,
- if applicable used for message protection and Proof-of-Possession.
+ The NID of the digest algorithm to be used in RFC 4210's MSG_SIG_ALG
+ for signature-based message protection and Proof-of-Possession (POPO).
Default is SHA256.
- OSSL_CMP_OPT_OWF_ALGNID
- The digest algorithm NID to be used as one-way function (OWF)
- in RFC 4210's MSG_MAC_ALG, if applicable used for message protection.
+=item B<OSSL_CMP_OPT_OWF_ALGNID>
+ The NID of the digest algorithm to be used as one-way function (OWF)
+ in RFC 4210's MSG_MAC_ALG for PBM-based message protection.
Default is SHA256.
- OSSL_CMP_OPT_MAC_ALGNID
- The MAC algorithm NID to be used in RFC 4210's MSG_MAC_ALG,
- if applicable used for message protection.
+=item B<OSSL_CMP_OPT_MAC_ALGNID>
+ The NID of the MAC algorithm to be used in RFC 4210's MSG_MAC_ALG
+ for PBM-based message protection.
Default is HMAC-SHA1 as per RFC 4210.
=item B<OSSL_CMP_OPT_REVOCATION_REASON>
=item B<OSSL_CMP_OPT_IGNORE_KEYUSAGE>
- Ignore key usage restrictions in signer certificate when
+ Ignore key usage restrictions in the signer's certificate when
validating signature-based protection in received CMP messages.
Else, 'digitalSignature' must be allowed by CMP signer certificates.
OSSL_CMP_CTX_get_option() reads the current value of the given option
(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) from the given OSSL_CMP_CTX structure.
-OSSL_CMP_CTX_set_log_cb() sets in B<ctx> the callback function C<cb>
+OSSL_CMP_CTX_set_log_cb() sets in I<ctx> the callback function I<cb>
for handling error queue entries and logging messages.
-When C<cb> is NULL errors are printed to STDERR (if available, else ignored)
+When I<cb> is NULL errors are printed to STDERR (if available, else ignored)
any log messages are ignored.
Alternatively, L<OSSL_CMP_log_open(3)> may be used to direct logging to STDOUT.
OSSL_CMP_CTX_set_log_verbosity() is a macro setting the
OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level.
-OSSL_CMP_CTX_print_errors() outputs any entries in the OpenSSL error queue.
-It is similar to B<ERR_print_errors_cb()> but uses the CMP log callback function
+OSSL_CMP_CTX_print_errors() outputs any entries in the OpenSSL error queue. It
+is similar to L<ERR_print_errors_cb(3)> but uses the CMP log callback function
if set in the C<ctx> for uniformity with CMP logging if given. Otherwise it uses
-B<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
+L<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host,
also known as "CMP alias".
-The default is "/".
+The default is C</>.
-OSSL_CMP_CTX_set1_server() sets the given server
B<address>
-(which may be a hostname or IP address or NULL) in the given B<ctx>.
+OSSL_CMP_CTX_set1_server() sets the given server
I<address>
+(which may be a hostname or IP address or NULL) in the given I<ctx>.
OSSL_CMP_CTX_set_serverPort() sets the port of the CMP server to connect to.
-If not used or the
B<port> argument is 0
+If not used or the
I<port> argument is 0
the default port applies, which is 80 for HTTP and 443 for HTTPS.
OSSL_CMP_CTX_set1_proxy() sets the HTTP proxy to be used for connecting to
the given CMP server unless overruled by any "no_proxy" settings (see below).
If TLS is not used this defaults to the value of
-the environment variable B<http_proxy> if set, else B<HTTP_PROXY>.
-Otherwise defaults to the value of B<https_proxy> if set, else B<HTTPS_PROXY>.
+the environment variable C<http_proxy> if set, else C<HTTP_PROXY>.
+Otherwise defaults to the value of C<https_proxy> if set, else C<HTTPS_PROXY>.
An empty proxy string specifies not to use a proxy.
-Else the format is I<[http[s]://]address[:port][/path]>,
+Else the format is C<[http[s]://]address[:port][/path]>,
where any path given is ignored.
-The default port number is 80, or 443 in case "https:" is given.
+The default port number is 80, or 443 in case C<https:> is given.
OSSL_CMP_CTX_set1_no_proxy() sets the list of server hostnames not to use
an HTTP proxy for. The names may be separated by commas and/or whitespace.
-Defaults to the environment variable B<no_proxy> if set, else B<NO_PROXY>.
+Defaults to the environment variable C<no_proxy> if set, else C<NO_PROXY>.
OSSL_CMP_CTX_set_http_cb() sets the optional BIO connect/disconnect callback
function, which has the prototype
typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *ctx, int connect, int detail);
-The callback may modify the BIO B<bio> provided by OSSL_CMP_MSG_http_perform(),
-whereby it may make use of a custom defined argument B<ctx>
+The callback may modify the I<bio> provided by L<OSSL_CMP_MSG_http_perform(3)>,
+whereby it may make use of a custom defined argument I<ctx>
stored in the OSSL_CMP_CTX by means of OSSL_CMP_CTX_set_http_cb_arg().
-During connection establishment, just after calling BIO_connect_retry(),
-the function is invoked with the B<connect> argument being 1 and the B<detail>
+During connection establishment, just after calling BIO_do_connect_retry(),
+the function is invoked with the I<connect> argument being 1 and the I<detail>
argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled. On
-disconnect B<connect> is 0 and B<detail> is 1 in case no error occurred, else 0.
+disconnect I<connect> is 0 and I<detail> is 1 in case no error occurred, else 0.
For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
after disconnect it may do some diagnostic output and/or specific cleanup.
The function should return NULL to indicate failure.
OSSL_CMP_CTX_set_http_cb_arg() sets an argument, respectively a pointer to
a structure containing arguments,
optionally to be used by the http connect/disconnect callback function.
-
B<arg> is not consumed, and it must therefore explicitly be freed when not
-needed any more.
B<arg> may be NULL to clear the entry.
+
I<arg> is not consumed, and it must therefore explicitly be freed when not
+needed any more.
I<arg> may be NULL to clear the entry.
OSSL_CMP_CTX_get_http_cb_arg() gets the argument, respectively the pointer to a
structure containing arguments, previously set by
Returns 1 on success, 0 on error.
Default is NULL, which implies the use of L<OSSL_CMP_MSG_http_perform(3)>.
-The callback should send the CMP request message it obtains via the B<req>
+The callback should send the CMP request message it obtains via the I<req>
parameter and on success return the response, else it must return NULL.
The transfer callback may make use of a custom defined argument stored in
the ctx by means of OSSL_CMP_CTX_set_transfer_cb_arg(), which may be retrieved
OSSL_CMP_CTX_set_transfer_cb_arg() sets an argument, respectively a pointer to a
structure containing arguments, optionally to be used by the transfer callback.
-
B<arg> is not consumed, and it must therefore explicitly be freed when not
-needed any more.
B<arg> may be NULL to clear the entry.
+
I<arg> is not consumed, and it must therefore explicitly be freed when not
+needed any more.
I<arg> may be NULL to clear the entry.
OSSL_CMP_CTX_get_transfer_cb_arg() gets the argument, respectively the pointer
to a structure containing arguments, previously set by
OSSL_CMP_CTX_set_transfer_cb_arg() or NULL if unset.
-OSSL_CMP_CTX_set1_srvCert() pins the given server certificate B<srvCert>
-directly trusts it (even if it is expired) for verifying response messages.
-The B<cert> argument may be NULL to clear the entry.
-
-OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN) expected to
-be given in the sender response for messages protected with MSG_SIG_ALG. This
-may be used to enforce that during validation of received messages the given DN
-matches the sender field of the PKIMessage header, which in turn is used to
-identify the server certificate.
-This can be used to ensure that only a particular entity is accepted to act as
-CMP server, and attackers are not able to use arbitrary certificates of a
-trusted PKI hierarchy to fraudulently pose as server.
-This defaults to the subject of the B<srvCert>, if any.
-
-OSSL_CMP_CTX_set0_trustedStore() sets the X509_STORE type certificate store
-containing trusted (root) CA certificates. The certificate store may also hold
-CRLs and a certificate verification callback function used for CMP server
-authentication. Any already existing store entry is freed. When given a NULL
-parameter the entry is cleared.
-
-OSSL_CMP_CTX_get0_trustedStore() returns a pointer to the certificate store
-containing trusted root CA certificates, which may be empty if unset.
-
-OSSL_CMP_CTX_set1_untrusted_certs() takes over a list of certificates containing
-non-trusted intermediate certs used for path construction in authentication
-of the CMP server and potentially others (TLS server, newly enrolled cert).
+OSSL_CMP_CTX_set1_srvCert() sets the expected server cert in I<ctx> and trusts
+it directly (even if it is expired) when verifying signed response messages.
+May be used alternatively to OSSL_CMP_CTX_set0_trustedStore()
+to pin the accepted server.
+Any previously set value is freed.
+The I<cert> argument may be NULL to clear the entry.
+If set, the subject of the certificate is also used
+as default value for the recipient of CMP requests
+and as default value for the expected sender of CMP responses.
+
+OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN)
+expected in the sender field of CMP response messages.
+Defaults to the subject of the pinned server certificate, if any.
+This can be used to make sure that only a particular entity is accepted as
+CMP message signer, and attackers are not able to use arbitrary certificates
+of a trusted PKI hierarchy to fraudulently pose as CMP server.
+Note that this gives slightly more freedom than OSSL_CMP_CTX_set1_srvCert(),
+which pins the server to the holder of a particular certificate, while the
+expected sender name will continue to match after updates of the server cert.
+
+OSSL_CMP_CTX_set0_trustedStore() sets the certificate store of type X509_STORE
+containing trusted (root) CA certificates.
+The store may also hold CRLs and
+a certificate verification callback function used for CMP server authentication.
+Any store entry already set before is freed.
+When given a NULL parameter the entry is cleared.
+
+OSSL_CMP_CTX_get0_trustedStore() returns a pointer to the currently set
+certificate store containing trusted cert etc., or an empty store if unset.
+
+OSSL_CMP_CTX_set1_untrusted() sets up a list of non-trusted certificates
+of intermediate CAs that may be useful for path construction for the CMP client
+certificate, for the TLS client certificate (if any), when verifying
+the CMP server certificate, and when verifying newly enrolled certificates.
The reference counts of those certificates handled successfully are increased.
-OSSL_CMP_CTX_get0_untrusted_certs(OSSL_CMP_CTX *ctx) returns a pointer to the
-list of untrusted certs, which my be empty if unset.
+OSSL_CMP_CTX_get0_untrusted(OSSL_CMP_CTX *ctx) returns a pointer to the
+list of untrusted certs, which may be empty if unset.
-OSSL_CMP_CTX_set1_clCert() sets the client certificate in the given B<ctx>.
-The public key of this B<clCert> must correspond to
-the private key set via B<OSSL_CMP_CTX_set1_pkey()>.
+OSSL_CMP_CTX_set1_cert() sets the certificate related to the private key
+used for CMP message protection.
+Therefore the public key of this I<cert> must correspond to
+the private key set before or thereafter via OSSL_CMP_CTX_set1_pkey().
When using signature-based protection of CMP request messages
-this "protection certificate" will be included first in the extraCerts field.
-The subject of this B<clCert> will be used as the "sender" field
-of outgoing CMP messages, with the fallback being
-the B<subjectName> set via B<OSSL_CMP_CTX_set1_subjectName()>.
-The B<cert> argument may be NULL to clear the entry.
-
-OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to
-the client certificate B<clCert> set via B<OSSL_CMP_CTX_set1_clCert()>.
+this CMP signer certificate will be included first in the extraCerts field.
+It serves as fallback reference certificate, see OSSL_CMP_CTX_set1_oldCert().
+The subject of this I<cert> will be used as the sender field of outgoing
+messages, while the subject of any cert set via OSSL_CMP_CTX_set1_oldCert()
+and any value set via OSSL_CMP_CTX_set1_subjectName() are used as fallback.
+
+The I<cert> argument may be NULL to clear the entry.
+
+OSSL_CMP_CTX_build_cert_chain() builds a certificate chain for the CMP signer
+certificate previously set in the I<ctx>. It adds the optional I<candidates>,
+a list of intermediate CA certs that may already constitute the targeted chain,
+to the untrusted certs that may already exist in the I<ctx>.
+Then the function uses this augumented set of certs for chain construction.
+If I<own_trusted> is NULL it builds the chain as far down as possible and
+ignores any verification errors. Else the CMP signer certificate must be
+verifiable where the chain reaches a trust anchor contained in I<own_trusted>.
+On success the function stores the resulting chain in I<ctx>
+for inclusion in the extraCerts field of signature-protected messages.
+Calling this function is optional; by default a chain construction
+is performed on demand that is equivalent to calling this function
+with the I<candidates> and I<own_trusted> arguments being NULL.
+
+OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to the
+CMP signer certificate set via OSSL_CMP_CTX_set1_cert().
This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG)
of outgoing messages
-unless a PBM secret has been set via B<OSSL_CMP_CTX_set1_secretValue()>.
-The
B<pkey> argument may be NULL to clear the entry.
+unless a PBM secret has been set via OSSL_CMP_CTX_set1_secretValue().
+The
I<pkey> argument may be NULL to clear the entry.
-OSSL_CMP_CTX_set1_secretValue() sets the byte string B<sec> with length B<len>
-as PBM secret in the given B<ctx> or clears it if the B<sec> argument is NULL.
+OSSL_CMP_CTX_set1_secretValue() sets the byte string I<sec> with length I<len>
+as PBM secret in the given I<ctx> or clears it if the I<sec> argument is NULL.
If present, this secret is used to create PBM-based protection of outgoing
messages and to verify any PBM-based protection of incoming messages
(protectionAlg = MSG_MAC_ALG). PBM stands for Password-Based MAC.
PBM-based protection takes precedence over signature-based protection.
-OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue B<ref> with
-length B<len> in the given B<ctx> or clears it if the B<ref> argument is NULL.
-According to RFC 4210 section 5.1.1, if no value for the "sender" field in
-CMP message headers can be determined (i.e., no B<clCert> and no B<subjectName>
-is given) then the "sender" field will contain the NULL-DN
+OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue I<ref> with
+length I<len> in the given I<ctx> or clears it if the I<ref> argument is NULL.
+According to RFC 4210 section 5.1.1, if no value for the sender field in
+CMP message headers can be determined (i.e., no CMP signer certificate
+and no subject DN is set via OSSL_CMP_CTX_set1_subjectName()
+then the sender field will contain the NULL-DN
and the senderKID field of the CMP message header must be set.
When signature-based protection is used the senderKID will be set to
-the subjectKeyIdentifier of the <clCert> as far as present.
+the subjectKeyIdentifier of the CMP signer certificate as far as present.
If not present or when PBM-based protection is used
-the B<ref> value is taken as the fallback value for the senderKID.
+the I<ref> value is taken as the fallback value for the senderKID.
OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the
-PKIHeader of a request message, i.e. the X509 name of the (CA) server.
-Setting is overruled by subject of B<srvCert> if set.
-If neither B<srvCert> nor recipient are set, the recipient of the PKI message is
-determined in the following order: issuer, issuer of old cert (oldCert),
-issuer of client cert (B<clCert>), else NULL-DN.
-When a response is received, its sender must match the recipient of the request.
-
-OSSL_CMP_CTX_push0_geninfo_ITAV() adds B<itav> to the stack in the B<ctx> to be
+PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server.
+
+The recipient field in the header of a CMP message is mandatory.
+If not given explicitly the recipient is determined in the following order:
+the subject of the CMP server certificate set using OSSL_CMP_CTX_set1_srvCert(),
+the value set using OSSL_CMP_CTX_set1_issuer(),
+the issuer of the certificate set using OSSL_CMP_CTX_set1_oldCert(),
+the issuer of the CMP signer certificate,
+as far as any of those is present, else the NULL-DN as last resort.
+
+OSSL_CMP_CTX_push0_geninfo_ITAV() adds I<itav> to the stack in the I<ctx> to be
added to the GeneralInfo field of the CMP PKIMessage header of a request
message sent with this context.
OSSL_CMP_CTX_set0_newPkey() can be used to explicitly set the given EVP_PKEY
structure as the private or public key to be certified in the CMP context.
-The
B<priv> parameter must be 0 if and only if the given key is a public key.
+The
I<priv> parameter must be 0 if and only if the given key is a public key.
OSSL_CMP_CTX_get0_newPkey() gives the key to use for certificate enrollment
dependent on fields of the CMP context structure:
the newPkey (which may be a private or public key) if present,
else the public key in the p10CSR if present, else the client private key.
-If the
B<priv> parameter is not 0 and the selected key does not have a
+If the
I<priv> parameter is not 0 and the selected key does not have a
private component then NULL is returned.
OSSL_CMP_CTX_set1_issuer() sets the name of the intended issuer that
OSSL_CMP_CTX_set1_subjectName() sets the subject DN that will be used in
the CertTemplate structure when requesting a new cert. For Key Update Requests
-(KUR), it defaults to the subject DN of the B<reference certificate>,
-see B<OSSL_CMP_CTX_set1_oldCert()>. This default is used for Initialization
+(KUR), it defaults to the subject DN of the reference certificate,
+see OSSL_CMP_CTX_set1_oldCert(). This default is used for Initialization
Requests (IR) and Certification Requests (CR) only if no SANs are set.
-The B<subjectName> is also used as the "sender" field for outgoing CMP messages
-if no B<clCert> has been set (e.g., in case requests are protected using PBM).
+The I<subjectName> is also used as fallback for the sender field
+of outgoing CMP messages if no reference certificate is available.
OSSL_CMP_CTX_push1_subjectAltName() adds the given X509 name to the list of
alternate names on the certificate template request. This cannot be used if
any Subject Alternative Name extension is set via
OSSL_CMP_CTX_set0_reqExtensions().
By default, unless OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT has been set,
-the Subject Alternative Names are copied from the B<reference certificate>,
-see B<OSSL_CMP_CTX_set1_oldCert()>.
-If set and the subject DN is not set with OSSL_CMP_CTX_set1_subjectName(), then
+the Subject Alternative Names are copied from the reference certificate,
+see OSSL_CMP_CTX_set1_oldCert().
+If set and the subject DN is not set with OSSL_CMP_CTX_set1_subjectName() then
the certificate template of an IR and CR will not be filled with the default
-subject DN from the B<reference certificate>.
+subject DN from the reference certificate.
If a subject DN is desired it needs to be set explicitly with
OSSL_CMP_CTX_set1_subjectName().
OSSL_CMP_CTX_set1_oldCert() sets the old certificate to be updated in
Key Update Requests (KUR) or to be revoked in Revocation Requests (RR).
-It must be given for RR, else it defaults to B<clCert>.
-The B<reference certificate> determined in this way, if any, is also used for
-deriving default subject DN and Subject Alternative Names for IR, CR, and KUR.
-Its issuer, if any, is used as default recipient in the CMP message header.
+It must be given for RR, else it defaults to the CMP signer certificate.
+The reference certificate determined in this way, if any, is also used for
+deriving default subject DN and Subject Alternative Names and the
+default issuer entry in the requested certificate template of IR/CR/KUR.
+The subject of the reference certificate is used as the sender field value
+in CMP message headers.
+Its issuer is used as default recipient in CMP message headers.
OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to be used in P10CR.
-OSSL_CMP_CTX_push0_genm_ITAV() adds B<itav> to the stack in the B<ctx> which
+OSSL_CMP_CTX_push0_genm_ITAV() adds I<itav> to the stack in the I<ctx> which
will be the body of a General Message sent with this context.
+OSSL_CMP_certConf_cb() is the default certificate confirmation callback function.
+If the callback argument is not NULL it must point to a trust store.
+In this case the function checks that the newly enrolled certificate can be
+verified using this trust store and untrusted certificates from the I<ctx>,
+which have been augmented by the list of extraCerts received.
+If the callback argument is NULL the function tries building an approximate
+chain as far as possible using the same untrusted certificates from the I<ctx>,
+and if this fails it takes the received extraCerts as fallback.
+The resulting cert chain can be retrieved using OSSL_CMP_CTX_get1_newChain().
+
OSSL_CMP_CTX_set_certConf_cb() sets the callback used for evaluating the newly
enrolled certificate before the library sends, depending on its result,
a positive or negative certConf message to the server. The callback has type
typedef int (*OSSL_CMP_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert,
int fail_info, const char **txt);
-and should inspect the certificate it obtains via the B<cert> parameter and may
-overrule the pre-decision given in the B<fail_info> and B<*txt> parameters.
+and should inspect the certificate it obtains via the I<cert> parameter and may
+overrule the pre-decision given in the I<fail_info> and I<*txt> parameters.
If it accepts the certificate it must return 0, indicating success. Else it must
return a bit field reflecting PKIFailureInfo with at least one failure bit and
-may set the B<*txt> output parameter to point to a string constant with more
+may set the I<*txt> output parameter to point to a string constant with more
detail. The transfer callback may make use of a custom defined argument stored
-in the B<ctx> by means of OSSL_CMP_CTX_set_certConf_cb_arg(), which may be
+in the I<ctx> by means of OSSL_CMP_CTX_set_certConf_cb_arg(), which may be
retrieved again through OSSL_CMP_CTX_get_certConf_cb_arg().
Typically, the callback will check at least that the certificate can be verified
using a set of trusted certificates.
OSSL_CMP_CTX_set_certConf_cb_arg() sets an argument, respectively a pointer to a
structure containing arguments, optionally to be used by the certConf callback.
-
B<arg> is not consumed, and it must therefore explicitly be freed when not
-needed any more.
B<arg> may be NULL to clear the entry.
+
I<arg> is not consumed, and it must therefore explicitly be freed when not
+needed any more.
I<arg> may be NULL to clear the entry.
OSSL_CMP_CTX_get_certConf_cb_arg() gets the argument, respectively the pointer
to a structure containing arguments, previously set by
OSSL_CMP_CTX_get0_newCert() returns the pointer to the newly obtained
certificate in case it is available, else NULL.
-OSSL_CMP_CTX_get1_caPubs() returns a pointer to a duplicate of the stack of
-X.509 certificates received in the caPubs field of last received certificate
-response message IP/CP/KUP.
+OSSL_CMP_CTX_get1_newChain() returns a pointer to a duplicate of the stack of
+X.509 certificates computed by OSSL_CMP_certConf_cb() (if this function has
+been called) on the last received certificate response message IP/CP/KUP.
+
+OSSL_CMP_CTX_get1_caPubs() returns a pointer to a duplicate of the list of
+X.509 certificates in the caPubs field of the last received certificate
+response message (of type IP, CP, or KUP),
+or an empty stack if no caPubs have been received in the current transaction.
-OSSL_CMP_CTX_get1_extraCertsIn() returns a pointer to a duplicate of the stack
-of X.509 certificates received in the last received non-empty extraCerts field.
-Returns an empty stack if no extraCerts have been received in the current
-transaction.
+OSSL_CMP_CTX_get1_extraCertsIn() returns a pointer to a duplicate of the list
+of X.509 certificates contained in the extraCerts field of the last received
+response message (except for pollRep and PKIConf), or
+an empty stack if no extraCerts have been received in the current transaction.
OSSL_CMP_CTX_set1_transactionID() sets the given transaction ID in the given
OSSL_CMP_CTX structure.
-OSSL_CMP_CTX_set1_senderNonce() stores the last sent sender B<nonce> in
-the B<ctx>. This will be used to validate the recipNonce in incoming messages.
+OSSL_CMP_CTX_set1_senderNonce() stores the last sent sender I<nonce> in
+the I<ctx>. This will be used to validate the recipNonce in incoming messages.
=head1 NOTES
OSSL_CMP_CTX_get_http_cb_arg(),
OSSL_CMP_CTX_get_transfer_cb_arg(),
OSSL_CMP_CTX_get0_trustedStore(),
-OSSL_CMP_CTX_get0_untrusted_certs(),
+OSSL_CMP_CTX_get0_untrusted(),
OSSL_CMP_CTX_get0_newPkey(),
OSSL_CMP_CTX_get_certConf_cb_arg(),
OSSL_CMP_CTX_get0_statusString(),
OSSL_CMP_CTX_get0_newCert(),
+OSSL_CMP_CTX_get0_newChain(),
OSSL_CMP_CTX_get1_caPubs(), and
OSSL_CMP_CTX_get1_extraCertsIn()
return the intended pointer value as described above or NULL on error.
OSSL_CMP_CTX_get_failInfoCode()
return the intended value as described above or -1 on error.
+OSSL_CMP_certConf_cb() returns I<fail_info> if it is not equal to 0,
+else 0 on successful validation,
+or else a bit field with the B<OSSL_CMP_PKIFAILUREINFO_incorrectData> bit set.
+
All other functions return 1 on success, 0 on error.
=head1 EXAMPLES
-The following code does an Initialization Request:
+The following code omits error handling.
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_server(cmp_ctx, address);
- OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
- OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
- OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
- OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
+Set up a CMP client context for sending requests and verifying responses:
- initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
+ cmp_ctx = OSSL_CMP_CTX_new();
+ OSSL_CMP_CTX_set1_server(cmp_ctx, name_or_address);
+ OSSL_CMP_CTX_set1_serverPort(cmp_ctx, port_string);
+ OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias);
+ OSSL_CMP_CTX_set0_trustedStore(cmp_ctx, ts);
-The following code does an Initialization Request using an
-external identity certificate (RFC 4210, Appendix E.7):
+Set up client credentials for password-based protection (PBM):
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_server(cmp_ctx, sname);
- OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
- OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
- OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
- OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
+ OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
+ OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
- initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
+Set up the details for certificate requests:
-Here externalCert is an X509 certificate granted to the EE by another CA
-which is trusted by the current CA the code will connect to.
+ OSSL_CMP_CTX_set1_subjectName(cmp_ctx, name);
+ OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, initialKey);
+Perform an Initialization Request transaction:
-The following code does a Key Update Request:
+ initialCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_server(cmp_ctx, url);
- OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
- OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
- OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
- OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
+Reset the transaction state of the CMP context and the credentials:
- updatedClCert = OSSL_CMP_exec_KUR_ses(cmp_ctx);
+ OSSL_CMP_CTX_reinit(cmp_ctx);
+ OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, NULL, 0);
+ OSSL_CMP_CTX_set1_secretValue(cmp_ctx, NULL, 0);
-The following code (which omits error handling) sends a General Message
-including, as an example, the id-it-signKeyPairTypes OID and prints info on
-the General Response contents.
+Perform a Certification Request transaction, making use of the new credentials:
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_server(cmp_ctx, sname);
- OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
- OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
+ OSSL_CMP_CTX_set1_cert(cmp_ctx, initialCert);
+ OSSL_CMP_CTX_set1_pkey(cmp_ctx, initialKey);
+ OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, curentKey);
+ currentCert = OSSL_CMP_exec_CR_ses(cmp_ctx);
+
+Perform a Key Update Request, signed using the cert (and key) to be updated:
+
+ OSSL_CMP_CTX_reinit(cmp_ctx);
+ OSSL_CMP_CTX_set1_cert(cmp_ctx, currentCert);
+ OSSL_CMP_CTX_set1_pkey(cmp_ctx, currentKey);
+ OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, updatedKey);
+ currentCert = OSSL_CMP_exec_KUR_ses(cmp_ctx);
+ currentKey = updatedKey;
+
+Perform a General Message transaction including, as an example,
+the id-it-signKeyPairTypes OID and prints info on the General Response contents:
+
+ OSSL_CMP_CTX_reinit(cmp_ctx);
ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1);
OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_new(type, NULL);
=head1 SEE ALSO
-L<OSSL_CMP_exec_IR_ses(3)>, L<OSSL_CMP_exec_KUR_ses(3)>,
-L<OSSL_CMP_exec_GENM_ses(3)>
+L<OSSL_CMP_exec_IR_ses(3)>, L<OSSL_CMP_exec_CR_ses(3)>,
+L<OSSL_CMP_exec_KUR_ses(3)>, L<OSSL_CMP_exec_GENM_ses(3)>,
+L<OSSL_CMP_exec_certreq(3)>, L<OSSL_CMP_MSG_http_perform(3)>,
+L<ERR_print_errors_cb(3)>
=head1 HISTORY
projects / openssl.git / blobdiff