From: Allan Date: Wed, 13 Jul 2022 08:55:06 +0000 (-0700) Subject: Updated X509v3_get_ext_by_NID.pod and X509_CRL_get0_by_serial.pod X-Git-Tag: openssl-3.2.0-alpha1~2384 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1711f4824be2c6b41d26f221d2aa0e2236363995;p=thirdparty%2Fopenssl.git Updated X509v3_get_ext_by_NID.pod and X509_CRL_get0_by_serial.pod Updated these to the current documentation style. Moved X509v3_delete_ext() under BUGS to NOTES and added information to call free. Reviewed-by: Hugo Landau Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/18786) --- diff --git a/doc/man3/X509_CRL_get0_by_serial.pod b/doc/man3/X509_CRL_get0_by_serial.pod index d1e0f077a3a..e0061563bc7 100644 --- a/doc/man3/X509_CRL_get0_by_serial.pod +++ b/doc/man3/X509_CRL_get0_by_serial.pod @@ -30,42 +30,42 @@ functions =head1 DESCRIPTION -X509_CRL_get0_by_serial() attempts to find a revoked entry in B for -serial number B. If it is successful it sets B<*ret> to the internal -pointer of the matching entry, as a result B<*ret> must not be freed up +X509_CRL_get0_by_serial() attempts to find a revoked entry in I for +serial number I. If it is successful, it sets I<*ret> to the internal +pointer of the matching entry. As a result, I<*ret> B be freed after the call. X509_CRL_get0_by_cert() is similar to X509_get0_by_serial() except it -looks for a revoked entry using the serial number of certificate B. +looks for a revoked entry using the serial number of certificate I. -X509_CRL_get_REVOKED() returns an internal pointer to a stack of all -revoked entries for B. +X509_CRL_get_REVOKED() returns an internal pointer to a STACK of all +revoked entries for I. X509_REVOKED_get0_serialNumber() returns an internal pointer to the -serial number of B. +serial number of I. X509_REVOKED_get0_revocationDate() returns an internal pointer to the -revocation date of B. +revocation date of I. -X509_REVOKED_set_serialNumber() sets the serial number of B to B. -The supplied B pointer is not used internally so it should be -freed up after use. +X509_REVOKED_set_serialNumber() sets the serial number of I to I. +The supplied I pointer is not used internally so it should be +freed after use. -X509_REVOKED_set_revocationDate() sets the revocation date of B to -B. The supplied B pointer is not used internally so it should be -freed up after use. +X509_REVOKED_set_revocationDate() sets the revocation date of I to +I. The supplied I pointer is not used internally so it should be +freed after use. -X509_CRL_add0_revoked() appends revoked entry B to CRL B. The -pointer B is used internally so it must not be freed up after the call: +X509_CRL_add0_revoked() appends revoked entry I to CRL I. The +pointer I is used internally so it B be freed after the call: it is freed when the parent CRL is freed. -X509_CRL_sort() sorts the revoked entries of B into ascending serial +X509_CRL_sort() sorts the revoked entries of I into ascending serial number order. =head1 NOTES Applications can determine the number of revoked entries returned by -X509_CRL_get_revoked() using sk_X509_REVOKED_num() and examine each one +X509_CRL_get_REVOKED() using sk_X509_REVOKED_num() and examine each one in turn using sk_X509_REVOKED_value(). =head1 RETURN VALUES @@ -74,15 +74,15 @@ X509_CRL_get0_by_serial() and X509_CRL_get0_by_cert() return 0 for failure, 1 on success except if the revoked entry has the reason C (8), in which case 2 is returned. -X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(), -X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for -failure. +X509_CRL_get_REVOKED() returns a STACK of revoked entries. -X509_REVOKED_get0_serialNumber() returns an B pointer. +X509_REVOKED_get0_serialNumber() returns an B structure. -X509_REVOKED_get0_revocationDate() returns an B value. +X509_REVOKED_get0_revocationDate() returns an B structure. -X509_CRL_get_REVOKED() returns a STACK of revoked entries. +X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(), +X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for +failure. =head1 SEE ALSO diff --git a/doc/man3/X509v3_get_ext_by_NID.pod b/doc/man3/X509v3_get_ext_by_NID.pod index f7fa2b29b64..9d26bfe19a7 100644 --- a/doc/man3/X509v3_get_ext_by_NID.pod +++ b/doc/man3/X509v3_get_ext_by_NID.pod @@ -41,7 +41,8 @@ X509_REVOKED_add_ext - extension stack utility functions int X509_CRL_get_ext_count(const X509_CRL *x); X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc); int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos); - int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos); + int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, + int lastpos); int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos); X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc); int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc); @@ -57,77 +58,79 @@ X509_REVOKED_add_ext - extension stack utility functions =head1 DESCRIPTION -X509v3_get_ext_count() retrieves the number of extensions in B. +X509v3_get_ext_count() retrieves the number of extensions in I. -X509v3_get_ext() retrieves extension B from B. The index B -can take any value from B<0> to X509_get_ext_count(x) - 1. The returned -extension is an internal pointer which B be freed up by the +X509v3_get_ext() retrieves extension I from I. The index I +can take any value from 0 to X509_get_ext_count(I) - 1. The returned +extension is an internal pointer which B be freed by the application. X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension -with B or B from extension stack B. The search starts from the -extension after B or from the beginning if is B<-1>. If -the extension is found its index is returned otherwise B<-1> is returned. +with I or I from extension STACK I. The search starts from the +extension after I or from the beginning if I is -1. If +the extension is found, its index is returned, otherwise -1 is returned. X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it -looks for an extension of criticality B. A zero value for B -looks for a non-critical extension a nonzero value looks for a critical +looks for an extension of criticality I. A zero value for I +looks for a non-critical extension. A nonzero value looks for a critical extension. -X509v3_delete_ext() deletes the extension with index B from B. +X509v3_delete_ext() deletes the extension with index I from I. The deleted extension is returned and must be freed by the caller. -If B is in invalid index value B is returned. +If I is an invalid index value, NULL is returned. -X509v3_add_ext() adds extension B to stack B<*x> at position B. If -B is B<-1> the new extension is added to the end. If B<*x> is B -a new stack will be allocated. The passed extension B is duplicated +X509v3_add_ext() adds extension I to STACK I<*x> at position I. If +I is -1, the new extension is added to the end. If I<*x> is NULL, +a new STACK will be allocated. The passed extension I is duplicated internally so it must be freed after use. X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(), X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext() -and X509_add_ext() operate on the extensions of certificate B they are +and X509_add_ext() operate on the extensions of certificate I. They are otherwise identical to the X509v3 functions. X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(), X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(), X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of -CRL B they are otherwise identical to the X509v3 functions. +CRL I. They are otherwise identical to the X509v3 functions. X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(), X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(), X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and -X509_REVOKED_add_ext() operate on the extensions of CRL entry B -they are otherwise identical to the X509v3 functions. +X509_REVOKED_add_ext() operate on the extensions of CRL entry I. +They are otherwise identical to the X509v3 functions. =head1 NOTES -These functions are used to examine stacks of extensions directly. Many -applications will want to parse or encode and add an extension: they should -use the extension encode and decode functions instead such as +These functions are used to examine stacks of extensions directly. +Applications that want to parse or encode and add an extension should +use the extension encode and decode functions instead, such as X509_add1_ext_i2d() and X509_get_ext_d2i(). -Extension indices start from zero, so a zero index return value is B an -error. These search functions start from the extension B the B -parameter so it should initially be set to B<-1>, if it is set to zero the -initial extension will not be checked. - -=head1 BUGS +For X509v3_get_ext_by_NID(), X509v3_get_ext_by_OBJ(), +X509v3_get_ext_by_critical() and its variants, a zero index return value +is not an error since extension STACK I indices start from zero. +These search functions start from the extension B the I parameter +so it should initially be set to -1. If it is set to zero, the initial extension +will not be checked. X509v3_delete_ext() and its variants are a bit counter-intuitive because these functions do not free the extension they delete. +They return an B object which must be explicitly freed +using X509_EXTENSION_free(). =head1 RETURN VALUES X509v3_get_ext_count() returns the extension count. X509v3_get_ext(), X509v3_delete_ext() and X509_delete_ext() return an -B pointer or B if an error occurs. +B structure or NULL if an error occurs. -X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and -X509v3_get_ext_by_critical() return the extension index or B<-1> if an +X509v3_get_ext_by_NID(), X509v3_get_ext_by_OBJ() and +X509v3_get_ext_by_critical() return the extension index or -1 if an error occurs. -X509v3_add_ext() returns a stack of extensions or B on error. +X509v3_add_ext() returns a STACK of extensions or NULL on error. X509_add_ext() returns 1 on success and 0 on error.