ezSign - Keys & certificates¶

A signing key is what actually signs. A key profile says how a signature is made; the key is the private half of the pair that makes it, and it lives inside the HSM - it is generated there and never leaves.

A key on its own cannot sign anything. It needs a certificate, and that comes from your certificate authority, not from ezSign. This page is where you drive that round trip: generate the key, hand the request to your CA, and bring the answer back.

The journey a key makes¶

flowchart LR
    Gen["Generate keypair<br/><i>in the HSM</i>"] --> Pending["PENDING CERT<br/><i>waiting on your CA</i>"]
    Pending -->|"you submit the CSR"| CA["Your CA<br/><i>issues the certificate</i>"]
    CA -->|"you import the chain"| Inactive["INACTIVE<br/><i>ready, not signing</i>"]
    Inactive -->|activate| Active["ACTIVE<br/><i>signing</i>"]
    Active -->|"a successor is activated"| Retired["RETIRED"]

Figure: the certificate round trip. The two steps in the middle happen at your CA, not in ezSign - which is why a key can sit at PENDING CERT for days, and why nothing switches over on its own.

Before you start¶

You need a key profile to generate the key for. The profile decides what kind of key it will be - if the profile signs with ECDSA you will be generating an EC key, and you choose only the curve.

A disabled profile cannot take a new key. A certificate costs money and takes days, and a key generated for a profile that is out of service could not be used until somebody put it back.

Open the Keys & certificates page¶

In the administration area, open Manage → Keys & certificates in the left-hand menu.

The list shows every signing key in the installation, across all profiles - so you can answer what expires soonest and what is still waiting on a certificate without opening each profile in turn.

Click any row to open the read-only detail sheet. Looking is the default gesture, so nothing changes because you clicked to check something.

Search the list¶

The search box asks the server, not just the rows on your screen.

Generate a keypair¶

Click + Generate keypair.

The dialog tells you what the profile decided - Profile signs with ECDSA - an EC key is generated - so a short list of curves is explained rather than mysterious.

Click Generate & create CSR. Three things happen at once:

1. the keypair is generated inside the HSM;
2. a certificate signing request (CSR) is created and signed with it;
3. the key is recorded as PENDING CERT.

You are then shown the CSR.

Order the certificate from your CA¶

This is the step that happens outside ezSign.

From the CSR panel you can Copy to clipboard or Download .csr. Give that request to your certificate authority however they take it - usually by pasting it into their portal.

Then come back and record the CA order reference they gave you, in the field on the same panel. It is optional, but it is the only thread tying this key to the order it is waiting on, and issuance can take days. The field holds up to 64 characters and stops there, so a reference that would be refused cannot be typed in the first place. Saving keeps the panel open - the CSR is still there.

Import the certificate¶

When your CA sends the certificate back, find the key in the list and click Import certificate.

Either choose the file the CA sent, or paste the PEM text into the box. Include the whole chain - the certificate and the intermediate certificates that came with it - not just the certificate on its own.

Before anything is stored, ezSign checks that:

• the text really is one or more X.509 certificates;
• one of them carries this key's public key - the surest way to catch importing the wrong file;
• the certificate is within its validity dates;
• it is permitted to create signatures;
• the chain hangs together, each certificate signed by the next one up.

If any check fails, nothing is stored, the key stays PENDING CERT, and the dialog tells you which check failed and what to do about it.

If they all pass, the certificate is bound and the key becomes INACTIVE - it is ready, but it is not signing yet.

Activate a key¶

Click Activate key on the row, or Activate in the import dialog.

A profile signs with exactly one key at a time. Activating a key retires whichever key of the same profile was signing before - the confirm names it, so you can see what is about to stop.

A retired key keeps its certificate. Documents already signed with it stay valid; the certificate is untouched and remains verifiable for as long as your CA says it is.

What the states mean¶

A key never goes backwards. A retired key is not brought back into service - you activate a successor instead - and a revoked one is the end of that key's life.

See everything about a key¶

Click the row, or choose View details from the ⋮ menu.

The list shows eight of a key's fields; the sheet shows the rest - the HSM alias, the key identifier, the certificate's full subject and issuer, its validity window, the CA order reference, when the key was last updated, and the key's ID.

The subject, issuer, serial and CA order reference are what your CA's support desk will ask for. The HSM alias is for the other direction: it is the name the key has inside the HSM, and the only name your HSM administrator can act on - the label you chose never leaves ezSign.

Where a certificate has been imported, the sheet also offers the chain as a PEM download.

Renew a key¶

On a retired or revoked key it is the second icon on the row - those are the two states where a successor is the only way forward. On any other key with a certificate it is Renew key in the ⋮ menu. Either way, do it well before the certificate expires.

Renewing generates a successor on the same profile, with the same algorithm and a label suggested from the old one - hsm-invoice-ecdsa-01 becomes hsm-invoice-ecdsa-02. From there it is the same journey as any new key: submit the CSR, import the certificate, activate.

Suspend a key¶

Suspend is the second icon on the row of the key that is signing - it is the one thing you are most likely to do to an active key, so it does not hide in the menu.

The key stops being used and drops back to INACTIVE. Its certificate is untouched and you can activate it again at any time.

Record a revocation¶

Choose Record revocation from the ⋮ menu.

Do it in that order. Once you record the revocation the key is final, and once you delete the key its serial number goes with it - and the serial is what your CA will ask you for.

Cancel an order, or delete a key¶

Both live in the ⋮ menu, and which one you see depends on the key. Neither is ever put on the row itself: they cannot be undone, so they keep the extra click.

Cancel order, on a key still waiting for its certificate, discards the request and removes the key from the HSM. If your CA has already issued the certificate, cancel it there too - you will have nothing left to import it against.

Delete key, on a key that has one, removes the key material from the HSM and the record from ezSign.

The key that is currently ACTIVE cannot be deleted at all. Activate another key or suspend it first - a profile should never lose the key it signs with by accident.

Troubleshooting¶

FAQ¶

Related¶

• Key profiles
• Groups
• ezSign - Initialization
• Key Management
• Signing Service
• Email notifications