From: Dr. Stephen Henson Date: Fri, 4 Jul 2014 22:03:17 +0000 (+0100) Subject: Extension parsing and encoding docs. X-Git-Tag: OpenSSL_1_1_0-pre1~553 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=047dd81efe47b9185fef7f1d35d0a1006b0c2cb6;hp=d8db9a0df5d742aa8f21d611e1df9072ecf0450e Extension parsing and encoding docs. Reviewed-by: Matt Caswell --- diff --git a/doc/crypto/X509V3_get_d2i.pod b/doc/crypto/X509V3_get_d2i.pod new file mode 100644 index 0000000000..8e7848894d --- /dev/null +++ b/doc/crypto/X509V3_get_d2i.pod @@ -0,0 +1,217 @@ +=pod + +=head1 NAME + +X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d, +X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i, +X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i, +X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions + +=head1 SYNOPSIS + + #include + + void *X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, + int *idx); + int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value, + int crit, unsigned long flags); + + void *X509V3_EXT_d2i(X509_EXTENSION *ext); + X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext); + + void *X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx); + int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit, + unsigned long flags); + + void *X509_CRL_get_ext_d2i(X509_CRL *crl, int nid, int *crit, int *idx); + int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit, + unsigned long flags); + + void *X509_REVOKED_get_ext_d2i(X509_REVOKED *r, int nid, int *crit, int *idx); + int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit, + unsigned long flags); + +=head1 DESCRIPTION + +X509V3_get_ext_d2i() looks for an extension with OID B in the extensions +B and, if found, decodes it. If B is B then only one +occurrence of an extension is permissible otherwise the first extension after +index B<*idx> is returned and B<*idx> updated to the location of the extension. +If B is not B then B<*crit> is set to a status value: -2 if the +extension occurs multiple times (this is only returned if B is B), +-1 if the extension could not be found, 0 if the extension is found and is +not critical and 1 if critical. A pointer to an extension specific structure +or B is returned. + +X509V3_add1_i2d() adds extension B to STACK B<*x> (allocating a new +STACK if necessary) using OID B and criticality B according +to B. + +X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension +B and returns a pointer to an extension specific structure or B +if the extension could not be decoded (invalid syntax or not supported). + +X509V3_EXT_i2d() encodes the extension specific structure B +with OID B and criticality B. + +X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of +certificate B, they are otherwise identical to X509V3_get_d2i() and +X509V3_add_i2d(). + +X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions +of CRL B, they are otherwise identical to X509V3_get_d2i() and +X509V3_add_i2d(). + +X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the +extensions of B structure B (i.e for CRL entry extensions), +they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d(). + +=head1 NOTES + +In almost all cases an extension can occur at most once and multiple +occurences is an error. Therefore the B parameter is usually B. + +The B parameter may be one of the following values. + +B appends a new extension only if the extension does +not already exist. An error is returned if the extension does already +exist. + +B appends a new extension, ignoring whether the extension +already exists. + +B replaces an extension if it exists otherwise apppends +a new extension. + +B replaces an existing extension if it exists +otherwise returns an error. + +B appends a new extension only if the extension does +not already exist. An error B returned if the extension does already +exist. + +B extension B is deleted: no new extenion is added. + +If B is ored with B: any error returned will not +be added to the error queue. + +The function X509V3_get_d2i() will return B if the extension is not +found, occurs multiple times or cannot be decoded. It is possible to +determine the precise reason by checking the value of B<*crit>. + +=head1 SUPPORTED EXTENSIONS + +The following sections contain a list of all supported extensions +including their name and NID. + +=head2 PKIX CERTIFICATE EXTENSIONS + +The following certificate extensions are defined in PKIX standards such as +RFC5280. + + Basic Constraints NID_basic_constraints + Key Usage NID_key_usage + Extended Key Usage NID_ext_key_usage + + Subject Key Identifier NID_subject_key_identifier + Authority Key Identifier NID_authority_key_identifier + + Private Key Usage Period NID_private_key_usage_period + + Subject Alternative Name NID_subject_alt_name + Issuer Alternative Name NID_issuer_alt_name + + Authority Information Access NID_info_access + Subject Information Access NID_sinfo_access + + Name Constraints NID_name_constraints + + Certificate Policies NID_certificate_policies + Policy Mappings NID_policy_mappings + Policy Constraints NID_policy_constraints + Inhibit Any Policy NID_inhibit_any_policy + +=head2 NETSCAPE CERTIFICATE EXTENSIONS + +The following are (largely obsolete) Netscape certificate extensions. + + Netscape Cert Type NID_netscape_cert_type + Netscape Base Url NID_netscape_base_url + Netscape Revocation Url NID_netscape_revocation_url + Netscape CA Revocation Url NID_netscape_ca_revocation_url + Netscape Renewal Url NID_netscape_renewal_url + Netscape CA Policy Url NID_netscape_ca_policy_url + Netscape SSL Server Name NID_netscape_ssl_server_name + Netscape Comment NID_netscape_comment + +=head2 MISCELLANEOUS CERTIFICATE EXTENSIONS + + Strong Extranet ID NID_sxnet + Proxy Certificate Information NID_proxyCertInfo + +=head2 PKIX CRL EXTENSIONS + +The following are CRL extensions from PKIX standards such as RFC5280. + + CRL Number NID_crl_number + CRL Distribution Points NID_crl_distribution_points + Delta CRL Indicator NID_delta_crl + Freshest CRL NID_freshest_crl + Invalidity Date NID_invalidity_date + Issuing Distrubution Point NID_issuing_distribution_point + +The following are CRL entry extensions from PKIX standards such as RFC5280. + + CRL Reason Code NID_crl_reason + Certificate Issuer NID_certificate_issuer + +=head2 OCSP EXTENSIONS + + OCSP Nonce NID_id_pkix_OCSP_Nonce + OCSP CRL ID NID_id_pkix_OCSP_CrlID + Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses + OCSP No Check NID_id_pkix_OCSP_noCheck + OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff + OCSP Service Locator NID_id_pkix_OCSP_serviceLocator + Hold Instruction Code NID_hold_instruction_code + +=head2 CERTIFICATE TRANSPARENCY EXTENSIONS + +The following extensions are used by certificate transparency, RFC6962 + + CT Precertificate SCTs NID_ct_precert_scts + CT Certificate SCTs NID_ct_cert_scts + +=head1 RETURN VALUES + +X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension +specific structure of B if an error occurs. + +X509V3_EXT_i2d() returns a pointer to an B structure +or B if an error occurs. + +X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it +fails due to a non-fatal error (extension not found, already exists, +cannot be encoded) or -1 due to a fatal error such as a memory allocation +failure. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut