From 1d3da367ab404dd0129277b6b9518d50175269d6 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Wed, 26 Feb 2025 18:42:11 +0100 Subject: [PATCH] minor doc fixes for CMP and HTTP Reviewed-by: Tim Hudson Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/26924) --- apps/openssl-vms.cnf | 4 +-- apps/openssl.cnf | 4 +-- doc/man1/openssl-cmp.pod.in | 24 +++++++-------- doc/man3/OSSL_CMP_ITAV_new_caCerts.pod | 42 +++++++++++++------------- doc/man3/OSSL_HTTP_transfer.pod | 4 ++- 5 files changed, 39 insertions(+), 39 deletions(-) diff --git a/apps/openssl-vms.cnf b/apps/openssl-vms.cnf index 8203d9ea0c..768291e4ee 100644 --- a/apps/openssl-vms.cnf +++ b/apps/openssl-vms.cnf @@ -342,8 +342,8 @@ path = pkix/ # Server authentication recipient = "/C=FI/O=Insta Demo/CN=Insta Demo CA" # or set srvcert or issuer -ignore_keyusage = 1 # potentially needed quirk -unprotected_errors = 1 # potentially needed quirk +ignore_keyusage = 1 # quirk needed to accept Insta CA cert not including digitalsignature +unprotected_errors = 1 # quirk needed to accept negative responses possibly not protected extracertsout = insta.extracerts.pem # Client authentication diff --git a/apps/openssl.cnf b/apps/openssl.cnf index 2833b6f30b..abace0ea7f 100644 --- a/apps/openssl.cnf +++ b/apps/openssl.cnf @@ -342,8 +342,8 @@ path = pkix/ # Server authentication recipient = "/C=FI/O=Insta Demo/CN=Insta Demo CA" # or set srvcert or issuer -ignore_keyusage = 1 # potentially needed quirk -unprotected_errors = 1 # potentially needed quirk +ignore_keyusage = 1 # quirk needed to accept Insta CA cert not including digitalsignature +unprotected_errors = 1 # quirk needed to accept negative responses possibly not protected extracertsout = insta.extracerts.pem # Client authentication diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 4505283e58..60c5ee1fd0 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -258,7 +258,7 @@ ITAV Bs is printed to stdout. Set InfoType name to use for requesting specific info in B, e.g., C. -There is specific support for C, C, +There is specific support for C, C, C, and C (CRL update retrieval). =item B<-profile> I @@ -480,7 +480,7 @@ if neither B<-recipient>, B<-srvcert>, nor B<-issuer> is given. =item B<-issuer> I -X.509 Distinguished Name (DN) use as issuer field +X.509 Distinguished Name (DN) to place as the issuer field in the requested certificate template in IR/CR/KUR/RR messages. If the NULL-DN (C) is given then no issuer is placed in the template. @@ -777,20 +777,21 @@ If on success no such cert was received, this is indicated by deleting the file. =item B<-crlcert> I -Certificate used for specifying a CRL issuer when requesting a CRL -in a genm message with infoType C. +Certificate to derive CRL issuer data for the source field +when obtaining a CRL in a genm request with infoType C. Any available distribution point name is preferred over issuer names. =item B<-oldcrl> I -CRL used for specifying a CRL issuer when requesting a CRL -in a genm message with infoType C. +The CRL to obtain an update for in a genm request with infoType C. +Unless the B<-crlcert> option is provided as well, +the given CRL is used for deriving CRL issuer data for the source field. Any available distribution point name is preferred over issuer names. -If also B<-crlcrt> is given, its data is preferred over data from B<-oldcrl>. +If the CRL contains a thisUpdate field, its value is copied to the request. =item B<-crlout> I -The file to save CRL received in a genp message of infoType C. +The file to save any CRL received in a genp message of infoType C. If on success no such CRL was received, this is indicated by deleting the file. =back @@ -1395,13 +1396,10 @@ or by referencing in addition the B<[cr]> section of the example configuration: In order to update the enrolled certificate one may call - openssl cmp -section insta,kur - -using MAC-based protection with PBM or - openssl cmp -section insta,kur,signature -using signature-based protection. +using signature-based protection with the certificate that is to be updated. +For certificate updates, MAC-based protection should generally not be used. In a similar way any previously enrolled certificate may be revoked by diff --git a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod index db69670171..c7fb5f92e0 100644 --- a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod +++ b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod @@ -108,27 +108,6 @@ Data from I, if present, is preferred over data from I. If no distribution point names are available, candidate issuer names are taken from following sources, as far as present: -OSSL_CMP_ITAV_new0_certReqTemplate() creates an B structure -of type B. -If I is NULL then also I must be NULL, -and the resulting ITAV can be used in a B message to obtain the -requirements a PKI has on the certificate template used to request certificates, -or in a B message stating that there are no such requirements. -Otherwise the resulting ITAV includes a CertReqTemplateValue structure -with I of type B and an optional list -of key specifications I, each being of type B, and -the resulting ATAV can be used in a B message to provide requirements. - -OSSL_CMP_ITAV_get1_certReqTemplate() -requires that I has type B. -If assigns NULL to I<*certTemplate> if no B structure -with a certificate template value is in I, -otherwise a copy of the certTemplate field value. -If I is not NULL, it is assigned NULL -if the structure is not present in I or the keySpec field is absent. -Otherwise, the function checks that all elements of keySpec field are of type -B or B and assigns to I<*keySpec> a copy of the keySpec field. - =over 4 =item the list of distribution points in the first cRLDistributionPoints @@ -171,6 +150,27 @@ the list of CRLs contained in the infoValue field of I. The pointer may be NULL if no CRL is included. It is an error if the infoType of I is not B. +OSSL_CMP_ITAV_new0_certReqTemplate() creates an B structure +of type B. +If I is NULL then also I must be NULL, +and the resulting ITAV can be used in a B message to obtain the +requirements a PKI has on the certificate template used to request certificates, +or in a B message stating that there are no such requirements. +Otherwise the resulting ITAV includes a CertReqTemplateValue structure +with I of type B and an optional list +of key specifications I, each being of type B, and +the resulting ATAV can be used in a B message to provide requirements. + +OSSL_CMP_ITAV_get1_certReqTemplate() +requires that I has type B. +If assigns NULL to I<*certTemplate> if no B structure +with a certificate template value is in I, +otherwise a copy of the certTemplate field value. +If I is not NULL, it is assigned NULL +if the structure is not present in I or the keySpec field is absent. +Otherwise, the function checks that all elements of keySpec field are of type +B or B and assigns to I<*keySpec> a copy of the keySpec field. + =head1 NOTES CMP is defined in RFC 4210. diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index 6f6f88a379..63fc530dc7 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -62,6 +62,7 @@ for connecting to the given server and the optionally given I, defaulting to 80 for HTTP or 443 for HTTPS. Then this internal BIO is used for setting up a connection and for exchanging one or more request and response. + If I is given and I is NULL then this I is used instead. If both I and I are given (which may be memory BIOs for instance) then no explicit connection is set up, but @@ -69,7 +70,8 @@ I is used for writing requests and I for reading responses. As soon as the client has flushed I the server must be ready to provide a response or indicate a waiting condition via I. -If I is given, it is an error to provide I or I arguments, +If I is given, +it is an error to provide non-NULL I or I arguments, while I and I arguments may be given to support diagnostic output. If I is NULL the optional I parameter can be used to set an HTTP(S) proxy to use (unless overridden by "no_proxy" settings).