Procedure

1. Start the sshd daemon in the current session and set it to start automatically at boot time:

   # systemctl start sshd
   # systemctl enable sshd

2. To specify different addresses than the default 0.0.0.0 (IPv4) or :: (IPv6) for the ListenAddress directive in the /etc/ssh/sshd_config configuration file and to use a slower dynamic network configuration, add the dependency on the network-online.target target unit to the sshd.service unit file. To achieve this, create the /etc/systemd/system/sshd.service.d/local.conf file with the following content:

   [Unit]
   Wants=network-online.target
   After=network-online.target

3. Review if OpenSSH server settings in the /etc/ssh/sshd_config configuration file meet the requirements of your scenario.

4. Optionally, change the welcome message that your OpenSSH server displays before a client authenticates by editing the /etc/issue file, for example:

   Welcome to ssh-server.example.com
   Warning: By accessing this server, you agree to the referenced terms and conditions.

   Ensure that the Banner option is not commented out in /etc/ssh/sshd_config and its value contains /etc/issue:

   # less /etc/ssh/sshd_config | grep Banner
   Banner /etc/issue

   Note that to change the message displayed after a successful login you have to edit the /etc/motd file on the server. See the pam_motd man page for more information.

5. Reload the systemd configuration and restart sshd to apply the changes:

   # systemctl daemon-reload
   # systemctl restart sshd

Verification

1. Check that the sshd daemon is running:

   # systemctl status sshd
   ● sshd.service - OpenSSH server daemon
      Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
      Active: active (running) since Mon 2019-11-18 14:59:58 CET; 6min ago
        Docs: man:sshd(8)
              man:sshd_config(5)
    Main PID: 1149 (sshd)
       Tasks: 1 (limit: 11491)
      Memory: 1.9M
      CGroup: /system.slice/sshd.service
              └─1149 /usr/sbin/sshd -D -oCiphers=aes128-ctr,aes256-ctr,aes128-cbc,aes256-cbc -oMACs=hmac-sha2-256,>
   
   Nov 18 14:59:58 ssh-server-example.com systemd[1]: Starting OpenSSH server daemon...
   Nov 18 14:59:58 ssh-server-example.com sshd[1149]: Server listening on 0.0.0.0 port 22.
   Nov 18 14:59:58 ssh-server-example.com sshd[1149]: Server listening on :: port 22.
   Nov 18 14:59:58 ssh-server-example.com systemd[1]: Started OpenSSH server daemon.

2. Connect to the SSH server with an SSH client.

   # ssh user@ssh-server-example.com
   ECDSA key fingerprint is SHA256:dXbaS0RG/UzlTTku8GtXSz0S1++lPegSy31v3L/FAEc.
   Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
   Warning: Permanently added 'ssh-server-example.com' (ECDSA) to the list of known hosts.
   
   user@ssh-server-example.com's password:

Procedure

1. Open the /etc/ssh/sshd_config configuration in a text editor, for example:

   # vi /etc/ssh/sshd_config

2. Change the PasswordAuthentication option to no:

   PasswordAuthentication no

   On a system other than a new default installation, check that PubkeyAuthentication no has not been set and the ChallengeResponseAuthentication directive is set to no. If you are connected remotely, not using console or out-of-band access, test the key-based login process before disabling password authentication.

3. To use key-based authentication with NFS-mounted home directories, enable the use_nfs_home_dirs SELinux boolean:

   # setsebool -P use_nfs_home_dirs 1

4. Reload the sshd daemon to apply the changes:

   # systemctl reload sshd

Procedure

1. To generate an ECDSA key pair for version 2 of the SSH protocol:

   $ ssh-keygen -t ecdsa
   Generating public/private ecdsa key pair.
   Enter file in which to save the key (/home/joesec/.ssh/id_ecdsa):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /home/joesec/.ssh/id_ecdsa.
   Your public key has been saved in /home/joesec/.ssh/id_ecdsa.pub.
   The key fingerprint is:
   SHA256:Q/x+qms4j7PCQ0qFd09iZEFHA+SqwBKRNaU72oZfaCI joesec@localhost.example.com
   The key's randomart image is:
   +---[ECDSA 256]---+
   |.oo..o=++        |
   |.. o .oo .       |
   |. .. o. o        |
   |....o.+...       |
   |o.oo.o +S .      |
   |.=.+.   .o       |
   |E.*+.  .  . .    |
   |.=..+ +..  o     |
   |  .  oo*+o.      |
   +----[SHA256]-----+

   You can also generate an RSA key pair by using the -t rsa option with the ssh-keygen command or an Ed25519 key pair by entering the ssh-keygen -t ed25519 command.

2. To copy the public key to a remote machine:

   $ ssh-copy-id joesec@ssh-server-example.com
   /usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
   joesec@ssh-server-example.com's password:
   ...
   Number of key(s) added: 1
   
   Now try logging into the machine, with: "ssh 'joesec@ssh-server-example.com'" and check to make sure that only the key(s) you wanted were added.

   If you do not use the ssh-agent program in your session, the previous command copies the most recently modified ~/.ssh/id*.pub public key if it is not yet installed. To specify another public-key file or to prioritize keys in files over keys cached in memory by ssh-agent, use the ssh-copy-id command with the -i option.

Verification

1. Log in to the OpenSSH server without providing any password:

   $ ssh joesec@ssh-server-example.com
   Welcome message.
   ...
   Last login: Mon Nov 18 18:28:42 2019 from ::1

Procedure

1. List all keys provided by the OpenSC PKCS #11 module including their PKCS #11 URIs and save the output to the keys.pub file:

   $ ssh-keygen -D pkcs11: > keys.pub
   $ ssh-keygen -D pkcs11:
   ssh-rsa AAAAB3NzaC1yc2E...KKZMzcQZzx pkcs11:id=%02;object=SIGN%20pubkey;token=SSH%20key;manufacturer=piv_II?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so
   ecdsa-sha2-nistp256 AAA...J0hkYnnsM= pkcs11:id=%01;object=PIV%20AUTH%20pubkey;token=SSH%20key;manufacturer=piv_II?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so

