Enabling

To use External RA Service Workers in EJBCA:

1. Enable the service in EJBCA_HOME/conf/externalra.properties
2. Configure DataSources in EJBCA_HOME/conf/externalra.properties
3. (Install the JDBC connector JARs in the application server for databases used in EJBCA_HOME/conf/externalra.properties)
4. Create datasource(s) matching the configuration in externalra.properties.
5. Re-build and deploy EJBCA with 'ant clean deployear'

To create a non-jta data source for JBoss 7 a command in jboss-cli.sh can be used, for example:

data-source add --name=ramessage1ds --jta=false --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/messages" --jndi-name="java:/RAMessage1DS" --use-ccm=true --user-name="ejbca" --password="ejbca" --validate-on-match=true --background-validation=false --prepared-statements-cache-size=50 --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED --check-valid-connection-sql="select 1;"

Or for PostgreSQL

data-source add --name=ramessage1ds --jta=false --driver-name="org.postgresql.Driver" --connection-url="jdbc:postgresql://127.0.0.1/messages" --jndi-name="java:/RAMessage1DS" --use-ccm=true --user-name="ejbca" --password="ejbca" --validate-on-match=true --background-validation=false --prepared-statements-cache-size=50 --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED --check-valid-connection-sql="select 1"

(note that 'select 1' must be different for DB2 and Oracle)

It is recommended to use the following indexes on the external message database:

create index message_idx1 on message (status);
create index message_idx2 on message (messageId);

Configuring

In the EJBCA Admin GUI, go to Services and create a new Custom Worker that runs at short intervals. The shorter the interval the more often the worker will poll the DataSource for new messages.

• Select Worker: Custom Worker
• Custom Worker Class Path: org.ejbca.extra.caservice.ExtRACAServiceWorker
• Custom Worker Properties: shown below
• Select Interval: Periodical Interval
• Period: 10 seconds (or any interval you like but not below 5 seconds)
• Select Action: No Action
• Active: Checked

• externalra-caservice.persistenceunit: A reference to the RA database configured in externalra.properties (Default: RAMessage1DS)
• externalra-caservice.encryption.required: Only accept encrypted messages in the RA database (Default: false)
• externalra-caservice.signature.required: Only accept signed messages in the RA database (Default: false)
• externalra-caservice.keystore.path: Full pathname to the PKCS#12 keystore used to decrypt and sign messages. This file must be available on all EJBCA nodes. Only required if encryption or signing is used. (Default for historic reasons: keystore/extrakeystore.p12)
• externalra-caservice.keystore.pwd: Password for the keystore defined by externalra-caservice.keystore.path. (Default: foo123)
• externalra-caservice.raissuer: CA Name of the CA issuing RA Certificates, used to check the validity of RA signatures. (Default: ManagementCA)
• externalra-caservice.whitelist: A comma separated list of request class-names that this worker will accept. If this is empty or undefined all kinds of request are accepted.

Both the worker's keystore and the one used on the RA server must be issued by 'externalra-caservice.raissuer'. The RA server also needs the certificate of the worker's keystore to be able to encrypt request messages. Signing required Key Usage 'Digital Signature' and encryption requires Key Usage 'Key Encipherment'.

Example:

externalra-caservice.persistenceunit=RAMessage1DS
externalra-caservice.encryption.required=false
externalra-caservice.signature.required=false

Configuring the SCEP RA Server on the external RA host

The SCEP RA Server is the module installed on the external RA server. This module receives SCEP requests from SCEP clients and uses the External RA API to get the CA to process the SCEP requests.

1. Setup a message database on the external RA server
2. Configure the conf/externalra.properties to deploy a new DataSouce for the message database and re-deploy EJBCA
3. Configure a new worker for this new DataSource (as described in previous sections)
4. Issue a PKCS#12 keystore for the SCEP RA Server from the SCEP CA and configure it in EJBCA_HOME/conf/scepra.properties. The SCEP CA is this issuer of all SCEP requests.
5. Create an End Entity Profile and Certificate Profile to issue SCEP requests from and configure it in EJBCA_HOME/conf/scepra.properties.
6. Configure a CA mapping in EJBCA_HOME/conf/scepra.properties.
7. Configure the database connection in EJBCA_HOME/conf/scepra.properties
8. Optional: Configure scep.ra.authPwd in EJBCA_HOME/conf/scepra.properties if you want to authenticate SCEP messages based on a password in the request.
9. Make sure the correct database JDBC connector JAR is installed in the application server for your database.
10. Run 'ant externalra-scep-deploy' to deploy the DataSource and SCEP RA Server (or run 'ant externalra-scep' and deploy the war file dist/scepraserver.war yourself).

