From e989e54f66a86aca816fc15c2e9edccc3c542547 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Thu, 10 Dec 2015 19:13:57 +0000 Subject: [PATCH] extension documentation Reviewed-by: Kurt Roeckx --- doc/crypto/X509v3_get_ext_by_NID.pod | 142 +++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 doc/crypto/X509v3_get_ext_by_NID.pod diff --git a/doc/crypto/X509v3_get_ext_by_NID.pod b/doc/crypto/X509v3_get_ext_by_NID.pod new file mode 100644 index 0000000000..b11d663509 --- /dev/null +++ b/doc/crypto/X509v3_get_ext_by_NID.pod @@ -0,0 +1,142 @@ +=pod + +=head1 NAME + +X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID, +X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext, +X509v3_add_ext, X509_get0_extensions, X509_CRL_get0_extensions, +X509_REVOKED_get0_extensions, 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, X509_add_ext, 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, X509_CRL_add_ext, 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, +X509_REVOKED_add_ext - extension stack utility functions. + +=head1 SYNOPSIS + + #include + + int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x); + X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc); + + int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x, + int nid, int lastpos); + int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x, + ASN1_OBJECT *obj, int lastpos); + int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x, + int crit, int lastpos); + X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc); + STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x, + X509_EXTENSION *ex, int loc); + + STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x); + STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(X509_CRL *crl); + STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(X509_REVOKED *r); + + int X509_get_ext_count(X509 *x); + X509_EXTENSION *X509_get_ext(X509 *x, int loc); + int X509_get_ext_by_NID(X509 *x, int nid, int lastpos); + int X509_get_ext_by_OBJ(X509 *x, ASN1_OBJECT *obj, int lastpos); + int X509_get_ext_by_critical(X509 *x, int crit, int lastpos); + X509_EXTENSION *X509_delete_ext(X509 *x, int loc); + int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc); + + int X509_CRL_get_ext_count(X509_CRL *x); + X509_EXTENSION *X509_CRL_get_ext(X509_CRL *x, int loc); + int X509_CRL_get_ext_by_NID(X509_CRL *x, int nid, int lastpos); + int X509_CRL_get_ext_by_OBJ(X509_CRL *x, ASN1_OBJECT *obj, int lastpos); + int X509_CRL_get_ext_by_critical(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); + + int X509_REVOKED_get_ext_count(X509_REVOKED *x); + X509_EXTENSION *X509_REVOKED_get_ext(X509_REVOKED *x, int loc); + int X509_REVOKED_get_ext_by_NID(X509_REVOKED *x, int nid, int lastpos); + int X509_REVOKED_get_ext_by_OBJ(X509_REVOKED *x, ASN1_OBJECT *obj, + int lastpos); + int X509_REVOKED_get_ext_by_critical(X509_REVOKED *x, int crit, int lastpos); + X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc); + int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc); + +=head1 DESCRIPTION + +X509v3_get_ext_count() retrieves the number of extensions in B. + +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 +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. + +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 non-zero value looks for a critical +extension. + +X509v3_delete_ext() deletes the extension with index B from B. The +deleted extension is returned and must be freed by the caller. If B +is in invalid index value B 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 +internally so it must be freed after use. + +X509_get0_extensions(), X509_CRL_get0_extensions() and +X509_REVOKED_get0_extensions() retrieve the extensions from a certificate +a CRL or a CRL entry respectively. + +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 +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. + +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. + +=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 +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 RETURN VALUES + +X509v3_get_ext_count() returns the extension count. + +X509v3_get_ext() and X509v3_delete_ext() return an B pointer +or B if an error occurs. + +X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and +X509v3_get_ext_by_critical() return the an extension index or B<-1> if an +error occurs. + +X509v3_add_ext() returns a stack of extensions or B on error. + +X509_get0_extensions(), X509_CRL_get0_extensions() and +X509_REVOKED_get0_extensions() return a stack of extensions. If the extensions +field is absent it will return B: this is B an error condition. + +=head1 SEE ALSO + +L -- 2.34.1