doc/crypto/X509v3_get_ext_by_NID.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID,
   6 X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext,
   7 X509v3_add_ext, X509_get0_extensions, X509_CRL_get0_extensions,
   8 X509_REVOKED_get0_extensions, X509_get_ext_count, X509_get_ext,
   9 X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical,
  10 X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext,
  11 X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical,
  12 X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count,
  13 X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ,
  14 X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext,
  15 X509_REVOKED_add_ext - extension stack utility functions.
  16
  17 =head1 SYNOPSIS
  18
  19  #include <openssl/x509.h>
  20
  21  int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x);
  22  X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc);
  23
  24  int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x,
  25                            int nid, int lastpos);
  26  int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x,
  27                            ASN1_OBJECT *obj, int lastpos);
  28  int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x,
  29                                 int crit, int lastpos);
  30  X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc);
  31  STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x,
  32                                           X509_EXTENSION *ex, int loc);
  33
  34  STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
  35  STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(X509_CRL *crl);
  36  STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(X509_REVOKED *r);
  37
  38  int X509_get_ext_count(X509 *x);
  39  X509_EXTENSION *X509_get_ext(X509 *x, int loc);
  40  int X509_get_ext_by_NID(X509 *x, int nid, int lastpos);
  41  int X509_get_ext_by_OBJ(X509 *x, ASN1_OBJECT *obj, int lastpos);
  42  int X509_get_ext_by_critical(X509 *x, int crit, int lastpos);
  43  X509_EXTENSION *X509_delete_ext(X509 *x, int loc);
  44  int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc);
  45
  46  int X509_CRL_get_ext_count(X509_CRL *x);
  47  X509_EXTENSION *X509_CRL_get_ext(X509_CRL *x, int loc);
  48  int X509_CRL_get_ext_by_NID(X509_CRL *x, int nid, int lastpos);
  49  int X509_CRL_get_ext_by_OBJ(X509_CRL *x, ASN1_OBJECT *obj, int lastpos);
  50  int X509_CRL_get_ext_by_critical(X509_CRL *x, int crit, int lastpos);
  51  X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc);
  52  int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc);
  53
  54  int X509_REVOKED_get_ext_count(X509_REVOKED *x);
  55  X509_EXTENSION *X509_REVOKED_get_ext(X509_REVOKED *x, int loc);
  56  int X509_REVOKED_get_ext_by_NID(X509_REVOKED *x, int nid, int lastpos);
  57  int X509_REVOKED_get_ext_by_OBJ(X509_REVOKED *x, ASN1_OBJECT *obj,
  58                                 int lastpos);
  59  int X509_REVOKED_get_ext_by_critical(X509_REVOKED *x, int crit, int lastpos);
  60  X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc);
  61  int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc);
  62
  63 =head1 DESCRIPTION
  64
  65 X509v3_get_ext_count() retrieves the number of extensions in B<x>.
  66
  67 X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc>
  68 can take any value from B<0> to X509_get_ext_count(x) - 1. The returned
  69 extension is an internal pointer which B<must not> be freed up by the
  70 application.
  71
  72 X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension
  73 with B<nid> or B<obj> from extension stack B<x>. The search starts from the
  74 extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If
  75 the extension is found its index is returned otherwise B<-1> is returned.
  76
  77 X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it
  78 looks for an extension of criticality B<crit>. A zero value for B<crit>
  79 looks for a non-critical extension a non-zero value looks for a critical
  80 extension.
  81
  82 X509v3_delete_ext() deletes the extension with index B<loc> from B<x>. The
  83 deleted extension is returned and must be freed by the caller. If B<loc>
  84 is in invalid index value B<NULL> is returned.
  85
  86 X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If
  87 B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL>
  88 a new stack will be allocated. The passed extension B<ex> is duplicated
  89 internally so it must be freed after use.
  90
  91 X509_get0_extensions(), X509_CRL_get0_extensions() and
  92 X509_REVOKED_get0_extensions() retrieve the extensions from a certificate
  93 a CRL or a CRL entry respectively.
  94
  95 X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(),
  96 X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext()
  97 and X509_add_ext() operate on the extensions of certificate B<x> they are
  98 otherwise identical to the X509v3 functions.
  99
 100 X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(),
 101 X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(),
 102 X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of
 103 CRL B<x> they are otherwise identical to the X509v3 functions.
 104
 105 X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(),
 106 X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(),
 107 X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and
 108 X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x>
 109 they are otherwise identical to the X509v3 functions.
 110
 111 =head1 NOTES
 112
 113 These functions are used to examine stacks of extensions directly. Many
 114 applications will want to parse or encode and add an extension: they should
 115 use the extension encode and decode functions instead such as
 116 X509_add1_ext_i2d() and X509_get_ext_d2i().
 117
 118 Extension indices start from zero, so a zero index return value is B<not> an
 119 error. These search functions start from the extension B<after> the B<lastpos>
 120 parameter so it should initially be set to B<-1>, if it is set to zero the
 121 initial extension will not be checked.
 122
 123 =head1 RETURN VALUES
 124
 125 X509v3_get_ext_count() returns the extension count.
 126
 127 X509v3_get_ext() and X509v3_delete_ext() return an B<X509_EXTENSION> pointer
 128 or B<NULL> if an error occurs.
 129
 130 X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and
 131 X509v3_get_ext_by_critical() return the an extension index or B<-1> if an
 132 error occurs.
 133
 134 X509v3_add_ext() returns a stack of extensions or B<NULL> on error.
 135
 136 X509_get0_extensions(), X509_CRL_get0_extensions() and
 137 X509_REVOKED_get0_extensions() return a stack of extensions. If the extensions
 138 field is absent it will return B<NULL>: this is B<not> an error condition.
 139
 140 =head1 SEE ALSO
 141
 142 L<X509V3_get_d2i(3)>