diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2019-12-13 18:54:15 +0100 |
---|---|---|
committer | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2020-02-17 07:43:58 +0100 |
commit | fcc25beb7b430fb0588accbb63bf369d914eacba (patch) | |
tree | 50ca72b613bfb7660b9ae5882b50828272784e25 /doc/internal | |
parent | a21314dbbc56cd30580123d74b3106a628540965 (diff) |
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)
Diffstat (limited to 'doc/internal')
-rw-r--r-- | doc/internal/man3/ossl_cmp_certReq_new.pod | 193 | ||||
-rw-r--r-- | doc/internal/man3/ossl_cmp_msg_create.pod | 81 | ||||
-rw-r--r-- | doc/internal/man3/ossl_cmp_msg_protect.pod | 53 |
3 files changed, 327 insertions, 0 deletions
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 |