diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2019-09-27 10:22:23 +0200 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2019-10-29 14:17:39 +0000 |
commit | 4dde554c6ae2375ce53b24cc535124355c339462 (patch) | |
tree | a60fc6631418823956f1553307f524f1017cbd16 /doc/internal | |
parent | 0a4d6c67480a4d2fce514e08d3efe571f2ee99c9 (diff) |
chunk 5 of CMP contribution to OpenSSL
Reviewed-by: Bernd Edlinger <bernd.edlinger@hotmail.de>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10036)
Diffstat (limited to 'doc/internal')
-rw-r--r-- | doc/internal/man3/ossl_cmp_hdr_init.pod | 127 | ||||
-rw-r--r-- | doc/internal/man3/ossl_cmp_statusinfo_new.pod | 107 |
2 files changed, 234 insertions, 0 deletions
diff --git a/doc/internal/man3/ossl_cmp_hdr_init.pod b/doc/internal/man3/ossl_cmp_hdr_init.pod new file mode 100644 index 0000000000..a7a4d87f09 --- /dev/null +++ b/doc/internal/man3/ossl_cmp_hdr_init.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +ossl_cmp_hdr_set_pvno, +ossl_cmp_hdr_get_pvno, +ossl_cmp_hdr_get0_sendernonce, +ossl_cmp_hdr_set1_sender, +ossl_cmp_hdr_set1_recipient, +ossl_cmp_hdr_update_messagetime, +ossl_cmp_hdr_set1_senderKID, +ossl_cmp_hdr_push0_freeText, +ossl_cmp_hdr_push1_freeText, +ossl_cmp_hdr_generalinfo_item_push0, +ossl_cmp_hdr_generalinfo_items_push1, +ossl_cmp_hdr_set_implicitConfirm, +ossl_cmp_hdr_check_implicitConfirm, +ossl_cmp_hdr_init +- functions manipulating CMP message headers + +=head1 SYNOPSIS + + #include "cmp_int.h" + + int ossl_cmp_hdr_set_pvno(OSSL_CMP_PKIHEADER *hdr, int pvno); + int ossl_cmp_hdr_get_pvno(const OSSL_CMP_PKIHEADER *hdr); + ASN1_OCTET_STRING + *ossl_cmp_hdr_get0_sendernonce(const OSSL_CMP_PKIHEADER *hdr); + + int ossl_cmp_hdr_set1_sender(OSSL_CMP_PKIHEADER *hdr, const X509_NAME *nm); + int ossl_cmp_hdr_set1_recipient(OSSL_CMP_PKIHEADER *hdr, const X509_NAME *nm); + int ossl_cmp_hdr_update_messagetime(OSSL_CMP_PKIHEADER *hdr); + int ossl_cmp_hdr_set1_senderKID(OSSL_CMP_PKIHEADER *hdr, + const ASN1_OCTET_STRING *senderKID); + int ossl_cmp_hdr_generalinfo_item_push0(OSSL_CMP_PKIHEADER *hdr, + OSSL_CMP_ITAV *itav); + int ossl_cmp_hdr_generalinfo_items_push1(OSSL_CMP_PKIHEADER *hdr, + STACK_OF(OSSL_CMP_ITAV) *itavs); + int ossl_cmp_hdr_push0_freeText(OSSL_CMP_PKIHEADER *hdr, + ASN1_UTF8STRING *text); + int ossl_cmp_hdr_push1_freeText(OSSL_CMP_PKIHEADER *hdr, + ASN1_UTF8STRING *text); + int ossl_cmp_hdr_set_implicitConfirm(OSSL_CMP_PKIHEADER *hdr); + int ossl_cmp_hdr_check_implicitConfirm(OSSL_CMP_PKIHEADER *hdr); + int ossl_cmp_hdr_init(OSSL_CMP_CTX *ctx, OSSL_CMP_PKIHEADER *hdr); + +=head1 DESCRIPTION + +ossl_cmp_hdr_set_pvno() sets hdr->pvno to the given B<pvno>. + +ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error. + +ossl_cmp_hdr_get0_sendernonce() returns the sender nonce of the given PKIHeader. + +ossl_cmp_hdr_set1_sender() sets the sender field in the given PKIHeader +to the given X509 Name value, without consuming the pointer. + +ossl_cmp_hdr_set1_recipient() sets the recipient field in the given +PKIHeader to the given X509 Name value, without consuming the pointer. +If B<nm> is NULL, recipient is set to the NULL DN (the empty list of strings). + +ossl_cmp_hdr_update_messagetime() (re-)sets the messageTime to the current +system time. As written in RFC 4210, section 5.1.1: +The messageTime field contains the time at which the sender created the message. +This may be useful to allow end entities to correct/check their local time for +consistency with the time on a central system. + +ossl_cmp_hdr_set1_senderKID() Sets hdr->senderKID to the given string. +In an PBMAC-protected IR this usually is a reference number issued by the CA, +else the subject key ID of the sender's protecting certificate. + +ossl_cmp_hdr_push0_freeText() pushes an ASN1_UTF8STRING to +hdr->freeText and consumes the given pointer. + +ossl_cmp_hdr_push1_freeText() pushes an ASN1_UTF8STRING to +hdr->freeText and does not consume the pointer. + +ossl_cmp_hdr_generalinfo_item_push0() adds the given InfoTypeAndValue +item to the hdr->generalInfo stack. Consumes the B<itav> pointer. + +ossl_cmp_hdr_generalinfo_items_push1() adds a copy of the B<itavs> stack to +the generalInfo field of PKIheader of the B<hdr>. Does not consume the B<itavs> +pointer. + +ossl_cmp_hdr_set_implicitConfirm() sets implicitConfirm in the generalInfo field +of the PKIMessage header. + +ossl_cmp_hdr_check_implicitConfirm() returns 1 if implicitConfirm is +set int generalInfo field of the given PKIMessage header, 0 if not. + +ossl_cmp_hdr_init() initializes a PKIHeader structure based on the +values in the given OSSL_CMP_CTX structure. +This starts a new transaction in case ctx->transactionID is NULL. +The sender name is copied from the subject of the client cert, if any, +or else from the subject name provided for certification requests. +As required by RFC 4210 section 5.1.1., if the sender name is not known +to the client it set to the NULL-DN. In this case for identification at least +the senderKID must be set, which we take from any referenceValue provided. + +=head1 NOTES + +CMP is defined in RFC 4210 (and CRMF in RFC 4211). + +=head1 RETURN VALUES + +ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error. + +ossl_cmp_hdr_get0_sendernonce() returns the respective nonce. + +All other functions return 1 on success, 0 on error. + +See the individual functions above. + +=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_statusinfo_new.pod b/doc/internal/man3/ossl_cmp_statusinfo_new.pod new file mode 100644 index 0000000000..6a72056455 --- /dev/null +++ b/doc/internal/man3/ossl_cmp_statusinfo_new.pod @@ -0,0 +1,107 @@ +=pod + +=head1 NAME + +ossl_cmp_statusinfo_new, +ossl_cmp_pkisi_pkistatus_get, +ossl_cmp_pkisi_pkifailureinfo_get, +ossl_cmp_pkisi_pkifailureinfo_check, +ossl_cmp_pkisi_failinfo_get0, +ossl_cmp_pkisi_statusstring_get0, +ossl_pkisi_snprint +- functions for managing PKI status information + +=head1 SYNOPSIS + + #include "cmp.h" + +# define OSSL_CMP_PKIFAILUREINFO_badAlg 0 +# define OSSL_CMP_PKIFAILUREINFO_badMessageCheck 1 +# define OSSL_CMP_PKIFAILUREINFO_badRequest 2 +# define OSSL_CMP_PKIFAILUREINFO_badTime 3 +# define OSSL_CMP_PKIFAILUREINFO_badCertId 4 +# define OSSL_CMP_PKIFAILUREINFO_badDataFormat 5 +# define OSSL_CMP_PKIFAILUREINFO_wrongAuthority 6 +# define OSSL_CMP_PKIFAILUREINFO_incorrectData 7 +# define OSSL_CMP_PKIFAILUREINFO_missingTimeStamp 8 +# define OSSL_CMP_PKIFAILUREINFO_badPOP 9 +# define OSSL_CMP_PKIFAILUREINFO_certRevoked 10 +# define OSSL_CMP_PKIFAILUREINFO_certConfirmed 11 +# define OSSL_CMP_PKIFAILUREINFO_wrongIntegrity 12 +# define OSSL_CMP_PKIFAILUREINFO_badRecipientNonce 13 +# define OSSL_CMP_PKIFAILUREINFO_timeNotAvailable 14 +# define OSSL_CMP_PKIFAILUREINFO_unacceptedPolicy 15 +# define OSSL_CMP_PKIFAILUREINFO_unacceptedExtension 16 +# define OSSL_CMP_PKIFAILUREINFO_addInfoNotAvailable 17 +# define OSSL_CMP_PKIFAILUREINFO_badSenderNonce 18 +# define OSSL_CMP_PKIFAILUREINFO_badCertTemplate 19 +# define OSSL_CMP_PKIFAILUREINFO_signerNotTrusted 20 +# define OSSL_CMP_PKIFAILUREINFO_transactionIdInUse 21 +# define OSSL_CMP_PKIFAILUREINFO_unsupportedVersion 22 +# define OSSL_CMP_PKIFAILUREINFO_notAuthorized 23 +# define OSSL_CMP_PKIFAILUREINFO_systemUnavail 24 +# define OSSL_CMP_PKIFAILUREINFO_systemFailure 25 +# define OSSL_CMP_PKIFAILUREINFO_duplicateCertReq 26 +# define OSSL_CMP_PKIFAILUREINFO_MAX 26 + + OSSL_CMP_PKISI *ossl_cmp_statusinfo_new(int status, int fail_info, + const char *text); + int ossl_cmp_pkisi_pkistatus_get(OSSL_CMP_PKISI *si); + int ossl_cmp_pkisi_pkifailureinfo_get(OSSL_CMP_PKISI *si); + int ossl_cmp_pkisi_pkifailureinfo_check(OSSL_CMP_PKISI *si, int bit_index); + OSSL_CMP_PKIFAILUREINFO *ossl_cmp_pkisi_failinfo_get0(const OSSL_CMP_PKISI *si); + OSSL_CMP_PKIFREETEXT *ossl_cmp_pkisi_statusstring_get0(const OSSL_CMP_PKISI *si); + char *ossl_pkisi_snprint(OSSL_CMP_PKISI *si, char *buf, int bufsize); + +=head1 DESCRIPTION + +ossl_cmp_statusinfo_new() creates a new PKIStatusInfo structure and fills it +with the given values. It sets the status field to B<status>. +If B<text> is not NULL, it is copied to statusString. +B<fail_info> is is interpreted as bit pattern for the failInfo field. +Returns a pointer to the structure on success, or NULL on error. + +ossl_cmp_pkisi_pkistatus_get() returns the PKIStatus of B<si>, or -1 on error. + +ossl_cmp_pkisi_pkifailureinfo_get() returns the PKIFailureInfo bits +of B<si>, encoded as integer, or -1 on error. + +ossl_cmp_pkisi_pkifailureinfo_check() returns the state of the bit (0 or 1) +with index B<bit_index> in the PKIFailureInfo of the B<si>, or -1 on error. + +ossl_cmp_pkisi_failinfo_get0() returns a direct pointer to the failInfo +field contained in B<si>, or NULL on error. + +ossl_cmp_pkisi_statusstring_get0() returns a direct pointer to the statusString +field contained in B<si>. + +ossl_pkisi_snprint() places at max B<bufsize> characters of human-readable +error string of B<si> in pre-allocated B<buf>. Returns pointer to the same +B<buf> containing the string, or NULL 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_certreq_new(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 |