ENTERPRISE  This is an EJBCA Enterprise feature.

To allow scalability on an enterprise level, the SSH protocol allows for the issuance of certificates for both client and server, doing away with the heavy load of managing individual SSH keys and instead relying on the PKI infrastructure for authentication. 

Overview

The Secure Shell Protocol (SSH) is a protocol used to establish communications between two network devices to allow operations such as remote logon and file transfer over a cryptographic channel. The default (and simple) setting is using username/password for authentication. This is far from secure and SSH instead allows for a key exchange to be processed using public keys and out-of-band communication to verify public key identities. This in turn requires public keys to be known and stored locally on both server and client, which is vulnerable to attackers pretending to be either server or client during the key exchange and requires manual administration of trusted key lists. 

SSH Certificates solve these issues by binding an identity to a key and minimizing the point of trust to a single CA certificate which can be used to authenticate both clients and servers. 

Configure EJBCA for SSH certificate issuance

Configuring EJBCA for SSH certificate issuance requires the following four basic elements just as with other certificate types: a Crypto Token, a Certificate Authority, an End Entity Profile, and a Certificate Profile. 

SSH Crypto Token

The crypto token used for an SSH CA will be a standard crypto token. Note however, that the SSH protocol has a restriction on key types. The following can be used for an SSH CA:

• RSA (of any size) 
• EC P256
• EC P384
• EC P512
• ed25519

The SSH Certificate Specification also allows the use of DSA keys, but as these are not considered secure there is no support for using them in EJBCA for SSH certificates. 

One major advantage of using EJBCA as an SSH CA instead of relying on OpenSSH is that the CA's private key can easily be stored on the HSM. 

SSH CA

The SSH CA is available as a CA type and is selected when creating the CA in EJBCA (CA Functions > Certification Authorities).

When selecting to create a CA of the type SSH CA, this enables the issuance of SSH certificates and also hides any X.509-related options that are not relevant for SSH operations. Since SSH does not define a certificate type for CA keys (relying on the public key alone), the SSH CA is functionally an X.509 CA. While it issues certificates in the SSH format and its public key can be downloaded as an SSH public key.

The SSH CA shares many of the same Directives as the standard X.509 CA, including enforcing unique public keys and disabling certificate storage to allow the issuance of ephemeral certificates. Enforcing unique DN with Use User storage enabled will result in unique SSH KeyIds among issued certificates.

Being an X.509 CA at heart, the CA certificate can be defined with a Subject DN, validity, and so forth for internal identification. SSH does not define a CA hierarchy, so SSH CAs should normally be self-signed. 

CA Public Key Access

The CA public key can be retrieved using either the EJBCA CA user interface, the EJBCA Web Services API, or the EJBCA REST API.

EJBCA CA UI

To download the CA public key in SSH format using the CA UI, go to CA Functions > CA Structure & CRLs.

EJBCA Web Services API

To retrieve the CA public key over SOAP, use the getSshCaPublicKey command.

EJBCA REST API

To retrieve the CA public key in SSH format over REST, use the pubkey endpoint.

SSH End Entity Profile

Upon enrolling, key holders will internally be identified in EJBCA as end entities. The SSH specification allows for some user-specific values, which requires defining a profile for them. When creating an End Entity Profile for an SSH End Entity, irrelevant fields such as Subject Distinguished Name (SDN) and Subject Alternative Name (SAN) values are hidden and replaced by relevant SSH specific configurations. 

SSH Certificate Data Fields

SSH Certificate Profiles

As with end entity profiles, selecting the SSH subtype for the certificate profile restricts the profile to a subset of values.

SSH Configuration Fields

Note that a signing algorithm is not selected in the certificate profile. This is because signing algorithms in SSH are defined by the key type. 

Enrollment and Issuance

SSH certificates can be created by using the EJBCA RA user interface, EJBCA Web Services, or the EJBCA REST API.

The EJBCA RA user interface and REST API can be used for searching certificates similarly to X.509 certificates and end entities. End entities can only be searched from RA GUI.

