Step 5: Running WebConf Wizard

The final step of the initial setup is to run the web-based configurator WebConf. During this procedure all components of the system will be configured according to the parameters provided:

WebConf is designed and tested to work with Firefox 26.0+. Other browsers like Chrome or Safari are not officially supported and minor incompatibilities may be observed.

Internet Explorer is not officially supported. Depending on the version, the configuration process may not finish successfully.

Initial Log In

For the initial log in you need to have the One Time Password (OTP) ready. It is displayed on the front display of the Hardware Appliance. Until the system is completely installed, the One Time Password changes every time the machine is started.

  1. In the Authenticate page, enter the One Time Password in the field Authentication code.
  2. Click Login.

Entering the OTP

Fresh Installation

After your login with the OTP on an unconfigured EJBCA Hardware Appliance eIDAS edition you will have the following options:

  • Fresh install
  • Restore system from backup
  • Update

Click Next in the section Fresh install.

Installation Choices

Network Settings

After the Fresh Install is complete, you can configure the network settings of the Hardware Appliance. There are two physical network setting interface designs:

  • Management Interface: This interface provides access to the configurator WebConf and to the Admin GUI of EJBCA.
    The Management Interface address has been configured via the front display in Step 3: Changing the IP Address of the Hardware Appliance. It is preset to a network prefix of /24 (subnet mask 255.255.255.0).
  • Application Interface: This interface provides routing for the operational payload.
    You can use this wizard step to enter the IP address, network prefix, and default gateway manually.

If needed, the two networks can be separated.

After the installation is complete you can use the WebConf > Network page to edit your network settings. However, we recommend to decide on the network configuration beforehand.

Proceed as follows to configure the Network Settings:

  1. Enter the Hostname for the Management and Application Interfaces.
    This is required if the Hardware Appliance needs to be available through DNS name resolution.
  2. If needed, enter the IP address, Network prefix and Gateway for the Application Interface.
  3. Click Next: Time to proceed to the next page of the wizard.

Network Settings

Date and Time Settings

Many Public Key Infrastructure (PKI) applications need a correct date and time. Use a Network Time Protocol (NTP) time source, as this protocol synchronizes the clocks of computers over a network. NTP is for example required to build a cluster.

We recommend to enable Use Network Time Protocol at this stage. If NTP is configured at a later time, there will be time synchronization issues between the NTP Server and the current system time.

Proceed as follows to configure the Date and Time Settings:

  1. Select the Time Zone from the select list.
  2. Enable Use Network Time Protocol if you want to use an NTP time source.
    If enabled, also specify the NTP Server to be used.
  3. Select the exact Date and time.
  4. Click Next: Management CA to proceed to the next page.

Date and Time Settings (NTP)

Management CA Settings

The initial management CA will be used to create the Hardware Appliance's server side TLS certificate. It will also generate a client TLS certificate for secure management of the Hardware Appliance.

Creating a new Management CA

Carefully consider the Management CA Settings. These settings cannot be altered after the installation. If there is an existing TLS PKI, you can use an existing Management CA. There will be a prompt to upload the PEM-encoded CA certificate.

If you use the option Create a new Management CA, the keys will be generated in PKCS#11 slot 1. The key activation keys (KAK) for those keys are stored in a soft crypto token. The default authentication code for that soft crypto token is preset as foo123.

For increased security, proceed as follows to manually change the authentication code of the soft crypto token after the installation:

  1. Navigate to WebConf > Platform > Platform Access, enable SSH access and configure a password or public key for SSH.
  2. Enter the EJBCA Hardware Appliance eIDAS edition via SSH. You will find yourself in a virtual machine called vgw.
  3. Enter the virtual machine called cos-ejbca by using this command:
    ssh cos-ejbca
  4. In the virtual machine cos-ejbca, enter this command:
    /opt/ejbca/bin/ejbca.sh cryptotoken setpin --token "Soft CT for KAK for MgmtCA CT (Slot1)" --oldpin foo123
    The tool will prompt you for the new authentication code.
  5. The command in Step 4 will also configure the soft crypto token to be auto-activated. For increased security, you can change this in the EJBCA AdminWeb CryptoToken Manager. Alternatively, you can enter the following command:
    /opt/ejbca/bin/ejbca.sh cryptotoken setpin --token "Soft CT for KAK for MgmtCA CT (Slot1)" --oldpin null --remove
    The tool will prompt you for the current activation code.
  6. The command in Step 4 will also activate the soft crypto token. You can change this in the EJBCA AdminWeb CryptoToken Manager. Alternatively, you can enter the following command:

    /opt/ejbca/bin/ejbca.sh cryptotoken deactivate --token "Soft CT for KAK for MgmtCA CT (Slot1)"
  7. For increased security, go back to WebConf > Platform > Platform Access and disable SSH.

