GitHub – srvrco/getssl: obtain free SSL certificates from letsencrypt ACME server Suitable for automating the process on remote servers.

About

Sick of googling every time you need a self signed certificate?

OMGWTFSSL is a small (< 8 mb) docker image based off alpine linux which makes creating self signed SSL certs easier.

It will dump the certs it generators into /certs by default and will also output them to stdout in a standard
YAML form making them easy to consume in Ansible or other tools that use YAML.

About us

Spatie is a webdesign agency based in Antwerp, Belgium. You’ll find an overview of all our open source projects on our website.

Advanced usage

Customize the certs using the following Environment Variables:

Automating updates

I use the following cron job

23  5 * * * /root/scripts/getssl -u -a -q

The cron will automatically update getssl and renew any certificates,
only giving output if there are issues / errors.

• The -u flag updates getssl if there is a more recent version available.
• The -a flag automatically renews any certificates that are due for renewal.
• The -q flag is “quiet” so that it only outputs and emails me if there
  was an error / issue.

Bundle client key into a pfx file

Most browsers will happily use this if they don’t like the raw ascii PEM file. You’ll possibly need to set a password here, which you’ll need on the browser/client end when you import the key cert PFX bundle.

openssl pkcs12 -export -out ${CLIENT_ID}.full.pfx -inkey ${CLIENT_ID}.key -in ${CLIENT_ID}.pem -certfile ca.pem

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Convert the certificate to an array

You can convert a certificate to an array using the toArray method.

The properties can be used to create a new instance of the certificate.

Create certificates for nginx

Creating web certs for testing SSL just got a hell of a lot easier…

Create Certificate:

Enable SSL in /etc/nginx/sites-enabled/default:

Restart NGINX and test:

Create keys for docker registry

Slightly more interesting example of using paulczar/omgwtfssl as a volume container to build and host SSL certs for the Docker Registry image

Create the volume container for the registry from paulczar/omgwtfssl:

Run the registry using –volumes-from to use the volume container created above:

Make sure it works:

Credits

The helper functions and tests were copied from the Laravel Framework.

Determining if the certificate is still valid

Returns true if the current Date and time is between validFromDate and expirationDate.

You also use this method to determine if a given domain is covered by the certificate. Of course it’ll keep checking if the current Date and time is between validFromDate and expirationDate.

Determining if the certificate is still valid until a given date

Returns true if the certificate is valid and if the expirationDate is after the given date.

Downloading invalid certificate

If you want to download certificates even if they are invalid (for example, if they are expired), you can pass a $verifyCertificate boolean to SslCertificate::createFromHostname() as the third argument, for example:

Generate keys for kubernetes secret for use with ingress:

The following environment variables will help control your Kubernetes secret:

• K8S_NAME (omgwtfssl)
• K8S_NAMESPACE (default)
• K8S_SAVE_CA_KEY (false)
• K8S_SAVE_CA_CRT (false)
• SILENT (true)

An example manifest can be found at examples/minikube/omgwtfssl.yaml.

$ kubectl apply -f examples/minikube
configmap "omgwtfssl" created
job "omgwtfssl" created

$ kc get pods -a
NAME              READY     STATUS      RESTARTS   AGE
omgwtfssl-blz7m   0/1       Completed   0          2m

$ kubectl logs omgwtfssl-blz7m
secret "omgwtfssl" created
kubectl get secret omgwtfssl -o yaml

apiVersion: v1
kind: Secret
metadata:
  name: omgwtfssl