The following sections outline how to create SSH certificates using the different EJBCA interfaces. The examples assume that an SSH CA, SSH certificate profile, and SSH end entity profile that allows enrollment has been created. Thus, an SSH certificate profile and an SSH CA should be selectable as Available in the SSH end entity profile, and an SSH CA should also be selectable in Available CAs in the SSH certificate profile.

EJBCA RA UI

SSH users can be enrolled in a similar manner to other enrollments via EJBCA RA UI.

To create a new end entity, select Enroll > Make New Request in RA UI.

For an SSH PKI, end entities create a key pair on a remote machine and then the administrator issues a certificate against the provided public key. EJBCA also supports the same and the public key can be uploaded during enrollment by selecting Provided by user for Key-pair generation or can be enrolled later by selecting Postpone. There is no support for server-side key generation for SSH CAs.

Other details regarding the end entity such as keyId and principals  can also be defined on the Make Request page. Note that the Upload SSH public key section only appears if you have selected Key-pair generation to be Provided by user.

The Upload SSH public key section fields may be mandated from the End entity profile. An administrator is free to choose the intended format for comment, source address, and force command fields. After specifying the details, click Add End Entity or Download SSH certificate to create an en entity to enroll later with a public key (if Key-pair generation=Postpone) or to create an SSH certificate immediately (if Key-pair generation=Provided by user).

When Postpone is selected, the administrator needs to select the Enroll > Use Username option and specify the user name and enrollment code entered during Make New Request. Next, upload the key on the Enrollment with Enrollment code page and click Download SSH certificate to download.

Both end entities and certificates can be searched, viewed, and edited by selecting the Search → End Entities or Search → Certificates options.

Click View to open the view end entities page, which also lists certificates at the bottom of the page. Click the serial to view the certificate. The end entities can also be edited by setting the status to New using a new enrollment code and selecting Enroll > Use Username to re-enroll or issue a new certificate for the end entity.

The View certificate page allows you to inspect the details of the issued certificate or to download the certificate again by clicking Download SSH certificate.

EJBCA Web Services

EJBCA Web Service API enrollAndIssueSshCertificate can be used to issue a certificate for an end entity. The Web Service API creates an end entity if no matching entity is found with the same username, and then issues a certificate. If a matching entity is found, then a new certificate is issued against that entity.

For more information on the Web Service API, see Web Service Interface and the EJBCA WS API documentation. Sample code for integrating the API can be found at modules/ssh/src-test/org/ejbca/core/protocol/ws/SshWsSystemTest.java in EJBCA.

EJBCA REST API

EJBCA REST API for SSH can be used to create an SSH certificate for an end entity.

To enable the REST API for SSH, go to System Configuration > Protocol Configuration and select Enable for REST SSH.

This REST SSH API creates an end entity if no matching entity is found with the same username and then issues a certificate. If a matching entity is found, then a new certificate is issued against that entity.

POST /v1/ssh/certificaterequest

Sample request:
{
  "end_entity_profile": "ExampleSshEndEntityProfile",
  "certificate_profile": "ExampleSshCertificateProfile",
  "certificate_authority": "ExampleSshCA",
  "key_id": "ski-02",
  "comment": "Yellow fish under blue water",
  "public_key": "ssh-rsa AAA...truncated...EWj",
  "principals": ["Wishman", "Bradman"],
  "critical_options": {
    "force_command": "./init.sh",
    "source_address": "1.2.3.0/24,1.10.10.1/32"
  },
  "username": "JohnDoe",
  "password": "foo123"
}

Sample response:
{
  "certificate": "c3N...truncated...T09",
  "response_format": "BYTE"
}

The publicKey in the sample request and  certificate in the sample response is truncated for brevity. Note that the certificate in the response is Base64 encoded, see EJBCA REST Interface for more information.

Revocation 

While SSH supports revocation through Key Revocation Lists (KRLs), SSH certificates tend to be short-lived, so this functionality is not yet implemented in EJBCA.

Publishing 

EJBCA does not yet support publishing operations for SSH certificates.

Validation

EJBCA does not yet support validation of client keys for SSH certificates.