enterprise

A SignServer instance can be connected with an EJBCA instance using peer connections with two different use cases:

  • In the first case, the SignServer instance can be set up 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 Web to manage a SignServer instance. However, in this case, the configured administrator is another EJBCA instance.
  • In the other case, the SignServer instance is acting as a Registration Authority (RA) and posts certificate signing requests that are picked up and processed by EJBCA. Connections are made using dual authenticated HTTPS, similar to how you use a client certificate to authenticate using the Admin Web to manage a SignServer 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 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.

Peer Systems with SignServer as RA

The OneTimeCryptoWorker allows you to configure a CA Connector that uses the peer system in RA mode.

To set up a peer connection with the SignServer instance acting as a Registration Authority (RA), the following configuration is needed:

  • On the EJBCA side, enable processing of incoming requests:
    • In the EJBCA Admin Web, click Peer Systems and enable the Process incoming requests option for the Peer Connector in EJBCA. For more information, refer to the EJBCA documentation on Adding an Outgoing Peer Connection.
  • On the SignServer side, enable incoming peer requests and authorize the peer system:
    • In the SignServer AdminWeb, go to the Administrators page and select Allow incoming connections, then click Save to allow incoming connections from peer systems.

    • Wait for EJBCA to connect, or go to EJBCA and issue a Ping request.
    • Then, on the Administrators page the incoming request should be visible under Incoming Connections. Click the Add Authorization link to authorize the peer.

For information on setting up one-time keys using the OneTimeCryptoWorker, see Setting up One-time Keys.

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

Property

Description

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).

Property

Description

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.

(varning) 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.

REQUESTSIGNATUREALGORITHM

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. If this property is not present or is empty, SignServer will use SIGNATUREALGORITHM as signature algorithm.

SIGNATUREALGORITHM

This property will be used if REQUESTSIGNATUREALGORITHM is not present unless any of the NONEwith signature algorithms is used, then it will default to SHA512withRSA.

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>.