4.7. Using OpenSSL

OpenSSL is a library that provides cryptographic protocols to applications. The openssl command line utility enables using the cryptographic functions from the shell. It includes an interactive mode.
The openssl command line utility has a number of pseudo-commands to provide information on the commands that the version of openssl installed on the system supports. The pseudo-commands list-standard-commands, list-message-digest-commands, and list-cipher-commands output a list of all standard commands, message digest commands, or cipher commands, respectively, that are available in the present openssl utility.
The pseudo-commands list-cipher-algorithms and list-message-digest-algorithms list all cipher and message digest names. The pseudo-command list-public-key-algorithms lists all supported public key algorithms. For example, to list the supported public key algorithms, issue the following command:
~]$ openssl list-public-key-algorithms
The pseudo-command no-command-name tests whether a command-name of the specified name is available. Intended for use in shell scripts. See man openssl(1) for more information.

4.7.1. Creating and Managing Encryption Keys

With OpenSSL, public keys are derived from the corresponding private key. Therefore the first step, once having decided on the algorithm, is to generate the private key. In these examples the private key is referred to as privkey.pem. For example, to create an RSA private key using default parameters, issue the following command:
~]$ openssl genpkey -algorithm RSA -out privkey.pem
The RSA algorithm supports the following options:
  • rsa_keygen_bits:numbits — The number of bits in the generated key. If not specified 1024 is used.
  • rsa_keygen_pubexp:value — The RSA public exponent value. This can be a large decimal value, or a hexadecimal value if preceded by 0x. The default value is 65537.
For example, to create a 2048 bit RSA private key using 3 as the public exponent, issue the following command:
~]$ openssl genpkey -algorithm RSA -out privkey.pem -pkeyopt rsa_keygen_bits:2048 \ -pkeyopt rsa_keygen_pubexp:3
To encrypt the private key as it is output using 128 bit AES and the passphrase hello, issue the following command:
~]$ openssl genpkey -algorithm RSA -out privkey.pem -aes-128-cbc -pass pass:hello
See man genpkey(1) for more information on generating private keys.

4.7.2. Generating Certificates

To generate a certificate using OpenSSL, it is necessary to have a private key available. In these examples the private key is referred to as privkey.pem. If you have not yet generated a private key, see Section 4.7.1, “Creating and Managing Encryption Keys”
To have a certificate signed by a certificate authority (CA), it is necessary to generate a certificate and then send it to a CA for signing. This is referred to as a certificate signing request. See Section 4.7.2.1, “Creating a Certificate Signing Request” for more information. The alternative is to create a self-signed certificate. See Section 4.7.2.2, “Creating a Self-signed Certificate” for more information.

4.7.2.1. Creating a Certificate Signing Request

To create a certificate for submission to a CA, issue a command in the following format:
~]$ openssl req -new -key privkey.pem -out cert.csr
This will create an X.509 certificate called cert.csr encoded in the default privacy-enhanced electronic mail (PEM) format. The name PEM is derived from Privacy Enhancement for Internet Electronic Mail described in RFC 1424. To generate a certificate file in the alternative DER format, use the -outform DER command option.
After issuing the above command, you will be prompted for information about you and the organization in order to create a distinguished name (DN) for the certificate. You will need the following information:
  • The two letter country code for your country
  • The full name of your state or province
  • City or Town
  • The name of your organization
  • The name of the unit within your organization
  • Your name or the host name of the system
  • Your email address
The req(1) man page describes the PKCS# 10 certificate request and generating utility. Default settings used in the certificate creating process are contained within the /etc/pki/tls/openssl.cnf file. See man openssl.cnf(5) for more information.

4.7.2.2. Creating a Self-signed Certificate

To generate a self-signed certificate, valid for 366 days, issue a command in the following format:
~]$ openssl req -new -x509 -key privkey.pem -out selfcert.pem -days 366

4.7.2.3. Creating a Certificate Using a Makefile

The /etc/pki/tls/certs/ directory contains a Makefile which can be used to create certificates using the make command. To view the usage instructions, issue a command as follows:
~]$ make -f /etc/pki/tls/certs/Makefile
Alternatively, change to the directory and issue the make command as follows:
~]$ cd /etc/pki/tls/certs/
~]$ make
See the make(1) man page for more information.

4.7.3. Verifying Certificates

A certificate signed by a CA is referred to as a trusted certificate. A self-signed certificate is therefore an untrusted certificate. The verify utility uses the same SSL and S/MIME functions to verify a certificate as is used by OpenSSL in normal operation. If an error is found it is reported and then an attempt is made to continue testing in order to report any other errors.
To verify multiple individual X.509 certificates in PEM format, issue a command in the following format:
~]$ openssl verify cert1.pem cert2.pem
To verify a certificate chain the leaf certificate must be in cert.pem and the intermediate certificates which you do not trust must be directly concatenated in untrusted.pem. The trusted root CA certificate must be either among the default CA listed in /etc/pki/tls/certs/ca-bundle.crt or in a cacert.pem file. Then, to verify the chain, issue a command in the following format:
~]$ openssl verify -untrusted untrusted.pem -CAfile cacert.pem cert.pem
See man verify(1) for more information.

