123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661 |
- =pod
- =head1 NAME
- OSSL_CMP_CTX_new,
- OSSL_CMP_CTX_free,
- OSSL_CMP_CTX_reinit,
- OSSL_CMP_CTX_set_option,
- OSSL_CMP_CTX_get_option,
- OSSL_CMP_CTX_set_log_cb,
- OSSL_CMP_CTX_set_log_verbosity,
- OSSL_CMP_CTX_print_errors,
- OSSL_CMP_CTX_set1_serverPath,
- OSSL_CMP_CTX_set1_serverName,
- OSSL_CMP_CTX_set_serverPort,
- OSSL_CMP_CTX_set1_proxyName,
- OSSL_CMP_CTX_set_proxyPort,
- OSSL_CMP_DEFAULT_PORT,
- OSSL_CMP_CTX_set_http_cb,
- OSSL_CMP_CTX_set_http_cb_arg,
- OSSL_CMP_CTX_get_http_cb_arg,
- OSSL_cmp_transfer_cb_t,
- OSSL_CMP_CTX_set_transfer_cb,
- OSSL_CMP_CTX_set_transfer_cb_arg,
- OSSL_CMP_CTX_get_transfer_cb_arg,
- OSSL_CMP_CTX_set1_srvCert,
- 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_pkey,
- OSSL_CMP_CTX_set1_referenceValue,
- OSSL_CMP_CTX_set1_secretValue,
- OSSL_CMP_CTX_set1_recipient,
- OSSL_CMP_CTX_push0_geninfo_ITAV,
- OSSL_CMP_CTX_set1_extraCertsOut,
- OSSL_CMP_CTX_set0_newPkey,
- OSSL_CMP_CTX_get0_newPkey,
- OSSL_CMP_CTX_set1_issuer,
- OSSL_CMP_CTX_set1_subjectName,
- OSSL_CMP_CTX_push1_subjectAltName,
- OSSL_CMP_CTX_set0_reqExtensions,
- OSSL_CMP_CTX_reqExtensions_have_SAN,
- OSSL_CMP_CTX_push0_policy,
- OSSL_CMP_CTX_set1_oldCert,
- OSSL_CMP_CTX_set1_p10CSR,
- OSSL_CMP_CTX_push0_genm_ITAV,
- OSSL_cmp_certConf_cb_t,
- OSSL_CMP_CTX_set_certConf_cb,
- OSSL_CMP_CTX_set_certConf_cb_arg,
- OSSL_CMP_CTX_get_certConf_cb_arg,
- OSSL_CMP_CTX_get_status,
- OSSL_CMP_CTX_get0_statusString,
- OSSL_CMP_CTX_get_failInfoCode,
- OSSL_CMP_CTX_get0_newCert,
- OSSL_CMP_CTX_get1_caPubs,
- OSSL_CMP_CTX_get1_extraCertsIn,
- OSSL_CMP_CTX_set1_transactionID,
- OSSL_CMP_CTX_set1_senderNonce
- - functions for managing the CMP client context data structure
- =head1 SYNOPSIS
- #include <openssl/cmp.h>
- OSSL_CMP_CTX *OSSL_CMP_CTX_new(void);
- 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);
- int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt);
- /* 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);
- /* message transfer: */
- int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);
- int OSSL_CMP_CTX_set1_serverName(OSSL_CMP_CTX *ctx, const char *name);
- int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port);
- int OSSL_CMP_CTX_set1_proxyName(OSSL_CMP_CTX *ctx, const char *name);
- int OSSL_CMP_CTX_set_proxyPort(OSSL_CMP_CTX *ctx, int port);
- #define OSSL_CMP_DEFAULT_PORT 80
- int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb);
- int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
- void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx);
- typedef OSSL_CMP_MSG *(*OSSL_cmp_transfer_cb_t)(OSSL_CMP_CTX *ctx,
- const OSSL_CMP_MSG *req);
- int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx,
- OSSL_cmp_transfer_cb_t cb);
- int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
- void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx);
- /* server authentication: */
- int OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert);
- int OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx,
- 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);
- /* client authentication: */
- int OSSL_CMP_CTX_set1_clCert(OSSL_CMP_CTX *ctx, X509 *cert);
- 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);
- int OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx, const unsigned char *sec,
- const int len);
- /* CMP message header and extra certificates: */
- int OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name);
- int OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);
- int OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx,
- STACK_OF(X509) *extraCertsOut);
- /* certificate template: */
- int OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey);
- EVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv);
- int OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name);
- int OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name);
- int OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx,
- const GENERAL_NAME *name);
- int OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts);
- int OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx);
- int OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo);
- int OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert);
- int OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr);
- /* misc body contents: */
- int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);
- /* certificate confirmation: */
- typedef int (*OSSL_cmp_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert,
- int fail_info, const char **txt);
- 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);
- /* result fetching: */
- int OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx);
- OSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(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_caPubs(const OSSL_CMP_CTX *ctx);
- STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx);
- /* for test purposes only: */
- int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx,
- const ASN1_OCTET_STRING *id);
- int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx,
- const ASN1_OCTET_STRING *nonce);
- =head1 DESCRIPTION
- 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_free() deallocates an OSSL_CMP_CTX structure.
- OSSL_CMP_CTX_reinit() prepares the given B<ctx> for a further transaction by
- clearing the internal CMP transaction (aka session) status, PKIStatusInfo,
- and any previous results (newCert, caPubs, and extraCertsIn)
- from the last executed transaction.
- All other field values (i.e., CMP options) are retained for potential re-use.
- OSSL_CMP_CTX_set_option() sets the given value for the given option
- (e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) in the given OSSL_CMP_CTX structure.
- The following options can be set:
- =over 4
- =item B<OSSL_CMP_OPT_LOG_VERBOSITY>
- The level of severity needed for actually outputting log messages
- due to errors, warnings, general info, debugging, etc.
- Default is OSSL_CMP_LOG_INFO. See also L<OSSL_CMP_log_open(3)>.
- =item B<OSSL_CMP_OPT_MSGTIMEOUT>
- Number of seconds (or 0 for infinite) a CMP message round trip is
- allowed to take before a timeout error is returned. Default is 120.
- =item B<OSSL_CMP_OPT_TOTALTIMEOUT>
- Maximum total number of seconds an enrollment (including polling)
- may take. Default is 0 (infinite).
- =item B<OSSL_CMP_OPT_VALIDITYDAYS>
- Number of days new certificates are asked to be valid for.
- =item B<OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT>
- Do not take default Subject Alternative Names
- from the reference certificate.
- =item B<OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL>
- Demand that the given Subject Alternative Names are flagged as critical.
- =item B<OSSL_CMP_OPT_POLICIES_CRITICAL>
- Demand that the given policies are flagged as critical.
- =item B<OSSL_CMP_OPT_POPOMETHOD>
- Select the proof of possession method to use. Possible values are:
- OSSL_CRMF_POPO_NONE - ProofOfPossession field omitted
- OSSL_CRMF_POPO_RAVERIFIED - assert that the RA has already
- verified the PoPo
- OSSL_CRMF_POPO_SIGNATURE - sign a value with private key,
- which is the default.
- OSSL_CRMF_POPO_KEYENC - decrypt the encrypted certificate
- ("indirect method")
- Note that a signature-based POPO can only be produced if a private key
- is provided as the newPkey or client pkey component of the CMP context.
- =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.
- 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.
- 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.
- Default is HMAC-SHA1 as per RFC 4210.
- =item B<OSSL_CMP_OPT_REVOCATION_REASON>
- The reason code to be included in a Revocation Request (RR);
- values: 0..10 (RFC 5210, 5.3.1) or -1 for none, which is the default.
- =item B<OSSL_CMP_OPT_IMPLICITCONFIRM>
- Request server to enable implicit confirm mode, where the client
- does not need to send confirmation upon receiving the
- certificate. If the server does not enable implicit confirmation
- in the return message, then confirmation is sent anyway.
- =item B<OSSL_CMP_OPT_DISABLECONFIRM>
- Do not confirm enrolled certificates, to cope with broken servers
- not supporting implicit confirmation correctly.
- B<WARNING:> This setting leads to unspecified behavior and it is meant
- exclusively to allow interoperability with server implementations violating
- RFC 4210.
- =item B<OSSL_CMP_OPT_UNPROTECTED_SEND>
- Send messages without CMP-level protection.
- =item B<OSSL_CMP_OPT_UNPROTECTED_ERRORS>
- Accept unprotected error responses which are either explicitly
- unprotected or where protection verification failed. Applies to regular
- error messages as well as certificate responses (IP/CP/KUP) and
- revocation responses (RP) with rejection.
- B<WARNING:> This setting leads to unspecified behavior and it is meant
- exclusively to allow interoperability with server implementations violating
- RFC 4210.
- =item B<OSSL_CMP_OPT_IGNORE_KEYUSAGE>
- Ignore key usage restrictions in signer certificate when
- validating signature-based protection in received CMP messages.
- Else, 'digitalSignature' must be allowed by CMP signer certificates.
- =item B<OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR>
- Allow retrieving a trust anchor from extraCerts and using that
- to validate the certificate chain of an IP message.
- =back
- OSSL_CMP_CTX_get_option() reads the current value of the given option
- (e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) from the given OSSL_CMP_CTX structure.
- OSSL_CMP_CTX_set_log_cb() sets in B<ctx> the callback function C<cb>
- for handling error queue entries and logging messages.
- When C<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
- 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).
- OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host.
- OSSL_CMP_CTX_set1_serverName() sets the given server Address (as IP or name)
- in the given OSSL_CMP_CTX structure.
- OSSL_CMP_CTX_set_serverPort() sets the port of the CMP server to connect to.
- Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly.
- OSSL_CMP_CTX_set1_proxyName() sets the hostname of the HTTP proxy to be used
- for connecting to the CA server.
- OSSL_CMP_CTX_set_proxyPort() sets the port of the HTTP proxy.
- Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly.
- 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>
- 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>
- 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.
- 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.
- After disconnect the modified BIO will be deallocated using BIO_free_all().
- 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.
- OSSL_CMP_CTX_get_http_cb_arg() gets the argument, respectively the pointer to a
- structure containing arguments, previously set by
- OSSL_CMP_CTX_set_http_cb_arg() or NULL if unset.
- OSSL_CMP_CTX_set_transfer_cb() sets the message transfer callback function,
- which has the type
- typedef OSSL_CMP_MSG *(*OSSL_cmp_transfer_cb_t) (OSSL_CMP_CTX *ctx,
- const OSSL_CMP_MSG *req);
- 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>
- parameter and on success return the response.
- 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
- again through OSSL_CMP_CTX_get_transfer_cb_arg().
- 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.
- 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 server certificate to be directly trusted
- (even if it is expired) for verifying response messages.
- The cert pointer is not consumed. It 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 DN of the certificate set via
- OSSL_CMP_CTX_set1_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).
- 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_set1_clCert() sets the client certificate in the given
- OSSL_CMP_CTX structure. The client certificate will then be used by the
- functions to set the "sender" field for outgoing messages and it will be
- included in the extraCerts field.
- OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to the client
- certificate set with B<OSSL_CMP_CTX_set1_clCert()> in the given CMP context.
- Used to create the protection in case of MSG_SIG_ALG.
- OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue in the given
- B<ctx> or clears it if the B<ref> argument is NULL.
- OSSL_CMP_CTX_set1_secretValue() sets the B<sec> with the length B<len> in the
- given B<ctx> or clears it if the B<sec> argument is NULL.
- 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 srvCert if set.
- If neither 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 (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
- added to the GeneralInfo field of the CMP PKIMessage header of a request
- message sent with this context. Consumes the pointer to B<itav>.
- OSSL_CMP_CTX_set1_extraCertsOut() sets the stack of extraCerts that will be
- sent to remote.
- 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.
- 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
- private component then NULL is returned.
- OSSL_CMP_CTX_set1_issuer() sets the name of the intended issuer that
- will be set in the CertTemplate, i.e., the X509 name of the CA server.
- 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 reference certificate,
- see B<OSSL_CMP_CTX_set1_oldCert()>. This default is used for Initialization
- Requests (IR) and Certification Requests (CR) only if no SANs are set.
- If clCert is not set (e.g. in case of IR with MSG_MAC_ALG), the subject DN
- is also used as sender of the PKI message.
- 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 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 reference certificate (see OSSL_CMP_CTX_set1_oldCert().
- If a subject DN is desired it needs to be set explicitly with
- OSSL_CMP_CTX_set1_subjectName().
- OSSL_CMP_CTX_set0_reqExtensions() sets the X.509v3 extensions to be used in
- IR/CR/KUR.
- OSSL_CMP_CTX_reqExtensions_have_SAN() returns 1 if the context contains
- a Subject Alternative Name extension, else 0 or -1 on error.
- OSSL_CMP_CTX_push0_policy() adds the certificate policy info object
- to the X509_EXTENSIONS of the requested certificate template.
- 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 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.
- 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
- will be the body of a General Message sent with this context.
- Consumes the pointer to B<itav>.
- 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.
- 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
- 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
- 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.
- It also could compare the subject DN and other fields of the newly
- enrolled certificate with the certificate template of the request.
- 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.
- OSSL_CMP_CTX_get_certConf_cb_arg() gets the argument, respectively the pointer
- to a structure containing arguments, previously set by
- OSSL_CMP_CTX_set_certConf_cb_arg(), or NULL if unset.
- OSSL_CMP_CTX_get_status() returns the PKIstatus from the last received
- CertRepMessage or Revocation Response or error message, or -1 if unset.
- OSSL_CMP_CTX_get0_statusString() returns the statusString from the last received
- CertRepMessage or Revocation Response or error message, or NULL if unset.
- OSSL_CMP_CTX_get_failInfoCode() returns the error code from the failInfo field
- of the last received CertRepMessage or Revocation Response or error message.
- This is a bit field and the flags for it are specified in the header file
- F<< <openssl/cmp.h> >>.
- The flags start with OSSL_CMP_CTX_FAILINFO, for example:
- OSSL_CMP_CTX_FAILINFO_badAlg. Returns -1 if the failInfoCode field is unset.
- 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_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_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.
- =head1 NOTES
- CMP is defined in RFC 4210 (and CRMF in RFC 4211).
- =head1 RETURN VALUES
- OSSL_CMP_CTX_free() and OSSL_CMP_CTX_print_errors() do not return anything.
- OSSL_CMP_CTX_new(),
- 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_newPkey(),
- OSSL_CMP_CTX_get_certConf_cb_arg(),
- OSSL_CMP_CTX_get0_statusString(),
- OSSL_CMP_CTX_get0_newCert(),
- 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_option(),
- OSSL_CMP_CTX_reqExtensions_have_SAN(),
- OSSL_CMP_CTX_get_status(), and
- OSSL_CMP_CTX_get_failInfoCode()
- return the intended value as described above or -1 on error.
- All other functions return 1 on success, 0 on error.
- =head1 EXAMPLES
- The following code does an Initialization Request:
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_serverName(cmp_ctx, opt_serverName);
- 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);
- initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
- The following code does an Initialization Request using an
- external identity certificate (RFC 4210, Appendix E.7):
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_serverName(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);
- initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
- 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.
- The following code does a Key Update Request:
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
- 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);
- updatedClCert = OSSL_CMP_exec_KUR_ses(cmp_ctx);
- 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.
- cmp_ctx = OSSL_CMP_CTX_new();
- OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
- OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
- OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
- 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);
- OSSL_CMP_CTX_push0_genm_ITAV(cmp_ctx, itav);
- STACK_OF(OSSL_CMP_ITAV) *itavs;
- itavs = OSSL_CMP_exec_GENM_ses(cmp_ctx);
- print_itavs(itavs);
- sk_OSSL_CMP_ITAV_pop_free(itavs, OSSL_CMP_ITAV_free);
- =head1 SEE ALSO
- L<OSSL_CMP_exec_IR_ses(3)>, L<OSSL_CMP_exec_KUR_ses(3)>,
- L<OSSL_CMP_exec_GENM_ses(3)>
- =head1 HISTORY
- The OpenSSL CMP support was added in OpenSSL 3.0.
- =head1 COPYRIGHT
- Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
- Licensed under the Apache License 2.0 (the "License"). You may not use
- this file except in compliance with the License. You can obtain a copy
- in the file LICENSE in the source distribution or at
- L<https://www.openssl.org/source/license.html>.
- =cut
|