mirror of https://github.com/openssl/openssl.git
175 lines
7.5 KiB
Plaintext
175 lines
7.5 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_CMP_exec_certreq,
|
|
OSSL_CMP_exec_IR_ses,
|
|
OSSL_CMP_exec_CR_ses,
|
|
OSSL_CMP_exec_P10CR_ses,
|
|
OSSL_CMP_exec_KUR_ses,
|
|
OSSL_CMP_IR,
|
|
OSSL_CMP_CR,
|
|
OSSL_CMP_P10CR,
|
|
OSSL_CMP_KUR,
|
|
OSSL_CMP_try_certreq,
|
|
OSSL_CMP_exec_RR_ses,
|
|
OSSL_CMP_exec_GENM_ses
|
|
- functions implementing CMP client transactions
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/cmp.h>
|
|
|
|
X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type,
|
|
const OSSL_CRMF_MSG *crm);
|
|
X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
|
|
X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
|
|
X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
|
|
X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
|
|
#define OSSL_CMP_IR
|
|
#define OSSL_CMP_CR
|
|
#define OSSL_CMP_P10CR
|
|
#define OSSL_CMP_KUR
|
|
int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type,
|
|
const OSSL_CRMF_MSG *crm, int *checkAfter);
|
|
X509 *OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
|
|
STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This is the OpenSSL API for doing CMP (Certificate Management Protocol)
|
|
client-server transactions, i.e., sequences of CMP requests and responses.
|
|
|
|
All functions take a populated OSSL_CMP_CTX structure as their first argument.
|
|
Usually the server name, port, and path ("CMP alias") need to be set, as well as
|
|
credentials the client can use for authenticating itself to the client.
|
|
In order to authenticate the server the client typically needs a trust store.
|
|
The functions return their respective main results directly, while there are
|
|
also accessor functions for retrieving various results and status information
|
|
from the B<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.
|
|
|
|
The default conveying protocol is HTTP.
|
|
Timeout values may be given per request-response pair and per transaction.
|
|
See L<OSSL_CMP_MSG_http_perform(3)> for details.
|
|
|
|
OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI.
|
|
|
|
OSSL_CMP_exec_CR_ses() requests an additional certificate.
|
|
|
|
OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate.
|
|
|
|
OSSL_CMP_exec_KUR_ses() obtains an updated certificate.
|
|
|
|
These four types of certificate enrollment are implemented as macros
|
|
calling OSSL_CMP_exec_certreq().
|
|
|
|
OSSL_CMP_exec_certreq() performs a certificate request of the type specified
|
|
by the B<req_type> parameter, which may be IR, CR, P10CR, or KUR.
|
|
For IR, CR, and KUR, the certificate template to be used in the request
|
|
may be supplied via the B<crm> parameter pointing to a CRMF structure.
|
|
Typically B<crm> is NULL, then the template ingredients are taken from B<ctx>
|
|
and need to be filled in using L<OSSL_CMP_CTX_set1_subjectName(3)>,
|
|
L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc.
|
|
For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead.
|
|
The enrollment session may be blocked by sleeping until the addressed
|
|
CA (or an intermedate PKI component) can fully process and answer the request.
|
|
|
|
OSSL_CMP_try_certreq() is an alternative to the above functions that is
|
|
more flexible regarding what to do after receiving a checkAfter value.
|
|
When called for the first time (with no certificate request in progress for
|
|
the given B<ctx>) it starts a new transaction by sending a certificate request
|
|
constructed as stated above using the B<req_type> and optional B<crm> parameter.
|
|
Otherwise (when according to B<ctx> a 'waiting' status has been received before)
|
|
it continues polling for the pending request
|
|
unless the B<req_type> argument is < 0, which aborts the request.
|
|
If the requested certificate is available the function returns 1 and the
|
|
caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate.
|
|
If no error occurred but no certificate is available yet then
|
|
OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried
|
|
and returns -1 after assigning the received checkAfter value
|
|
via the output pointer argument (unless it is NULL).
|
|
The checkAfter value indicates the number of seconds the caller should let pass
|
|
before trying again. The caller is free to sleep for the given number of seconds
|
|
or for some other time and/or to do anything else before retrying by calling
|
|
OSSL_CMP_try_certreq() again with the same parameter values as before.
|
|
OSSL_CMP_try_certreq() then polls
|
|
to see whether meanwhile the requested certificate is available.
|
|
If the caller decides to abort the pending certificate request and provides
|
|
a negative value as the B<req_type> argument then OSSL_CMP_try_certreq()
|
|
aborts the CMP transaction by sending an error message to the server.
|
|
|
|
OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
|
|
specified in the B<ctx> using L<OSSL_CMP_CTX_set1_oldCert(3)>.
|
|
RFC 4210 is vague in which PKIStatus should be returned by the server.
|
|
We take "accepted" and "grantedWithMods" as clear success and handle
|
|
"revocationWarning" and "revocationNotification" just as warnings because CAs
|
|
typically return them as an indication that the certificate was already revoked.
|
|
"rejection" is a clear error. The values "waiting" and "keyUpdateWarning"
|
|
make no sense for revocation and thus are treated as an error as well.
|
|
|
|
OSSL_CMP_exec_GENM_ses() sends a general message containing the sequence of
|
|
infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>)
|
|
provided in the B<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
|
|
It returns the list of B<ITAV>s received in the GenRep.
|
|
This can be used, for instance, to poll for CRLs or CA Key Updates.
|
|
See RFC 4210 section 5.3.19 and appendix E.5 for details.
|
|
|
|
=head1 NOTES
|
|
|
|
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
|
|
|
|
So far the CMP client implementation is limited to one request per CMP message
|
|
(and consequently to at most one response component per CMP message).
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(),
|
|
OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a
|
|
pointer to the newly obtained X509 certificate on success, B<NULL> on error.
|
|
This pointer will be freed implicitly by OSSL_CMP_CTX_free() or
|
|
CSSL_CMP_CTX_reinit().
|
|
|
|
OSSL_CMP_try_certreq() returns 1 if the requested certificate is available
|
|
via L<OSSL_CMP_CTX_get0_newCert(3)>
|
|
or on successfully aborting a pending certificate request, 0 on error, and -1
|
|
in case a 'waiting' status has been received and checkAfter value is available.
|
|
In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL
|
|
and the output parameter B<checkAfter> has been used to
|
|
assign the received value unless B<checkAfter> is NULL.
|
|
|
|
OSSL_CMP_exec_RR_ses() returns the
|
|
pointer to the revoked certificate on success, B<NULL> on error.
|
|
This pointer will be freed implicitly by OSSL_CMP_CTX_free().
|
|
|
|
OSSL_CMP_exec_GENM_ses() returns a
|
|
pointer to the received B<ITAV> sequence on success, B<NULL> on error.
|
|
This pointer must be freed by the caller.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
See OSSL_CMP_CTX for examples on how to prepare the context for these
|
|
functions.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>,
|
|
L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>,
|
|
L<OSSL_CMP_CTX_set1_p10CSR(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>,
|
|
L<OSSL_CMP_CTX_get0_newCert(3)>, L<OSSL_CMP_CTX_push0_genm_ITAV(3)>,
|
|
L<OSSL_CMP_MSG_http_perform(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The OpenSSL CMP support was added in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2007-2020 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
|