autocsr 1.0.11

AutoCSR is a command-line tool and library for automatically generating Certificate Signing Requests from easy to define configuration files.

AutoCSR: Automatic Certificate Signing Request Generation

AutoCSR is a command-line tool and library for automatically generating Certificate Signing Requests from basic user input and easy to define templates.

AutoCSR was developed to empower non-security professionals to quickly and easily generate their own simple Certificate Signing Requests with minimal security knowledge required.

AutoCSR also provides security professionals with the ability to define complex Certificate Signing Requests with templates that can be easily shared with non-security professionals to generate complex Certificate Signing Requests without the need for detailed instructions or handholding.

Install

pip install autocsr

Usage

Usage: autocsr [OPTIONS] COMMAND [ARGS]...

Commands:
  build   Create certificate signing requests from a config file.
  create  Create a new Certificate Signing Request with little customization.
  prompt  Prompt the user for Certificate Signing Request fields.

Quickstart

Create a simple CSR with a Common Name

The easiest way to generate a Certificate Signing Request is by specifying the common name and letting autocsr create handle the rest! This is perfect for simple Certificate Signing Requests that don't require any custom attributes, extensions, or specific key formats.

max@wolfetop:/app# autocsr create "My Common Name"
Where to store the new key? [./My Common Name.pem]:
Where to store the new csr? [./My Common Name.csr]:
Created new CSR at ./My Common Name.csr

You can also specify the key-path and output-path to avoid the mandatory prompts.

max@wolfetop:/app# autocsr create "My Common Name" --key-path my_common_name.pem --output-path my_common_name.csr
Created new CSR at my_common_name.csr

Create a simple CSR with a Prompt

If you need to generate a Certificate Signing Request without custom attributes or extensions, but still want to customize the subject and signing information, autocsr prompt can guide you through the process while offering you safe defaults and a list of options where applicable.

max@wolfetop:/app# autocsr prompt "My Prompted CSR"
Where to store the new key? [./My Prompted CSR.pem]:
Where to store the new csr? [./My Prompted CSR.csr]:
What is your country identifier? (2 characters) []:
What is your state or province name? []:
What is your locality name? []:
What is your organization name? []:
What is your organizational unit name? []:
What is your email address? []:
What is the desired hash algorithm to use? (SHA256, SHA224, SHA384, SHA512, SHA512_224, SHA512_256, BLAKE2b, BLAKE2s, SHA3_224, SHA3_256, SHA3_384, SHA3_512, SHAKE128, SHAKE256) [SHA256]:
What is the desired type of key? (RSA, DSA, EC) [RSA]:
What is the desired key size? (1024, 2048, 4096) [2048]:
Created new CSR at ./My Prompted CSR.csr

Create a CSR with a Template

For more customized Certificate Signing Requests and those that need to be repeatedly generated in a consistent way, it will often be desirable to add the details of your Certificate Signing Request inside a template. autocsr build can be used to construct one or many Certificate Signing Requests from the details present in a template.

Create a Template

# quick_csr.yaml
My First CSR:
  subject:
    common_name: My first AutoCSR
  key_info:
    key_path: /tmp/my_first_key.key
    create: True
  output_path: /tmp/my_first_autocsr.csr

Run AutoCSR

max@wolfetop:/app# autocsr build quick_csr.yaml
Created new CSR at /tmp/my_first_autocsr.csr

Validate New CSR

