This repository contains scripts meant to make managing an openssl ca less painful inside a terminal environment
Here, the use cases for issuing Entities also known as certificate authorities are collected.
Building an new CA is done in several steps:
This process is rather lengthy and there are several scripts involved: After the policy is written down, you should have all information for customizing the CA about to be created. Now, you need to use create_ca.sh. This script guides you through all the steps needed for
The script offers an optional way to specify some of the information the user
has to enter during this process beforehand - by writing an ini file named ca_presets.ini.
This file has to reside in the current directory. Its format is key="value". The double quotes can be
omitted if the value does not contain spaces. Allowed keys at this time are:
A template for this file can be generated by calling create_ca.sh with command line
switch -g.
Additionally, the script lets the user specify default values for config file items - especially when creating an issuing CA: Maybe you want to save your end users the hustle having to specify Country and Locality? Then here is your chance: Just define defaults and your end users can just click through those annoying questions! Another thing is the (optional) provision of Certificate Policy Statements: For each config of the CA you can specify them - so they get incorporated into every certificate you create using the corresponding configuration.
And last but not least: The script offers you the (optional) means to define additional OIDs: If you use custom OIDs (for example for specifying custom policies), an application will display them as unintuitive sequences of numbers separated by dots - unless you take the time to define them: then a mapping is included into each issued certificate that allows applications to display a descriptive text instead of the numeric OID.
These additional OIDs can be used for a multitude of possible scenarios. In issuing CAs, issuing end entity certificates the operator of the CA can decide to add more fields to the Distiguished Name (DN) (also see RFC 4519) of the subjects. One could for example add some of the fields defined in X.500 - such as postalAddress, name and givenName among others.
After adding such fields - the operator of the pki can use those additional fields
as he would the common or standard fields already defined. To be more precise:
the operator has to add them to the respective policy in the CA configuration -
else they are not inserted into the new certificate. An example for this would be the
client configuration for creation of Certificate Signing Requests (CSRs) for an
S/Mime certificate as created by the create_ca.sh script:
# S/MIME certificate request
oid_section = additional_oids
[ additional_oids ]
CustomOid2 = 2.2.3
CustomOid1 = 1.2.3
[ req ]
default_bits = 4096 # RSA key size
encrypt_key = yes # Protect private key
default_md = sha256 # MD to use
utf8 = yes # Input is UTF-8
string_mask = utf8only # Emit UTF-8 strings
prompt = yes # Prompt for DN
distinguished_name = smime_dn # DN template
req_extensions = smime_reqext # Desired extensions
[ smime_dn ]
countryName = "1. Country Name (2 letters) (eg, US) "
countryName_max = 2
stateOrProvinceName = "2. State or Province Name (eg, region) "
localityName = "3. Locality Name (eg, city) "
organizationName = "4. Organization Name (eg, company) "
organizationalUnitName = "5. Organizational Unit Name (eg, section) "
commonName = "6. Common Name (eg, full name)"
commonName_max = 64
emailAddress = "7. Email Address (eg, name@fqdn)"
emailAddress_max = 40
#CustomOid1 = "descriptiona"
#CustomOid2 = "descriptionb"
[ smime_reqext ]
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = emailProtection,clientAuth
subjectKeyIdentifier = hash
subjectAltName = email:move
#1.2.3=ASN1:UTF8String:descriptiona
#2.2.3=ASN1:UTF8String:descriptionb
We see here that there are two additional custom OIDs defined (section [ additional_oids ])
To actually use them, one has to decide what they should be used for: They can be used as additional
extensions - in that case, the operator has to remove the comment in the corresponding line in the section
describing the extensions - in this example
[ smime_reqext ].
As a side note, custom extensions can just as well be added to the configuration of the CA - effectively changing the set of extensions contained in issued certificates - further information concerning extensions in issed certificates can be found here.
If the operator wants to use them for extending the DN, the comments from the appropriate line(s) in the DN
section - in this example
[ smime_dn ]
must be removed.
In the second case, the operator must also change the configuration file of the CA itself: The policy sections therein define, what parts constitute the DN of issued certificates. In our example, those sections would look like this (we only show a part of the rather lengthy configuration file here):
[ match_O_pol ]
#CustomOid2 = optional
#CustomOid1 = optional
countryName = supplied
stateOrProvinceName = optional
localityName = optional
organizationName = match
organizationalUnitName = optional
commonName = supplied
[ minimal_pol ]
#CustomOid2 = optional
#CustomOid1 = optional
domainComponent = optional
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
The operator has to remove the comments in the appropriate lines according to the changes in the CSR configurations.
There is one additional scenario where custom OIDs come in handy: Besides extensions and properties as part
of the DN, there is the possibility to add so-called attributes to the client configuration for creation of
Certificate Signing Requests (CSRs). This often is used in Microsofts CAs - for example for specifying
certificate templates. An example for this can be seen here: An additional OID is defined in section
[ additional_oids ]:
oid_section = additional_oids
[ additional_oids ]
certificateTemplateName = 1.3.6.1.4.1.311.20.2
Then, the configuration needs to be altered so that attributes are included in the CSRs and that OpenSSL
knows where to get the actual attributes, we define a section for that in section [ req ]:
attributes = smime_attributes
The section containing the attributes looks like this:
[ smime_attributes ]
certificateTemplateName = "Template name for using a Windows PKI"
certificateTemplateName_default = CustomUserOffline
unstructuredName = "unstructured"
unstructuredName_default = "unstructured"
#in the case of prompt = no
#certificateTemplateName = CustomUserOffline
unstructuredName is an OID that can be used to transfer arbitrary textual information along with the CSR.
Furter information about attributes in CSRs can be found here, here and here
After the script is done, you have a fully populated directory structure for your CA as well as a CSR you need to get signed by another CA. When this is done, you get a certificate back ready for installation. The script install_ca_certificate.sh helps with that: it
A certificate authority needs a private key an a valid certificate to operate. Certificates however always have an expiration date. So every certficate authority gets sooner or later to a point in time where the certificate needs to be renewed.
For certificate authorities it is crucial that the digital identity does not change when it gets a new certificate. This is only possible if the private key does not change.
The project supports this use case by means of the script reneq_cert_req.sh: It constructs a Certificate signing request from an existing private key and certificate to be signed by the certificate authority that signed the soon-to-be-expiring certificate.
At the first glance many people might think that there should never be a need for this use case - however: When an authorized operator of the certificate authority gets her privileges removed, she must not be able to act on behalf of the certificate authority. If the key is not on some kind of hardware token management could withdraw, the password needs to be changed - and this is where the script change_ca_password.sh comes into play.
It asks for the current password and for the new password. It then backs up the old key file and secures the key using the given password and aes256. The new key is written back into a file with the original name. After checking that the key file works - the backup file must be immediately destroyed!!
Responding to certificate signing requests is done by using the script sign_request.sh. A Certificate signing request essentially asks a certificate authority to certify the association between a certain private key and whatever claims the CSR holds (canonical name, server adresses, email adresses and so on). It needs the CSR of course as well as the private key of the CA itself. The user has to specify the password protecting the CAs private key. Additionally, the user has to decide, what kind of certificate he wants to issue: For example the identity CA configuration allows to issue
The certificate is then packaged with additional files into a ZIP-Archive ready to be shipped to the end-user.
The revocation is done by receiving information about the party whose certificate should be invalidated. Once the script revoke_crl.sh is started, a scrollable list of all valid certificates is displayed. The user selects the one matching the request and is then asked for confirmation. If he gives it, the revocation is executed and the CRL of the CA updated.
However, attention is required from the administrator or operator of the certificate authority: Depending on the policies implemented, it is the duty of the operator to ascertain that the entity that made the request is actually the rightful owner and therefore permitted to actually do so. This can be done for example by checking the Fingerprint of the private key obtained from the requestor with the fingerprint of the certificate to be revoked. The equality alone is -one can not stress this enough- however depending on the policy not sufficient to actually revoke the certificate in question.
The validity period of a certificate revocation list is always limited. The PKI or CA is responsible for refreshing the CRL before the validity of the last one is up. The script refresh_crl.shoffers a convenient method of doing so.
It is crucial for a well-managed CA to watch out for certificates about to reach their end-of-validity date. If this is monitored closely, one can remember the end users of the impending end of the certificates validity and remind them of applying for a renewal.
For this, the script reneq_cert_req.sh was made: The end user can use it to create a new CSR using his private key. He can send this new CSR to the CA and get his certificate renewed.
To get information about certificates soon to become invalid, the script manage_certs.sh is used: The user can choose a certain day and the script presents a list with certificates expiring before that date. This makes it possible for example to get a list of all certificates expiring within the next two months.
Here, all use cases for Subjects are collected that do not issue certificates themselves but use them for a variety of possible uses ( establishing the identity of a web server or email sender for example ). Those uses are not in the scop of this project and neither of this document.
To apply for a certificate, the script request_certificate.sh is used: The end user has to give his private key and the password for unlocking it as well as the name of the file the new CSR is to be saved into. An important additional parameter is the kind of certificate he wishes to obtain - the identity CA for example is able to issue the following flavours:
If the end user already has a certificate and only wants to renew it without also creating a new private key, the script request_certificate_renewal.sh supports this: The user has to provide her private key and the soon-to-be-expired certificate. The resulting CSR can then be sent to the certificate authority that acted as issuer for the old certificate for renewal.
This method has the benefit of not changing the digital identity of the subject by keeping the private key.
A nin-issuing entity needs to check that their private key is not compromised. If it is, it should request that the issuing certificate authority revokes the associated certificate. How exactly this request is made depends strongly on the policies implemented by the certificate authority in question and for this reason, no script is contained in this project to address this particular use case.