add internal doc files actually belonging to CMP contribution chunk 6

[openssl.git] / doc / internal / man3 / ossl_cmp_msg_protect.pod

diff --git a/doc/internal/man3/ossl_cmp_msg_protect.pod b/doc/internal/man3/ossl_cmp_msg_protect.pod
new file mode 100644 (file)
index 0000000..7fd4e82
--- /dev/null
+++ b/doc/internal/man3/ossl_cmp_msg_protect.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+ossl_cmp_msg_protect,
+ossl_cmp_msg_add_extraCerts
+- functions for producing CMP message protection
+
+=head1 SYNOPSIS
+
+  #include "cmp_int.h"
+
+  int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
+  int ossl_cmp_msg_add_extraCerts(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
+
+=head1 DESCRIPTION
+
+ossl_cmp_msg_protect() protects the given message B<msg> using an algorithm
+depending on the available context information given in the B<ctx>.
+If there is a secretValue it selects PBMAC. Else if there is a clCert
+it selects Signature and uses B<ossl_cmp_msg_add_extraCerts()>.
+It also sets the protectionAlg field in the message header accordingly.
+
+ossl_cmp_msg_add_extraCerts() adds elements to the extraCerts field in the given
+message B<msg>. It tries to build the certificate chain of the client cert in
+the B<ctx> if present by using certificates in ctx->untrusted_certs;
+if no untrusted certs are set, it will at least add the client certificate.
+In any case all the certificates explicitly specified to be sent out (i.e.,
+B<ctx->extraCertsOut>) are added. Note that it will NOT add the root certificate
+of the chain, i.e, the trust anchor (unless it is part of extraCertsOut).
+
+=head1 NOTES
+
+CMP is defined in RFC 4210 (and CRMF in RFC 4211).
+
+=head1 RETURN VALUES
+
+All functions return 1 on success, 0 on error.
+
+=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