doc/man3/OSSL_CMP_validate_msg.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_CMP_validate_msg,
   6 OSSL_CMP_validate_cert_path
   7 - functions for verifying CMP message protection
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/cmp.h>
  12  int OSSL_CMP_validate_msg(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
  13  int OSSL_CMP_validate_cert_path(const OSSL_CMP_CTX *ctx,
  14                                  X509_STORE *trusted_store, X509 *cert);
  15
  16 =head1 DESCRIPTION
  17
  18 This is the API for validating the protection of CMP messages,
  19 which includes validating CMP message sender certificates and their paths
  20 while optionally checking the revocation status of the certificates(s).
  21
  22 OSSL_CMP_validate_msg() validates the protection of the given C<msg>
  23 using either password-based mac (PBM) or a signature algorithm.
  24
  25 In case of signature algorithm, the certificate to use for the signature check
  26 is preferably the one provided by a call to L<OSSL_CMP_CTX_set1_srvCert(3)>.
  27 If no such sender cert has been pinned then candidate sender certificates are
  28 taken from the list of certificates received in the C<msg> extraCerts, then any
  29 certificates provided before via L<OSSL_CMP_CTX_set1_untrusted_certs(3)>, and
  30 then all trusted certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>,
  31 where a candidate is acceptable only if has not expired, its subject DN matches
  32 the C<msg> sender DN (as far as present), and its subject key identifier
  33 is present and matches the senderKID (as far as the latter present).
  34 Each acceptable cert is tried in the given order to see if the message
  35 signature check succeeds and the cert and its path can be verified
  36 using any trust store set via L<OSSL_CMP_CTX_set0_trustedStore(3)>.
  37
  38 If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling
  39 L<OSSL_CMP_CTX_set_option(3)>, for an Initialization Response (IP) message
  40 any self-issued certificate from the C<msg> extraCerts field may also be used
  41 as trust anchor for the path verification of an acceptable cert if it can be
  42 used also to validate the issued certificate returned in the IP message. This is
  43 according to TS 33.310 [Network Domain Security (NDS); Authentication Framework
  44 (AF)] document specified by the The 3rd Generation Partnership Project (3GPP).
  45
  46 Any cert that has been found as described above is cached and tried first when
  47 validating the signatures of subsequent messages in the same transaction.
  48
  49 After successful validation of PBM-based protection of a certificate response
  50 the certificates in the caPubs field (if any) are added to the trusted
  51 certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>, such that
  52 they are available for validating subsequent messages in the same context.
  53 Those could apply to any Polling Response (pollRep), error, or PKI Confirmation
  54 (PKIConf) messages following in the same or future transactions.
  55
  56 OSSL_CMP_validate_cert_path() attempts to validate the given certificate and its
  57 path using the given store of trusted certs (possibly including CRLs and a cert
  58 verification callback) and non-trusted intermediate certs from the B<ctx>.
  59
  60 =head1 NOTES
  61
  62 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
  63
  64 =head1 RETURN VALUES
  65
  66 OSSL_CMP_validate_msg() and OSSL_CMP_validate_cert_path()
  67 return 1 on success, 0 on error or validation failed.
  68
  69 =head1 SEE ALSO
  70
  71 L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_IR_ses(3)>
  72
  73 =head1 HISTORY
  74
  75 The OpenSSL CMP support was added in OpenSSL 3.0.
  76
  77 =head1 COPYRIGHT
  78
  79 Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
  80
  81 Licensed under the Apache License 2.0 (the "License").  You may not use
  82 this file except in compliance with the License.  You can obtain a copy
  83 in the file LICENSE in the source distribution or at
  84 L<https://www.openssl.org/source/license.html>.
  85
  86 =cut