Latest update.

doc/internal/man3/ossl_cmp_msg_check_received.pod

@@ -0,0 +1,86 @@
+=pod
+
+=head1 NAME
+
+ossl_cmp_allow_unprotected_cb_t,
+ossl_cmp_msg_check_received
+- does all checks on a received CMP message that can be done generically
+
+=head1 SYNOPSIS
+
+ #include "cmp_local.h"
+
+ typedef int (*ossl_cmp_allow_unprotected_cb_t)(const OSSL_CMP_CTX *ctx,
+                                                const OSSL_CMP_MSG *msg,
+                                                int invalid_protection, int arg);
+
+ int ossl_cmp_msg_check_received(OSSL_CMP_CTX *ctx, const OSSL_CMP_MSG *msg,
+                                 ossl_cmp_allow_unprotected_cb_t cb, int cb_arg);
+
+=head1 DESCRIPTION
+
+ossl_cmp_msg_check_received() checks the given message B<msg>,
+which may be a server response or a request by some client.
+
+It is ensured for the B<msg> that
+
+=over 4
+
+=item it has a valid body type,
+
+=item its protection is present and valid (or a callback function B<cb>
+is present and indicates that a missing or invalid protection is acceptable),
+
+=item its recipNonce matches any previous senderNonce stored in B<ctx>, and
+
+=item its transaction ID matches any previous transaction ID stored in B<ctx>.
+
+=back
+
+In case no protection is present and B<cb> is not NULL then this callback
+function is called with its B<invalid_protection> parameter being 0, while in
+case an invalid protection is present the B<invalid_protection> parameter is 1.
+The callback is passed also the arguments B<ctx>, B<msg>, and <cb_arg>
+(which typically contains the expected message type).
+The callback should return 1 on acceptance, 0 on rejection, or -1 on error.
+It should not put and error on the error stack since this could be misleading.
+
+If all checks pass then ossl_cmp_msg_check_received()
+
+=over 4
+
+=item learns the senderNonce from the received message,
+
+=item learns the transaction ID if it is not yet in B<ctx>, and
+
+=item adds any extraCerts contained in the <msg> to the list of untrusted
+certificates in B<ctx> for future use, such that
+they are available already to the certificate confirmation callback and the
+peer does not need to send them again (at least not in the same transaction).
+For efficiency, the extraCerts are prepended to the list so they get used first.
+
+=back
+
+=head1 RETURN VALUES
+
+ossl_cmp_msg_check_received() returns the message body type (which is >= 0)
+on success, -1 on error.
+
+=head1 SEE ALSO
+
+L<OSSL_CMP_validate_msg(3)>
+
+=head1 HISTORY
+
+The OpenSSL CMP support was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut