From 32483de4f2ad9c4b7cfa9f703f3bc44ce7ec47f9 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Tue, 5 Jul 2022 14:59:21 -0700 Subject: [PATCH] doc update --- docs/parsers/x509_cert.md | 181 ++++++++++++++++++++++++++++++++++-- jc/parsers/x509_cert.py | 189 ++++++++++++++++++++++++++++++++++---- 2 files changed, 345 insertions(+), 25 deletions(-) diff --git a/docs/parsers/x509_cert.md b/docs/parsers/x509_cert.md index bb8d1ffa..f0c24bd2 100644 --- a/docs/parsers/x509_cert.md +++ b/docs/parsers/x509_cert.md @@ -5,7 +5,7 @@ jc - JSON Convert X.509 Certificate format file parser -This parser will convert DER and PEM encoded X.509 certificates. +This parser will convert DER and PEM encoded X.509 certificate files. Usage (cli): @@ -20,19 +20,182 @@ Schema: [ { - "x509_cert": string, - "bar": boolean, - "baz": integer + "tbs_certificate": { + "version": string, + "serial_number": string, # [0] + "signature": { + "algorithm": string, + "parameters": string/null, + }, + "issuer": { + "country_name": string, + "state_or_province_name" string, + "locality_name": string, + "organization_name": array/string, + "organizational_unit_name": array/string, + "common_name": string, + "email_address": string + }, + "validity": { + "not_before": integer, # [1] + "not_after": integer, # [1] + "not_before_iso": string, + "not_after_iso": string + }, + "subject": { + "country_name": string, + "state_or_province_name": string, + "locality_name": string, + "organization_name": array/string, + "organizational_unit_name": array/string, + "common_name": string, + "email_address": string + }, + "subject_public_key_info": { + "algorithm": { + "algorithm": string, + "parameters": string/null, + }, + "public_key": { + "modulus": string, # [0] + "public_exponent": integer + } + }, + "issuer_unique_id": string/null, + "subject_unique_id": string/null, + "extensions": [ + { + "extn_id": string, + "critical": boolean, + "extn_value": array/object/string/integer # [2] + } + ] + }, + "signature_algorithm": { + "algorithm": string, + "parameters": string/null + }, + "signature_value": string # [0] } ] + [0] in colon-delimited hex notation + [1] time-zone-aware (UTC) epoch timestamp + [2] See below for well-known Extension schemas: + + Basic Constraints: + { + "extn_id": "basic_constraints", + "critical": boolean, + "extn_value": { + "ca": boolean, + "path_len_constraint": string/null + } + } + + Key Usage: + { + "extn_id": "key_usage", + "critical": boolean, + "extn_value": [ + string + ] + } + + Key Identifier: + { + "extn_id": "key_identifier", + "critical": boolean, + "extn_value": string # [0] + } + + Authority Key Identifier: + { + "extn_id": "authority_key_identifier", + "critical": boolean, + "extn_value": { + "key_identifier": string, # [0] + "authority_cert_issuer": string/null, + "authority_cert_serial_number": string/null + } + } + Examples: - $ cat certificate.pem | jc --x509-cert -p - [] - - $ cat certificate.der | jc --x509-cert -p -r - [] + $ cat entrust-ec1.pem| jc --x509-cert -p + [ + { + "tbs_certificate": { + "version": "v3", + "serial_number": "a6:8b:79:29:00:00:00:00:50:d0:91:f9", + "signature": { + "algorithm": "sha384_ecdsa", + "parameters": null + }, + "issuer": { + "country_name": "US", + "organization_name": "Entrust, Inc.", + "organizational_unit_name": [ + "See www.entrust.net/legal-terms", + "(c) 2012 Entrust, Inc. - for authorized use only" + ], + "common_name": "Entrust Root Certification Authority - EC1" + }, + "validity": { + "not_before": 1355844336, + "not_after": 2144764536, + "not_before_iso": "2012-12-18T15:25:36+00:00", + "not_after_iso": "2037-12-18T15:55:36+00:00" + }, + "subject": { + "country_name": "US", + "organization_name": "Entrust, Inc.", + "organizational_unit_name": [ + "See www.entrust.net/legal-terms", + "(c) 2012 Entrust, Inc. - for authorized use only" + ], + "common_name": "Entrust Root Certification Authority - EC1" + }, + "subject_public_key_info": { + "algorithm": { + "algorithm": "ec", + "parameters": "secp384r1" + }, + "public_key": "04:84:13:c9:d0:ba:6d:41:7b:e2:6c:d0:eb:55:..." + }, + "issuer_unique_id": null, + "subject_unique_id": null, + "extensions": [ + { + "extn_id": "key_usage", + "critical": true, + "extn_value": [ + "crl_sign", + "key_cert_sign" + ] + }, + { + "extn_id": "basic_constraints", + "critical": true, + "extn_value": { + "ca": true, + "path_len_constraint": null + } + }, + { + "extn_id": "key_identifier", + "critical": false, + "extn_value": "b7:63:e7:1a:dd:8d:e9:08:a6:55:83:a4:e0:6a:..." + } + ] + }, + "signature_algorithm": { + "algorithm": "sha384_ecdsa", + "parameters": null + }, + "signature_value": "30:64:02:30:61:79:d8:e5:42:47:df:1c:ae:53:..." + } + ] diff --git a/jc/parsers/x509_cert.py b/jc/parsers/x509_cert.py index 91b7d08c..691bb837 100644 --- a/jc/parsers/x509_cert.py +++ b/jc/parsers/x509_cert.py @@ -1,6 +1,6 @@ """jc - JSON Convert X.509 Certificate format file parser -This parser will convert DER and PEM encoded X.509 certificates. +This parser will convert DER and PEM encoded X.509 certificate files. Usage (cli): @@ -15,19 +15,182 @@ Schema: [ { - "x509_cert": string, - "bar": boolean, - "baz": integer + "tbs_certificate": { + "version": string, + "serial_number": string, # [0] + "signature": { + "algorithm": string, + "parameters": string/null, + }, + "issuer": { + "country_name": string, + "state_or_province_name" string, + "locality_name": string, + "organization_name": array/string, + "organizational_unit_name": array/string, + "common_name": string, + "email_address": string + }, + "validity": { + "not_before": integer, # [1] + "not_after": integer, # [1] + "not_before_iso": string, + "not_after_iso": string + }, + "subject": { + "country_name": string, + "state_or_province_name": string, + "locality_name": string, + "organization_name": array/string, + "organizational_unit_name": array/string, + "common_name": string, + "email_address": string + }, + "subject_public_key_info": { + "algorithm": { + "algorithm": string, + "parameters": string/null, + }, + "public_key": { + "modulus": string, # [0] + "public_exponent": integer + } + }, + "issuer_unique_id": string/null, + "subject_unique_id": string/null, + "extensions": [ + { + "extn_id": string, + "critical": boolean, + "extn_value": array/object/string/integer # [2] + } + ] + }, + "signature_algorithm": { + "algorithm": string, + "parameters": string/null + }, + "signature_value": string # [0] } ] + [0] in colon-delimited hex notation + [1] time-zone-aware (UTC) epoch timestamp + [2] See below for well-known Extension schemas: + + Basic Constraints: + { + "extn_id": "basic_constraints", + "critical": boolean, + "extn_value": { + "ca": boolean, + "path_len_constraint": string/null + } + } + + Key Usage: + { + "extn_id": "key_usage", + "critical": boolean, + "extn_value": [ + string + ] + } + + Key Identifier: + { + "extn_id": "key_identifier", + "critical": boolean, + "extn_value": string # [0] + } + + Authority Key Identifier: + { + "extn_id": "authority_key_identifier", + "critical": boolean, + "extn_value": { + "key_identifier": string, # [0] + "authority_cert_issuer": string/null, + "authority_cert_serial_number": string/null + } + } + Examples: - $ cat certificate.pem | jc --x509-cert -p - [] - - $ cat certificate.der | jc --x509-cert -p -r - [] + $ cat entrust-ec1.pem| jc --x509-cert -p + [ + { + "tbs_certificate": { + "version": "v3", + "serial_number": "a6:8b:79:29:00:00:00:00:50:d0:91:f9", + "signature": { + "algorithm": "sha384_ecdsa", + "parameters": null + }, + "issuer": { + "country_name": "US", + "organization_name": "Entrust, Inc.", + "organizational_unit_name": [ + "See www.entrust.net/legal-terms", + "(c) 2012 Entrust, Inc. - for authorized use only" + ], + "common_name": "Entrust Root Certification Authority - EC1" + }, + "validity": { + "not_before": 1355844336, + "not_after": 2144764536, + "not_before_iso": "2012-12-18T15:25:36+00:00", + "not_after_iso": "2037-12-18T15:55:36+00:00" + }, + "subject": { + "country_name": "US", + "organization_name": "Entrust, Inc.", + "organizational_unit_name": [ + "See www.entrust.net/legal-terms", + "(c) 2012 Entrust, Inc. - for authorized use only" + ], + "common_name": "Entrust Root Certification Authority - EC1" + }, + "subject_public_key_info": { + "algorithm": { + "algorithm": "ec", + "parameters": "secp384r1" + }, + "public_key": "04:84:13:c9:d0:ba:6d:41:7b:e2:6c:d0:eb:55:..." + }, + "issuer_unique_id": null, + "subject_unique_id": null, + "extensions": [ + { + "extn_id": "key_usage", + "critical": true, + "extn_value": [ + "crl_sign", + "key_cert_sign" + ] + }, + { + "extn_id": "basic_constraints", + "critical": true, + "extn_value": { + "ca": true, + "path_len_constraint": null + } + }, + { + "extn_id": "key_identifier", + "critical": false, + "extn_value": "b7:63:e7:1a:dd:8d:e9:08:a6:55:83:a4:e0:6a:..." + } + ] + }, + "signature_algorithm": { + "algorithm": "sha384_ecdsa", + "parameters": null + }, + "signature_value": "30:64:02:30:61:79:d8:e5:42:47:df:1c:ae:53:..." + } + ] """ import binascii from collections import OrderedDict @@ -62,12 +225,6 @@ def _process(proc_data: List[Dict]) -> List[Dict]: List of Dictionaries. Structured to conform to the schema. """ - - # process the data here - # rebuild output for added semantic information - # use helper functions in jc.utils for int, float, bool - # conversions and timestamps - return proc_data @@ -164,7 +321,7 @@ def parse( raw_output: List = [] if jc.utils.has_data(data): - # convert to bytes, if not already for PEM detection since that's + # convert to bytes, if not already, for PEM detection since that's # what pem.detect() needs. (cli.py will auto-convert to UTF-8 if it can) try: der_bytes = bytes(data, 'utf-8') # type: ignore