Important

Verification of signatures using the MD5 hash algorithm is disabled in Red Hat Enterprise Linux 7 due to insufficient strength of this algorithm. Always use strong algorithms such as SHA256.

4.7.4. Encrypting and Decrypting a File

For encrypting (and decrypting) files with OpenSSL, either the pkeyutl or enc built-in commands can be used. With pkeyutl, RSA keys are used to perform the encrypting and decrypting, whereas with enc, symmetric algorithms are used.

Using RSA Keys

To encrypt a file called plaintext, issue a command as follows:
~]$ openssl pkeyutl -in plaintext -out cyphertext -inkey privkey.pem
The default format for keys and certificates is PEM. If required, use the -keyform DER option to specify the DER key format.
To specify a cryptographic engine, use the -engine option as follows:
~]$ openssl pkeyutl -in plaintext -out cyphertext -inkey privkey.pem -engine id
Where id is the ID of the cryptographic engine. To check the availability of an engine, issue the following command:
~]$ openssl engine -t
To sign a data file called plaintext, issue a command as follows:
~]$ openssl pkeyutl -sign -in plaintext -out sigtext -inkey privkey.pem
To verify a signed data file and to extract the data, issue a command as follows:
~]$ openssl pkeyutl -verifyrecover -in sig -inkey key.pem
To verify the signature, for example using a DSA key, issue a command as follows:
~]$ openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
The pkeyutl(1) manual page describes the public key algorithm utility.

Using Symmetric Algorithms

To list available symmetric encryption algorithms, execute the enc command with an unsupported option, such as -l:
~]$ openssl enc -l
To specify an algorithm, use its name as an option. For example, to use the aes-128-cbc algorithm, use the following syntax:
openssl enc -aes-128-cbc
To encrypt a file called plaintext using the aes-128-cbc algorithm, enter the following command:
~]$ openssl enc -aes-128-cbc -in plaintext -out plaintext.aes-128-cbc
To decrypt the file obtained in the previous example, use the -d option as in the following example:
~]$ openssl enc -aes-128-cbc -d -in plaintext.aes-128-cbc -out plaintext

Important

The enc command does not properly support AEAD ciphers, and the ecb mode is not considered secure. For best results, do not use other modes than cbc, cfb, ofb, or ctr.

4.7.5. Generating Message Digests

The dgst command produces the message digest of a supplied file or files in hexadecimal form. The command can also be used for digital signing and verification. The message digest command takes the following form:
openssl dgst algorithm -out filename -sign private-key
Where algorithm is one of md5|md4|md2|sha1|sha|mdc2|ripemd160|dss1. At time of writing, the SHA1 algorithm is preferred. If you need to sign or verify using DSA, then the dss1 option must be used together with a file containing random data specified by the -rand option.
To produce a message digest in the default Hex format using the sha1 algorithm, issue the following command:
~]$ openssl dgst sha1 -out digest-file
To digitally sign the digest, using a private key privekey.pem, issue the following command:
~]$ openssl dgst sha1 -out digest-file -sign privkey.pem
See man dgst(1) for more information.

4.7.6. Generating Password Hashes

The passwd command computes the hash of a password. To compute the hash of a password on the command line, issue a command as follows:
~]$ openssl passwd password
The -crypt algorithm is used by default.
To compute the hash of a password from standard input, using the MD5 based BSD algorithm 1, issue a command as follows:
~]$ openssl passwd -1 password
The -apr1 option specifies the Apache variant of the BSD algorithm.
To compute the hash of a password stored in a file, and using a salt xx, issue a command as follows:
~]$ openssl passwd -salt xx -in password-file
The password is sent to standard output and there is no -out option to specify an output file. The -table will generate a table of password hashes with their corresponding clear text password.
See man sslpasswd(1) for more information and examples.

4.7.7. Generating Random Data

To generate a file containing random data, using a seed file, issue the following command:
~]$ openssl rand -out rand-file -rand seed-file
Multiple files for seeding the random data process can be specified using the colon, :, as a list separator.
See man rand(1) for more information.

4.7.8. Benchmarking Your System

To test the computational speed of a system for a given algorithm, issue a command in the following format:
~]$ openssl speed algorithm
where algorithm is one of the supported algorithms you intended to use. To list the available algorithms, type openssl speed and then press tab.

4.7.9. Configuring OpenSSL

OpenSSL has a configuration file /etc/pki/tls/openssl.cnf, referred to as the master configuration file, which is read by the OpenSSL library. It is also possible to have individual configuration files for each application. The configuration file contains a number of sections with section names as follows: [ section_name ]. Note the first part of the file, up until the first [ section_name ], is referred to as the default section. When OpenSSL is searching for names in the configuration file the named sections are searched first. All OpenSSL commands use the master OpenSSL configuration file unless an option is used in the command to specify an alternative configuration file. The configuration file is explained in detail in the config(5) man page.
Two RFCs explain the contents of a certificate file. They are: