X509V3_get_d2i.pod 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  1. =pod
  2. =head1 NAME
  3. X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions,
  4. X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d,
  5. X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i,
  6. X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i,
  7. X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions
  8. =head1 SYNOPSIS
  9. #include <openssl/x509v3.h>
  10. void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit,
  11. int *idx);
  12. int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value,
  13. int crit, unsigned long flags);
  14. void *X509V3_EXT_d2i(X509_EXTENSION *ext);
  15. X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
  16. void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx);
  17. int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
  18. unsigned long flags);
  19. void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx);
  20. int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit,
  21. unsigned long flags);
  22. void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx);
  23. int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit,
  24. unsigned long flags);
  25. const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
  26. const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl);
  27. const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r);
  28. =head1 DESCRIPTION
  29. X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions
  30. B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one
  31. occurrence of an extension is permissible otherwise the first extension after
  32. index B<*idx> is returned and B<*idx> updated to the location of the extension.
  33. If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the
  34. extension occurs multiple times (this is only returned if B<idx> is B<NULL>),
  35. -1 if the extension could not be found, 0 if the extension is found and is
  36. not critical and 1 if critical. A pointer to an extension specific structure
  37. or B<NULL> is returned.
  38. X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new
  39. STACK if necessary) using OID B<nid> and criticality B<crit> according
  40. to B<flags>.
  41. X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension
  42. B<ext> and returns a pointer to an extension specific structure or B<NULL>
  43. if the extension could not be decoded (invalid syntax or not supported).
  44. X509V3_EXT_i2d() encodes the extension specific structure B<ext>
  45. with OID B<ext_nid> and criticality B<crit>.
  46. X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of
  47. certificate B<x>, they are otherwise identical to X509V3_get_d2i() and
  48. X509V3_add_i2d().
  49. X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions
  50. of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and
  51. X509V3_add_i2d().
  52. X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the
  53. extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions),
  54. they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d().
  55. X509_get0_extensions(), X509_CRL_get0_extensions() and
  56. X509_REVOKED_get0_extensions() return a stack of all the extensions
  57. of a certificate a CRL or a CRL entry respectively.
  58. =head1 NOTES
  59. In almost all cases an extension can occur at most once and multiple
  60. occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>.
  61. The B<flags> parameter may be one of the following values.
  62. B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does
  63. not already exist. An error is returned if the extension does already
  64. exist.
  65. B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension
  66. already exists.
  67. B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends
  68. a new extension.
  69. B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists
  70. otherwise returns an error.
  71. B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does
  72. not already exist. An error B<is not> returned if the extension does already
  73. exist.
  74. B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extension is added.
  75. If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not
  76. be added to the error queue.
  77. The function X509V3_get_d2i() will return B<NULL> if the extension is not
  78. found, occurs multiple times or cannot be decoded. It is possible to
  79. determine the precise reason by checking the value of B<*crit>.
  80. =head1 SUPPORTED EXTENSIONS
  81. The following sections contain a list of all supported extensions
  82. including their name and NID.
  83. =head2 PKIX Certificate Extensions
  84. The following certificate extensions are defined in PKIX standards such as
  85. RFC5280.
  86. Basic Constraints NID_basic_constraints
  87. Key Usage NID_key_usage
  88. Extended Key Usage NID_ext_key_usage
  89. Subject Key Identifier NID_subject_key_identifier
  90. Authority Key Identifier NID_authority_key_identifier
  91. Private Key Usage Period NID_private_key_usage_period
  92. Subject Alternative Name NID_subject_alt_name
  93. Issuer Alternative Name NID_issuer_alt_name
  94. Authority Information Access NID_info_access
  95. Subject Information Access NID_sinfo_access
  96. Name Constraints NID_name_constraints
  97. Certificate Policies NID_certificate_policies
  98. Policy Mappings NID_policy_mappings
  99. Policy Constraints NID_policy_constraints
  100. Inhibit Any Policy NID_inhibit_any_policy
  101. TLS Feature NID_tlsfeature
  102. =head2 Netscape Certificate Extensions
  103. The following are (largely obsolete) Netscape certificate extensions.
  104. Netscape Cert Type NID_netscape_cert_type
  105. Netscape Base Url NID_netscape_base_url
  106. Netscape Revocation Url NID_netscape_revocation_url
  107. Netscape CA Revocation Url NID_netscape_ca_revocation_url
  108. Netscape Renewal Url NID_netscape_renewal_url
  109. Netscape CA Policy Url NID_netscape_ca_policy_url
  110. Netscape SSL Server Name NID_netscape_ssl_server_name
  111. Netscape Comment NID_netscape_comment
  112. =head2 Miscellaneous Certificate Extensions
  113. Strong Extranet ID NID_sxnet
  114. Proxy Certificate Information NID_proxyCertInfo
  115. =head2 PKIX CRL Extensions
  116. The following are CRL extensions from PKIX standards such as RFC5280.
  117. CRL Number NID_crl_number
  118. CRL Distribution Points NID_crl_distribution_points
  119. Delta CRL Indicator NID_delta_crl
  120. Freshest CRL NID_freshest_crl
  121. Invalidity Date NID_invalidity_date
  122. Issuing Distribution Point NID_issuing_distribution_point
  123. The following are CRL entry extensions from PKIX standards such as RFC5280.
  124. CRL Reason Code NID_crl_reason
  125. Certificate Issuer NID_certificate_issuer
  126. =head2 OCSP Extensions
  127. OCSP Nonce NID_id_pkix_OCSP_Nonce
  128. OCSP CRL ID NID_id_pkix_OCSP_CrlID
  129. Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses
  130. OCSP No Check NID_id_pkix_OCSP_noCheck
  131. OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff
  132. OCSP Service Locator NID_id_pkix_OCSP_serviceLocator
  133. Hold Instruction Code NID_hold_instruction_code
  134. =head2 Certificate Transparency Extensions
  135. The following extensions are used by certificate transparency, RFC6962
  136. CT Precertificate SCTs NID_ct_precert_scts
  137. CT Certificate SCTs NID_ct_cert_scts
  138. =head1 RETURN VALUES
  139. X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension
  140. specific structure of B<NULL> if an error occurs.
  141. X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure
  142. or B<NULL> if an error occurs.
  143. X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it
  144. fails due to a non-fatal error (extension not found, already exists,
  145. cannot be encoded) or -1 due to a fatal error such as a memory allocation
  146. failure.
  147. X509_get0_extensions(), X509_CRL_get0_extensions() and
  148. X509_REVOKED_get0_extensions() return a stack of extensions. They return
  149. NULL if no extensions are present.
  150. =head1 SEE ALSO
  151. L<d2i_X509(3)>,
  152. L<ERR_get_error(3)>,
  153. L<X509_CRL_get0_by_serial(3)>,
  154. L<X509_get0_signature(3)>,
  155. L<X509_get_ext_d2i(3)>,
  156. L<X509_get_extension_flags(3)>,
  157. L<X509_get_pubkey(3)>,
  158. L<X509_get_subject_name(3)>,
  159. L<X509_get_version(3)>,
  160. L<X509_NAME_add_entry_by_txt(3)>,
  161. L<X509_NAME_ENTRY_get_object(3)>,
  162. L<X509_NAME_get_index_by_NID(3)>,
  163. L<X509_NAME_print_ex(3)>,
  164. L<X509_new(3)>,
  165. L<X509_sign(3)>,
  166. L<X509_verify_cert(3)>
  167. =head1 COPYRIGHT
  168. Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
  169. Licensed under the OpenSSL license (the "License"). You may not use
  170. this file except in compliance with the License. You can obtain a copy
  171. in the file LICENSE in the source distribution or at
  172. L<https://www.openssl.org/source/license.html>.
  173. =cut