Accessing the Scep RA Server on the external RA host

You can access the Scep RA server on the external RA host by pointing your client (vpn router etc) to the URL http://scepraserver.hostname:8080/scepraserver/scep/pkiclient.exe.

Using this URL will include the certificate chain in the SCEP responses. Depending on your client you may instead use the URL http://scepraserver.hostname:8080/scepraserver/scep/noca/pkiclient.exe. Using this URL will return only the client certificate on the SCEP response.

Security options

Using the External RA, the CA trusts all messages that comes from the RA. This means that if a SCEP client sends a request to the RA, the CA will create the user and issue a certificate as soon as it picks up the message from the RA.

To make a more secure setup, one of the two following ways are recommended:

• Each SCEP request can contain a password. Set authPwd in conf/scepra.properties to another value then none. This will require a correct password to be sent in the SCEP request.
• Configure Approvals on the CA(s) issuing SCEP certificates.

When approvals are activated, a SCEP request will result in an approval request being created in the CA. The approval request will be for adding or editing a user. An administrator can then view the approval request and approve or reject the new request from the SCEP client. The SCEP client will continue to poll the RA until the request is approved, then a certificate is returned, or the request is rejected, then a failure message is returned.

Activation of approvals are described in the Admin Guide.

If an approval request is rejected, because the router administrator mistyped something for example, you will have to wait 30 minutes before a new request can be done, because the RA will remember the rejection for 30 minutes.

An approval request will be valid for one hour. After one hour a new request will be created.

The normal work-flow using approvals will be the following:

1. A router admin creates a SCEP request to the RA
2. The router admin calls up a EJBCA admin and asks to get approval of the request.
3. The EJBCA admin approves the request and the router gets the certificate, or the EJBCA admin rejects the request and the router gets a failure message.

Configuration on the External RA GUI host

1. Create a "messages" database on the External RA GUI host that can be accessed from both the EJBCA installation and locally.
2. Issue a new JKS keystore with EJBCA to enable SSL (HTTPS) on the External RA GUI host.
3. Issue a PKCS#12 keystore with EJBCA for signing and encrypting messages to the CA and copy it to the host. Don't forget to add the right administrator privileges to this certificate as described above in 'Security'.
4. Download the certificate of the CA service's PKCS#12 keystore and copy it to the host.
5. Download the issuing certificate of the host's PKCS#12 keystore and copy it to the host (should be the same as the issuer for CA service's PKCS#12).
6. Configure conf/externalra-gui.properties to use the keystores, the certificates, the local database and the local application server.
7. Make sure a database JDBC connector JAR is installed in the local application server for your database.
8. Run 'ant externalra-gui-deploy' to deploy the DataSource and External RA GUI application, or...
9. run 'ant externalra-gui' to build dist/externalra-gui/externalra-gui.war that can be manually deployed to a pre-cconfigured application server.
10. Start JBoss and verify that the application is available at http://hostname:8080/externalra-gui/

Configuration message polling from EJBCA

1. Issue a new PKCS#12 keystore for protection of messages.
2. Configure the conf/externalra.properties to deploy a new DataSource for the message database and re-deploy EJBCA.
3. Configure a new worker for this new DataSource and keystore (as described in previous sections). Use white-listing described in the service configuration section to only allow org.ejbca.extra.db.CertificateRequestRequest and org.ejbca.extra.db.KeyStoreRetrievalRequest request messages.
4. Make sure a database JDBC connector JAR is installed in the local application server for the external RA message database.

• Select Worker: Custom Worker
• Custom Worker Class Path: org.ejbca.extra.caservice.ExtRACAServiceWorker
• Custom Worker Properties: (copy below)
• Select Interval: Periodical Interval
• Period: 5 seconds
• Select Action: No Action
• Active: Checked

externalra-caservice.whitelist=org.ejbca.extra.db.CertificateRequestRequest,org.ejbca.extra.db.KeyStoreRetrievalRequest
externalra-caservice.keystore.path=/home/ejbca/externalra-caservice.p12
externalra-caservice.keystore.pwd=foo123
externalra-caservice.raissuer=ManagementCA
externalra-caservice.signature.required=true
externalra-caservice.encryption.required=false
externalra-caservice.persistenceunit=RAMessage1DS

Verified platforms and browsers

The external RA GUI currently supports JBoss and MySQL. Additional databases supported by Hibernate can easily be added.

Known browsers that support key varies over the years, and a list quickly becomes obsolete. Test and report.

