How to use autossl module

Blueprinting

All SSL certificates are blueprinted with a yaml file defining:

  • name of the certificate (used to identify easily the certificate)
  • information of server (or list of servers) where certificate must be deployed.
  • certificate details: type (DV, OV, ..), common name, san, renewal delay, …
  • storage: where artifacts generated will be stored
  • tracking: what tracking mechanism will be used to track the operations performed (certificate renewal, deployment, …)

Note that configuration linked to storage, tracking can be put either in a dedicated blueprint in order to reuse same global config for several certificates or in each certificate blueprint.

  • Certificate blueprint
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
 ---
 name: tst.example.autossl.com

 servers:
   - type: autossl.server.local.LocalServer
     parameters:
       path: /etc/ssl/my_certificates
   - type: autossl.server.local.LocalServer
     parameters:
       path: /etc/ssl_path2/my_certificates

 certificate:
   type: DV
   certificate_authority: LetsEncrypt
   common_name: tst.example.autossl.com
   san:
     - tst1.example.autossl.com
     - tst2.example.autossl.com
     - tst3.example.autossl.com
  • Global configuration blueprint
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
---

certificate_authorities:
  - name: Sectigo
    key: Sectigo
    certificate_types: ['OV', 'DV']
    chain_of_trust:
      # intermediate certificate
      - |
        -----BEGIN CERTIFICATE-----
        MIIGGTCCBAGgAwIBAgIQE31TnKp8MamkM3AZaIR6jTANBgkqhkiG9w0BAQwFADCBiDELMAkGA1UE
        BhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0plcnNleSBDaXR5MR4wHAYDVQQK
        ExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNVBAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNh
        dGlvbiBBdXRob3JpdHkwHhcNMTgxMTAyMDAwMDAwWhcNMzAxMjMxMjM1OTU5WjCBlTELMAkGA1UE
        BhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEYMBYG
        A1UEChMPU2VjdGlnbyBMaW1pdGVkMT0wOwYDVQQDEzRTZWN0aWdvIFJTQSBPcmdhbml6YXRpb24g
        VmFsaWRhdGlvbiBTZWN1cmUgU2VydmVyIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
        AQEAnJMCRkVKUkiS/FeN+S3qU76zLNXYqKXsW2kDwB0Q9lkz3v4HSKjojHpnSvH1jcM3ZtAykffE
        nQRgxLVK4oOLp64m1F06XvjRFnG7ir1xon3IzqJgJLBSoDpFUd54k2xiYPHkVpy3O/c8Vdjf1Xox
        fDV/ElFw4Sy+BKzL+k/hfGVqwECn2XylY4QZ4ffK76q06Fha2ZnjJt+OErK43DOyNtoUHZZYQkBu
        CyKFHFEirsTIBkVtkuZntxkj5Ng2a4XQf8dS48+wdQHgibSov4o2TqPgbOuEQc6lL0giE5dQYkUe
        CaXMn2xXcEAG2yDoG9bzk4unMp63RBUJ16/9fAEc2wIDAQABo4IBbjCCAWowHwYDVR0jBBgwFoAU
        U3m/WqorSs9UgOHYm8Cd8rIDZsswHQYDVR0OBBYEFBfZ1iUnZ/kxwklD2TA2RIxsqU/rMA4GA1Ud
        DwEB/wQEAwIBhjASBgNVHRMBAf8ECDAGAQH/AgEAMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEF
        BQcDAjAbBgNVHSAEFDASMAYGBFUdIAAwCAYGZ4EMAQICMFAGA1UdHwRJMEcwRaBDoEGGP2h0dHA6
        Ly9jcmwudXNlcnRydXN0LmNvbS9VU0VSVHJ1c3RSU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNy
        bDB2BggrBgEFBQcBAQRqMGgwPwYIKwYBBQUHMAKGM2h0dHA6Ly9jcnQudXNlcnRydXN0LmNvbS9V
        U0VSVHJ1c3RSU0FBZGRUcnVzdENBLmNydDAlBggrBgEFBQcwAYYZaHR0cDovL29jc3AudXNlcnRy
        dXN0LmNvbTANBgkqhkiG9w0BAQwFAAOCAgEAThNAlsnD5m5bwOO69Bfhrgkfyb/LDCUW8nNTs3Ya
        t6tIBtbNAHwgRUNFbBZaGxNh10m6pAKkrOjOzi3JKnSj3N6uq9BoNviRrzwB93fVC8+Xq+uH5xWo
        +jBaYXEgscBDxLmPbYox6xU2JPti1Qucj+lmveZhUZeTth2HvbC1bP6mESkGYTQxMD0gJ3NR0N6F
        g9N3OSBGltqnxloWJ4Wyz04PToxcvr44APhL+XJ71PJ616IphdAEutNCLFGIUi7RPSRnR+xVzBv0
        yjTqJsHe3cQhifa6ezIejpZehEU4z4CqN2mLYBd0FUiRnG3wTqN3yhscSPr5z0noX0+FCuKPkBur
        cEya67emP7SsXaRfz+bYipaQ908mgWB2XQ8kd5GzKjGfFlqyXYwcKapInI5v03hAcNt37N3j0VcF
        cC3mSZiIBYRiBXBWdoY5TtMibx3+bfEOs2LEPMvAhblhHrrhFYBZlAyuBbuMf1a+HNJav5fyakyw
        xnB2sJCNwQs2uRHY1ihc6k/+JLcYCpsM0MF8XPtpvcyiTcaQvKZN8rG61ppnW5YCUtCC+cQKXA0o
        4D/I+pWVidWkvklsQLI+qGu41SWyxP7x09fn1txDAXYw+zuLXfdKiXyaNb78yvBXAfCNP6CHMntH
        WpdLgtJmwsQt6j8k9Kf5qLnjatkYYaA7jBU=
        -----END CERTIFICATE-----

  - name: Let's Encrypt
    key: LetsEncrypt
    type: autossl.ca_manager.acme_v2_http01.AcmeHttp01
    certificate_types: ['DV']
    acme_api:
      production: https://acme-v02.api.letsencrypt.org
      staging: https://acme-staging-v02.api.letsencrypt.org
    # specify where acme account key is located
    storage:
      type: autossl.storage.local.LocalFileStorage
      name: lets_encrypt_account_key
      parameters:
        path: /etc/ca_account_keys/
    chain_of_trust:
      # intermediate certificate
      - |
        -----BEGIN CERTIFICATE-----
        MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/MSQwIgYDVQQK
        ExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMTDkRTVCBSb290IENBIFgzMB4X
        DTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0NlowSjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxl
        dCdzIEVuY3J5cHQxIzAhBgNVBAMTGkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkq
        hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnNMM8FrlLke3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4
        S0EFq6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8SMx+yk13
        EiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0Z8h/pZq4UmEUEz9l6YKH
        y9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWAa6xK8xuQSXgvopZPKiAlKQTGdMDQMc2P
        MTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj/PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIDAQAB
        o4IBfTCCAXkwEgYDVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEE
        czBxMDIGCCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNvbTA7
        BggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9kc3Ryb290Y2F4My5w
        N2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAwVAYDVR0gBE0wSzAIBgZngQwBAgEw
        PwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcCARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNy
        eXB0Lm9yZzA8BgNVHR8ENTAzMDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9P
        VENBWDNDUkwuY3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF
        AAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJouM2VcGfl96S8
        TihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/wApIvJSwtmVi4MFU5aMqrSDE
        6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwuX4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPM
        TZ+sOPAveyxindmjkW8lGy+QsRlGPfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M
        +X+Q7UNKEkROb3N6KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==
        -----END CERTIFICATE-----
      # root certificate
      - |
        -----BEGIN CERTIFICATE-----
        MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/MSQwIgYDVQQK
        ExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMTDkRTVCBSb290IENBIFgzMB4X
        DTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVowPzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1
        cmUgVHJ1c3QgQ28uMRcwFQYDVQQDEw5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQAD
        ggEPADCCAQoCggEBAN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmT
        rE4Orz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEqOLl5CjH9
        UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9bxiqKqy69cK3FCxolkHRy
        xXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40d
        utolucbY38EVAjqr2m7xPi71XAicPNaDaeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0T
        AQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQ
        MA0GCSqGSIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69ikug
        dB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXrAvHRAosZy5Q6XkjE
        GB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZzR8srzJmwN0jP41ZL9c8PDHIyh8bw
        RLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubS
        fZGL+T0yjWW06XyxV3bqxbYoOb8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ
        -----END CERTIFICATE-----


