openssl
/
openssl
mirror of https://github.com/openssl/openssl
1
0
Fork 0
Code Issues Releases Wiki Activity

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 <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18786)
This commit is contained in:
Allan 2022-07-13 01:55:06 -07:00 committed by Tomas Mraz
parent 086d88a637
commit 1711f4824b
2 changed files with 59 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
doc/man3/X509_CRL_get0_by_serial.pod
View File

@ -30,42 +30,42 @@ functions
=head1 DESCRIPTION
X509_CRL_get0_by_serial() attempts to find a revoked entry in B<crl> for
serial number B<serial>. 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<crl> for
serial number I<serial>. If it is successful, it sets I<*ret> to the internal
pointer of the matching entry. As a result, I<*ret> B<MUST NOT> 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<x>.
looks for a revoked entry using the serial number of certificate I<x>.
X509_CRL_get_REVOKED() returns an internal pointer to a stack of all
revoked entries for B<crl>.
X509_CRL_get_REVOKED() returns an internal pointer to a STACK of all
revoked entries for I<crl>.
X509_REVOKED_get0_serialNumber() returns an internal pointer to the
serial number of B<r>.
serial number of I<r>.
X509_REVOKED_get0_revocationDate() returns an internal pointer to the
revocation date of B<r>.
revocation date of I<r>.
X509_REVOKED_set_serialNumber() sets the serial number of B<r> to B<serial>.
The supplied B<serial> pointer is not used internally so it should be
freed up after use.
X509_REVOKED_set_serialNumber() sets the serial number of I<r> to I<serial>.
The supplied I<serial> pointer is not used internally so it should be
freed after use.
X509_REVOKED_set_revocationDate() sets the revocation date of B<r> to
B<tm>. The supplied B<tm> pointer is not used internally so it should be
freed up after use.
X509_REVOKED_set_revocationDate() sets the revocation date of I<r> to
I<tm>. The supplied I<tm> pointer is not used internally so it should be
freed after use.
X509_CRL_add0_revoked() appends revoked entry B<rev> to CRL B<crl>. The
pointer B<rev> is used internally so it must not be freed up after the call:
X509_CRL_add0_revoked() appends revoked entry I<rev> to CRL I<crl>. The
pointer I<rev> is used internally so it B<MUST NOT> be freed after the call:
it is freed when the parent CRL is freed.
X509_CRL_sort() sorts the revoked entries of B<crl> into ascending serial
X509_CRL_sort() sorts the revoked entries of I<crl> 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,16 +74,16 @@ 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<removeFromCRL> (8),
in which case 2 is returned.
X509_CRL_get_REVOKED() returns a STACK of revoked entries.
X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> structure.
X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> structure.
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_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> pointer.
X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> value.
X509_CRL_get_REVOKED() returns a STACK of revoked entries.
=head1 SEE ALSO
L<d2i_X509(3)>,

67
doc/man3/X509v3_get_ext_by_NID.pod
View File

@ -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<x>.
X509v3_get_ext_count() retrieves the number of extensions in I<x>.
X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc>
can take any value from B<0> to X509_get_ext_count(x) - 1. The returned
extension is an internal pointer which B<must not> be freed up by the
X509v3_get_ext() retrieves extension I<loc> from I<x>. The index I<loc>
can take any value from 0 to X509_get_ext_count(I<x>) - 1. The returned
extension is an internal pointer which B<MUST NOT> be freed by the
application.
X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension
with B<nid> or B<obj> from extension stack B<x>. The search starts from the
extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If
the extension is found its index is returned otherwise B<-1> is returned.
with I<nid> or I<obj> from extension STACK I<x>. The search starts from the
extension after I<lastpos> or from the beginning if I<lastpos> 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<crit>. A zero value for B<crit>
looks for a non-critical extension a nonzero value looks for a critical
looks for an extension of criticality I<crit>. A zero value for I<crit>
looks for a non-critical extension. A nonzero value looks for a critical
extension.
X509v3_delete_ext() deletes the extension with index B<loc> from B<x>.
X509v3_delete_ext() deletes the extension with index I<loc> from I<x>.
The deleted extension is returned and must be freed by the caller.
If B<loc> is in invalid index value B<NULL> is returned.
If I<loc> is an invalid index value, NULL is returned.
X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If
B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL>
a new stack will be allocated. The passed extension B<ex> is duplicated
X509v3_add_ext() adds extension I<ex> to STACK I<*x> at position I<loc>. If
I<loc> 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<ex> 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<x> they are
and X509_add_ext() operate on the extensions of certificate I<x>. 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<x> they are otherwise identical to the X509v3 functions.
CRL I<x>. 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<x>
they are otherwise identical to the X509v3 functions.
X509_REVOKED_add_ext() operate on the extensions of CRL entry I<x>.
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<not> an
error. These search functions start from the extension B<after> the B<lastpos>
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<x> indices start from zero.
These search functions start from the extension B<after> the I<lastpos> 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<X509_EXTENSION> 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<X509_EXTENSION> pointer or B<NULL> if an error occurs.
B<X509_EXTENSION> 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<NULL> 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.