Proceed as follows to configure the Management CA Settings:

  1. Enter the Common Name of the EJBCA Management CA.
  2. Add the Additional Subject Fields, such as organization and country:
    1. It is important to specify a meaningful identifier as the Additional Subject Fields.
    2. The Additional Subject DN will be reflected in the TLS certificates that are stored in your browser and in the name of the backup files.
    3. If you want to perform several test and/or demo installations, this is where the name can be branded.
  3. Add the Signature Algorithm to be used by the EJBCA Management CA:
    • SHA1withRSA
    • SHA256withRSA
    • SHA256withECDSA
  4. Enter the signing Key Specification strength:

    • ECDSA - secp256r1 / prime256v1 / P-256
    • RSA 2048
    • RSA 4096
  5. Enter the SuperAdmin Common Name. This is the name of the first post-install administrator.

  6. Click Next: Security.

Management CA Settings

Hardware Security Module Settings

Security settings cannot be altered after the installation.

Use this tab to configure all relevant security aspects of the Hardware Appliance.


Proceed as follows to configure the Hardware Security Module Settings:
  1. Select the desired Appliance Security Level option. See below for more information.
  2. Define the HSM Admin User Smart Cards options. See below for more information.
  3. Select Store signed audit log, if needed. See below for more information.
  4. Click Next: Secrets.


Security Settings

Appliance Security Level - Detailed information

Defines here if and how many smart cards shall be used to protect the HSM key material. For example, if 2 out of 3 Backup key share cards is chosen, 3 smart cards are inserted during installation and each card will share and store a symmetric key (the Backup Key). The symmetric key will be used to encrypt the backups. As the Backup Key is also securely stored on the HSM smart cards, it will not need to be provided for every backup operation.

If the EJBCA Hardware Appliance eIDAS edition needs to be restored from a backup:

  1. Import the Backup Key into the HSM to decrypt with 2 of the 3 initial smart cards.
  2. Import the backup data.

The same scenario for the 3 out of 5 Backup key share smart cards.

For low security or testing scenarios, it is possible to operate the EJBCA Hardware Appliance eIDAS edition without smart cards and use software based keys, which are stored on the Hardware Appliance instead. In this case, any backup of cryptographic keys (from the HSM) will not be secured by the Backup Key Share smart cards, but only by the Domain Master Secret, that encrypts all data in a backup file.

Higher security can be achieved by enabling smart card activation on slots.

HSM Admin User Smart Cards - Detailed information

These smart cards are for example required for deleting the HSM Audit Logs. You need a minimum of 2 different admin users. You can have up to 5 copies of admin user smart cards.


Audit Log Storage - Detailed information

Here you can select to Store signed audit logs, that is, log records of security operations to the clustered storage. By default, the option is enabled. Audit log records consume database disk space. For a typical installation, the creation of a single certificate issues approximately 10 audit log records. For all typical installations, the audit log database table will be at least double the size of the other database tables. If you disable the option, you can store the audit log records externally, over syslog shipping (unsigned, unencrypted).

In case the HSM Audit Log is full, do NOT reboot the EJBCA Hardware Appliance eIDAS edition. Refer to the Troubleshooting section for more information.


The KAK for the database protection key is stored on the file system for unattended reboot.

Security Settings - Secrets

Domain Master Secret

A Domain Master Secret ensures a higher level of security. This passphrase is used to derive a symmetric key which is used to encrypt backup archives created by the Hardware Appliance. A Domain Master Secret can be specified manually or it can be generated by the system. If generated by the system, the highly secure Domain Master Secret can be printed.

Important

Document the Domain Master Secret and keep it in a safe place. If lost, you will not be able to restore the device from a backup and you will be unable to extend this system to a cluster.

Hardware Security Module Settings

You need to manually enter a PIN for each PKCS#11 slot. Enter the PIN in the column Authentication Code and repeat it in the column Confirm Authentication Code.

Security Settings - Secrets

Summary and Begin installation

The Summary step lists all configuration settings from the previous wizard steps. We highly recommend the following:

  • Double-check everything on this page before starting the actual installation.
  • Print this page for future reference.

Ensure the following:

  • Connect the PIN pad, included in the delivery, to one of the USB ports at the front of the EJBCA Hardware Appliance.
  • Have a sufficient number of smart cards ready.
    The smart cards are delivered with the default PIN "123456". You can change the PIN of a smart card after the installation.

Proceed as follows to check and confirm the Summary and begin the installation:

  1. Check the settings in the Summary.
    To correct any errors in the configuration, use the Previous: ... buttons at the bottom or the links in the breadcrumbs path at the top to navigate to the affected wizard page.
  2. Connect the smart card PIN pad included in the delivery.
  3. Click Begin installation at the bottom of the page. The installation will take a few minutes.
  4. Follow the installation and configuration steps shown below the progress bar. These steps include the configuration of the HSM, the database and the applications, like EJBCA.

