doc/internal/man3/ossl_cmp_msg_check_update.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_cmp_allow_unprotected_cb_t,
   6 ossl_cmp_msg_check_update
   7 - generic checks on a received CMP message, updating the context
   8
   9 =head1 SYNOPSIS
  10
  11  #include "cmp_local.h"
  12
  13  typedef int (*ossl_cmp_allow_unprotected_cb_t)(const OSSL_CMP_CTX *ctx,
  14                                                 const OSSL_CMP_MSG *msg,
  15                                                 int invalid_protection, int arg);
  16
  17  int ossl_cmp_msg_check_update(OSSL_CMP_CTX *ctx, const OSSL_CMP_MSG *msg,
  18                                ossl_cmp_allow_unprotected_cb_t cb, int cb_arg);
  19
  20 =head1 DESCRIPTION
  21
  22 ossl_cmp_msg_check_update() does all generic checks on the given message B<msg>,
  23 which may be a server response or a request by some client,
  24 and updates the B<ctx> accordingly.
  25
  26 The B<msg> is checked for the following:
  27
  28 =over 4
  29
  30 =item its sender is of appropriate type (currently only B<X509_NAME>)
  31       and matches any expected sender or srvCert subject given in B<ctx>,
  32
  33 =item its protection is present and valid (or a callback function B<cb>
  34 is present and indicates that a missing or invalid protection is acceptable),
  35
  36 =item its CMP protocol version is acceptable, namely B<OSSL_CMP_PVNO>,
  37
  38 =item its body type is valid,
  39
  40 =item its transaction ID matches any transaction ID given in B<ctx>, and
  41
  42 =item its recipNonce matches any senderNonce given in B<ctx>.
  43
  44 =back
  45
  46 In case no protection is present and B<cb> is not NULL then this callback
  47 function is called with its B<invalid_protection> parameter being 0, while in
  48 case an invalid protection is present the B<invalid_protection> parameter is 1.
  49 The callback is passed also the arguments B<ctx>, B<msg>, and <cb_arg>
  50 (which typically contains the expected message type).
  51 The callback should return 1 on acceptance, 0 on rejection, or -1 on error.
  52 It should not put an error on the error stack since this could be misleading.
  53
  54 ossl_cmp_msg_check_update() adds all extraCerts contained in the <msg> to
  55 the list of untrusted certificates in B<ctx> such that they are already usable
  56 for OSSL_CMP_validate_msg(), which is called internally, and for future use.
  57 Thus they are available also to the certificate confirmation callback, and the
  58 peer does not need to send them again (at least not in the same transaction).
  59 Note that it does not help validating the message before storing the extraCerts
  60 because they are not part of the protected portion of the message anyway.
  61 For efficiency, the extraCerts are prepended to the list so they get used first.
  62
  63 If all checks pass then ossl_cmp_msg_check_update()
  64 records in B<ctx> the senderNonce of the received message as the new recipNonce
  65 and learns the transaction ID if none is currently present in B<ctx>.
  66
  67 Moreover, according to RFC 4210 section 5.3.2, if the message protection is
  68 PBM-based then any certificates in the caPubs field are added to the list of
  69 trusted certificates (if set via L<OSSL_CMP_CTX_set0_trustedStore(3)>).
  70 This way these certs are available for validating subsequent messages in the
  71 same context and could apply to any Polling Response (pollRep), error, or PKI
  72 Confirmation (PKIConf) messages following in the same or future transactions.
  73
  74 =head1 RETURN VALUES
  75
  76 ossl_cmp_msg_check_update() returns 1 on success, -1 on error.
  77
  78 =head1 SEE ALSO
  79
  80 L<OSSL_CMP_validate_msg(3)>
  81
  82 =head1 HISTORY
  83
  84 The OpenSSL CMP support was added in OpenSSL 3.0.
  85
  86 =head1 COPYRIGHT
  87
  88 Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
  89
  90 Licensed under the Apache License 2.0 (the "License").  You may not use
  91 this file except in compliance with the License.  You can obtain a copy
  92 in the file LICENSE in the source distribution or at
  93 L<https://www.openssl.org/source/license.html>.
  94
  95 =cut