Use in CMP+CRMF libctx and propq param added to sign/verify/HMAC/decrypt

[thirdparty/openssl.git] / doc / internal / man3 / ossl_cmp_msg_protect.pod

=pod

=head1 NAME

ossl_cmp_build_cert_chain,
ossl_cmp_calc_protection,
ossl_cmp_msg_protect,
ossl_cmp_msg_add_extraCerts
- functions for producing CMP message protection

=head1 SYNOPSIS

 #include "cmp_local.h"

 STACK_OF(X509)
     *ossl_cmp_build_cert_chain(OPENSSL_CTX *libctx, const char *propq,
                                STACK_OF(X509) *certs, X509 *cert);
 ASN1_BIT_STRING *ossl_cmp_calc_protection(const OSSL_CMP_CTX *ctx,
                                           const OSSL_CMP_MSG *msg);
 int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
 int ossl_cmp_msg_add_extraCerts(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);

=head1 DESCRIPTION

ossl_cmp_build_cert_chain() builds up the chain of intermediate CA certificates
starting from the given certificate I<cert> as high up as possible using
the given list of candidate certificates, similarly to ssl_add_cert_chain().
It internally uses a B<X509_STORE_CTX> structure associated with the library
context I<libctx> and property query string I<propq>, both of which may be NULL.
Intended use of this function is to find all the certificates above the trust
anchor needed to verify an EE's own certificate.
Those are supposed to be included in the ExtraCerts field of every first
CMP message of a transaction when MSG_SIG_ALG is utilized.
This allocates a stack and increments the reference count of each cert,
so when not needed any more the stack and all its elements should be freed.
In case there is more than one possibility for the chain,
OpenSSL seems to take the first one; check X509_verify_cert() for details.

ossl_cmp_calc_protection() calculates the protection for the given I<msg>
according to the algorithm and parameters in the message header's protectionAlg
using the credentials, library context, and property criteria in the I<ctx>.

ossl_cmp_msg_protect() (re-)protects the given message I<msg> using an algorithm
depending on the available context information given in the I<ctx>.
If there is a secretValue it selects PBMAC, else if there is a protection cert
it selects Signature and uses L<ossl_cmp_msg_add_extraCerts(3)>.
It also sets the protectionAlg field in the message header accordingly.

ossl_cmp_msg_add_extraCerts() adds elements to the extraCerts field in the given
message I<msg>. It tries to build the certificate chain of the client cert in
the I<ctx> if present by using certificates in ctx->untrusted_certs;
if no untrusted certs are set, it will at least add the client certificate.
In any case all the certificates explicitly specified to be sent out (i.e.,
I<ctx->extraCertsOut>) are added. Note that it will NOT add the root certificate
of the chain, i.e, the trust anchor (unless it is part of extraCertsOut).

=head1 NOTES

CMP is defined in RFC 4210 (and CRMF in RFC 4211).

=head1 RETURN VALUES

ossl_cmp_build_cert_chain() returns NULL on error,
else a pointer to a stack of (up_ref'ed) certificates
containing the EE certificate given in the function arguments (cert)
and all intermediate certificates up the chain toward the trust anchor.
The (self-signed) trust anchor is not included.

ossl_cmp_calc_protection() returns the protection on success, else NULL.

All other functions return 1 on success, 0 on error.

=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