Configuring the CMP Proxy on the external RA host

The CMP Proxy is the module installed on the external RA server.

1. Unpack an Apache Tomcat server, or a JBoss server.
2. Setup a message database on the external RA server.
3. Configure the database datasource in the application server (see below for Tomcat example).
4. Make sure the correct database JDBC connector JAR is installed in the application server on the external RA server. (i.e. copy mariadb-java-client-1.2.0.jar to apache-tomcat-7.0.67/lib/)
5. Configure the external RA backend and datasource in EJBCA_HOME/modules/cmpProxy/resources/properties/cmpProxy.properties (if using default datasource name only cmp.backend.protocol needs to be set).
6. Configure logging level in modules/cmpProxy/resources/properties/log4j.xml.
7. Run 'ant cmpHttpProxy' to build the CMP Proxy (to dist/cmpHttpProxy) and copy the war file to the deploy directory of the application server.

If you need to trim the configuration of the database connection on the external RA host it is done in modules/cmpProxy/resources/properties/persistence.xml.

To configure a datasource, using a connection pool, in Tomcat you need to edit conf/server.xml>, adding the following Resource to <GlobalNamingResources>:

<Resource 
  name="jdbc/CMPRAMessageDS" 
  auth="Container" 
  type="javax.sql.DataSource" 
  maxActive="100" 
  maxIdle="30" 
  maxWait="10000"
  username="ejbca" 
  password="ejbca" 
  driverClassName="org.mariadb.jdbc.Driver" 
  url="jdbc:mysql://database-host:3306/messages"
  />

You need to edit username, password and URL.

You also need to make the datasource available to the webapp by editing conf/context.xml, adding a resource link in the end (just before </Context>):

<ResourceLink 
    name="jdbc/CMPRAMessageDS" 
    global="jdbc/CMPRAMessageDS"
    type="javax.sql.DataSource"/>

Configuration message polling from EJBCA

1. On the CA host, configure conf/externalra.properties to enable External RA service and to deploy a new DataSouce for the message database, and re-deploy EJBCA.
2. Configure a new worker for this new DataSource (as described in previous sections).
3. Configure CMP aliases, as you would using direct CMP communication.
4. Make sure a database JDBC connector JAR is installed in the local application server for the external RA message database.
5. Configure a new worker for this new DataSource.
   • Optional: If message signing and encryption is required create and configure keystores for this.
   • Optional: For an extra layer of security, Use white-listing described in the service configuration section to only allow org.ejbca.extra.db.CMPRequest.

• Select Worker: Custom Worker
• Custom Worker Class Path: org.ejbca.extra.caservice.ExtRACAServiceWorker
• Custom Worker Properties: (copy below)
• Select Interval: Periodical Interval
• Period: 5 seconds
• Select Action: No Action
• Active: Checked

externalra-caservice.whitelist=org.ejbca.extra.db.CMPRequest
externalra-caservice.keystore.path=/home/ejbca/externalra-caservice.p12
externalra-caservice.keystore.pwd=foo123
externalra-caservice.raissuer=ManagementCA
externalra-caservice.signature.required=true
externalra-caservice.encryption.required=false
externalra-caservice.persistenceunit=RAMessage1DS

Accessing the CMP Proxy on the external RA host

You can access the CMP Proxy as described in the CMP Proxy instructions. There is no difference from a client wether using HTTP backend of External RA backend. Example command, using cmpforopenssl (as in CMP examples in Admin Guide) but through the proxy:

./cmpclient --server localhost --port 8080 --path cmpProxy-6.4.0/cmpalias --srvcert ManagementCA.cacert.pem --ir --user mykeyid --password password --newclcert clcert.der --newkey privkey.pem --subject "CN=user1,O=My Organization,C=SE"

As compared to a session directly to the CA:

./cmpclient --server localhost --port 8080 --path ejbca/publicweb/cmp/cmpalias --srvcert ManagementCA.cacert.pem --ir --user mykeyid --password password --newclcert clcert.der --newkey privkey.pem --subject "CN=user1,O=My Organization,C=SE"

Security Options

Using the External RA, the CA works in the same was as if a client connects directly, which means you can use client or RA mode etc. See the CMP documentation for full information about that. You can use whitelisting and signed external RA messages to further limit capabilities of the external RA host itself.

To sign and encrypt external RA messages use the options to configure keystores in cmpProxy.properties:

cmp.backend.keystorepath
cmp.backend.keystorepwd
cmp.backend.caservicecertpath
cmp.backend.issuerchainpath