organization:
  company_name: Autossl corporation
  street_address: Newbury street
  city: Boston
  state: Massachusetts
  postal_code: '02115'
  country_code: US

storage:
  type: autossl.storage.gitscm.GitStorage
  credentials: git_credentials
  parameters:
    git_url: https://git.autossl.com/autossl/my_certs.git
  data:
    # type of data to store/retrieve in this storage
    - type: key
    - type: csr
    - type: crt

tracking:
  type: autossl.tracking.local.LocalFileTracking
  parameters:
    log_folder: /var/log/ssl_logs
  data:
    - type: yaml
    - type: csr
    - type: crt

credentials:
  git_credentials:
    type: UserPassword

...

Command line options

All commands accepts the following options

  • –config (optional) is the global blueprint yaml file
  • –blueprint is the certificate blueprint yaml file

Both –config and –blueprint files can also be merged in a single blueprint and in that case use only –blueprint option. If same section (tracking, storage, …) appears in both global config and certificate blueprint, global config is ignored and section from certificate blueprint will be used

Monitoring

The check action allow to monitor certificates deployed on servers and provide status.

$ autossl \
  --config global_config.yaml \
  --blueprint example.autossl.com.yaml check
INFO:autossl:Processing blueprint example.autossl.com.yaml
INFO:autossl.server.base:[LocalServer - AUTOSSL_MACHINE:/etc/ssl_path_1] - example.autossl.com - 2019-05-20T17:37:28 => valid (42 days remaining)
INFO:autossl.ssl:Following domains not covered by certificate: [new.example.autossl.com]
INFO:autossl.manager:Certificate definition changed for 'example.autossl.com' on server '[LocalServer - AUTOSSL_MACHINE:/etc/ssl_path_1]'
INFO:autossl.server.base:[LocalServer - AUTOSSL_MACHINE:/etc/ssl_path_2] - example.autossl.com - 2019-05-20T17:37:28 => valid (42 days remaining)
INFO:autossl.ssl:Following domains not covered by certificate: [new.example.autossl.com]
INFO:autossl.manager:Certificate definition changed for 'example.autossl.com' on server '[LocalServer - AUTOSSL_MACHINE:/etc/ssl_path_2]'

