Manage Certificates and CAs

The following commands manage the certificates and certificate authorities used for NFS TLS mutual authentication.

List the System Root CA

Display the Hammerspace-generated root CA certificate(s). The active CA is used to sign all internal node certificates:

cert-ca-list

To list a specific CA by role:

cert-ca-list --role SYSTEM_ACTIVE
cert-ca-list --role SYSTEM_OLD

SYSTEM_ACTIVE is the CA that signs node certificates and certificates signed from a CSR. The SYSTEM_OLD role is reserved for a CA that has been replaced. Hammerspace 5.3 provides no way to replace the system CA, so cert-ca-list --role SYSTEM_OLD normally returns nothing.

List All Registered Certificates

Display all certificates known to the system:
Display certificates
```
cert-list
```
For detailed output including validity dates and subject information:
Display detailed output
```
cert-list --full
```

To filter by how a certificate was added to the system, use the --origin option:

Certificate origin

cert-list --origin <origin>

Table 1. Origin values
Origin value	Description
`SYSTEM_CA`	The Hammerspace root CA certificate, generated automatically at cluster startup.
`SYSTEM_ISSUED`	Per-node X.509 certificates signed by the Hammerspace system CA and distributed to each product node.
`CSR_SIGNED_BY_CA`	Certificates generated by signing a user-supplied CSR with the Hammerspace system CA (see `cert-csr-sign`).
`UPLOADED_ROOT_CA`	A self-signed CA certificate uploaded by an administrator to serve as a trust anchor, extending the trust store.
`UPLOADED_INTERMEDIATE_CA`	A CA-signed (non-self-signed) intermediate CA certificate uploaded by an administrator with `--trust-intermediate-ca`.
`UPLOADED_PINNED_CERT`	An individual self-signed certificate uploaded by an administrator and pinned directly to the trust store.

To retrieve a specific certificate by ID:
Retrieve certificate using ID
```
cert-list --id <certificate_id>
```

Add a Trusted CA Certificate Using the Management GUI

Add a CA certificate to the Hammerspace trust store when Hammerspace must trust certificates that your organization’s CA issued: to clients and storage servers that connect with NFS over TLS, to external movers, or to an LDAP or Active Directory server that Hammerspace connects to over LDAPS or StartTLS. You do not need to add the Hammerspace system CA; it is trusted automatically.

Navigate to Administration TLS and select the Trusted Certificates tab.
Click Add Trusted Certificate.
In Certificates File, select the PEM certificate file. Accepted file extensions are .pem, .crt, .cer, and .csr.
Click Add.

Each certificate that is added is reported as Certificate <serial number> added successfully. A certificate that cannot be added is listed with the reason.

In Hammerspace 5.3, the Management GUI adds root (self-signed) CA certificates only. To add an intermediate CA certificate or a self-signed certificate that is not a CA, use the cert-add command described in the Add a Certificate or CA to the Trust Store section of this page.

The certificate is listed on the Trusted Certificates tab, with its expiration date. To remove it later, use the delete action in its row and confirm in the Delete Trusted Certificate dialog, or use cert-remove.

Add a Certificate or CA to the Trust Store

Upload an external CA certificate, a certificate chain, or an individual client or storage certificate to the Hammerspace trust store. The --pem option accepts PEM-format content:

cert-add --pem "<pem_content>"

By default, cert-add accepts only root CA certificates. Use the following options when adding other certificate types:

# Add an intermediate CA certificate (the PEM holds the intermediate certificate followed by its root)
cert-add --pem "<pem_content>" --trust-intermediate-ca

# Add a self-signed non-CA certificate (e.g. a pinned server cert)
cert-add --pem "<pem_content>" --trust-self-signed-certificate

An intermediate CA certificate is verified against its issuer in the same <pem_content>, so give the intermediate certificate and its root together, intermediate first. An intermediate given on its own is rejected with Certificate signature verification failed, even when its root is already in the trust store. If the root is already there, it is reported as Certificate already exists and the intermediate is still added.

You do not need to add the Hammerspace system root CA using cert-add — it is generated and distributed automatically. Use cert-add for certificates issued by your organization’s CA or by external parties.

cert-add accepts CA certificates (self-signed root CAs, or CA-signed intermediate CAs with --trust-intermediate-ca) and self-signed non-CA certificates (with --trust-self-signed-certificate). A CA-signed leaf (end-entity) certificate — one that is neither a CA itself nor self-signed — is rejected: Certificate is not a CA or self-signed.

Sign a CSR with the Hammerspace System CA

If a client or storage system does not have its own certificate authority, you can sign its Certificate Signing Request (CSR) using the Hammerspace system CA. Hammerspace signs the request and, with --track, keeps the signed certificate so that you can download it for the client or storage system to install. A certificate signed by the system CA is trusted by the cluster without any further trust-store change.

Include at least one IP address in the Subject Alternative Name (SAN) field of the CSR. cert-csr-sign does not enforce this — it signs the CSR regardless of SAN contents — but clients and Hammerspace nodes performing TLS validation generally match against the SAN, so a certificate without an IP SAN may fail validation elsewhere even though it signs successfully.

cert-csr-sign --pem "<csr_pem_content>"

To add the signed certificate to the Hammerspace certificate inventory for expiration tracking:

cert-csr-sign --pem "<csr_pem_content>" --track

The Admin CLI prints the signed certificate’s details (issuer, subject, validity, fingerprints) but not the certificate itself. Always use --track: it adds the signed certificate to the Signed Certificates tab, from which you download it (it is also returned as certPem by GET /pki-certificates in the REST API). A certificate signed without --track cannot be retrieved afterwards.

The certificate’s expiration date is shown on the Signed Certificates tab. A certificate signed from a CSR is valid for 365 days. Hammerspace does not alert you before it expires. See Certificate Lifetimes and Expiration.

Create a Self-Signed Certificate for Labs and POCs

Remove a Certificate from the Trust Store

Remove an uploaded CA certificate or pinned certificate from the trust store. First retrieve the certificate ID using cert-list, then pass it to cert-remove:

cert-list --full
cert-remove --id <certificate_id>

SYSTEM_CA and SYSTEM_ISSUED certificates are managed by Hammerspace and cannot be removed. cert-remove refuses them with the message Cannot delete certificate with origin: <origin>.