75 lines
8.4 KiB
Plaintext
75 lines
8.4 KiB
Plaintext
# Format of Certificate Data for Import by Let's Encrypt
|
|
There are three CSV files:
|
|
* A `domains` CSV file, which maps the SHA1 fingerprint of a certificate to the domain which the certificate applies to (as read from the Subject field and the Subject Alternative Name field of the given certificate). Note that any given domain may appear in multiple rows in this file (if there are multiple certificates for this domain). Similarly, any given fingerprint may appear in multiple rows (if a certificate applies to multiple domains, i.e. via the SAN field). However, the combination of domain and fingerprint constitutes a unique entry, and no two rows should have the same domain *and* fingerprint.
|
|
* A `valid-certs` CSV file, which contains all the details (other than the domain) of a given certificate. Each row in the table represents one certificate (but as mentioned above, may map to multiple domains via the `domains` file).
|
|
* An `invalid-certs` CSV file, which is identical in format to the `valid-certs` CSV file, but whose rows represent certificates that are no longer valid (due to expiration, revocation, etc.).
|
|
|
|
For the purposes of importing by the Let's Encrypt system, these tables will be provided as CSV files. Each entry in the CSV file will be enclosed by double quotes (") and interior double quotes will be backslash-escaped (\"). The columns will be as follows (in the order listed).
|
|
|
|
## Table Formats
|
|
|
|
###`domains`
|
|
1. Column Name: SHA1 Fingerprint
|
|
Data Type: 40 hexadecimal characters
|
|
Description: The SHA1 fingerprint of the DER-encoded certificate, in hexadecimal, without colons separating bytes.
|
|
Example: `"10A9C1F8ADAACBFE2B0F83F7D5FA1FC293A8D2A2"`
|
|
1. Column Name: Domain
|
|
Data Type: Up to 255 characters
|
|
Description: The domain to which the certificate applies, with the DNS labels reversed. Wildcards are included.
|
|
Example: `"org.eff.*"`
|
|
|
|
###`valid-certs`
|
|
1. Column Name: SHA1 Fingerprint
|
|
Data Type: 40 hexadecimal characters
|
|
Description: The SHA1 fingerprint of the DER-encoded certificate, in hexadecimal, without colons separating bytes. Matches the SHA1 Fingerprint column in the `domains_to_fingerprints` table.
|
|
Example: `"10A9C1F8ADAACBFE2B0F83F7D5FA1FC293A8D2A2"`
|
|
1. Column Name: Issuer
|
|
Data Type: Text
|
|
Description: The Issuer field for the certificate this row represents.
|
|
Example: `"C=IL, O=StartCom Ltd., OU=Secure Digital Certificate Signing, CN=StartCom Class 2 Primary Intermediate Server CA"`
|
|
1. Column Name: Subject
|
|
Data Type: Text
|
|
Description: The Subject field for the certificate this row represents.
|
|
Example: `"description=571208-SLe257oHY9fVQ07Z, C=US, ST=California, L=San Francisco, O=Electronic Frontier Foundation, Inc., CN=*.eff.org/emailAddress=hostmaster@eff.org"`
|
|
1. Column Name: Not Valid After Datetime
|
|
Data Type: A MySQL `DATETIME`, 19 characters long. (More information is available at https://dev.mysql.com/doc/refman/5.5/en/datetime.html)
|
|
Description: The UTC expiration date/time (not valid after date/time) for the certificate this row represents.
|
|
Example: `"2016-04-14 23:42:01"`
|
|
1. Column Name: Modulus (Public Key)
|
|
Data Type: Hexadecimal characters
|
|
Description: The public key for the certificate this row represents (hexadecimal characters only, no colons).
|
|
Example: `"EA402791CB7E2721CAC9EB916BC2FFA5C3D3AEB9EA1B0A76AAE8594DACC091AA9E3942B89165DEF25C081380E4F963AC6FF84DC2433BC8C15D2FD618C23AC9CD1A6DEB5A069B275E4A9F0E4840B9C6ED9F82715472575EF966648ADFB5BA7491E2A2D1C4DA74769D84537E42BC8664C413F84AE2451A4564B1817930914E0EFBB19BA76512A29F2A5E72B6C96B8AFD74CBEE6072E7969836540BECD286A1295DBE91803DB6AE87A193320E8787E18D4473D37FB153D1E0299CEFC7BC9E6CC2E1790B3516867B549EB30A5ECE36B715D3C949E3DFA33DD6A8D351898611459259BA5E25C8CB5CFBB2868C39FD1467C5096497690B962243E863D0391CFBCDAE99"`
|
|
1. Column Name: Valid?
|
|
Data Type: 0 or 1
|
|
Description: 0 if the certificate is no longer valid (due to expiration or revocation), and 1 if the certificate is still valid (as determined via the method described below in the section *Certificate Validity*).
|
|
Example: 1
|
|
1. Column Name: EV?
|
|
Data Type: 0 or 1
|
|
Description: 1 if the certificate is a valid Extended Validation (EV) certificate (as determined via the method described below in the section *EV Validity*), and 0 otherwise.
|
|
Example: 0
|
|
1. Column Name: Hex-Encoded Certificate
|
|
Data Type: Hexadecimal characters
|
|
Description: The hexadecimal encoding of the DER-encoded certificate.
|
|
Example:
|
|
`"308205653082044DA003020102020727D9C3047132A9300D06092A864886F70D01010505003081CA310B30090603550406130255533110300E060355040813074172697A6F6E61311330110603550407130A53636F74747364616C65311A3018060355040A1311476F44616464792E636F6D2C20496E632E31333031060355040B132A687474703A2F2F6365727469666963617465732E676F64616464792E636F6D2F7265706F7369746F72793130302E06035504031327476F204461646479205365637572652043657274696669636174696F6E20417574686F726974793111300F060355040513083037393639323837301E170D3132313233313139323434365A170D3136303230363139323132375A305931193017060355040A0C102A2E6C617965727661756C742E636F6D3121301F060355040B1318446F6D61696E20436F6E74726F6C2056616C6964617465643119301706035504030C102A2E6C617965727661756C742E636F6D30820122300D06092A864886F70D01010105000382010F003082010A0282010100A59FD2DF4BAAD4A968E1BCEBDAB01CA11296972458F23E9B411A32709CA71A72514E26DB997CA7DB8E4C4E5799A8F0D7FA67116D146DA0CCD4A21560382602D670033AF80C00AA972649B7703D5534AF46E4D4E4259DDCB7447C7F23BA131ACC099B1880DF92981FF0614DAA79DFEFBD3978F04FCB118FC9624D35889BEAC447E4999668F27EE85ADB144472168256E8DCF7E0A185D346D0795C06B1340D122AB3C0C717EBFD96642F72A05345143BA502D034CF0DAA47D8A62C56B05C7F80923386546463C491DD9C916C2885B78491CF035E3400D1BCD1F43D8A8D5CE7BEB79D05E67FC6834E60D3A624F6ACF14304EBBDF1E5E9E785EA70D691990AF46B9D0203010001A38201BE308201BA300F0603551D130101FF04053003010100301D0603551D250416301406082B0601050507030106082B06010505070302300E0603551D0F0101FF0404030205A030330603551D1F042C302A3028A026A0248622687474703A2F2F63726C2E676F64616464792E636F6D2F676473312D38322E63726C30530603551D20044C304A3048060B6086480186FD6D010717013039303706082B06010505070201162B687474703A2F2F6365727469666963617465732E676F64616464792E636F6D2F7265706F7369746F72792F30818006082B0601050507010104743072302406082B060105050730018618687474703A2F2F6F6373702E676F64616464792E636F6D2F304A06082B06010505073002863E687474703A2F2F6365727469666963617465732E676F64616464792E636F6D2F7265706F7369746F72792F67645F696E7465726D6564696174652E637274301F0603551D23041830168014FDAC6132936C45D6E2EE855F9ABAE7769968CCE7302B0603551D110424302282102A2E6C617965727661756C742E636F6D820E6C617965727661756C742E636F6D301D0603551D0E04160414355D68525E6F2915C2551C9915B0ED75596EAE86300D06092A864886F70D0101050500038201010087F6A332EB0EBB039209E74A529892B64F3FEDB00C16CA621928E9CC2862E9C6C2ABC120E3A6010157186D4B96D4B7B36C922C7193DDADB72E02CB3BAD4B17157452D2D2895B1CA969A9E29A36507540C317E8C68BE17EC5061A2AAEBE58E1E2DDA7B352484142D3D91D60D5779C6A4EA464269304471CBB0B025B1BBAAE4C0AF5A1DDB5D48D0697C5EF94A06B723DA1188CDA1DC1540CEC7A7D7604F8482F23B8716D6A98BCB7582170D9ED7D09F8993D865D2236DDC9075C3551CE810124796F909ECDF8FF04155AF0BDED3144B2E21C5561082D107F6720C5FFCB2CD003BA9CA4EF00E2A16B3F7F3D379D1180DFC1A6BBBAA195ACC8768BEBAF9CAB3A04BE"`
|
|
|
|
|
|
###`invalid-certs`
|
|
Same format as the `valid-certs` CSV file.
|
|
|
|
## Certificate Validity
|
|
A certificate is considered valid if the following `openssl` command reports the certificate is valid:
|
|
|
|
openssl verify -CApath root_cas -crl_check -untrusted intermediate_ca_certs certificate.pem
|
|
|
|
where
|
|
* `root_cas` is a directory containing the transitive closure of all valid CA certificates contained in the data source, starting with the union of the root CA certificates included with Mozilla Firefox and Microsoft Windows,
|
|
* `intermediate_ca_certs` is a file containing all the intermediate CAs the data source has seen in chains connected to the certificate in question, and,
|
|
* `certificate.pem` is the certificate in question in PEM format.
|
|
|
|
## EV Validity
|
|
A certificate is considered a valid Extended Validation certificate if it is valid as described in *Certificate Validity* and all of the following are true:
|
|
* An OID is given in the *Certificate Policies* X.509 extension field,
|
|
* The root certificate in one of the valid chains that end with this certificate is also in Mozilla's list of EV CAs (which can be found at https://mxr.mozilla.org/mozilla-central/source/security/certverifier/ExtendedValidation.cpp), and
|
|
* The OID associated with that root certificate and the OID given by the certificate in question are identical.
|