data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQU5VWFdBaFJ4U0RqTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TXpBMU1qSXhOakF3V2hjTk1qZ3dNVEV5TWpJeE5qQXdXakFpTVNBdwpIZ1lEVlFRRERCY3FMakU1TWk0eE5qZ3VPVGt1TVRBd0xuaHBjQzVwYnpDQ0FTSXdEUVlKS29aSWh2Y05BUUVCCkJRQURnZ0VQQURDQ0FRb0NnZ0VCQUtldG5qcWVXY1liWktvQ0JVWHp5NWxQRGszRFo3S0R2cDZWWFBQTGhPTy8Ka2w3NDAwd2JjcGQ5aXdHNFY5elV3RkRiTG83dkFEMVVIMVRDL2lzWUtCZ1dvK2s1UEQwVzVWTlFiRnlmRUtzYQpaUjNycHFsMC9vR2M2eXdvWi9rUlVaZlF2M0s1TUV1WHQ1enA1LzVycllVdHFpVUxadTVlYjc3UW1pWUpOemMyCjFEWVYvaWNYc2pxTmhNL05ZQmtGZWpjd0lvUWp0YmZTejl5YldXS2VESURLQVY4a0RsN2pFVlNHVFRGYllwSGkKMnVjS1BpOEZxTGNRZEVCSDB5NnR5Q3N6ZW01cnhWM2VBeFMrN2EvZ1JaWXpZN2RwdDlia1R3M1AyRytKOWFidgpIa0FHbHN0Z01nY2l0VThZb0c4dmRNM01rRy9ReGl0Sk5xVDNwQVJFN0JNQ0F3RUFBYU5qTUdFd0NRWURWUjBUCkJBSXdBREFMQmdOVkhROEVCQU1DQmVBd0hRWURWUjBsQkJZd0ZBWUlLd1lCQlFVSEF3SUdDQ3NHQVFVRkJ3TUIKTUNnR0ExVWRFUVFoTUIrQ0Z5b3VNVGt5TGpFMk9DNDVPUzR4TURBdWVHbHdMbWx2aHdUQXFHTmtNQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFCQ1BOeEpHNUIrQjFiaEZ4U09oTHNVdVhSb0s1QldHeS94OGw4dDdGU2VWYjhuCmJmd2VSSnZZV0U0WDZkRnZJV2dOdDRyYTFodHhGc2k1b0Nad1FBaXd0U0xSMzEydU11d0RxN09VY256LzNXSUwKQlRaeEJIaGZCZkNCMnlJZEp6a3YrQUsrSTFsQitxY1VFKzd2bVJOb3EzK1BOeXk2SUNBQUlpbTc5RW1BcVVodwp6YnQ1YnhqYmlteFJUMWQ5dWdnTC9lM3NqZFpRM1VJTEZzNkdNemNkWXQ5WHBTdWdsb1RKTHZOTThCampXOTl5CkFxWUdWYkltc3craFdUZFhIVGljZXgwOVFCa3p4RUxzYmszb0hLOWFoV3VDSmU2ZDB3emJiTldEUWlJcEgvN1EKSDB0V2kzNTBYOVZBV2lqQXdSZ3UybG1lcVp6bVlwNk1ibWQzcjFuMQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
  tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcFFJQkFBS0NBUUVBcDYyZU9wNVp4aHRrcWdJRlJmUExtVThPVGNObnNvTytucFZjODh1RTQ3K1NYdmpUClRCdHlsMzJMQWJoWDNOVEFVTnN1anU4QVBWUWZWTUwrS3hnb0dCYWo2VGs4UFJibFUxQnNYSjhRcXhwbEhldW0KcVhUK2daenJMQ2huK1JGUmw5Qy9jcmt3UzVlM25Pbm4vbXV0aFMycUpRdG03bDV2dnRDYUpnazNOemJVTmhYKwpKeGV5T28yRXo4MWdHUVY2TnpBaWhDTzF0OUxQM0p0WllwNE1nTW9CWHlRT1h1TVJWSVpOTVZ0aWtlTGE1d28rCkx3V290eEIwUUVmVExxM0lLek42Ym12RlhkNERGTDd0citCRmxqTmp0Mm0zMXVSUERjL1liNG4xcHU4ZVFBYVcKeTJBeUJ5SzFUeGlnYnk5MHpjeVFiOURHSzBrMnBQZWtCRVRzRXdJREFRQUJBb0lCQVFDRnZleVVFdFBHT1BrOAp4T25SMXRnUlMwWThibHlhdll4Z1R3QmFFSDNKYm5iZ081WEZnYXNQKy9uUkFHbE1ZWUdYdkl0UlJINnJiQnFsCmIvWnRCeEtMekJzbkhoalhIUmtETUFXT2h1MHpuSlVFblg1TWNWM0NvaGZPRzloNmgvN05tWm5xZHAxMzNlWjkKU1BCYk5TV3RNVFFoNGd0U200NkQ0enpnazc4djBNZjAyMWh4UmFtRVRHM0MxTGd0Q3ZXY0dhWWh5TGlTNXhkKwpPeWVSb08zQXR0ZU5ObUszZkhIR2ZNSDRRR2FScnQzSktabUQrcnQ5NHQzbEhNY2YwOFV5d1A4Tjg0K2xOUlVLClpOZkd4bjNnYXZyNWJPT2twYUNvUTMxWnVPL3JFM0RzTGMwd25NTnVCMU9SeEJjR2tLYVZPVWI0YmhwVEE4dGwKR1MwejU2RHhBb0dCQU5oMzV0NGZzRjJxbVlwaGdxU2NvWEU0WUgzNVV2NzFVai9hWndDK0NlcythS2pHczRJSwpXeXpvQnIwR21Na20yQ3AreDkwbFhjano0WmFKUG1NWXdNcEVyQnluaTFVY3Z0Z08rb1VheTdWNGZWOUNsUUdLCnNENmlCUVFnSjloTEtZdkJnRDBkUjV2TWFWYTM2SFF3S3EzTjRHdzNIRFVwZ0NBeEFFenVWUDJaQW9HQkFNWk0KdXZCRVRBWU5odE5SdHFRUlgzUHhtTVJCWmt3YlZrK2ZFWjY1cWd4MUFGeTd4UURxNGxJanpKZHh5T3J5OWd0ZApxMWRLQkFhRzVrN0tWWWJzaXlSdUwxS0pwRlhKQm1WZURyaG14NEV0OWc3dlM0dmRRSklPQzlROWtMTS9TRE1lCnNjc0VqS243UXFVR0o0UHJwY0lIakY0ZW5lRE4xK3k2VzYwSitVcUxBb0dBSkhCS2xLbVE3ck9CRlNKRTg2REsKTEZ6cElVdVBCUXdXeEZqbmJlQ1BtdUh1akRxbWpRVmhRN1hyTEhhbjBYU1FmdGJJbmhsa0tDZWxtY21RanUzagp4aWk1TURtajRyZnNDRUs5T1JyQm45S2dpQ0NWSktWTDliOGdTUW1BcTVBN2RpTWtpeVVhb01kUUZDRHhLRjNUClVWNk9vS2pHUHN5MW5MV2k3MUJQVGtFQ2dZRUFzK1dpWmh5Zmw1SW44WWdkR0lVR1FvbzRYRHMwa2ZEdkFYYSsKcG0rclhIZThwMlJWV2ZxODdXVzYwdDJRTjgzSTl4QzRRNDFMVDV5TVRZaHp4TjdOY0hSaGpCQ0F2SzZObGVLWgptaUxyOVQ1OERwcDZ2OTB1R2hLU0dxN3JtaUhiM3p5R2NUYWtZZ1VuTmN6NmhreCs2U0t0N2lqNmM1cHF2RUZvCnIvZnZaL2NDZ1lFQXZGU29QZmhxaTkxOTFVWXA2K3R6YVBIQmcxeGRSWlVjQ2o2UFI4L0hQZVJhWWFCQkdMVysKdUVmWm1VbGhOUVkwblozT1p3aEw1VGlWNzUyTVFtdEMwQlVtSUhrQmg1MnEzcUorMW1qdi9wS0xZWkhxcnpSVwpXcHp6cTdlWFdwNVE2R0YwZTBQa0pFVzdMWmMwYjN3UmFMRTBhUStLeGc0ODZSUlFEVGFJQ0xjPQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=

