Peer Systems

ENTERPRISE  This is a SignServer Enterprise feature.

A SignServer instance can be setup to be the target of remote operations from an EJBCA instance. Connections are made using dual authenticated HTTPS, similar to how you use a client certificate to authenticate using the Admin GUI or Admin Web to manage a SignServer instance. However, in this case the configured administrator is another EJBCA instance.

Generally, the instance with higher security requirements (for example, an EJBCA acting as CA) initiates connections to a system with lower security requirements (for example, a SignServer instance or an EJBCA acting as VA or RA). SignServer currently only implements support for incoming peer connections.

Peer Systems for Certificate Renewal

SignServer can be configured to expose the worker's keys as Remote Key Bindings in EJBCA. This allows the EJBCA administrators to issue new certificates to workers in SignServer directly from within the EJBCA interface, without incoming network connections to the CA.

For instructions on how to set up the systems for certificate renewal using peer systems, see Certificate Renewals Using Peer Systems. Alternatively, see Renewal Worker, which instead of Peer Systems uses the EJBCA web services interface and connects in to the CA.

Mapping SignServer Workers to Remote Key Bindings in EJBCA

EJBCA has a concept called Internal Key Bindings. When accessed over peer systems, Internal Key Bindings are seen as Remote Key Bindings. SignServer does not explicitly have Internal Key Bindings, but a worker having a key assigned to it could be seen from the EJBCA side as a Remote Key Binding. How this is done is described below.

Listed Key Bindings

All workers of worker type PROCESSABLE can be exposed as a remote key binding to EJBCA over peers, if they have a crypto token either internally or by referencing one using the CRYPTOTOKEN worker property.

By setting the worker property PEERS_VISIBLE=true, the worker will be considered when returning the list of key bindings to EJBCA.

Certificate Fingerprint

After a worker has been renewed over peers, the worker will have the property PEERS_ISSUED=true, indicating that the current certificate is issued by the remote peer. This makes SignServer include the certificate fingerprint when exposing the remote internal key binding. The consequence on the EJBCA side is that if it was the issuer of the certificate, the web GUI displays a link to the certificate and matches it to an end entity. However, if that certificate is not available in the EJBCA database, it will not display the remote internal key binding at all, as it is assumed that the certificate is managed by another CA. For this reason, the PEERS_ISSUED property is not set for new workers (or set to false), so that EJBCA will list it and the first certificate can be issued.

Offline Crypto Token

If the crypto token is offline or the configured key-pair is not available, the remote key-pair can be displayed as disabled in EJBCA, and Renew or issuance buttons can be unavailable. In that case, make sure to first generate and configure the key-pair at the SignServer side.

Support for EJBCA Before Versions 6.9

In EJBCA versions prior to 6.9, the default behavior when renewing a certificate was that only the end entity certificate is received and not any CA certificates. Consequently, you would have to manually append the CA certificates to the SIGNERCERTIFICATECHAIN property of the worker after each renewal. To avoid having to manually append the certificates, the worker property PEERS_KEEPCHAIN can be enabled to allow only the end entity certificate to be replaced, and the CA certificates to remain. This requires that the CA certificates are added beforehand and that the CA certificates used with the new certificate is the same as before. If the issuing CA changes, then the CA certificate(s) has to be manually updated.

Authentication/Authorization

The incoming peer (the CA) needs to authenticate towards the application server using a TLS client certificate.

Additionally, in order for the peer to be allowed to list key bindings and to perform operations, the certificate must be authorized to the Peer System role. For information on managing authorizations, see Administrators Page (for Admin Web), or the wspeersystems command in the Administration CLI.

Note the Admin Web allows seeing incoming (i.e. ping) requests and adding an authorization rule for it.

Global Configuration Properties

PropertyDescription
PEERS_INCOMING_ENABLED

Set to true to allow incoming peer connections. Corresponds to the Admin Web Allow incoming connections option on the Administrator Page.

Worker Properties

The following properties can be set on the workers that should be exposed as key binding to peer system(s).

PropertyDescription
PEERS_VISIBLE

Set to true to make the worker exposed as a internal key binding to all authorized peer systems. Default: false.

PEERS_ISSUED

Indicates that the current key has been issued by the peer system.

When enabled, SignServer will include the fingerprint of the current certificate and EJBCA will only display the remote key binding if it has the issuer of the certificate. For that reason, before the worker has got its first certificate from the peer, this value should be false so that the key binding will be listed on the EJBCA side. After the certificate has been issued, the property will automatically be changed to true. Default: false.

(warning) This property should normally not have to be changed manually.

PEERS_KEEPCHAIN

If using an EJBCA version prior to 6.9, the end entity certificate will be provided without the chain. In that case, enabling this property makes the current CA certificates in the chain stay, and only the end entity certificate is replaced when renewing. Thus, the CA certificates will only have to be added manually the first time (assuming the CA certificates do not change).

DISABLED

Disabling the worker by setting this to false will show the key binding as disabled to EJBCA. Default: false.

SIGNATUREALGORITHM

The value of this property will be used as signature algorithm for signing the certificate signing request (CSR/PKCS#10) sent to the CA as part of the renewal. Default: SHA256withRSA.

KEYALG

The value of this property will be used as key algorithm when generating the next key-pair. Default: RSA.

KEYSPEC

The value of this property will be used as key specification (i.e. bit length for RSA or curve name for ECDSA) when generating the next key-pair. Default: 2048.

REQUESTDN

Subject DN to include in the certificate signing request (CSR/PKCS#10) sent to the CA as port of the renewal. Default: CN=<key alias>.