From: Dr. David von Oheimb <David.von.Oheimb@siemens.com>
Date: Fri, 13 Dec 2019 17:54:15 +0000 (+0100)
Subject: add internal doc files actually belonging to CMP contribution chunk 6
X-Git-Tag: openssl-3.0.0-alpha1~457
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=fcc25beb7b430fb0588accbb63bf369d914eacba;p=oweals%2Fopenssl.git

add internal doc files actually belonging to CMP contribution chunk 6

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Bernd Edlinger <bernd.edlinger@hotmail.de>
(Merged from https://github.com/openssl/openssl/pull/10620)
---

diff --git a/doc/internal/man3/ossl_cmp_certReq_new.pod b/doc/internal/man3/ossl_cmp_certReq_new.pod
new file mode 100644
index 0000000000..f54c215fa4
--- /dev/null
+++ b/doc/internal/man3/ossl_cmp_certReq_new.pod
@@ -0,0 +1,193 @@
+=pod
+
+=head1 NAME
+
+ossl_cmp_certReq_new,
+ossl_cmp_certRep_new,
+ossl_cmp_rr_new,
+ossl_cmp_rp_new,
+ossl_cmp_certConf_new,
+ossl_cmp_pkiconf_new,
+ossl_cmp_pollReq_new,
+ossl_cmp_pollRep_new,
+ossl_cmp_genm_new,
+ossl_cmp_genp_new,
+ossl_cmp_error_new
+- functions for generating CMP messages
+
+=head1 SYNOPSIS
+
+ #include <openssl/cmp.h>
+
+# define OSSL_CMP_PKIBODY_IR        0
+# define OSSL_CMP_PKIBODY_IP        1
+# define OSSL_CMP_PKIBODY_CR        2
+# define OSSL_CMP_PKIBODY_CP        3
+# define OSSL_CMP_PKIBODY_P10CR     4
+# define OSSL_CMP_PKIBODY_POPDECC   5
+# define OSSL_CMP_PKIBODY_POPDECR   6
+# define OSSL_CMP_PKIBODY_KUR       7
+# define OSSL_CMP_PKIBODY_KUP       8
+# define OSSL_CMP_PKIBODY_KRR       9
+# define OSSL_CMP_PKIBODY_KRP      10
+# define OSSL_CMP_PKIBODY_RR       11
+# define OSSL_CMP_PKIBODY_RP       12
+# define OSSL_CMP_PKIBODY_CCR      13
+# define OSSL_CMP_PKIBODY_CCP      14
+# define OSSL_CMP_PKIBODY_CKUANN   15
+# define OSSL_CMP_PKIBODY_CANN     16
+# define OSSL_CMP_PKIBODY_RANN     17
+# define OSSL_CMP_PKIBODY_CRLANN   18
+# define OSSL_CMP_PKIBODY_PKICONF  19
+# define OSSL_CMP_PKIBODY_NESTED   20
+# define OSSL_CMP_PKIBODY_GENM     21
+# define OSSL_CMP_PKIBODY_GENP     22
+# define OSSL_CMP_PKIBODY_ERROR    23
+# define OSSL_CMP_PKIBODY_CERTCONF 24
+# define OSSL_CMP_PKIBODY_POLLREQ  25
+# define OSSL_CMP_PKIBODY_POLLREP  26
+
+ OSSL_ossl_cmp_MSG *ossl_cmp_certReq_new(OSSL_CMP_CTX *ctx, int bodytype,
+                                         int err_code);
+ OSSL_CMP_MSG *ossl_cmp_certRep_new(OSSL_CMP_CTX *ctx, int bodytype,
+                                    int certReqId, OSSL_CMP_PKISI *si,
+                                    X509 *cert, STACK_OF(X509) *chain,
+                                    STACK_OF(X509) *caPubs,
+                                    int encrypted, int unprotectedErrors);
+ OSSL_CMP_MSG *ossl_cmp_rr_new(OSSL_CMP_CTX *ctx);
+ OSSL_CMP_MSG *ossl_cmp_rp_new(OSSL_CMP_CTX *ctx, OSSL_CMP_PKISI *si,
+                               OSSL_CRMF_CERTID *cid, int unprot_err);
+ OSSL_CMP_MSG *ossl_cmp_certConf_new(OSSL_CMP_CTX *ctx, int fail_info,
+                                     const char *text);
+ OSSL_CMP_MSG *ossl_cmp_pkiconf_new(OSSL_CMP_CTX *ctx);
+ OSSL_CMP_MSG *ossl_cmp_pollReq_new(OSSL_CMP_CTX *ctx, int crid);
+ OSSL_CMP_MSG *ossl_cmp_pollRep_new(OSSL_CMP_CTX *ctx, int crid, int poll_after)
+ OSSL_CMP_MSG *ossl_cmp_genm_new(OSSL_CMP_CTX *ctx);
+ OSSL_CMP_MSG *ossl_cmp_genp_new(OSSL_CMP_CTX *ctx);
+ OSSL_CMP_MSG *ossl_cmp_error_new(OSSL_CMP_CTX *ctx, OSSL_CMP_PKISI *si,
+                                  int errorCode,
+                                  OSSL_CMP_PKIFREETEXT *errorDetails,
+                                  int unprotected)
+
+=head1 DESCRIPTION
+
+This is the API for creating various CMP PKIMESSAGES. The
+functions allocate a new message, fill it with the relevant data derived from
+the given OSSL_CMP_CTX, and create the applicable protection.
+
+ossl_cmp_certReq_new() creates a PKIMessage for requesting a certificate,
+which can be either of IR/CR/KUR/P10CR, depending on the given B<bodytype>.
+The OpenSSL error reason code defined in err.h to use on error is given as
+B<err_code>.
+
+Available CMP certificate request PKIMessage B<bodytype>s are:
+
+=over 4
+
+=item * B<OSSL_CMP_PKIBODY_IR>    - Initialization Request
+
+=item * B<OSSL_CMP_PKIBODY_CR>    - Certification Request
+
+=item * B<OSSL_CMP_PKIBODY_P10CR> - PKCS#10 Certification Request
+
+=item * B<OSSL_CMP_PKIBODY_KUR>   - Key Update Request
+
+=back
+
+ossl_cmp_certrep_new() creates a PKIMessage for certificate response, which can
+be either of IP/CP/KUP, depending on the given B<bodytype>.
+
+Available CMP certificate response PKIMessage B<bodytype>s are:
+
+=over 4
+
+=item * B<OSSL_CMP_PKIBODY_IP>    - Initialization Response
+
+=item * B<OSSL_CMP_PKIBODY_CP>    - Certification Response
+
+=item * B<OSSL_CMP_PKIBODY_KUP>   - Key Update Response
+
+=back
+
+The list of all CMP PKIMessage B<bodytype>s is:
+
+ #define OSSL_CMP_PKIBODY_IR        0
+ #define OSSL_CMP_PKIBODY_IP        1
+ #define OSSL_CMP_PKIBODY_CR        2
+ #define OSSL_CMP_PKIBODY_CP        3
+ #define OSSL_CMP_PKIBODY_P10CR     4
+ #define OSSL_CMP_PKIBODY_POPDECC   5
+ #define OSSL_CMP_PKIBODY_POPDECR   6
+ #define OSSL_CMP_PKIBODY_KRR       9
+ #define OSSL_CMP_PKIBODY_KRP      10
+ #define OSSL_CMP_PKIBODY_RR       11
+ #define OSSL_CMP_PKIBODY_RP       12
+ #define OSSL_CMP_PKIBODY_CCR      13
+ #define OSSL_CMP_PKIBODY_CCP      14
+ #define OSSL_CMP_PKIBODY_CKUANN   15
+ #define OSSL_CMP_PKIBODY_CANN     16
+ #define OSSL_CMP_PKIBODY_RANN     17
+ #define OSSL_CMP_PKIBODY_CRLANN   18
+ #define OSSL_CMP_PKIBODY_PKICONF  19
+ #define OSSL_CMP_PKIBODY_NESTED   20
+ #define OSSL_CMP_PKIBODY_GENM     21
+ #define OSSL_CMP_PKIBODY_GENP     22
+ #define OSSL_CMP_PKIBODY_ERROR    23
+ #define OSSL_CMP_PKIBODY_CERTCONF 24
+ #define OSSL_CMP_PKIBODY_POLLREQ  25
+ #define OSSL_CMP_PKIBODY_POLLREP  26
+
+ossl_cmp_rr_new() creates a Revocation Request message from the
+information set via OSSL_CMP_CTX_set1_oldClCert().
+
+ossl_cmp_rp_new() creates a Revocation Response message with status set to
+B<si> and CertID set to B<cid>. Consumes B<cid>.
+Accepts unprotected errors if B<uprot_err> != 0.
+
+ossl_cmp_certConf_new() creates a Certificate Confirmation message for the last
+received certificate. PKIStatus defaults to B<accepted> if the B<fail_info> bit
+field is 0. Else it is taken as the failInfo of the PKIStatusInfo, PKIStatus is
+set to B<rejected>, and B<text> is copied to statusString unless it is NULL.
+
+ossl_cmp_pkiconf_new() creates a PKI Confirmation message.
+
+ossl_cmp_pollReq_new() creates a Polling Request message with certReqId set to
+B<crid>.
+
+ossl_cmp_pollRep_new() creates a Polling Response message with certReqId set to
+B<crid> and pollAfter to B<poll_after>.
+
+ossl_cmp_genm_new() creates a new General Message with an empty ITAV stack.
+
+ossl_cmp_genp_new() creates a new General Response with an empty ITAV stack.
+
+ossl_cmp_error_new() creates a new Error Message with the given contents,
+copying B<si> and B<errorDetails>.
+
+=head1 NOTES
+
+CMP is specified in RFC 4210 (and CRMF in RFC 4211).
+
+=head1 RETURN VALUES
+
+All of the functions return a new OSSL_CMP_MSG structure containing
+the generated message on success, or NULL on error.
+
+=head1 SEE ALSO
+
+L<OSSL_CMP_CTX_new(3)>, L<ERR_load_strings(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
diff --git a/doc/internal/man3/ossl_cmp_msg_create.pod b/doc/internal/man3/ossl_cmp_msg_create.pod
new file mode 100644
index 0000000000..7498a1d6fd
--- /dev/null
+++ b/doc/internal/man3/ossl_cmp_msg_create.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+ossl_cmp_bodytype_to_string,
+ossl_cmp_msg_get_bodytype,
+ossl_cmp_msg_set_bodytype,
+ossl_cmp_msg_create,
+ossl_cmp_msg_load,
+ossl_cmp_msg_gen_ITAV_push0,
+ossl_cmp_msg_gen_ITAVs_push1
+- functions manipulating CMP messages
+
+=head1 SYNOPSIS
+
+  #include "cmp_int.h"
+
+  const char *ossl_cmp_bodytype_to_string(int type);
+  int ossl_cmp_msg_get_bodytype(const OSSL_CMP_MSG *msg);
+  int ossl_cmp_msg_set_bodytype( OSSL_CMP_MSG *msg, int type);
+  OSSL_CMP_MSG *ossl_cmp_msg_create(OSSL_CMP_CTX *ctx, int bodytype);
+  OSSL_CMP_MSG *ossl_cmp_msg_load(const char *file);
+  int ossl_cmp_msg_gen_ITAV_push0(OSSL_CMP_MSG *msg, OSSL_CMP_ITAV *itav);
+  int ossl_cmp_msg_gen_ITAVs_push1(OSSL_CMP_MSG *msg,
+                                    STACK_OF(OSSL_CMP_ITAV) *itavs);
+
+=head1 DESCRIPTION
+
+ossl_cmp_bodytype_to_string() returns the name of the given body type as string,
+or "illegal body type" on error.
+
+ossl_cmp_msg_get_bodytype() returns the body type of the given PKIMessage,
+or -1 on error.
+
+ossl_cmp_msg_set_bodytype() sets the type of the message contained in
+the PKIMessage body field.
+Returns 1 on success, 0 on error.
+
+ossl_cmp_msg_create() creates and initializes a OSSL_CMP_MSG structure,
+using B<ctx> for the header and B<bodytype> for the body.
+Returns pointer to created OSSL_CMP_MSG on success, NULL on error.
+
+OSSL_CMP_MSG *ossl_cmp_msg_load() loads a OSSL_CMP_MSG from a B<file>.
+Returns pointer to created OSSL_CMP_MSG on success, NULL on error.
+
+ossl_cmp_msg_gen_ITAV_push0() pushes the B<itav> to the body of the
+PKIMessage B<msg> of GenMsg or GenRep type. Consumes the B<itavs> pointer.
+Returns 1 on success, 0 on error.
+
+ossl_cmp_msg_gen_ITAVs_push1() adds a copy of the B<itavs> stack to the body
+of the PKIMessage B<msg> of GenMsg or GenRep type.
+Does not consume the B<itavs> pointer nor its elements.
+Returns 1 on success, 0 on error.
+
+=head1 NOTES
+
+CMP is defined in RFC 4210 (and CRMF in RFC 4211).
+
+=head1 RETURN VALUES
+
+See the individual functions above.
+
+=head1 SEE ALSO
+
+L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_IR_ses(3)>,
+L<OSSL_CMP_MSG_http_perform(3)>
+
+=head1 HISTORY
+
+The OpenSSL CMP support was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2007-2020 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
diff --git a/doc/internal/man3/ossl_cmp_msg_protect.pod b/doc/internal/man3/ossl_cmp_msg_protect.pod
new file mode 100644
index 0000000000..7fd4e82e0b
--- /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
diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index a1f0c3487e..95d300eda3 100644
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -1567,7 +1567,6 @@ i2v_GENERAL_NAME(3)
 i2v_GENERAL_NAMES(3)
 o2i_ECPublicKey(3)
 openssl-core_numbers.h(7)
-ossl_cmp_certReq_new(3)
 provider-kdf(7)
 s2i_ASN1_IA5STRING(3)
 s2i_ASN1_INTEGER(3)