Getting the additional domain names

A certificate can cover multiple (sub)domains. Here’s how to get them.

A domain name return with this method can start with * meaning it is valid for all subdomains of that domain.

Important notice

Currently, this package does not check if the certificate is signed by a trusted authority. We’ll add this check soon in a next point release.

Include root certificate in full chain

Some servers, including those that use Java keystores, will not accept a server certificate if it cannot valid the full chain of signers.

Specifically, Nutanix Prism (Element and Central) will not accept the fullchain.crt until the root CA’s certificate has been appended to it manually.

If your application requires the full chain, i.e. including the
root certificate of the CA, then this can be included in the fullchain.crt file by
adding the following line to getssl.cfg

Install client key on client device (os or browser)

Use client.full.pfx (most commonly accepted in GUI apps) and/or client.full.pem. Actual instructions vary.

Installation

Since the script is only one file, you can use the following command for
a quick installation of GetSSL only:

This will copy the getssl Bash script to the current location and change
the permissions to make it executable for you.

For a more comprehensive installation (e.g. install also helper scripts)
use the provided Makefile with each release tarball. Use the install
target.

You’ll find the latest version in the git repository:

For Arch Linux there are packages in the AUR, see
here and
there.

If you use puppet, there is a GetSSL Puppet
module by dthielking

License

The MIT License (MIT). Please see License File for more information.

Overview

GetSSL was written in standard bash ( so it can be run on a server, a
desktop computer, or even a virtualbox) and add the checks, and
certificates to a remote server ( providing you have a ssh with key,
sftp or ftp access to the remote server).

getssl ver. 2.36
Obtain SSL certificates from the letsencrypt.org ACME server

Usage: getssl [-h|--help] [-d|--debug] [-c|--create] [-f|--force] [-a|--all] [-q|--quiet] [-Q|--mute] [-u|--upgrade] [-X|--experimental tag] [-U|--nocheck] [-r|--revoke cert key] [-w working_dir] [--preferred-chain chain] domain   

Options:
  -a, --all          Check all certificates
  -d, --debug        Output debug information
  -c, --create       Create default config files
  -f, --force        Force renewal of cert (overrides expiry checks)
  -h, --help         Display this help message and exit
  -i, --install      Install certificates and reload service
  -q, --quiet        Quiet mode (only outputs on error, success of new cert, or getssl was upgraded)
  -Q, --mute         Like -q, but also mute notification about successful upgrade
  -r, --revoke   "cert" "key" [CA_server] Revoke a certificate (the cert and key are required)
  -u, --upgrade      Upgrade getssl if a more recent version is available - can be used with or without domain(s)
  -X  --experimental tag Allow upgrade to a specified version of getssl
  -U, --nocheck      Do not check if a more recent version is available
  -v  --version      Display current version of getssl
  -w working_dir "Working directory"
    --preferred-chain "chain" Use an alternate chain for the certificate

Postcardware

You’re free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, 2021 Antwerp, Belgium.

We publish all received postcards on our company website.

Praise for omgwtfssl

“We should try to find a replacement for omgwtfssl, which is currently used to generate self-signed certificates. The name is inappropriate and unprofessional.” – gitlab

Preferred chain

If a CA offers multiple chains then it is possible to select which chain
is used by using the PREFERRED_CHAIN variable in getssl.cfg or specifying
–preferred-chain in the call to getssl

This uses wildcard matching so requesting “X1” returns the first certificate
returned by the CA which contains the text “X1″, Note you may need to escape
any characters which special characters, e.g.
PREFERRED_CHAIN=”(STAGING) Doctored Durian Root CA X3”

• Staging options are: “(STAGING) Doctored Durian Root CA X3” and “(STAGING) Pretend Pear X1”
• Production options are: “ISRG Root X1” and “ISRG Root X2”

Revoke a certificate

In general revoking a certificate is not required.

Usage: getssl -r path/to/cert path/to/key [CA_server]

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Structure

The design aim was to provide flexibility in running the code. The
default working directory is ~/.getssl (which can be modified via the
command line).

Within the working directory is a config file getssl.cfg which is a
simple bash file containing variables, an example of which is:

then, within the working directory there will be a folder for each
certificate (based on its domain name). Within that folder will be a
config file (again called getssl.cfg). An example of which is:

# Uncomment and modify any variables you need# see https://github.com/srvrco/getssl/wiki/Config-variables for details# see https://github.com/srvrco/getssl/wiki/Example-config-files for example configs## The staging server is best for testing#CA="https://acme-staging-v02.api.letsencrypt.org"# This server issues full certificates, however has rate limits#CA="https://acme-v02.api.letsencrypt.org"#AGREEMENT="https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2021.pdf"

PRIVATE_KEY_ALG="rsa"# Additional domains - this could be multiple domains / subdomains in a comma separated list
SANS="www.example.org"# Acme Challenge Location. The first line for the domain, the following ones for each additional domain.# If these start with ssh: then the next variable is assumed to be the hostname and the rest the location.# An ssh key will be needed to provide you with access to the remote server.# Optionally, you can specify a different userid for ssh/scp to use on the remote server before the @ sign.# If left blank, the username on the local server will be used to authenticate against the remote server.# If these start with ftp: then the next variables are ftpuserid:ftppassword:servername:ACL_location# These should be of the form "/path/to/your/website/folder/.well-known/acme-challenge"# where "/path/to/your/website/folder/" is the path, on your web server, to the web root for your domain.#ACL=('/var/www/${DOMAIN}/web/.well-known/acme-challenge'#     'ssh:server5:/var/www/${DOMAIN}/web/.well-known/acme-challenge'#     'ssh:sshuserid@server5:/var/www/${DOMAIN}/web/.well-known/acme-challenge'#     'ftp:ftpuserid:ftppassword:${DOMAIN}:/web/.well-known/acme-challenge')# Location for all your certs, these can either be on the server (so full path name) or using ssh as for the ACL
DOMAIN_CERT_LOCATION="ssh:server5:/etc/ssl/domain.crt"
DOMAIN_KEY_LOCATION="ssh:server5:/etc/ssl/domain.key"#CA_CERT_LOCATION="/etc/ssl/chain.crt"#DOMAIN_CHAIN_LOCATION="" this is the domain cert and CA cert#DOMAIN_PEM_LOCATION="" this is the domain_key. domain cert and CA cert# The command needed to reload apache / nginx or whatever you use.# Several (ssh) commands may be given using a bash array:# RELOAD_CMD=('ssh:sshuserid@server5:systemctl reload httpd' 'logger getssl for server5 efficient.')
RELOAD_CMD="service apache2 reload"# Define the server type. This can be https, ftp, ftpi, imap, imaps, pop3, pop3s, smtp,# smtps_deprecated, smtps, smtp_submission, xmpp, xmpps, ldaps or a port number which# will be checked for certificate expiry and also will be checked after# an update to confirm correct certificate is running (if CHECK_REMOTE) is set to true#SERVER_TYPE="https"#CHECK_REMOTE="true"

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You’ll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Usage

