SSL, SSL certificates, and PKI seem to be a mystery to a lot of people — even experienced engineers. One of the reasons is the huge complexity, but also you normally do not need to work with SSL and SSL certificates every day.
In this multipart article, we will discuss about SSL certificates in detail to remove any doubts on this topic. We will learn how to use the Let’s Encrypt ACME version 2 API using Python to develop software that can create, install, renew and revoke SSL certificates for Alibaba Cloud. Although we have used Alibaba Cloud products for the tutorial, the same principles apply to any computing service that supports X.509 SSL certificates.
Is This Article Series for Me?
Let’s Encrypt is a popular topic; a lot of information about it are already available online. However, this article can be useful if you want to know more about these topics:
- Learn how to use and benefit from Let’s Encrypt, and how to use the ACME v2 API.
- Creating an automated client for Alibaba Cloud API Gateway and Alibaba Cloud CDN to request, validate, issue, and install an SSL certificate without multiple manual methods.
- Developing an inexpensive solution for protecting numerous cloud services as purchasing SSL certificates for each service can quickly get expensive.
- Quick setup of SSL for services; unlike the process of getting conventional commercial certificates, which is time consuming.
As cloud services begin to be accepted universally, popular services such as API Gateway and CDN are difficult to request, issue and install SSL certificates. This article hopefully demonstrates how to do this simply and correctly. The focus is not on website SSL certificates, rather hard to configure cloud services, REST endpoints, etc.
These articles focus on SSL certificates for services that do not have existing Let’s Encrypt client support through certbot or a third-party product. For example, certbot has excellent support for automating Apache web server SSL certificate creation and renewal. However, there is little or poor support for Windows IIS Server. In the last part we will demonstrate creating an SSL certificate for IIS, bundling into the PKCS#12 format and importing into IIS.
What Is an SSL Certificate?
An SSL Certificate binds together:
- A domain name, server name or hostname.
- An organizational identity, such as company name and location.
The depth of details bound to an SSL certificate vary based upon the type of validation performed by the Certificate Authority (CA) before issuing the SSL certificate.
An SSL Certificate is a set of one or more small data files that digitally bind a cryptographic key to an organization’s details. When installed on a web server, it activates the padlock, the https protocol and allows secure connections from a web server to a browser. When installed on a service, such as API Gateway, it secures communications between systems.
What Is Let’s Encrypt?
According to Wikipedia, Let’s Encrypt is a certificate authority that provides free X.509 certificates for Transport Layer Security (TLS) encryption via an automated process designed to eliminate the hitherto complex process of manual creation, validation, signing, installation, and renewal of certificates for secure websites. It launched on April 12, 2016.
In other words, Let’s Encrypt provides free SSL certificates for your websites and numerous cloud services such as API Gateway, CDN, ECS, etc.
What Is a Certificate Authority (CA)?
Certificate authorities (CAs) are entities that cryptographically sign SSL certificates to vouch for their authenticity. Browsers and operating systems have a list of trusted CAs that they use to verify site certificates.
Until recently, most CAs were commercial operations that charged money for their verification and signing services. Let’s Encrypt has made this process free for users by completely automating the procedure, and by relying on sponsorship and donations to fund the necessary infrastructure.
Let’s Encrypt is a CA that issues Domain Validated SSL certificates. The Let’s Encrypt server use the ACME protocol to communicate with ACME clients to request, issue, renew and revoke SSL certificates.
Types of SSL Certificates
There are many types of SSL certificates, but the three most common types are Domain Validated (DV), Organization Validated (OV), and Extended Validated (EV).
- Domain Validated (CABF OID 22.214.171.124.2.1) — The most common type and verified using only the domain name.
- Organization Validated (CABF OID 126.96.36.199.2.2) — Requires more validation compared with DV because the organization’s name is attached to the certificate.
- Extended Validated (CABF OID 188.8.131.52.1) — Requires the most effort by the CA to validate, providing the maximum amount of trust to visitors (shows up as a green bar on your web browser).
- Miscellaneous types such as Self Signed, Individual Validated, Test, Code Signing, etc.
SSL certificates can also be single domain, multiple domain, and wildcard for each type. This is really just a marketing feature as all SSL certificates support one or more domain names including wildcard domain names.
Please note that Let’s Encrypt only issues DV SSL certificates. If you require OV or EV SSL certificates, you will need to go to a commercial CA such as Alibaba Cloud SSL Certificates Service. There is no difference between the certificates except for the amount and type of information stored in the certificate. It is the time and processes that the CA completes to validate not only the domain name but the organization that controls the domain name. For services that provide financial transactions, strongly consider EV SSL certificates. For services such as a CDN or API Gateway, DV certificates are perfect.
To a web server or cloud service, the type (DV, OV, EV) of SSL certificate makes absolutely no difference. The client (web browser or an actual person) may care. If I am connecting to my bank and they only have a DV SSL certificate, I am going to question why. The key is to evaluate the value of what you are protecting and the cost if protection fails. A DV SSL certificate for a website contact form is just fine. To process my credit card will require an EV certificate. I want whoever is transferring money to be fully validated at the extended validation level and not just domain validated.
What Is ACME?
ACME stands for: Automatic Certificate Management Environment. ACME is a communications protocol for a client to interface with a CA (Certificate Authority) for the management of SSL certificates (issue, renew, and revoke).
The ACME protocol is based upon passing JSON formatted messages over HTTPS. The requests are signed by a private key and authenticated with the corresponding public key. This key pair is called the Account Key. Note that this key pair is not the same key pair used to create the CSR (Certificate Signing Request).
The Account Key is used to provide the identity of the account that is requesting certificate services. There is no login / password or similar method used. Therefore, it is very important to save your Account Key key pair in a safe location as the Account Key is used to issue, renew and revoke SSL certificates. If you lose the Account Key the certificates that were created under that account will be in limbo. You will not be able to renew or revoke those certificates. In this case you will need to create a new Account Key and issue new SSL certificates to replace the once that you lost control of. If a malicious third party obtained access to your Account Key, they could change the contact email address and revoke your certificates. They would not be able to issue new SSL certificates for your domains as this would require either HTTP or DNS validation of the domain names.
The Certificate Key is a key pair used to sign CSRs (Certificate Signing Request). This is not the Account Key even though both are key pairs. For security reasons you do not want to use the Account Key to sign CSRs. Common practice is to create a new Certificate Key for each SSL Certificate.
CSR — Certificate Signing Request
A CSR is a file (message) sent to a CA (Certificate Authority — Let’s Encrypt) to apply for an SSL certificate. The CSR contains details about who is applying for the SSL certificate such as company name, location, domain name, etc. Since Let’s Encrypt only issues DV (Domain Validated) SSL certificates, only the domain names are validated and only the domain names are included in the generated SSL certificate plus an optional email address for contact information. Details such as company name, location, etc. are not included.
ACME API Python Examples
This article series will show how to use each ACME API with small, easy to understand Python programs. We will also show you how to use the Alibaba Cloud APIs for automating DNS record changes and installing an SSL certificate into the Alibaba Cloud services (API Gateway and CDN) so that you have a custom domain name for each service protected with SSL.
Requirements: Python 3.6 or newer (Python 2 is not supported)
Platforms: Tested on Windows 10
Python Libraries: (versions tested)
- cryptography version 2.2.2 (March 27, 2018)
- pyOpenSSL version 18.0.0 (May 16, 2018)
- requests version 2.19.1 (June 14, 2018)
Programs: (versions tested)
- Python version 3.6.5 for Windows (March 28, 2018)
- https://slproweb.com/products/Win32OpenSSL.html">OpenSSL version 1.1.0h for Windows (March 27, 2018)
Download: ACME Examples in Python (Zip — 20 KB)
Note: Antivirus software will prompt a warning about this download because it is a zip file with Python source code.
How to use the ACME examples:
- Create a working directory on your system.
- Download the package above.
- Unzip the package into your working directory.
- Create your Let’s Encrypt Account Key — python make_account_key.py.
- Display your account information — python get_account-info.py.
- Read the article series and study the example source code.
Once you have created your Account Key, Certificate Key and CSR you have everything you need to request an SSL Certificate through Let’s Encrypt. Before Let’s Encrypt will issue an SSL certificate, it needs to validate your certificate request (called an order in Let’s Encrypt terminology) by validating that you control the domain name via either an HTTP validation file or DNS TXT record. The examples in this article series only support DNS validation as most cloud services, such as API Gateway, do not support HTTP file-based validation.
Now would be a good time to go to setup Python, the required Python packages, and download the ACME example source code.
In Part 2 of the series, we will create the Account Key, Certificate Key, Certificate Signing Request (CSR), and then begin working with each ACME API in Python.