max@wolfetop:/app# openssl req -text -noout -verify -in /tmp/my_first_autocsr.csr
verify OK
Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = My first AutoCSR
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus:
                    00:93:f6:52:6e:51:64:0a:a6:95:d5:89:71:11:bf:
                    50:c6:cc:54:e7:9a:06:ec:16:0a:3f:dc:8f:ee:57:
                    50:6f:bd:6b:92:89:50:d5:97:5c:74:ca:86:08:41:
                    52:af:13:5a:a9:8c:3d:79:64:14:77:fe:ef:52:d6:
                    57:6c:59:01:f4:02:03:a7:b0:c6:24:9c:1d:26:72:
                    15:f8:8b:58:25:85:83:b4:b4:26:7b:4f:db:59:93:
                    09:07:02:d3:8f:92:1d:d1:c6:94:9c:6a:06:77:de:
                    f5:5e:b8:4a:30:86:c5:6e:81:35:f4:cb:88:e7:79:
                    a3:91:22:c9:03:92:9c:8a:3a:3c:49:58:fe:18:e2:
                    e2:18:c3:6d:e0:a2:7d:21:62:80:dd:54:fb:4b:85:
                    ed:08:5f:10:0b:af:2e:66:bc:57:53:a3:d9:06:23:
                    ce:97:63:54:4c:8e:13:0f:01:1a:3e:9d:80:53:91:
                    71:f8:3f:93:03:41:d7:64:2b:5e:b6:d1:b8:17:bd:
                    10:6f:56:b5:d2:ec:3d:1a:91:0e:7a:2e:f2:ff:d4:
                    03:33:8b:91:48:6b:e3:e6:ea:f2:49:48:49:81:5a:
                    c7:b9:5a:ef:85:ce:71:61:28:7e:28:8c:07:23:48:
                    e3:c3:7e:74:46:bc:88:fa:84:9b:d3:16:98:9b:58:
                    29:9d
                Exponent: 65537 (0x10001)
        Attributes:
        Requested Extensions:
    Signature Algorithm: sha256WithRSAEncryption
         07:6c:ac:32:92:04:f2:57:42:8f:93:92:09:92:77:01:c6:5e:
         e4:7f:17:f6:78:fd:8a:83:8a:d7:55:3f:f1:c4:ba:09:1c:9e:
         2a:04:db:e3:2f:b9:c1:d0:49:53:59:47:6f:d0:3e:ae:c3:4d:
         96:f2:f0:f8:b2:9f:67:62:fc:4b:32:35:c7:f3:cc:78:83:d0:
         82:0a:b6:f0:90:83:12:10:73:49:36:ac:f2:27:85:91:b1:9d:
         0d:22:d7:2f:34:84:0a:2f:c1:d3:ee:62:82:72:78:64:93:17:
         83:7c:68:65:89:e5:ad:cc:e3:f0:c8:03:1e:18:c0:11:89:af:
         9f:5d:7a:23:a0:c9:c7:97:44:fd:18:40:6e:aa:02:cf:bb:8a:
         17:6c:24:64:3b:a5:9b:0c:c8:52:e1:8f:8f:83:ec:8b:14:5c:
         a7:38:83:f8:67:6b:2d:3e:1a:02:39:2a:57:27:3a:c0:62:b7:
         bc:90:6c:b6:f5:2c:32:f5:87:dc:b0:0c:b2:93:d3:2d:8d:cb:
         0b:a1:e6:70:aa:b9:67:bf:9b:89:ae:25:12:08:08:83:ee:7e:
         58:33:e6:53:37:fb:28:7c:79:98:39:bf:b4:8b:b9:e3:b5:75:
         8d:bd:b6:ce:e1:11:69:81:ab:37:d9:f0:3c:6e:35:b1:23:d8:
         6a:10:be:2e

Creating Templates

A template is an overall definition of the data you want to be include in your Certificate Signing Request. Most fields can be optionally excluded or have safe default values for those who don't want to worry too much about the details.

Subject

The subject of the Certificate Signing Request contains various metadata about the certificate, the only required portion being the common_name.

# subject_example.yaml
A Subject CSR:
  subject:
    common_name: All about the subject
    country_name: US
    state_or_province_name: California
    locality_name: Bay Area
    organization_name: SecurityWolfe
    organizational_unit_name: The Cool Team
    email_address: [e-mail]
  key_info:
    key_path: /tmp/subject_example.key
    create: True
  output_path: /tmp/subject_example.csr

Explicit Subject Example

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = All about the subject, C = US, ST = California, L = Bay Area, O = SecurityWolfe, OU = The Cool Team, emailAddress = [e-mail]

Key and Signing Information

AutoCSR allows keys to be generated on the fly or loaded directly from files. You can also explicitly define the hash algorithm to use for signing.

# key_example.yaml
RSA With Explicit Key Parameters:
  subject:
    common_name: RSA CSR with explicit key parameters
  key_info:
    key_path: /tmp/my_rsa.key
    create: True
    key_type: RSA
    key_size: 2048
    public_exponent: 65537
  hash_type: SHA256
  output_path: /tmp/my_rsa_autocsr.csr

DSA From Key File:
  subject:
    common_name: DSA CSR from key file
  key_info:
    key_path: /tmp/my_dsa.key
  output_path: /tmp/my_dsa_autocsr.csr

EC With Explicit Key Parameters:
  subject:
    common_name: EC CSR with explicit key parameters
  key_info:
    key_path: /tmp/my_ec.key
    create: True
    key_type: EC
    curve: SECP256R1
  hash_type: SHA512
  output_path: /tmp/my_ec_autocsr.csr