Renewal

Process to renew certificate is the same, whatever the CA used (Sectigo, Let’s Encrypt, …) or the type of certificate requested. Renewal can be requested for 1 or several blueprints.

Depending on the type of certificate requested and the CA, automated certificate renewal may or not be possible.

For each blueprint, the flow starts with the following:

  • compare blueprint with stored certificate: checking for close expiration, change of certificate content
  • compare blueprint with existing certificate on the server(s): same checks than before + track servers with missing certificate
  • generate a csr based on blueprint
  • call tracking api and send it specified files in config (generally blueprint and CSR)
  • then, when supported by specified CA, certificate is generated automatically with CA specified renewal method protocol (see details below) and also sent to tracking api
$ autossl \
  --blueprint --blueprint example.autossl.com.yaml \
  renew --force\
INFO:autossl.ssl_manager:Processing blueprint example.autossl.com.yaml
INFO:autossl.ssl_manager:Force renewal for 'auto_example.autossl.com'
Continue ? (y/n)y
INFO:autossl.ssl_manager:Start renewal process for certificate 'auto_example.autossl.com'
INFO:autossl.ssl_manager:Tracking record created: TR 98765432: SSL certificate for example.autossl.com
INFO:autossl.ssl_manager:Processing blueprint example.autossl.com.yaml
INFO:autossl.manager:Start renewal process for certificate 'example.autossl.com.yaml'
INFO:autossl.acme.acme_manager:Parsing account key...
INFO:autossl.acme.acme_manager:Registering account...
INFO:autossl.acme.acme_manager:Already registered!
INFO:autossl.acme.acme_manager:Starting validation for domain example.autossl.com
INFO:autossl.server.local:Deploy challenge on LocalServer AUTOSSL_MACHINE:/etc/acme_dir
INFO:autossl.acme.acme_manager:example.autossl.com verified!
INFO:autossl.server.local:Cleanup challenge from LocalServer AUTOSSL_MACHINE:/etc/acme_dir
INFO:autossl.acme.acme_manager:Signing certificate...
INFO:autossl.acme.acme_manager:Certificate signed

Deployment

To perform the deployment, several information are required: - certificate - private key - ssl blueprint - tracking record ID (optional)

All those information can be directly given in command line or can be retrieved directly from configured storage and/or tracking record.

  1. from tracking record and blueprint (or global config)

At least global config is needed to identify tracking type and retrieve data from specified tracking record. If only global config specified, full blueprint must be attached to tracking record to know where to deploy this certificate.

$ autossl --config global_config.yaml deploy --tracking-record 12345678
  1. with all information from command line
$ autossl --config global_config.yaml deploy \
   --private-key example.autossl.com.key \
   --certificate example.autossl.com.crt \
   --tracking-record 12345678

These commands will:

  • retrieve all needed artifacts (yaml blueprint, new certificate, …) if not already given in command line
  • ensure certificate is compatible with yaml blueprint, private key, CA certificate chain
  • deploy key+certificate in all servers listed in yaml blueprint
  • update tracking record with status of the deployment and set it as completed
$ autossl --config global_config.yaml deploy \
   --tracking-record 98765432 \
   --private-key /etc/keys/example.autossl.com.key
INFO:autossl.manager:Blueprint: example.autossl.com.yaml
INFO:autossl.manager:Certificate: example.autossl.com.crt
INFO:autossl.manager:PrivateKey: example.autossl.com.key
INFO:autossl.server.base:[LocalServer - slave-ql6n8] - example.autossl.com - 2019-07-10T08:43:29 => valid (90 days remaining)
INFO:autossl.server.local:Certificate/Key example.autossl.com updated successfully on [LocalServer - AUTOSSL_MACHINE:/etc/ssl_path_1].
INFO:autossl.server.local:Certificate/Key example.autossl.com updated successfully on [LocalServer - AUTOSSL_MACHINE:/etc/ssl_path_2].
  • global config is needed here to know how to retrieve tracking record specified
  • –private-key is the path to the certificate private key (can also be retrieved automatically from configured storage or tracking record)
  • –certificate is the path to the new certificate (can also be retrieved automatically from configured storage or tracking record)
  • –tracking-record is the tracking record created in renewal step above

Note that using tracking record is optional, and you can directly give certificate blueprint, private key and SSL certificate in input of deploy.