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