2. To enable authentication using a smart card on a remote server (example.com), transfer the public key to the remote server. Use the ssh-copy-id command with keys.pub created in the previous step:

   $ ssh-copy-id -f -i keys.pub username@example.com

3. To connect to example.com using the ECDSA key from the output of the ssh-keygen -D command in step 1, you can use just a subset of the URI, which uniquely references your key, for example:

   $ ssh -i "pkcs11:id=%01?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so" example.com
   Enter PIN for 'SSH key':
   [example.com] $

4. You can use the same URI string in the ~/.ssh/config file to make the configuration permanent:

   $ cat ~/.ssh/config
   IdentityFile "pkcs11:id=%01?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so"
   $ ssh example.com
   Enter PIN for 'SSH key':
   [example.com] $

   Because OpenSSH uses the p11-kit-proxy wrapper and the OpenSC PKCS #11 module is registered to PKCS#11 Kit, you can simplify the previous commands:

   $ ssh -i "pkcs11:id=%01" example.com
   Enter PIN for 'SSH key':
   [example.com] $

Procedure

1. Define the jump host by editing the ~/.ssh/config file on your local system, for example:

   Host jump-server1
     HostName jump1.example.com

   • The Host parameter defines a name or alias for the host you can use in ssh commands. The value can match the real host name, but can also be any string.
   • The HostName parameter sets the actual host name or IP address of the jump host.

2. Add the remote server jump configuration with the ProxyJump directive to ~/.ssh/config file on your local system, for example:

   Host remote-server
     HostName remote1.example.com
     ProxyJump jump-server1

3. Use your local system to connect to the remote server through the jump server:

   $ ssh remote-server

   The previous command is equivalent to the ssh -J jump-server1 remote-server command if you omit the configuration steps 1 and 2.

Procedure

1. Optional: Verify you can use the key to authenticate to the remote host:

   1. Connect to the remote host using SSH:

      $ ssh example.user1@198.51.100.1 hostname

   2. Enter the passphrase you set while creating the key to grant access to the private key.

      $ ssh example.user1@198.51.100.1 hostname
       host.example.com

2. Start the ssh-agent.

   $ eval $(ssh-agent)
   Agent pid 20062

3. Add the key to ssh-agent.

   $ ssh-add ~/.ssh/id_rsa
   Enter passphrase for ~/.ssh/id_rsa:
   Identity added: ~/.ssh/id_rsa (example.user0@198.51.100.12)

Procedure

1. Copy the example playbook for the sshd System Role:

   # cp /usr/share/doc/rhel-system-roles/sshd/example-root-login-playbook.yml ~/sshd-playbook.yml

2. Open the copied playbook by using a text editor, for example:

   # vim ~/sshd-playbook.yml
   
   ---
   - hosts: all
     tasks:
     - name: Configure sshd to prevent root and password login except from particular subnet
       include_role:
         name: rhel-system-roles.sshd
       vars:
         sshd:
           # root login and password login is enabled only from a particular subnet
           PermitRootLogin: no
           PasswordAuthentication: no
           Match:
           - Condition: "Address 192.0.2.0/24"
             PermitRootLogin: yes
             PasswordAuthentication: yes

   The playbook configures the managed node as an SSH server configured so that:

   • password and root user login is disabled
   • password and root user login is enabled only from the subnet 192.0.2.0/24

   You can modify the variables according to your preferences. For more details, see sshd System Role variables.

3. Validate the playbook syntax:

   # ansible-playbook --syntax-check ~/sshd-playbook.yml

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

4. Run the playbook:

   # ansible-playbook ~/sshd-playbook.yml
   
   ...
   
   PLAY RECAP
   **************************************************
   
   localhost : ok=12 changed=2 unreachable=0 failed=0
   skipped=10 rescued=0 ignored=0

Verification

1. Log in to the SSH server:

   $ ssh user1@10.1.1.1

   Where:

   • user1 is a user on the SSH server.
   • 10.1.1.1 is the IP address of the SSH server.

2. Check the contents of the sshd_config file on the SSH server:

   $ cat /etc/ssh/sshd_config
   …
   PasswordAuthentication no
   PermitRootLogin no
   …
   Match Address 192.0.2.0/24
     PasswordAuthentication yes
     PermitRootLogin yes
   …

3. Check that you can connect to the server as root from the 192.0.2.0/24 subnet:

   1. Determine your IP address:

      $ hostname -I
      192.0.2.1

      If the IP address is within the 192.0.2.1 - 192.0.2.254 range, you can connect to the server.

   2. Connect to the server as root:

      $ ssh root@10.1.1.1

Procedure

1. Create a playbook file, for example ~/ssh-clients-playbook.yml, with the following content:

   ---
   - hosts: all
     tasks:
     - name: "Configure ssh clients"
       include_role:
         name: rhel-system-roles.ssh
       vars:
         ssh_user: root
         ssh:
           Compression: true
           GSSAPIAuthentication: no
           ControlMaster: auto
           ControlPath: ~/.ssh/.cm%C
           Host:
             - Condition: example
               Hostname: example.com
               User: user1
         ssh_ForwardX11: no

   This playbook configures the root user’s SSH client preferences on the managed nodes with the following configurations:

   • Compression is enabled.
   • ControlMaster multiplexing is set to auto.
   • The <example> alias for connecting to the <example.com> host is <user1>.
   • The <example> host alias is created, which represents a connection to the <example.com> host the with the <user1> user name.
   • X11 forwarding is disabled.

   Optionally, you can modify these variables according to your preferences. For more details, see ssh System Role variables.

2. Validate the playbook syntax:

   # ansible-playbook --syntax-check ~/ssh-clients-playbook.yml

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

3. Run the playbook:

   # ansible-playbook ~/ssh-clients-playbook.yml

Procedure