You can create an instance of SpatieSslCertificateSslCertificate with this named constructor:

You can create an instance of SpatieSslCertificateSslCertificate passing the port with this named constructor:

You can use this fluent style to specify a specific port to connect to.

You can check the certificate on a different IP address using the same style.

You can specify socket context options.

If the given ipAddress is invalid SpatieSslCertificateExceptionsInvalidIpAddress will be thrown.

If the given hostName is invalid SpatieSslCertificateExceptionsInvalidUrl will be thrown.

If the given hostName is valid but there was a problem downloading the certifcate SpatieSslCertificateExceptionsCouldNotDownloadCertificate will be thrown.

Using cacert keys

(removed)

Генерация self-sign сертификата

Для работы с ключами принято использовать OpenSSL

Команда openssl req — это запрос на генерацию нового сертификата.

Параметры:

При выполнении команды у вас будут запрошены данные вашего ресурса. Вот так это может выглядеть:

Параметр Common Name обязательно должен совпадать с адресом вашего ресурса.

Возможна неинтерактивная генерация сертификата с использованием параметра -subj:

При использовании сертификата необходимо явно указать Web-серверу какой шифр (chipers) используется.
Для примера выше стоит использовать значение EECDH AESGCM:EDH AESGCM:AES256 EECDH:AES256 EDH

На ресурсе cipherli.st можно узнать какие настройки безопасность актуальны на текущий момент и
как установить их в одном из популярных веб-серверов.

UPD: 27.08.2021

Для генерации сертификата, который включает Subject Alter Names необходимо поработать с конфигурационным файлом openssl.cnf. Узнать его местонахождение можно командой find /usr/lib -name openssl.cnf.

Далее, на лету изменяем в нём необходимые параметры и генерируем privkey.pem и fullchain.pem:

openssl req -x509 -nodes -newkey ec:<(openssl ecparam -name secp384r1) -keyout privkey.pem -out fullchain.pem -days 365 -subj "/C=RU/ST=Moscow/L=Moscow/O=My Company/CN=domain.local" -config <(cat /usr/lib/ssl/openssl.cnf | sed 's/[ v3_ca ]/[ v3_ca ]nsubjectAltName = @alternate_names/g' | sed 's/# copy_extensions/copy_extensions/g' | printf "$(cat -)n[ alternate_names ]nDNS.1 = domain.localnDNS.2 = *.domain.local")

Криптографические алгоритмы

На сегодняшний день (27 января 2021) в криптографии наиболее широко распространены алгоритмы
построенные на базе RSA и Elliptic Curves.

RSA имеет большую популярность, в следствии того, что был изобретен раньше и прост в исполнении.
RSA основан на вычислительной сложности задачи факторизации больших целых чисел.

Задачей факторизации люди занимаются уже множество десятилетий,
а вот субэкспоненциальных алгоритмов решения задачи дискретного логарифмирования на сегодняшний день не известно.
Алгортмы основанные на эллиптических кривых используют именно этот факт.

Недостатки ecc в сравнении с rsa

• Теория и реализация существенно сложнее.
• При использовании кривого генератора случайных чисел ключ может быть скомпрометирован.
• Теоретически новые алгоритмы могут быть менее проверенными, например это касается binary curves.
• До сих пор имеются некоторые проблемы с патентами, особенно это касается binary curves.

Таким образом, если вы задумались о том, что выбрать при генерации SSL сертификата, смело выбирайте ECC

Преимущества ecc над rsa:

• Меньший размер ключа.
• Намного быстрее генерация ключа.
• Быстрее подпись данных.
• Умеренно быстрое шифрование и дешифрование.