Pay attention to the PIN pad during the installation process: You will be prompted to insert the smart cards and enter the PIN. Enter the smart cards in two steps using the 'k out of n' schema:

  1. Key generation: Insert all (n) smart cards you have chosen to use, always providing the PIN.
  2. Key import (to HSM): Insert again the amount of smart cards that is needed to restore the backup key (k)
Confirm installation choices

Choose SuperAdmin Credentials

You need a client side SuperAdmin TLS certificate for managing the Hardware Appliance. This certificate is issued by the Management CA and can be used by your browser. The certificate will be your only authentication to the system, unless you configure other access methods. For information on configuration of further users and other authentication methods, see the section Access.

After the installation you will be automatically prompted to choose your SuperAdmin credential procedure:


End of Installation - SuperAdmin credentials

To retrieve SuperAdmin credentials, select the option that suits the current client environment:

  • Get PKCS#12 key store: The SuperAdmin certificate and corresponding key pair is generated on the Hardware Appliance and manually imported into the browser.
  • Use legacy browser enrollment: The SuperAdmin key pair is generated in the browser and the SuperAdmin certificate is automatically imported into the browser.
  • Get certificate from Certificate Signing Request: The SuperAdmin key pair is generated outside the browser context and the SuperAdmin certificate will be created from a Certificate Signing Request.

Refer to the following sections for details on each of these options.

The certificate and corresponding key pair is a vital component of your system. Protect and back it up with the same care that you apply to the backups and data of the Hardware Appliance itself. Anyone in possession of this certificate can manipulate your installation. Without this certificate, you have no access to the Hardware Appliance.

Get PKCS#12 key store

A PKCS#12 key store is a format for storing both private keys and certificates protected by a password. Select this option to download such a key store that contains both a SuperAdmin certificate and the corresponding key pair. You will then have to manually import the .p12-file into the browser using the PKCS#12 protection password shown to you.

Proceed as follows to download a PKCS#12 key store:

  1. Select Get PKCS#12 key store and click Proceed.
  2. Copy the PKCS#12 protection password. You will need it for a later step.
  3. Click Get SuperAdmin PKCS#12 key store. The EJBCA Token Certificate Enrollment page opens in a new tab.
  4. Select a Key specification in the EJBCA Token Certificate Enrollment page. It must match your organization’s security requirements. Click Enroll:

    Get PKCS#12 key store
  5. You will be prompted to save the .p12 file. Download the file to the local machine, and close the tab.
  6. In the installation wizard tab, make a note of the PKCS#12 protection password. With your browser’s import mechanism import the .p12 file using the PKCS#12 protection password.

  7. When the .p12 has been successfully imported, click Finalize installation.

Use legacy browser enrollment

Proceed as follows to use the legacy browser enrollment:

  1. Select Use the legacy browser enrollment and click Proceed.
  2. Click Get SuperAdmin certificate. The EJBCA page opens in a new tab.
  3. Click Enroll in the EJBCA page. This allows your browser to generate a key pair, request the certificate from the Management CA, and automatically install the certificate in your browser:

    Using legacy browser enrollment
  4. Click OK to confirm the information message and close the tab.

  5. In the installation wizard tab, click Finalize installation.

Get certificate from CSR

Only enroll the initial SuperAdmin certificate with the option Get certificate from CSR (Certificate Signing Request) if you cannot use any of the other methods. Creating the CSR and installing the resulting certificate so that it is usable for client TLS authentication is outside the scope of this document.

Proceed as follows to get a certificate from a CSR:

  1. Select Get certificate from CSR and click Proceed.
  2. Make a note of Enrollment username and Enrollment code. Click Go to SuperAdmin enrollment page to open the Certificate enrollment from a CSR page.

    Get a certificate from a CSR Credentials


  3. Enter the Enrollment username and Enrollment code from the previous page.

  4. Select or paste the certificate signing request you want to use to issue the initial SuperAdmin certificate.

  5. Click OK:

    Get a certificate from a CSR Enrollment
  6. Click Download certificate on the Certificate Created page

  7. Install the certificate using a proprietary method. Close the tab when done.

  8. In the installation wizard tab, click Finalize installation.

Finalize Installation

After you clicked Finalize installation, finalizing will take about 30 seconds. The browser will reload the page and ask you to confirm the client side certificate used for authentication.

Certificate Selection

If you use different AdditionalSubjectDN for the different installations, the matching certificate should be pre-selected. If you need to delete certificates from your browser later, you will have to restart your browser for these changes to take full effect.

Some antivirus software performs a Man-in-the-Middle (MITM) on all TLS connections. In such a case, the wizard will stop the finalization step and will display the following message:
"Another client session is currently installing."
To avoid this, you must turn off the MITM feature in your antivirus software or completely disable the software.


Configuration changes are only permanent after approximately one hour or when the Hardware Appliance is properly shut down and rebooted. Therefore a power outage right after installation can lead to lost configuration changes. Please keep that in mind if you are running a test installation on your desk or in a test lab.