1. Add a configuration snippet with the sshd_config_namespace variable to the playbook:

   ---
   - hosts: all
     tasks:
     - name: <Configure SSHD to accept some useful environment variables>
       include_role:
         name: rhel-system-roles.sshd
       vars:
         sshd_config_namespace: <my-application>
         sshd:
           # Environment variables to accept
           AcceptEnv:
             LANG
             LS_COLORS
             EDITOR

   When you apply the playbook to the inventory, the role adds the following snippet, if not already present, to the /etc/ssh/sshd_config file:

   # BEGIN sshd system role managed block: namespace <my-application>
   Match all
     AcceptEnv LANG LS_COLORS EDITOR
   # END sshd system role managed block: namespace <my-application>

Procedure

1. Generate a private key for your CA. For example, the following command creates a 256-bit Elliptic Curve Digital Signature Algorithm (ECDSA) key:

   $ openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-256 -out <ca.key>

   The time for the key-generation process depends on the hardware and entropy of the host, the selected algorithm, and the length of the key.

2. Create a certificate signed using the private key generated in the previous command:

   $ openssl req -key <ca.key> -new -x509 -days 3650 -addext keyUsage=critical,keyCertSign,cRLSign -subj "/CN=<Example CA>" -out <ca.crt>

   The generated ca.crt file is a self-signed CA certificate that you can use to sign other certificates for ten years. In the case of a private CA, you can replace <Example CA> with any string as the common name (CN).

3. Set secure permissions on the private key of your CA, for example:

   # chown <root>:<root> <ca.key>
   # chmod 600 <ca.key>

Verification

1. Create a certificate signing request (CSR), and use your CA to sign the request. The CA must successfully create a certificate based on the CSR, for example:

   $ openssl x509 -req -in <client-cert.csr> -CA <ca.crt> -CAkey <ca.key> -CAcreateserial -days 365 -extfile <openssl.cnf> -extensions <client-cert> -out <client-cert.crt>
   Signature ok
   subject=C = US, O = Example Organization, CN = server.example.com
   Getting CA Private Key

   See Section 3.5, “Using a private CA to issue certificates for CSRs with OpenSSL” for more information.

2. Display the basic information about your self-signed CA:

   $ openssl x509 -in <ca.crt> -text -noout
   Certificate:
   …
           X509v3 extensions:
               …
               X509v3 Basic Constraints: critical
                   CA:TRUE
               X509v3 Key Usage: critical
                   Certificate Sign, CRL Sign
   …

3. Verify the consistency of the private key:

   $ openssl pkey -check -in <ca.key>
   Key is valid
   -----BEGIN PRIVATE KEY-----
   MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgcagSaTEBn74xZAwO
   18wRpXoCVC9vcPki7WlT+gnmCI+hRANCAARb9NxIvkaVjFhOoZbGp/HtIQxbM78E
   lwbDP0BI624xBJ8gK68ogSaq2x4SdezFdV1gNeKScDcU+Pj2pELldmdF
   -----END PRIVATE KEY-----

Procedure

1. Generate a private key on your server system, for example:

   $ openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-256 -out <server-private.key>

2. Optional: Use a text editor of your choice to prepare a configuration file that simplifies creating your CSR, for example:

   $ vim <example_server.cnf>
   [server-cert]
   keyUsage = critical, digitalSignature, keyEncipherment, keyAgreement
   extendedKeyUsage = serverAuth
   subjectAltName = @alt_name
   
   [req]
   distinguished_name = dn
   prompt = no
   
   [dn]
   C = <US>
   O = <Example Organization>
   CN = <server.example.com>
   
   [alt_name]
   DNS.1 = <example.com>
   DNS.2 = <server.example.com>
   IP.1 = <192.168.0.1>
   IP.2 = <::1>
   IP.3 = <127.0.0.1>

   The extendedKeyUsage = serverAuth option limits the use of a certificate.

