doc/internal/man3/ossl_cmp_msg_protect.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_cmp_build_cert_chain,
   6 ossl_cmp_calc_protection,
   7 ossl_cmp_msg_protect,
   8 ossl_cmp_msg_add_extraCerts
   9 - functions for producing CMP message protection
  10
  11 =head1 SYNOPSIS
  12
  13  #include "cmp_local.h"
  14
  15  STACK_OF(X509)
  16      *ossl_cmp_build_cert_chain(OPENSSL_CTX *libctx, const char *propq,
  17                                 X509_STORE *store,
  18                                 STACK_OF(X509) *certs, X509 *cert);
  19  ASN1_BIT_STRING *ossl_cmp_calc_protection(const OSSL_CMP_CTX *ctx,
  20                                            const OSSL_CMP_MSG *msg);
  21  int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
  22  int ossl_cmp_msg_add_extraCerts(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
  23
  24 =head1 DESCRIPTION
  25
  26 ossl_cmp_build_cert_chain() builds a certificate chain starting from I<cert>
  27 using the optional list of intermediate CA certificates I<certs>.
  28 If I<store> is NULL builds the chain as far down as possible, ignoring errors.
  29 Else the chain must reach a trust anchor contained in I<store>.
  30 It internally uses a B<X509_STORE_CTX> structure associated with the library
  31 context I<libctx> and property query string I<propq>, both of which may be NULL.
  32 If a non-NULL stack is returned the caller is responsible for freeing it.
  33 In case there is more than one possibility for the chain,
  34 OpenSSL seems to take the first one; check L<X509_verify_cert(3)> for details.
  35
  36 ossl_cmp_calc_protection() calculates the protection for the given I<msg>
  37 according to the algorithm and parameters in the message header's protectionAlg
  38 using the credentials, library context, and property criteria in the I<ctx>.
  39
  40 ossl_cmp_msg_protect() (re-)protects the given message I<msg> using an algorithm
  41 depending on the available context information given in the I<ctx>.
  42 If there is a secretValue it selects PBMAC, else if there is a protection cert
  43 it selects Signature and uses L<ossl_cmp_msg_add_extraCerts(3)>.
  44 It also sets the protectionAlg field in the message header accordingly.
  45
  46 ossl_cmp_msg_add_extraCerts() adds elements to the extraCerts field in I<msg>.
  47 If signature-based message protection is used it adds first the CMP signer cert
  48 ctx->cert and then its chain ctx->chain. If this chain is not present in I<ctx>
  49 tries to build it using ctx->untrusted and caches the result in ctx->chain.
  50 In any case all the certificates explicitly specified to be sent out (i.e.,
  51 I<ctx->extraCertsOut>) are added. Note that it will NOT add the root certificate
  52 of the chain, i.e, the trust anchor (unless it is part of extraCertsOut).
  53
  54 =head1 NOTES
  55
  56 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
  57
  58 =head1 RETURN VALUES
  59
  60 ossl_cmp_build_cert_chain() returns NULL on error,
  61 else a pointer to a stack of (up_ref'ed) certificates
  62 starting with given EE certificate and followed by all available intermediate
  63 certificates down towards (but excluding) any trusted root certificate.
  64
  65 ossl_cmp_calc_protection() returns the protection on success, else NULL.
  66
  67 All other functions return 1 on success, 0 on error.
  68
  69 =head1 HISTORY
  70
  71 The OpenSSL CMP support was added in OpenSSL 3.0.
  72
  73 =head1 COPYRIGHT
  74
  75 Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
  76
  77 Licensed under the Apache License 2.0 (the "License").  You may not use
  78 this file except in compliance with the License.  You can obtain a copy
  79 in the file LICENSE in the source distribution or at
  80 L<https://www.openssl.org/source/license.html>.
  81
  82 =cut