OpenSSL - ArchWiki

Jump to content

# OpenSSL

From ArchWiki

Related articles

- Transport Layer Security

OpenSSL is an open-source implementation of the SSL and TLS protocols, designed to be as flexible as possible. It is supported on a variety of platforms, including BSD, Linux, OpenVMS, Solaris and Windows.

## Installation

openssl is installed by default on Arch Linux (as a dependency of coreutils).

There are various OpenSSL library bindings available for developers:

- python-pyopenssl
- perl-net-ssleay
- lua-sec, lua52-sec, lua51-sec
- haskell-hsopenssl
- haskell-openssl-streams

## Configuration

On Arch Linux the `OPENSSLDIR` is `/etc/ssl`.

The OpenSSL configuration file, conventionally placed in `/etc/ssl/openssl.cnf`, may appear complicated at first. Remember that variables may be expanded in assignments, much like how shell scripts work. For a thorough explanation of the configuration file format, see config(5ssl).

### req section

This article or section is a candidate for merging with #Generate a certificate signing request.

Notes: Same topic. (Discuss in Talk:OpenSSL#Plan)

Settings related to generating keys, requests and self-signed certificates.

The req section is responsible for the DN prompts. A general misconception is the Common Name (CN) prompt, which suggests that it should have the user's proper name as a value. End-user certificates need to have the machine hostname as CN, whereas CA should not have a valid TLD, so that there is no chance that, between the possible combinations of certified end-users' CN and the CA certificate's, there is a match that could be misinterpreted by some software as meaning that the end-user certificate is self-signed. Some CA certificates do not even have a CN, for example:

    $ openssl x509 -subject -noout -in /etc/ssl/certs/AC_RAIZ_FNMT-RCM.pem

    subject=C=ES, O=FNMT-RCM, OU=AC RAIZ FNMT-RCM

## Usage

This sections assumes you have read Transport Layer Security#Obtaining a certificate.

### Generate an Ed25519 private key

    $ openssl genpkey -algorithm ed25519 -out filename

### Generate a Curve25519 private key

    $ openssl genpkey -algorithm x25519 -out filename

### Generate an ECDSA private key

    $ openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out filename

### Generate an RSA private key

With openssl-genpkey(1ssl), which supersedes genrsa according to openssl(1ssl):

    $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:keysize -out filename

If an encrypted key is desired, use the `-aes-256-cbc` option.

### Generate a certificate signing request

Use openssl-req(1ssl):

    $ openssl req -new -sha256 -key private_key -out filename

### Show a certificate signing request

Certificate signing requests are stored in an encoded format. To view the request in human readable format:

    $ openssl req -noout -text -in filename

### Generate a self-signed certificate

This article or section needs expansion.

Reason: This produces a certificate for the (root) Certificate Authority, which you are acting as. Most web browsers do not seem to accept CA certificates, deeming it necessary to request another certificate and sign it with the CA cert and CA key. The "Generate a certificate issued by own CA" procedure in this forum post is what seems to satisfy browsers. (Discuss in Talk:OpenSSL)

    $ openssl req -key private_key -x509 -new -days days -out filename

### Generate a self-signed certificate with private key in a single command

You can combine the above command in OpenSSL into a single command which might be convenient in some cases.

ECDSA:

    $ openssl req -x509 -newkey ec -pkeyopt 'ec_paramgen_curve:P-256' -days days -keyout key_filename -out cert_filename

RSA:

    $ openssl req -x509 -newkey rsa:4096 -days days -keyout key_filename -out cert_filename

### Sign a certificate signing request with a CA certificate

    $ openssl x509 -req -in cert_req_filename -days days -CA CA_cert -CAkey CA_cert_private_key -CAserial CA_cert_serial_file -out cert_out

### Generate Diffie–Hellman parameters

DH, Diffie–Hellman, key exchange is a protocol to negotiate a shared secret between two parties, where the negotiation itself is held securely over public networks. (Wikipedia article). The resulted shared secret can be used for secret communication for exchanging data over a public network. The DH protocol establishes a method for both parties to contribute to the eventual shared secret by communicating over public networks in a way a passive listener will not be able to reconstruct the resulted shared secret. The other common way to achieve a shared secret by communicating over public networks is have one party use some long-term asymmetric key to encrypt the secret and send it to the owner of the key (like in an RSA key exchange)[1]. Other algorithms are consequently used for encryption itself[2]. In order to set demands that will be raised while negotiating, each party can a priory define a set of demands. These demands are the Diffie–Hellman parameters. The common way to define these parameters is by mathematical functions. There are two functions commonly used: exponentiation modulo prime (forming Finite Field Diffie-Hellman, or FFDH) and point multiplication over elliptic curve, forming Elliptic Curve Diffie-Hellman (ECDH).

Current best practice is to use one of the standard DH groups from RFC:7919, eg. ffdhe2048.

Alternatively you can generate a random group of your own:

    $ openssl dhparam -out filename 2048

Tip To speed up generating, especially when not on high-end hardware, add the `-dsaparam` option [3].

### Show certificate information

    $ openssl x509 -text -in cert_filename

To view a server's certificate, use openssl-s_client(1ssl):

    $ openssl s_client -showcerts -connect hostname:port </dev/null | openssl x509 -text

### Show certificate fingerprint

    $ openssl x509 -noout -in cert_filename -fingerprint -digest

`-digest` is optional and one of `-md5`, `-sha1`, `-sha256`, or `-sha512`. See "-digest" in x509(1ssl) § Input, Output, and General Purpose Options for when the digest is unspecified.

### Convert certificate format

Use `openssl x509` to convert certificates from binary (DER) format to PEM format (the text format with `BEGIN CERTIFICATE` headers)：

    $ openssl x509 -inform DER -in myCA.crt -out myCA_pem.crt

### Use third-party providers

OpenSSL 3 introduced providers as a new concept for OpenSSL plugability. It is possible to use algorithms not included in OpenSSL without having to recompile it.

#### oqsprovider

To test the NIST Post-Quantum Cryptography algorithms, you can install the Open Quantum Safe provider oqsproviderAUR. As an example, you can generate a quantum-safe self-signed certificate with private key using one of the variants of ML-DSA (formerly CRYSTALS-Dilithium):

    $ openssl req -provider default -provider oqsprovider -x509 -newkey mldsa65 -days days -keyout key -out cert

#### tpm2-openssl

To store ECDSA and RSA private keys in the TPM, install tpm2-openssl. See its README for documentation on how to use it.

## Troubleshooting

### "bad decrypt" while decrypting

OpenSSL 1.1.0 changed the default digest algorithm for the dgst and enc commands from MD5 to SHA256. [4]

Therefore if a file has been encrypted using OpenSSL 1.0.2 or older, trying to decrypt it with an up to date version may result in an error like:

    error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt:crypto/evp/evp_enc.c:540

Supplying the `-md md5` option should solve the issue:

    $ openssl enc -d -md md5 -in encrypted -out decrypted

### Python 3.10 and "ca md too weak" errors

In Python 3.10 by default there is a hardcoded list of allowed OpenSSL ciphers. Some of the less secure, like MD5, have been disabled at the `ssl` module level, ignoring the system-wide configuration of OpenSSL. It results sometimes in strange errors on older certificates, sometimes even when establishing `https` connections, like:

    requests.exceptions.SSLError: HTTPSConnectionPool(host='a.kind.of.example.com', port=443): Max retries exceeded with url: / (Caused by SSLError(SSLError(398, '[SSL: CA_MD_TOO_WEAK] ca md too weak (_ssl.c:3862)')))

To make Python follow the system configuration, you may have to rebuild it, adding `--with-ssl-default-suites=openssl` parameter to `./configure`. The issue has been also reported as FS#73549.

### Error setting cipher XXX

If you try to use a "retired" cipher, you'll get an error of this type:

    $ openssl bf -d -in cipher_file -K passphrase
    Error setting cipher BF-CBC
    4087A97A8A7F0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:crypto/evp/evp_fetch.c:341:Global default library context, Algorithm (BF-CBC : 12)

Since OpenSSL 3.0, crypto algorithms are supplied through "providers". Oldest or least used algorithms belong to the legacy provider. [5]

If you need to use retired algorithms like DES, RC4, Blowfish, etc., you must add the option `-provider legacy` in your command line.

Here is a complete example for decoding a Blowfish cipher.

    $ openssl bf -d -in cipher_file -provider legacy -provider default -K passphrase

## See also

- Wikipedia page on OpenSSL, with background information.
- OpenSSL's wiki is intended to collect, organize, and refine useful information about OpenSSL that is currently strewn among multiple locations and formats.
- FreeBSD Handbook
- Step-by-step guide to create a signed SSL certificate
- OpenSSL Certificate Authority: A guide demonstrating how to act as your own certificate authority.
- Bulletproof SSL and TLS by Ivan Ristić, a more formal introduction to SSL/TLS

Category:

- Transport Layer Security

Hidden categories:

- Pages or sections flagged with Template:Merge
- Pages or sections flagged with Template:Expansion

OpenSSL
Add topic