3. Create a CSR using the private key you created previously:

   $ openssl req -key <server-private.key> -config <example_server.cnf> -new -out <server-cert.csr>

   If you omit the -config option, the req utility prompts you for additional information, for example:

   You are about to be asked to enter information that will be incorporated
   into your certificate request.
   What you are about to enter is what is called a Distinguished Name or a DN.
   There are quite a few fields but you can leave some blank
   For some fields there will be a default value,
   If you enter '.', the field will be left blank.
   -----
   Country Name (2 letter code) [XX]: <US>
   State or Province Name (full name) []: <Washington>
   Locality Name (eg, city) [Default City]: <Seattle>
   Organization Name (eg, company) [Default Company Ltd]: <Example Organization>
   Organizational Unit Name (eg, section) []:
   Common Name (eg, your name or your server's hostname) []: <server.example.com>
   Email Address []: <server@example.com>

Verification

1. After you obtain the requested certificate from the CA, check that the human-readable parts of the certificate match your requirements, for example:

   $ openssl x509 -text -noout -in <server-cert.crt>
   Certificate:
   …
           Issuer: CN = Example CA
           Validity
               Not Before: Feb  2 20:27:29 2023 GMT
               Not After : Feb  2 20:27:29 2024 GMT
           Subject: C = US, O = Example Organization, CN = server.example.com
           Subject Public Key Info:
               Public Key Algorithm: id-ecPublicKey
                   Public-Key: (256 bit)
   …
           X509v3 extensions:
               X509v3 Key Usage: critical
                   Digital Signature, Key Encipherment, Key Agreement
               X509v3 Extended Key Usage:
                   TLS Web Server Authentication
               X509v3 Subject Alternative Name:
                   DNS:example.com, DNS:server.example.com, IP Address:192.168.0.1, IP
   …

Procedure

1. Generate a private key on your client system, for example:

   $ openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-256 -out <client-private.key>

2. Optional: Use a text editor of your choice to prepare a configuration file that simplifies creating your CSR, for example:

   $ vim <example_client.cnf>
   [client-cert]
   keyUsage = critical, digitalSignature, keyEncipherment
   extendedKeyUsage = clientAuth
   subjectAltName = @alt_name
   
   [req]
   distinguished_name = dn
   prompt = no
   
   [dn]
   CN = <client.example.com>
   
   [clnt_alt_name]
   email= <client@example.com>

   The extendedKeyUsage = clientAuth option limits the use of a certificate.

3. Create a CSR using the private key you created previously:

   $ openssl req -key <client-private.key> -config <example_client.cnf> -new -out <client-cert.csr>

   If you omit the -config option, the req utility prompts you for additional information, for example:

   You are about to be asked to enter information that will be incorporated
   into your certificate request.
   …
   Common Name (eg, your name or your server's hostname) []: <client.example.com>
   Email Address []: <client@example.com>

Verification

1. Check that the human-readable parts of the certificate match your requirements, for example:

   $ openssl x509 -text -noout -in <client-cert.crt>
   Certificate:
   …
               X509v3 Extended Key Usage:
                   TLS Web Client Authentication
               X509v3 Subject Alternative Name:
                   email:client@example.com
   …

Procedure

1. Optional: Use a text editor of your choice to prepare an OpenSSL configuration file for adding extensions to certificates, for example:

   $ vim <openssl.cnf>
   [server-cert]
   extendedKeyUsage = serverAuth
   
   [client-cert]
   extendedKeyUsage = clientAuth

2. Use the x509 utility to create a certificate based on a CSR, for example:

   $ openssl x509 -req -in <server-cert.csr> -CA <ca.crt> -CAkey <ca.key> -CAcreateserial -days 365 -extfile <openssl.cnf> -extensions <server-cert> -out <server-cert.crt>
   Signature ok
   subject=C = US, O = Example Organization, CN = server.example.com
   Getting CA Private Key

   To increase security, delete the serial-number file before you create another certificate from a CSR. This way, you ensure that the serial number is always random. If you omit the CAserial option for specifying a custom file name, the serial-number file name is the same as the file name of the certificate, but its extension is replaced with the .srl extension (server-cert.srl in the previous example).

Procedure

1. Generate a private key for your CA. For example, the following command creates a 256-bit ECDSA (Elliptic Curve Digital Signature Algorithm) key:

   $ certtool --generate-privkey --sec-param High --key-type=ecdsa --outfile <ca.key>

   The time for the key-generation process depends on the hardware and entropy of the host, the selected algorithm, and the length of the key.

2. Create a template file for a certificate.

   1. Create a file with a text editor of your choice, for example:

      $ vi <ca.cfg>

   2. Edit the file to include the necessary certification details:

      organization = "Example Inc."
      state = "Example"
      country = EX
      cn = "Example CA"
      serial = 007
      expiration_days = 365
      ca
      cert_signing_key
      crl_signing_key

3. Create a certificate signed using the private key generated in step 1:

   The generated <ca.crt> file is a self-signed CA certificate that you can use to sign other certificates for one year. <ca.crt> file is the public key (certificate). The loaded file <ca.key> is the private key. You should keep this file in safe location.

   $ certtool --generate-self-signed --load-privkey <ca.key> --template <ca.cfg> --outfile <ca.crt>

4. Set secure permissions on the private key of your CA, for example:

   # chown <root>:<root> <ca.key>
   # chmod 600 <ca.key>

Verification

1. Display the basic information about your self-signed CA:

   $ certtool --certificate-info --infile <ca.crt>
   Certificate:
   …
       	X509v3 extensions:
           	…
           	X509v3 Basic Constraints: critical
               	CA:TRUE
           	X509v3 Key Usage: critical
               	Certificate Sign, CRL Sign

2. Create a certificate signing request (CSR), and use your CA to sign the request. The CA must successfully create a certificate based on the CSR, for example:

   1. Generate a private key for your CA:

      $ certtool --generate-privkey --outfile <example-server.key>

   2. Open a new configuration file in a text editor of your choice, for example:

      $ vi <example-server.cfg>

   3. Edit the file to include the necessary certification details:

      signing_key
      encryption_key
      key_agreement
      
      tls_www_server
      
      country = "US"
      organization = "Example Organization"
      cn = "server.example.com"
      
      dns_name = "example.com"
      dns_name = "server.example.com"
      ip_address = "192.168.0.1"
      ip_address = "::1"
      ip_address = "127.0.0.1"

   4. Generate a request with the previously created private key:

      $ certtool --generate-request --load-privkey <example-server.key> --template <example-server.cfg> --outfile <example-server.crq>

   5. Generate the certificate and sign it with the private key of the CA:

      $ certtool --generate-certificate --load-request <example-server.crq> --load-ca-certificate <ca.crt> --load-ca-privkey <ca.key> --outfile <example-server.crt>

      Additional resources

      • certtool(1) and trust(1) man pages

Procedure

1. Generate a private key on your server system, for example:

   $ certtool --generate-privkey --sec-param High --outfile <example-server.key>

2. Optional: Use a text editor of your choice to prepare a configuration file that simplifies creating your CSR, for example:

   $ vim <example_server.cnf>
   signing_key
   encryption_key
   key_agreement
   
   tls_www_server
   
   country = "US"
   organization = "Example Organization"
   cn = "server.example.com"
   
   dns_name = "example.com"
   dns_name = "server.example.com"
   ip_address = "192.168.0.1"
   ip_address = "::1"
   ip_address = "127.0.0.1"

3. Create a CSR using the private key you created previously:

   $ certtool --generate-request --template <example-server.cfg> --load-privkey <example-server.key> --outfile <example-server.crq>

   If you omit the --template option, the certool utility prompts you for additional information, for example:

   You are about to be asked to enter information that will be incorporated
   into your certificate request.
   What you are about to enter is what is called a Distinguished Name or a DN.
   There are quite a few fields but you can leave some blank
   For some fields there will be a default value,
   If you enter '.', the field will be left blank.
   -----
   Generating a PKCS #10 certificate request...
   Country name (2 chars): <US>
   State or province name: <Washington>
   Locality name: <Seattle>
   Organization name: <Example Organization>
   Organizational unit name:
   Common name: <server.example.com>

Verification

1. After you obtain the requested certificate from the CA, check that the human-readable parts of the certificate match your requirements, for example:

   $ certtool --certificate-info --infile <example-server.crt>
   Certificate:
   …
           Issuer: CN = Example CA
           Validity
               Not Before: Feb  2 20:27:29 2023 GMT
               Not After : Feb  2 20:27:29 2024 GMT
           Subject: C = US, O = Example Organization, CN = server.example.com
           Subject Public Key Info:
               Public Key Algorithm: id-ecPublicKey
                   Public-Key: (256 bit)
   …
           X509v3 extensions:
               X509v3 Key Usage: critical
                   Digital Signature, Key Encipherment, Key Agreement
               X509v3 Extended Key Usage:
                   TLS Web Server Authentication
               X509v3 Subject Alternative Name:
                   DNS:example.com, DNS:server.example.com, IP Address:192.168.0.1, IP
   …

Procedure

1. Generate a private key on your client system, for example:

   $ certtool --generate-privkey --sec-param High --outfile <example-client.key>

2. Optional: Use a text editor of your choice to prepare a configuration file that simplifies creating your CSR, for example:

   $ vim <example_client.cnf>
   signing_key
   encryption_key
   
   tls_www_client
   
   cn = "client.example.com"
   email = "client@example.com"

3. Create a CSR using the private key you created previously:

   $ certtool --generate-request --template <example-client.cfg> --load-privkey <example-client.key> --outfile <example-client.crq>

   If you omit the --template option, the certtool utility prompts you for additional information, for example:

   Generating a PKCS #10 certificate request...
   Country name (2 chars): <US>
   State or province name: <Washington>
   Locality name: <Seattle>
   Organization name: <Example Organization>
   Organizational unit name:
   Common name: <server.example.com>

Verification

1. Check that the human-readable parts of the certificate match your requirements, for example:

   $ certtool --certificate-info --infile <example-client.crt>
   Certificate:
   …
               X509v3 Extended Key Usage:
                   TLS Web Client Authentication
               X509v3 Subject Alternative Name:
                   email:client@example.com
   …

Procedure

1. Optional: Use a text editor of your choice to prepare an GnuTLS configuration file for adding extensions to certificates, for example:

   $ vi <server-extensions.cfg>
   honor_crq_extensions
   ocsp_uri = "http://ocsp.example.com"

2. Use the certtool utility to create a certificate based on a CSR, for example:

   $ certtool --generate-certificate --load-request <example-server.crq> --load-ca-privkey <ca.key> --load-ca-certificate <ca.crt> --template <server-extensions.cfg> --outfile <example-server.crt>

Procedure

1. To add a certificate in the simple PEM or DER file formats to the list of CAs trusted on the system, copy the certificate file to the /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/ directory, for example:

   # cp ~/certificate-trust-examples/Cert-trust-test-ca.pem /usr/share/pki/ca-trust-source/anchors/

2. To update the system-wide truststore configuration, use the update-ca-trust command:

   # update-ca-trust

Procedure

1. Install the libreswan packages:

   # yum install libreswan

2. If you are re-installing Libreswan, remove its old database files and create a new database:

   # systemctl stop ipsec
   # rm /etc/ipsec.d/*db
   # ipsec initnss

3. Start the ipsec service, and enable the service to be started automatically on boot:

   # systemctl enable ipsec --now

4. Configure the firewall to allow 500 and 4500/UDP ports for the IKE, ESP, and AH protocols by adding the ipsec service:

   # firewall-cmd --add-service="ipsec"
   # firewall-cmd --runtime-to-permanent

Procedure

1. Generate a raw RSA key pair on each host:

   # ipsec newhostkey

2. The previous step returned the generated key’s ckaid. Use that ckaid with the following command on left, for example:

   # ipsec showhostkey --left --ckaid 2d3ea57b61c9419dfd6cf43a1eb6cb306c0e857d

   The output of the previous command generated the leftrsasigkey= line required for the configuration. Do the same on the second host (right):

   # ipsec showhostkey --right --ckaid a9e1f6ce9ecd3608c24e8f701318383f41798f03

3. In the /etc/ipsec.d/ directory, create a new my_host-to-host.conf file. Write the RSA host keys from the output of the ipsec showhostkey commands in the previous step to the new file. For example:

   conn mytunnel
       leftid=@west
       left=192.1.2.23
       leftrsasigkey=0sAQOrlo+hOafUZDlCQmXFrje/oZm [...] W2n417C/4urYHQkCvuIQ==
       rightid=@east
       right=192.1.2.45
       rightrsasigkey=0sAQO3fwC6nSSGgt64DWiYZzuHbc4 [...] D/v8t5YTQ==
       authby=rsasig

4. After importing keys, restart the ipsec service:

   # systemctl restart ipsec

5. Load the connection:

   # ipsec auto --add mytunnel

6. Establish the tunnel:

   # ipsec auto --up mytunnel

7. To automatically start the tunnel when the ipsec service is started, add the following line to the connection definition:

   auto=start

Procedure

1. Copy the file with the configuration of your host-to-host VPN to a new file, for example:

   # cp /etc/ipsec.d/my_host-to-host.conf /etc/ipsec.d/my_site-to-site.conf

2. Add the subnet configuration to the file created in the previous step, for example:

   conn mysubnet
        also=mytunnel
        leftsubnet=192.0.1.0/24
        rightsubnet=192.0.2.0/24
        auto=start
   
   conn mysubnet6
        also=mytunnel
        leftsubnet=2001:db8:0:1::/64
        rightsubnet=2001:db8:0:2::/64
        auto=start
   
   # the following part of the configuration file is the same for both host-to-host and site-to-site connections:
   
   conn mytunnel
       leftid=@west
       left=192.1.2.23
       leftrsasigkey=0sAQOrlo+hOafUZDlCQmXFrje/oZm [...] W2n417C/4urYHQkCvuIQ==
       rightid=@east
       right=192.1.2.45
       rightrsasigkey=0sAQO3fwC6nSSGgt64DWiYZzuHbc4 [...] D/v8t5YTQ==
       authby=rsasig

Procedure

1. On each node, import PKCS #12 files. This step requires the password used to generate the PKCS #12 files:

   # ipsec import nodeXXX.p12

2. Create the following three connection definitions for the IPsec required (private), IPsec optional (private-or-clear), and No IPsec (clear) profiles:

   # cat /etc/ipsec.d/mesh.conf
   conn clear
   	auto=ondemand 1
   	type=passthrough
   	authby=never
   	left=%defaultroute
   	right=%group
   
   conn private
   	auto=ondemand
   	type=transport
   	authby=rsasig
   	failureshunt=drop
   	negotiationshunt=drop
   	ikev2=insist
   	left=%defaultroute
   	leftcert=nodeXXXX
   	leftid=%fromcert 2
   	rightid=%fromcert
   	right=%opportunisticgroup
   
   conn private-or-clear
   	auto=ondemand
   	type=transport
   	authby=rsasig
   	failureshunt=passthrough
   	negotiationshunt=passthrough
   	# left
   	left=%defaultroute
   	leftcert=nodeXXXX 3
   	leftid=%fromcert
   	leftrsasigkey=%cert
   	# right
   	rightrsasigkey=%cert
   	rightid=%fromcert
   	right=%opportunisticgroup

1. Open an IPsec tunnel by using the ping command:

   # ping <nodeYYY>

2. Display the NSS database with the imported certification:

   # certutil -L -d sql:/etc/ipsec.d
   
   Certificate Nickname    Trust Attributes
                           SSL,S/MIME,JAR/XPI
   
   west                    u,u,u
   ca                      CT,,

3. See which tunnels a node has opened:

   # ipsec trafficstatus
   006 #2: "private#10.15.0.0/16"[1] ...nodeYYY, type=ESP, add_time=1691399301, inBytes=512, outBytes=512, maxBytes=2^63B, id='C=US, ST=NC, O=Example Organization, CN=east'

Procedure

1. Install the libreswan packages:

   # yum install libreswan

2. If you are re-installing Libreswan, remove its old NSS database:

   # systemctl stop ipsec
   # rm /etc/ipsec.d/*db

3. Start the ipsec service, and enable the service to be started automatically on boot:

   # systemctl enable ipsec --now

4. Configure the firewall to allow 500 and 4500/UDP ports for the IKE, ESP, and AH protocols by adding the ipsec service:

   # firewall-cmd --add-service="ipsec"
   # firewall-cmd --runtime-to-permanent

5. Switch the system to FIPS mode:

   # fips-mode-setup --enable

6. Restart your system to allow the kernel to switch to FIPS mode:

   # reboot

Verification

1. To confirm Libreswan is running in FIPS mode:

   # ipsec whack --fipsstatus
   000 FIPS mode enabled

2. Alternatively, check entries for the ipsec unit in the systemd journal:

   $ journalctl -u ipsec
   ...
   Jan 22 11:26:50 localhost.localdomain pluto[3076]: FIPS Product: YES
   Jan 22 11:26:50 localhost.localdomain pluto[3076]: FIPS Kernel: YES
   Jan 22 11:26:50 localhost.localdomain pluto[3076]: FIPS Mode: YES

3. To see the available algorithms in FIPS mode:

   # ipsec pluto --selftest 2>&1 | head -11
   FIPS Product: YES
   FIPS Kernel: YES
   FIPS Mode: YES
   NSS DB directory: sql:/etc/ipsec.d
   Initializing NSS
   Opening NSS database "sql:/etc/ipsec.d" read-only
   NSS initialized
   NSS crypto library initialized
   FIPS HMAC integrity support [enabled]
   FIPS mode enabled for pluto daemon
   NSS library is running in FIPS mode
   FIPS HMAC integrity verification self-test passed

4. To query disabled algorithms in FIPS mode:

   # ipsec pluto --selftest 2>&1 | grep disabled
   Encryption algorithm CAMELLIA_CTR disabled; not FIPS compliant
   Encryption algorithm CAMELLIA_CBC disabled; not FIPS compliant
   Encryption algorithm SERPENT_CBC disabled; not FIPS compliant
   Encryption algorithm TWOFISH_CBC disabled; not FIPS compliant
   Encryption algorithm TWOFISH_SSH disabled; not FIPS compliant
   Encryption algorithm NULL disabled; not FIPS compliant
   Encryption algorithm CHACHA20_POLY1305 disabled; not FIPS compliant
   Hash algorithm MD5 disabled; not FIPS compliant
   PRF algorithm HMAC_MD5 disabled; not FIPS compliant
   PRF algorithm AES_XCBC disabled; not FIPS compliant
   Integrity algorithm HMAC_MD5_96 disabled; not FIPS compliant
   Integrity algorithm HMAC_SHA2_256_TRUNCBUG disabled; not FIPS compliant
   Integrity algorithm AES_XCBC_96 disabled; not FIPS compliant
   DH algorithm MODP1024 disabled; not FIPS compliant
   DH algorithm MODP1536 disabled; not FIPS compliant
   DH algorithm DH31 disabled; not FIPS compliant

5. To list all allowed algorithms and ciphers in FIPS mode:

   # ipsec pluto --selftest 2>&1 | grep ESP | grep FIPS | sed "s/^.*FIPS//"
   {256,192,*128}  aes_ccm, aes_ccm_c
   {256,192,*128}  aes_ccm_b
   {256,192,*128}  aes_ccm_a
   [*192]  3des
   {256,192,*128}  aes_gcm, aes_gcm_c
   {256,192,*128}  aes_gcm_b
   {256,192,*128}  aes_gcm_a
   {256,192,*128}  aesctr
   {256,192,*128}  aes
   {256,192,*128}  aes_gmac
   sha, sha1, sha1_96, hmac_sha1
   sha512, sha2_512, sha2_512_256, hmac_sha2_512
   sha384, sha2_384, sha2_384_192, hmac_sha2_384
   sha2, sha256, sha2_256, sha2_256_128, hmac_sha2_256
   aes_cmac
   null
   null, dh0
   dh14
   dh15
   dh16
   dh17
   dh18
   ecp_256, ecp256
   ecp_384, ecp384
   ecp_521, ecp521

Procedure

1. Enable password protection for the NSS database for Libreswan:

   # certutil -N -d sql:/etc/ipsec.d
   Enter Password or Pin for "NSS Certificate DB":
   Enter a password which will be used to encrypt your keys.
   The password should be at least 8 characters long,
   and should contain at least one non-alphabetic character.
   
   Enter new password:

2. Create the /etc/ipsec.d/nsspassword file containing the password you have set in the previous step, for example:

   # cat /etc/ipsec.d/nsspassword
   NSS Certificate DB:MyStrongPasswordHere

   Note that the nsspassword file use the following syntax:

   token_1_name:the_password
   token_2_name:the_password

   The default NSS software token is NSS Certificate DB. If your system is running in FIPS mode, the name of the token is NSS FIPS 140-2 Certificate DB.

3. Depending on your scenario, either start or restart the ipsec service after you finish the nsspassword file:

   # systemctl restart ipsec

Verification

1. Check that the ipsec service is running after you have added a non-empty password to its NSS database:

   # systemctl status ipsec
   ● ipsec.service - Internet Key Exchange (IKE) Protocol Daemon for IPsec
      Loaded: loaded (/usr/lib/systemd/system/ipsec.service; enabled; vendor preset: disable>
      Active: active (running)...

2. Optionally, check that the Journal log contains entries confirming a successful initialization:

   # journalctl -u ipsec
   ...
   pluto[6214]: Initializing NSS using read-write database "sql:/etc/ipsec.d"
   pluto[6214]: NSS Password from file "/etc/ipsec.d/nsspassword" for token "NSS Certificate DB" with length 20 passed to NSS
   pluto[6214]: NSS crypto library initialized
   ...

Procedure

1. Add the following option to the /etc/ipsec.conf file in the config setup section:

   listen-tcp=yes

2. To use TCP encapsulation as a fallback option when the first attempt over UDP fails, add the following two options to the client’s connection definition:

   enable-tcp=fallback
   tcp-remoteport=4500

   Alternatively, if you know that UDP is permanently blocked, use the following options in the client’s connection configuration:

   enable-tcp=yes
   tcp-remoteport=4500

Procedure

1. Edit the Libreswan configuration file in the /etc/ipsec.d/ directory of the connection that should use automatic detection of ESP hardware offload support.
2. Ensure the nic-offload parameter is not set in the connection’s settings.

3. If you removed nic-offload, restart the ipsec service:

   # systemctl restart ipsec

1. Display the tx_ipsec and rx_ipsec counters of the Ethernet device the IPsec connection uses:

   # ethtool -S enp1s0 | egrep "_ipsec"
        tx_ipsec: 10
        rx_ipsec: 10

2. Send traffic through the IPsec tunnel. For example, ping a remote IP address:

   # ping -c 5 remote_ip_address

3. Display the tx_ipsec and rx_ipsec counters of the Ethernet device again:

   # ethtool -S enp1s0 | egrep "_ipsec"
        tx_ipsec: 15
        rx_ipsec: 15

   If the counter values have increased, ESP hardware offload works.

Procedure

1. Enable ESP hardware offload support on the network bond:

   # nmcli connection modify bond0 ethtool.feature-esp-hw-offload on

   This command enables ESP hardware offload support on the bond0 connection.

2. Reactivate the bond0 connection:

   # nmcli connection up bond0

3. Edit the Libreswan configuration file in the /etc/ipsec.d/ directory of the connection that should use ESP hardware offload, and append the nic-offload=yes statement to the connection entry:

   conn example
       ...
       nic-offload=yes

4. Restart the ipsec service:

   # systemctl restart ipsec

Verification

1. Display the active port of the bond:

   # grep "Currently Active Slave" /proc/net/bonding/bond0
   Currently Active Slave: enp1s0

2. Display the tx_ipsec and rx_ipsec counters of the active port:

   # ethtool -S enp1s0 | egrep "_ipsec"
        tx_ipsec: 10
        rx_ipsec: 10

3. Send traffic through the IPsec tunnel. For example, ping a remote IP address:

   # ping -c 5 remote_ip_address

4. Display the tx_ipsec and rx_ipsec counters of the active port again:

   # ethtool -S enp1s0 | egrep "_ipsec"
        tx_ipsec: 15
        rx_ipsec: 15

   If the counter values have increased, ESP hardware offload works.

1. Reload the vpn.example.com connection:

   # ipsec auto --add vpn.example.com
   002 added connection description "vpn.example.com"

2. Next, initiate the VPN connection:

   # ipsec auto --up vpn.example.com

Procedure

1. Create a playbook file, for example ~/vpn-playbook.yml, with the following content:

   - name: Host to host VPN
     hosts: <managed_node1>, <managed_node2>
     roles:
       - rhel-system-roles.vpn
     vars:
       vpn_connections:
         - hosts:
             <managed_node1>:
             <managed_node2>:
       vpn_manage_firewall: true
       vpn_manage_selinux: true

   This playbook configures the connection <managed_node1>-to-<managed_node2> using pre-shared key authentication with keys auto-generated by the system role. Because vpn_manage_firewall and vpn_manage_selinux are both set to true, the vpn role uses the firewall and selinux roles to manage the ports used by the vpn role.

2. Optional: Configure connections from managed hosts to external hosts that are not listed in the inventory file by adding the following section to the vpn_connections list of hosts:

       vpn_connections:
         - hosts:
             <managed_node1>:
             <managed_node2>:
             <external_node>:
               hostname: <192.0.2.2>

   This configures two additional connections: <managed_node1>-to-<external_node> and <managed_node2>-to-<external_node>.

   Note

   The connections are configured only on the managed nodes and not on the external node.

3. Optional: You can specify multiple VPN connections for the managed nodes by using additional sections within vpn_connections, for example, a control plane and a data plane:

   - name: Multiple VPN
     hosts: <managed_node1>, <managed_node2>
     roles:
       - rhel-system-roles.vpn
     vars:
       vpn_connections:
         - name: control_plane_vpn
           hosts:
             <managed_node1>:
               hostname: 192.0.2.0 # IP for the control plane
             <managed_node2>:
               hostname: 192.0.2.1
         - name: data_plane_vpn
           hosts:
             <managed_node1>:
               hostname: 10.0.0.1 # IP for the data plane
             <managed_node2>:
               hostname: 10.0.0.2

4. Optional: You can modify the variables according to your preferences. For more details, see the /usr/share/doc/rhel-system-roles/vpn/README.md file.

5. Validate the playbook syntax:

   # ansible-playbook ~/vpn-playbook.yml --syntax-check

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

6. Run the playbook:

   # ansible-playbook ~/vpn-playbook.yml

Verification

1. On the managed nodes, confirm that the connection is successfully loaded:

   # ipsec status | grep <connection_name>

   Replace <connection_name> with the name of the connection from this node, for example managed_node1-to-managed_node2.

   Note

   By default, the role generates a descriptive name for each connection it creates from the perspective of each system. For example, when creating a connection between managed_node1 and managed_node2, the descriptive name of this connection on managed_node1 is managed_node1-to-managed_node2 but on managed_node2 the connection is named managed_node2-to-managed_node1.

2. On the managed nodes, confirm that the connection is successfully started:

   # ipsec trafficstatus | grep <connection_name>

3. Optional: If a connection does not successfully load, manually add the connection by entering the following command. This provides more specific information indicating why the connection failed to establish:

   # ipsec auto --add <connection_name>

   Note

   Any errors that may occur during the process of loading and starting the connection are reported in the /var/log/pluto.log file. Because these logs are hard to parse, manually add the connection to obtain log messages from the standard output instead.

Procedure

1. Create a playbook file, for example ~/mesh-vpn-playbook.yml, with the following content:

   - name: Mesh VPN
     hosts: managed_node1, managed_node2, managed_node3
     roles:
       - rhel-system-roles.vpn
     vars:
       vpn_connections:
         - opportunistic: true
           auth_method: cert
           policies:
             - policy: private
               cidr: default
             - policy: private-or-clear
               cidr: 198.51.100.0/24
             - policy: private
               cidr: 192.0.2.0/24
             - policy: clear
               cidr: 192.0.2.7/32
       vpn_manage_firewall: true
       vpn_manage_selinux: true

   Note

   Because vpn_manage_firewall and vpn_manage_selinux are both set to true, the vpn role uses the firewall and selinux roles to manage the ports used by the vpn role.

2. Optional: You can modify the variables according to your preferences. For more details, see the /usr/share/doc/rhel-system-roles/vpn/README.md file.

3. Validate the playbook syntax:

   # ansible-playbook ~/mesh-vpn-playbook.yml --syntax-check

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

4. Run the playbook:

   # ansible-playbook ~/mesh-vpn-playbook.yml

Procedure

1. On the first host on which you configure MACsec:

   • Create the connectivity association key (CAK) and connectivity-association key name (CKN) for the pre-shared key:

     1. Create a 16-byte hexadecimal CAK:

        # dd if=/dev/urandom count=16 bs=1 2> /dev/null | hexdump -e '1/2 "%04x"'
        50b71a8ef0bd5751ea76de6d6c98c03a

     2. Create a 32-byte hexadecimal CKN:

        # dd if=/dev/urandom count=32 bs=1 2> /dev/null | hexdump -e '1/2 "%04x"'
        f2b4297d39da7330910a74abc0449feb45b5c0b9fc23df1430e1898fcf1c4550

2. On both hosts you want to connect over a MACsec connection:

3. Create the MACsec connection:

   # nmcli connection add type macsec con-name macsec0 ifname macsec0 connection.autoconnect yes macsec.parent enp1s0 macsec.mode psk macsec.mka-cak 50b71a8ef0bd5751ea76de6d6c98c03a macsec.mka-ckn f2b4297d39da7330910a74abc0449feb45b5c0b9fc23df1430e1898fcf1c4550

   Use the CAK and CKN generated in the previous step in the macsec.mka-cak and macsec.mka-ckn parameters. The values must be the same on every host in the MACsec-protected network.

4. Configure the IP settings on the MACsec connection.

   1. Configure the IPv4 settings. For example, to set a static IPv4 address, network mask, default gateway, and DNS server to the macsec0 connection, enter:

      # nmcli connection modify macsec0 ipv4.method manual ipv4.addresses '192.0.2.1/24' ipv4.gateway '192.0.2.254' ipv4.dns '192.0.2.253'

   2. Configure the IPv6 settings. For example, to set a static IPv6 address, network mask, default gateway, and DNS server to the macsec0 connection, enter:

      # nmcli connection modify macsec0 ipv6.method manual ipv6.addresses '2001:db8:1::1/32' ipv6.gateway '2001:db8:1::fffe' ipv6.dns '2001:db8:1::fffd'

5. Activate the connection:

   # nmcli connection up macsec0

Verification

1. Verify that the traffic is encrypted:

   # tcpdump -nn -i enp1s0

2. Optional: Display the unencrypted traffic:

   # tcpdump -nn -i macsec0

3. Display MACsec statistics:

   # ip macsec show

4. Display individual counters for each type of protection: integrity-only (encrypt off) and encryption (encrypt on)

   # ip -s macsec show

1. Traffic ingresses only one zone.
2. Traffic egresses only one zone.
3. A zone defines a level of trust.
4. Intrazone traffic (within the same zone) is allowed by default.
5. Interzone traffic (from zone to zone) is denied by default.