enterprise

This section provides instructions for how to setup and use peer systems for certificate renewals or rekeying.

For background and more information, see Peer Systems in the SignServer Reference section.

Initial Setup

Configuring EJBCA for Outgoing Peer Connections

For information on how to setup Peer Connectors for outgoing connections, refer to EJBCA documentation on Peer Systems Operations.

The following is required at the EJBCA side is:

  • An AuthenticationKeyBinding with a TLS client certificate and key-pair to use for authentication towards SignServer.
  • Allowing outgoing connections checked.
  • An enabled Peer Connector configured to use the AuthenticationKeyBinding and the URL of the peers endpoint in SignServer, that is "https://example.com:8443/signserver/peer/v1".

Now test to connect to SignServer before configuring the SignServer side. On the EJBCA Peer Systems page, click Ping. At this point there will likely be an error message like "Unable to connect to peer. Unauthorized" as the SignServer side has not yet been configured to allow the connection. Now proceed to configure the SignServer side before re-trying the Ping.

Configuring SignServer for Incoming Peer Connections

Configure SignServer for incoming Per Connections either using the Admin Web or the Admin CLI:

Configuring SignServer for Incoming Peer Connections using Admin Web

To configure SignServer for incoming Peer Connections the Admin Web, do the following:

  1. In the SignServer Administration Web go to the Administrators page.
  2. Under Incoming Connections, a row should have been created when the ping request was sent from EJBCA.
    If the client certificate of the incoming request does not already match an authorization rule, an Add Authorization link is available to for selection.
    If, on the other hand, an existing rule already existed, a Modify Authorization button is available.
  3. Make sure the rule has the Peer System role selected, and save the rule.
  4. Under Incoming Connections, the Authorized column should display Yes for the connection.

You can now send another ping request from EJBCA that should not display an error message.

Configuring SignServer for Incoming Peer Connections using Admin CLI

To configure SignServer for incoming Peer Connections the Admin CLI, do the following:

  1. Using the SignServer Administration CLI, set the global configuration property PEERS_INCOMING_ENABLED:

    $ bin/signserver setproperty global PEERS_INCOMING_ENABLED true
    $ bin/signserver reload all

  2. Check the server log for the error message created when the ping request from EJBCA was denied. It looks something like this:

    Denied peer access to 4fe9278255cba7b issuer: 'C=SE, O=SignServer, OU=Testing, CN=DSS Sub CA 11'

    The error message contains the certificate serial number and issuer DN that should be added to the authorization rules.

    Note that it is important to preserve the format of the serial number and issuer DN, and it is therefore recommended to copy the values from the log.

  3. Using the certificate serial number and issue DN exactly as it is written in the log, run the follwoing command to add the authorization rule:

    bin/signserver wspeersystems -add -certserialno 4fe9278255cba7b -issuerdn "C=SE, O=SignServer, OU=Testing, CN=DSS Sub CA 11"

You can now send another ping request from EJBCA that should not display an error message.

Exposing Workers as Key Bindings

In EJBCA, click Manage on the configured Peer System and then select the Remote Key Bindings tag. For more information, refer to the EJBCA documentation on Peer Systems Operations.

The list should display all remote key bindings found, or a message like "No authorized remote Internal Key Bindings found". Note that the list might at this stage be empty, or not show any of the workers from SignServer. To display the worker listed as a key binding in EJBCA, edit the worker by adding the worker property PEERS_VISIBLE with the value true. Then refresh the page in EJBCA to list the worker.

Issuing the First Certificate

Prior to issuing a certificate, ensure that the worker has a key-pair configured. If the configured key alias (the DEFAULTKEY property value) does not yet exist, the Remote key pair might be disabled/grayed out in EJBCA. If this is the case, first generate the key-pair.

EJBCA requires an end entity to be configured, in order to issue a certificate. Then there will be a text field or some way of choosing to use this end entity for the remote key binding, before clicking the Issue signing certificate button (or similar).

Selecting to issue signing certificate, the following will happen:

  1. EJBCA contacts SignServer over the Peer Connector and asks for a certificate signing request (CSR).
  2. SignServer generates the CSR and returns it to EJBCA.
  3. EJBCA processes the request, issues the certificate, and sends it to SignServer.
  4. SignServer installs the certificate to the worker and also adds the worker property PEERS_ISSUED=true to indicate that the certificate was issued by a peer.
  5. The new certificate(s) can now be seen when looking at the worker's status. In EJBCA, the remote key binding will now show the Bound certificate and the button will now instead be named Renew.

The algorithm used for signing the CSR as well as subject DN to include etc was using the default values. To choose other values, see information on available worker properties on the Peer Systems page.

Subsequent Renewals/Rekeyings

The next time it is time to renew or rekey a worker's certificate, everything should already have been set-up as part of the previous steps and in EJBCA the Renew button should be available.

In order to also generate a new key-pair (i.e. to rekey), select the key pair in EJBCA to be rekeyed.