ossl_cmp_msg_protect.pod 2.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869
  1. =pod
  2. =head1 NAME
  3. ossl_cmp_calc_protection,
  4. ossl_cmp_msg_protect,
  5. ossl_cmp_msg_add_extraCerts
  6. - functions for producing CMP message protection
  7. =head1 SYNOPSIS
  8. #include "cmp_local.h"
  9. ASN1_BIT_STRING *ossl_cmp_calc_protection(const OSSL_CMP_CTX *ctx,
  10. const OSSL_CMP_MSG *msg);
  11. int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
  12. int ossl_cmp_msg_add_extraCerts(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
  13. =head1 DESCRIPTION
  14. ossl_cmp_calc_protection() calculates the protection for the given I<msg>
  15. according to the algorithm and parameters in the message header's protectionAlg
  16. using the credentials, library context, and property criteria in the I<ctx>.
  17. Unless I<msg->header->protectionAlg> is B<PasswordBasedMAC>,
  18. its value is completed according to I<ctx->pkey> and I<ctx->digest>,
  19. where the latter irrelevant in the case of Edwards curves.
  20. ossl_cmp_msg_protect() (re-)protects the given message I<msg> using an algorithm
  21. depending on the available context information given in the I<ctx>.
  22. If there is a secretValue it selects PBMAC, else if there is a protection cert
  23. it selects Signature and uses ossl_cmp_msg_add_extraCerts (see below).
  24. It also sets the protectionAlg field in the message header accordingly.
  25. ossl_cmp_msg_add_extraCerts() adds elements to the extraCerts field in I<msg>.
  26. If signature-based message protection is used it adds first the CMP signer cert
  27. ctx->cert and then its chain ctx->chain. If this chain is not present in I<ctx>
  28. tries to build it using ctx->untrusted and caches the result in ctx->chain.
  29. In any case all the certificates explicitly specified to be sent out (i.e.,
  30. I<ctx->extraCertsOut>) are added. Note that it will NOT add the root certificate
  31. of the chain, i.e, the trust anchor (unless it is part of extraCertsOut).
  32. =head1 NOTES
  33. CMP is defined in RFC 4210 (and CRMF in RFC 4211).
  34. The I<ctx> parameter of ossl_cmp_msg_add_extraCerts()
  35. and thus also of ossl_cmp_msg_protect() cannot be made I<const>
  36. because I<ctx->chain> may get adapted to cache the chain of the CMP signer cert.
  37. =head1 RETURN VALUES
  38. ossl_cmp_calc_protection() returns the protection on success, else NULL.
  39. All other functions return 1 on success, 0 on error.
  40. =head1 HISTORY
  41. The OpenSSL CMP support was added in OpenSSL 3.0.
  42. =head1 COPYRIGHT
  43. Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved.
  44. Licensed under the Apache License 2.0 (the "License"). You may not use
  45. this file except in compliance with the License. You can obtain a copy
  46. in the file LICENSE in the source distribution or at
  47. L<https://www.openssl.org/source/license.html>.
  48. =cut