Integrated EKCA

Intended Audience: All persons acting as Æ-DIR admins

  1. Installation
  2. Initialization / key generation
  3. Activation on start
  4. Key Rotation
  5. Client Configuration

To avoid the need for implementing an out-of-band trust process for authorized keys and enforce rotation of user keys it is recommended to issue temporary OpenSSH user certificates only valid for a limited time-span (e.g. a few hours). Æ-DIR has built-in support for that based on EKCA - Epheremal Keys Certificate Authority.
Combined with built-in two-factor authentication this gives you higher security for your SSH logins while preserving usability also when accessing many machines (e.g. with ansible).

Note:
Using OpenSSH user certificates currently only works with OpenSSH servers and clients, not PuTTY or its derivates.

See also:

OpenSSH documentation:

Installation

For installing EKCA on Æ-DIR provider set this ansible variable:

ekca_enabled: True

For customizing some EKCA settings review the ansible variables with prefix ekca_.

After next ansible playbook run two additional services are installed and enabled on Æ-DIR providers:

ekca-service
This is a web service reachable via the web server on URL /ekca. It will authenticate the user, create the new user's key pair and will sign the user certificate by using the SSH key agent started as service ekca-agent.
ekca-agent
This service starts an ssh-agent(1) process which listens on a certain Unix domain socket.

Initialization / key generation

SSH-CA keys are supposed to only exist on the Æ-DIR provider. For high availability you run several Æ-DIR providers each with its own SSH-CA key pair. You then distribute the public keys of all these SSH-CA as trusted user authority keys to the SSH systems.

This avoids the need to copy private SSH-CA keys to other Æ-DIR providers. And also private key loss on one provider does not cause any harm because your other EKCA instances running on the other providers will still be able to sign user certificates.

Note:
If you plan to use CA keys from crypto hardware (HSM) you have to follow the vendor-specific key-generation instructions and stick to security best practices recommend by the vendor.

The SSH-CA private key is protected by a pass-phrase which you must set at initial key generation and provide interactively each time during startup. For starting the key generation you simply invoke the script ekca-key-gen.sh.

# /opt/ae-dir/sbin/ekca-key-gen.sh
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /opt/ae-dir/etc/ekca/priv/ssh-ca-1
Your public key has been saved in /opt/ae-dir/etc/ekca/priv/ssh-ca-1.pub
The key fingerprint is:
SHA256:r3…HI ssh-ca-1 on ae-dir-demo.dmz.hv.local
The key's randomart image is:
+---[RSA 4096]----+
|@*.  .           |
…
|..    oooo       |
+----[SHA256]-----+

Activation on start

While service ekca-agent starts automatically the private key of the SSH-CA has to be manually loaded into the key agent by interactively entering the key passphrase. This avoids having to grant any file access to the private key to any service and allows PKCS#11-based integration of crypto hardware (HSM).

# /opt/ae-dir/sbin/ekca-key-add.sh
Enter passphrase for /opt/ae-dir/etc/ekca/priv/ssh-ca-1:
Identity added: /opt/ae-dir/etc/ekca/priv/ssh-ca-1 (ssh-ca-1 on ae-dir-demo.dmz.hv.local)
ssh-rsa AA…gQ== ssh-ca-1 on ae-dir-demo.dmz.hv.local

Key Rotation

SSH-CA keys should not be used for an infinite period! Rather you should generate new SSH-CA key pairs at regular planned intervals. You can do this in a rotating manner on all Æ-DIR providers so that the risk of locking out users is low if anything goes wrong.

For generating new SSH-CA keys (key rotation) you can simply invoke ekca-key-gen.sh again and allow it to overwrite the old SSH-CA key pair.

Don't forget to update the trusted authority key set on all the affected SSH systems: Add the new generated SSH-CA key, remove the old SSH-CA key.

Client Configuration

On the SSH client you have to install ekca-client.

Store the following config file to $HOME/.ekca_client:

[ekca_client]

baseurl = https://demo.ae-dir.com/ekca

# name of SSH-CA is always empty with AE-DIR
sshca_name = 

# trusted root CA cert
ca_certs = /etc/ssl/ca-bundle.pem

# directory where SSH command line tools are installed
#ssh_cmd_dir = /usr/bin

# where to find the ssh-keygen command-line tool
ssh_keygen = ssh-keygen

# where to find the ssh-keygen command-line tool
ssh_add = ssh-add

# 8 digit OTP with OATH identifier for yubikey as prefix
otp_regex = ^ubhe[0-9]{8}[0-9]{8}$
# 6-digit OTP
#otp_regex = ^[0-9]{6}$