Running autocsr build on this template will generate three Certificate Signing Requests:

RSA Example CSR

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = RSA CSR with explicit key parameters
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus: ...
                Exponent: 65537 (0x10001)
        Attributes:
        Requested Extensions:
    Signature Algorithm: sha256WithRSAEncryption

DSA Example CSR

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = DSA CSR from key file
        Subject Public Key Info:
            Public Key Algorithm: dsaEncryption
                pub: ...
                P: ...
                Q: ...
                G: ...
        Attributes:
        Requested Extensions:
    Signature Algorithm: dsa_with_SHA256

EC Example CSR

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = EC CSR with explicit key parameters
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub: ...
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        Attributes:
        Requested Extensions:
    Signature Algorithm: ecdsa-with-SHA512

Attributes

Certificates can optionally contain a plethora of pre-defined and custom attributes which map an oid to a binary value. Because we primarily use YAML for our template, we require that attribute values are base64 encoded in the template when defining attributes. Optionally for predefined attributes, a string name can be used instead of the dotted-string oid.

# attribute_example.yaml
CSR with Attributes:
  subject:
    common_name: My CSR with custom and well-known attributes
  key_info:
    key_path: /tmp/my_attributes.key
    create: True
  output_path: /tmp/my_attributes_autocsr.csr
  attributes:
    - oid: issuerAltName
      b64_value: TXkgSXNzdWVyIEFsdCBOYW1l
    - oid: 1.2.345.678  # A custom OID
      b64_value: TXkgQ3VzdG9tIEF0dHJpYnV0ZQ==

Custom and Predefined Attributes Example

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = My CSR with custom and well-known attributes
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus: ...
                Exponent: 65537 (0x10001)
        Attributes:
            X509v3 Issuer Alternative Name:My Issuer Alt Name
            1.2.345.678              :My Custom Attribute

Extensions

Certificate Signing Requests offer a plethora of predefined extensions. An exhaustive list of the available extensions are available here, but I will provide a few examples of modeling extensions in templates below. Keep in mind that like attributes, extensions that require bytes as input will need to have their data represented in base64.

# extension_example.yaml
My CSR with Extensions:
  subject:
    common_name: Some Common Extensions for CSRs
  key_info:
    key_path: /tmp/my_extension_example.key
    create: True
  output_path: /tmp/my_extension_autocsr.csr
  extensions:
    - critical: True
      extension_type: OCSPNoCheck
    - critical: True
      subject_key_identifier:
        b64_digest: TXkgRXhhbXBsZSBTdWJqZWN0IEtleSBJZGVudGlmaWVy
    - critical: False
      extended_key_usage:
        usages:
          - "serverAuth"
          - "1.2.3.4.5"
    - critical: True
      key_usage:
        digital_signature: True
        content_commitment: False
        key_encipherment: True
        data_encipherment: False
        key_agreement: True
        key_cert_sign: False
        crl_sign: True
        encipher_only: False
        decipher_only: True

Various Extensions Example

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = Some Common Extensions for CSRs
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus: ...
                Exponent: 65537 (0x10001)
        Attributes:
        Requested Extensions:
            OCSP No Check: critical

            X509v3 Subject Key Identifier: critical
                4D:79:20:45:78:61:6D:70:6C:65:20:53:75:62:6A:65:63:74:20:4B:65:79:20:49:64:65:6E:74:69:66:69:65:72
            X509v3 Extended Key Usage:
                TLS Web Server Authentication, 1.2.3.4.5
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment, Key Agreement, CRL Sign, Decipher Only

Jinja Templates

Alternatively to using .yaml files, you can use .jinja2 files modeled after YAML, but including environment variables to be replaced. If you wanted to recreate the first example using environment variables, you can do so like this:

# quick_csr.jinja2
{{ NAME }}'s First CSR:
  subject:
    common_name: {{ NAME }}'s first AutoCSR
  key_info:
    key_path: /tmp/{{ NAME }}s_first_key.key
    create: True
  output_path: /tmp/{{ NAME }}s_first_autocsr.csr

Run AutoCSR on a Jinja Template

max@wolfetop:/app# NAME=Max autocsr quick_csr.jinja2
Created new CSR at /tmp/Maxs_first_autocsr.csr

Validate Jinja Templated CSR

max@wolfetop:/app# openssl req -text -noout -verify -in /tmp/Maxs_first_autocsr.csr
verify OK
Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = Max's first AutoCSR
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)