From: Dr. Stephen Henson Date: Thu, 10 Sep 2015 23:06:37 +0000 (+0100) Subject: Add comments to x509_int.h X-Git-Tag: OpenSSL_1_1_0-pre1~565 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=40ffdc9cfa0717d778c674bb79850e404b587077 Add comments to x509_int.h Reviewed-by: Rich Salz Reviewed-by: Emilia Käsper --- diff --git a/crypto/include/internal/x509_int.h b/crypto/include/internal/x509_int.h index d9147aea3b..26678cfe61 100644 --- a/crypto/include/internal/x509_int.h +++ b/crypto/include/internal/x509_int.h @@ -59,72 +59,75 @@ /* Internal X509 structures and functions: not for application use */ +/* Note: unless otherwise stated a field pointer is mandatory and should + * never be set to NULL: the ASN.1 code and accessors rely on mandatory + * fields never being NULL. + */ + +/* + * name entry structure, equivalent to AttributeTypeAndValue defined + * in RFC5280 et al. + */ struct X509_name_entry_st { - ASN1_OBJECT *object; - ASN1_STRING *value; - int set; + ASN1_OBJECT *object; /* AttributeType */ + ASN1_STRING *value; /* AttributeValue */ + int set; /* index of RDNSequence for this entry */ int size; /* temp variable */ }; -/* we always keep X509_NAMEs in 2 forms. */ +/* Name from RFC 5280. */ struct X509_name_st { - STACK_OF(X509_NAME_ENTRY) *entries; + STACK_OF(X509_NAME_ENTRY) *entries; /* DN components */ int modified; /* true if 'bytes' needs to be built */ - BUF_MEM *bytes; -/* unsigned long hash; Keep the hash around for lookups */ + BUF_MEM *bytes; /* cached encoding: cannot be NULL */ + /* canonical encoding used for rapid Name comparison */ unsigned char *canon_enc; int canon_enclen; } /* X509_NAME */ ; -/* - * This stuff is certificate "auxiliary info" it contains details which are - * useful in certificate stores and databases. When used this is tagged onto - * the end of the certificate itself - */ - -struct x509_cert_aux_st { - STACK_OF(ASN1_OBJECT) *trust; /* trusted uses */ - STACK_OF(ASN1_OBJECT) *reject; /* rejected uses */ - ASN1_UTF8STRING *alias; /* "friendly name" */ - ASN1_OCTET_STRING *keyid; /* key id of private key */ - STACK_OF(X509_ALGOR) *other; /* other unspecified info */ -}; +/* PKCS#10 certificate request */ struct X509_req_info_st { - ASN1_ENCODING enc; - ASN1_INTEGER *version; - X509_NAME *subject; - X509_PUBKEY *pubkey; - /* d=2 hl=2 l= 0 cons: cont: 00 */ - STACK_OF(X509_ATTRIBUTE) *attributes; /* [ 0 ] */ + ASN1_ENCODING enc; /* cached encoding of signed part */ + ASN1_INTEGER *version; /* version, defaults to v1(0) so can be NULL */ + X509_NAME *subject; /* certificate request DN */ + X509_PUBKEY *pubkey; /* public key of request */ + /* + * Zero or more attributes. + * NB: although attributes is a mandatory field some broken + * encodings omit it so this may be NULL in that case. + */ + STACK_OF(X509_ATTRIBUTE) *attributes; }; struct X509_req_st { - X509_REQ_INFO req_info; - X509_ALGOR sig_alg; - ASN1_BIT_STRING *signature; + X509_REQ_INFO req_info; /* signed certificate request data */ + X509_ALGOR sig_alg; /* signature algorithm */ + ASN1_BIT_STRING *signature; /* signature */ int references; }; struct X509_crl_info_st { - ASN1_INTEGER *version; - X509_ALGOR sig_alg; - X509_NAME *issuer; - ASN1_TIME *lastUpdate; - ASN1_TIME *nextUpdate; - STACK_OF(X509_REVOKED) *revoked; - STACK_OF(X509_EXTENSION) /* [0] */ *extensions; - ASN1_ENCODING enc; + ASN1_INTEGER *version; /* version: defaults to v1(0) so may be NULL */ + X509_ALGOR sig_alg; /* signagture algorithm */ + X509_NAME *issuer; /* CRL issuer name */ + ASN1_TIME *lastUpdate; /* lastUpdate field */ + ASN1_TIME *nextUpdate; /* nextUpdate field: optional */ + STACK_OF(X509_REVOKED) *revoked; /* revoked entries: optional */ + STACK_OF(X509_EXTENSION) *extensions; /* extensions: optional */ + ASN1_ENCODING enc; /* encoding of signed portion of CRL */ }; struct X509_crl_st { - /* actual signature */ - X509_CRL_INFO crl; - X509_ALGOR sig_alg; - ASN1_BIT_STRING *signature; + X509_CRL_INFO crl; /* signed CRL data */ + X509_ALGOR sig_alg; /* CRL signature algorithm */ + ASN1_BIT_STRING *signature; /* CRL signature */ int references; int flags; - /* Copies of various extensions */ + /* + * Cached copies of decoded extension values, since extensions + * are optional any of these can be NULL. + */ AUTHORITY_KEYID *akid; ISSUING_DIST_POINT *idp; /* Convenient breakdown of IDP */ @@ -133,19 +136,40 @@ struct X509_crl_st { /* CRL and base CRL numbers for delta processing */ ASN1_INTEGER *crl_number; ASN1_INTEGER *base_crl_number; - unsigned char sha1_hash[SHA_DIGEST_LENGTH]; STACK_OF(GENERAL_NAMES) *issuers; + /* hash of CRL */ + unsigned char sha1_hash[SHA_DIGEST_LENGTH]; + /* alternative method to handle this CRL */ const X509_CRL_METHOD *meth; void *meth_data; }; struct x509_revoked_st { - ASN1_INTEGER *serialNumber; - ASN1_TIME *revocationDate; - STACK_OF(X509_EXTENSION) /* optional */ *extensions; - /* Set up if indirect CRL */ + ASN1_INTEGER *serialNumber; /* revoked entry serial number */ + ASN1_TIME *revocationDate; /* revocation date */ + STACK_OF(X509_EXTENSION) *extensions; /* CRL entry extensions: optional */ + /* decoded value of CRLissuer extension: set if indirect CRL */ STACK_OF(GENERAL_NAME) *issuer; - /* Revocation reason */ + /* revocation reason: set to CRL_REASON_NONE if reason extension absent */ int reason; - int sequence; /* load sequence */ + /* + * CRL entries are reordered for faster lookup of serial numbers. This + * field contains the original load sequence for this entry. + */ + int sequence; +}; + +/* + * This stuff is certificate "auxiliary info": it contains details which are + * useful in certificate stores and databases. When used this is tagged onto + * the end of the certificate itself. OpenSSL specific structure not defined + * in any RFC. + */ + +struct x509_cert_aux_st { + STACK_OF(ASN1_OBJECT) *trust; /* trusted uses */ + STACK_OF(ASN1_OBJECT) *reject; /* rejected uses */ + ASN1_UTF8STRING *alias; /* "friendly name" */ + ASN1_OCTET_STRING *keyid; /* key id of private key */ + STACK_OF(X509_ALGOR) *other; /* other unspecified info */ };