Online Help · © 2020 PrimeKey Published by PrimeKey Solutions AB Solna Access, Sundbybergsvägen...

Release date: May 2020

Online HelpPKI Appliance 3.5.1

© 2020 PrimeKey

Published by PrimeKey Solutions AB

Solna Access, Sundbybergsvägen 1

SE-171 73 Solna, Sweden

To report errors, please send a note to [email protected]

Notice of Rights

All rights reserved. No part of this book may be reproduced or transmitted in any form by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of the publisher. For more information on getting permission for reprints and excerpts, contact [email protected]

Notice of Liability

The information in this book is distributed on an “As Is” basis without warranty. While every precaution has been taken in the preparation of the book, neither the authors nor PrimeKey shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the instructions contained in the book or by computer software and hardware products described in it.

Trademarks

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and PrimeKey was aware of a trademark claim, the designations appear as requested by the owner of the trademark. All other product names and services identified throughout this book are used in editorial fashion only and for the benefit of such companies with no intention of infringement of the trademark. No such use, or the use of any trade name, is intended to convey endorsement or other affiliation with this book.

mailto:[email protected]

mailto:[email protected]

Table of Contents

1 Introduction .........................................................................................................................61.1 Technical Specifications ................................................................................................................................ 6

1.2 Model Specifications ...................................................................................................................................... 7

1.2.1 Hardware Appliance Models .......................................................................................................................7

1.2.2 Model Comparison Overview ......................................................................................................................8

2 Appliance Installation ...................................................................................................... 112.1 PKI Appliance Unboxing ............................................................................................................................... 11

2.1.1 Scope of delivery....................................................................................................................................... 11

2.1.2 Overview - Front ........................................................................................................................................ 12

2.1.3 Overview - Back......................................................................................................................................... 13

2.1.4 Taking into Operation / Powering Up ...................................................................................................... 14

2.2 Initial Set-up................................................................................................................................................... 15

2.2.1 Step 1: External Erase and Factory Reset................................................................................................ 15

2.2.2 Step 2: One Time Password and TLS Fingerprint ................................................................................... 17

2.2.3 Step 3: Changing the IP Address of the PKI Appliance .......................................................................... 18

2.2.4 Step 4: Connecting to the PKI Appliance................................................................................................. 19

2.2.5 Step 5: Running WebConf Wizard ............................................................................................................ 20

2.3 Restore from Backup.................................................................................................................................... 34

2.3.1 Restore Standalone System from Backup .............................................................................................. 34

2.4 Connect to Cluster ........................................................................................................................................ 35

2.5 Using external CA for installation ................................................................................................................ 36

2.5.1 Step 1: Configuring the smart card in Firefox ......................................................................................... 37

2.5.2 Step 2: Installing the first PKI Appliance ................................................................................................. 39

2.5.3 Step 3: Installing PKI Appliance with existing Management CA............................................................ 44

3 Appliance Operations ...................................................................................................... 463.1 Basic Hardware Operations ......................................................................................................................... 46

3.1.1 Audible Feedback ..................................................................................................................................... 46

3.1.2 Smart Card Handling ................................................................................................................................ 47

3.1.3 PKI Appliance Battery Adapter................................................................................................................. 53

3.2 WebConf - Configurator of PKI Appliance................................................................................................... 56

3.2.1 Status......................................................................................................................................................... 57

3.2.2 Network ..................................................................................................................................................... 57

3.2.3 Access ....................................................................................................................................................... 60

3.2.4 HSM ........................................................................................................................................................... 64

3.2.5 Backup....................................................................................................................................................... 68

3.2.6 Cluster........................................................................................................................................................ 71

3.2.7 Monitoring ................................................................................................................................................. 72

3.2.8 Platform..................................................................................................................................................... 79

3.3 Certificates and trusted CAs ........................................................................................................................ 84

3.3.1 Creating a new TLS server side certificate for Application interface .................................................... 84

3.3.2 Changing client certificate and trusted CA for Management interface................................................. 90

3.3.3 Changing client certificate and trusted CA for Application interface.................................................... 93

3.4 Maintenance.................................................................................................................................................. 95

3.4.1 PKI Appliance State .................................................................................................................................. 95

3.4.2 Reasons for Maintenance ........................................................................................................................ 96

3.4.3 Effects........................................................................................................................................................ 97

3.4.4 Support Packages..................................................................................................................................... 98

3.5 Setting up a VA............................................................................................................................................ 100

3.5.1 Online Certificate Revocation Protocol ................................................................................................. 100

3.5.2 CRL Distribution Point ............................................................................................................................ 100

3.5.3 VA Setup Scenarios ................................................................................................................................ 100

3.5.4 Peer Connector CA-VA setup ................................................................................................................. 100

3.5.5 VA setup for CRL Downloader service................................................................................................... 116

3.6 HA Setup...................................................................................................................................................... 119

3.6.1 Scope of Availability ............................................................................................................................... 119

3.6.2 Continuous Service Availability.............................................................................................................. 120

3.6.3 Levels of Availability ............................................................................................................................... 121

3.6.4 High Availability ...................................................................................................................................... 121

3.6.5 Backup, Restore and Update .................................................................................................................. 123

3.6.6 Cluster shutdown and startup................................................................................................................ 125

3.6.7 Operational Caution ................................................................................................................................ 126

3.7 PKCS#11 Slot Smart Card Activation ........................................................................................................ 127

3.7.1 Introduction ............................................................................................................................................. 127

3.7.2 Installation/Configuration ...................................................................................................................... 127

3.7.3 Application/Activation of a slot ............................................................................................................. 129

4 EJBCA............................................................................................................................. 1304.1 EJBCA Introduction..................................................................................................................................... 130

4.1.1 Certificate Lifecycle Management......................................................................................................... 130

4.1.2 Integration and DevOps .......................................................................................................................... 130

4.1.3 Dynamic and Scalable ............................................................................................................................ 130

4.2 EJBCA Concepts ......................................................................................................................................... 130

4.3 EJBCA Architecture .................................................................................................................................... 131

4.4 Interoperability and Certifications ............................................................................................................. 131

4.5 EJBCA Administration ................................................................................................................................ 131

4.5.1 Accessing EJBCA ................................................................................................................................... 131

4.5.2 EJBCA Administration ............................................................................................................................ 131

4.5.3 CA Operations Guide .............................................................................................................................. 132

4.5.4 RA Operations Guide............................................................................................................................... 132

4.5.5 Command Line Interfaces ...................................................................................................................... 132

4.5.6 EJBCA Batch Enrollment GUI ................................................................................................................. 132

4.5.7 ConfigDump Export and Audit Tool ....................................................................................................... 132

4.6 EJBCA Operations....................................................................................................................................... 133

4.6.1 Certificate Life Cycle Management ....................................................................................................... 133

4.6.2 Creating CA Hierarchy ............................................................................................................................ 135

4.6.3 Managing End Entities............................................................................................................................ 178

4.6.4 Creating Java Truststore........................................................................................................................ 179

5 SignServer ...................................................................................................................... 1845.1 SignServer Introduction .............................................................................................................................. 184

5.2 Accessing SignServer ................................................................................................................................. 184

5.3 SignServer Administration Web ................................................................................................................ 185

5.3.1 Administration Web pages ..................................................................................................................... 186

5.4 SignServer Operations ................................................................................................................................ 186

5.4.1 Use-Case: Setting up a PDF Signer ........................................................................................................ 186

5.4.2 Use-Case: Signing and Verifying PDF .................................................................................................... 189

5.4.3 Use-Case: Rekeying Signer..................................................................................................................... 190

PKI APPLIANCE ONLINE HELP - INTRODUCTION

PKI APPLIANCE © 2020 PRIMEKEY 6 (192)

1 IntroductionPrimeKey PKI Appliance brings all components needed to successfully deploy and operate a full-blown Public Key Infrastructure (PKI). It includes a complete Certificate Management System (CMS), with an unlimited number of Certification Authorities (CAs) and/or subordinate CAs, Registration Authority (RA) and a Validation Authority (VA).

An integrated FIPS 140-2 Level 3 Certified HSM brings enterprise-grade security keeping all cryptographic keys secure.

Depending on the requirements PrimeKey offers different PKI Appliance models to address your needs.

Easy and effective management is the key to a secure and reliable PKI deployment. PrimeKey PKI Appliance offers a web-based interface including all functions needed for a straightforward deployment and effective operation. For more information, see WebConf - Configurator of PKI Appliance.

1.1 Technical SpecificationsThe following lists technical specifications of the hardware appliance.

Technical Specifications

Form Factor 2U

Dimensions Height: 88,4 mm (3 1/2 inch)Width: 430 mm (17 inch)Depth: 633 mm (25 inch)

Weight 12,5 kg (27.5 lb)

Safety Agency Approval CE, RoHS, FCC

Power Supply Dual 300 W

AC Power 110/240 V, 50/60 Hz

Power Consumption Idle 80 W, max 135 W

Network Ports 2 x 1 Gigabit Ethernet (GbE)

Environmental Temperature

Operational Environment +10°C - +50°C (+50°F - 122°F)

Storage Environment -10°C +55°C (+14°F - 131°F)



1.2 Model SpecificationsPrimeKey EJBCA Hardware Appliance offers the complete feature set needed to operate a comprehensive, highly available PKI. It is based on PrimeKey EJBCA Enterprise, with easy-to-use management functions, high-performance hardware and a built-in FIPS 140-2 Level 3, certified Hardware Security Module (HSM).

Depending on your requirements, we offer different Hardware Appliance models to address your needs.

1.2.1 Hardware Appliance ModelsAll models include EJBCA Enterprise with a core library for Certificate Authority (CA), Registration Authority (RA), and Validation Authority (VA) functionality capable of hosting an unlimited number of CAs.

Extra Small (XS)Model Extra Small is the smallest hardware appliance with support for up to 1,000 certificates. This model is ideal for an offline Root CA in a PKI deployment.

The model Extra Small includes an entry-level performance Hardware Security Module (HSM). If standard or high-speed performance is required, refer to the models Medium, Large, or Extra Large, see the Model Comparison Overview below.

Small (S)This is your PKI start environment - EJBCA with everything you need. The Small model supports the operation of multiple, independent PKI hierarchies with one installation. In addition, this model includes Registration Authority (RA) functionality and highly flexible integration interfaces based on web services, REST API, and support for ACME, CMP v2 RFC 4210, SCEP, and EST. This model supports up to 1 M certificates. Many customers are utilizing the Small model for test or lab environments.

The model Small includes an entry-level performance Hardware Security Module (HSM). If standard or high-speed performance is required, refer to the models Medium, Large, or Extra Large, see the Model Comparison Overview below.

Medium (M)Model Medium is the right choice if you already know that you need more certificates and better certificate issuing performance. This model supports up to 15 million certificates.

The model Medium includes a standard performance Hardware Security Module (HSM). If high-speed performance is required, refer to the models Large or Extra Large, see the Model Comparison Overviewbelow.

Large (L)Model Large has an increased certificate issuing performance and can manage even more certificates. If you have one or a couple of use cases that require a high number of certificates, and you soon expect to add



additional use cases on top, then you should choose this model. This model supports up to 60 million certificates.

Extra Large (XL)Model XL is suited for extremely large PKI deployments with the need for more than 100 million certificates. It has the same certificate issuing performance as model Large, but supports up to 160 million certificates and has upgraded storage.

Validation Authority (VA) ApplianceValidation Authority (VA) hardware appliance is a standalone, turn-key solution that brings all components needed to deploy and operate a Validation Authority (VA). It includes a complete OCSP responder, serving an unlimited number of Certification Authorities (CAs), and a CRL and CA certificate download service and an integrated HSM. The VA hardware appliance is available as a standard level performance model and as a high-speed performance model.

Registration Authority (RA) ApplianceRegistration Authority (RA) hardware appliance model is a standalone toolbox that provides for enrollment of certificates for people, software, or things. It is often desirable to physically separate CA and RA, allowing the CA to reside in a secure environment with minimal access, while the RA can reside in a DMZ or even publicly. The standalone RA hardware appliance enables an additional layer of security around the CA.

1.2.2 Model Comparison OverviewThe following provides a model comparison overview.

EJBCA Hardware Appliance

Extra Small

Small Medium Large Extra Large

VA Standard

VA High-speed

RA

Software stack: EJBCA Enterprise & PrimeKey Secure Linux (Prime LFS)

Protocols & API’s



Certificate Validation (OCSP/CRL)

CRL CRL

SCEP

CMP

EST

ACME

WebServices API

REST API

Key Features

Certificate Capacity *

Up to 1 K Up to 1 M Up to 15 M

Up to 60 M

Up to 160 M

NA NA

NA

Secure & Automated Backup Mechanism

2 Factor Authentication

FIPS 140-2 Level 3 validated HSM inside

Entry-level performance HSM inside

NA NA

NA

Standard performance HSM inside

High-speed performance HSM inside

Dedicated Mng & App Interfaces

Redundancy



SNMP, Syslog, Audit Log

Accessories

SmartCards Not included

10 10 10 10 10 10

10

PinPad Reader Not included

1 1 1 1 1 1 1

External Battery adapter

For testing purposes, it is possible to run CA, VA, and RA on one single instance of the appliance.

*Based on EJBCA Version 7.3.x, audit log on, typical key sizes (RSA 3072 SHA 384 with RSA), typical subject DN length: 100 characters. Synthetic benchmark with a certificate revoked once a second and no further system usage.

PKI APPLIANCE ONLINE HELP - APPLIANCE INSTALLATION


•••••

2 Appliance InstallationPKI Appliance UnboxingInitial Set-upRestore from BackupConnect to ClusterUsing external CA for installation

2.1 PKI Appliance UnboxingCongratulations! You have obtained the PKI Appliance from PrimeKey Solutions AB.

The sections below contain information on the scope of delivery as well as details about the PKI Appliance device.

2.1.1 Scope of deliveryThe PKI Appliance package contains the following items:

1 Quality Assurance Test Report The PKI Appliance Test Report lists the quality checks that have been performed. It is signed by PrimeKey authorized personnel.

1 Packing List

1 PKI Appliance

1 set of mounting rails with a mounting instruction and a set of screws



4 mains cables, one pair each for European and American standard

1 PIN pad and 10 smart cards (optional)

2.1.2 Overview - FrontThe following illustrates the front view of the PKI appliance.



1.

2.3.4.5.6.

7.

8.9.

10.

11.

Figure 1: Front View of the PKI Appliance

Four bays for customer serviceable hard disks, Solid State Disks (SSD), for database and RAID1.Two disks are provided, two bays are empty.SSD Slot 0SSD Slot 1SSD Slot 2, emptySSD Slot 3, emptyCooling ventsDo not obstruct the vents.Status LED row:Green LED: Power Red LED: Hard DiskYellow LED: InfoFront display for status information and IP address configuration messagesMenu buttons to operate the front display:Up, Down, Enter, CancelFront USB ports:The ports are suitable for PIN pad connection.Power button, ATX power supply

2.1.3 Overview - BackThe following illustrates the back view of the PKI appliance.



1.2.3.4.5.6.7.

8.9.

10.

1.2.3.4.5.6.

Figure 2: Back View of the PKI Appliance

PKI Appliance serial numberTwo power supply units (PSU), redundantMainboard serial connection, not operationalMainboard USB ports, suitable for PIN pad connectionApplication network interface (left) and Management network interface (right)Mainboard VGA connector, not required for operationHardware Security Module (HSM)Do not use the USB port or the buttonsConnector for external battery and test automationSafeguarded External Erase button for Factory ResetAdditional network interfaces, currently not activated

2.1.4 Taking into Operation / Powering UpNote the following when taking the PKI Appliance into operation and powering it up.

Make sure the seal at the right side of the PKI Appliance is intact and untampered.Make sure the serviceable hard disks are sitting properly in their bay.Make sure the PSUs sit properly.Connect the power cord.Connect the network cables.Power on the machine to start booting. Booting will take about 5 minutes.

Default IP addressWe recommend to connect the network cables before booting and starting the installation.The default IP addresses used by the PKI Appliance are 192.168.5.160 and 192.168.5.161. If these IP addresses are already in use in your network this will lead to an IP address conflict.



•••••

•••••

2.2 Initial Set-upWith the initial setup, you will transfer the PKI Appliance from its delivery state to a production setup. During this process, you will configure all components of the system. The initial setup requires the following steps:

Step 1: External Erase and Factory ResetStep 2: One Time Password and TLS FingerprintStep 3: Changing the IP Address of the PKI ApplianceStep 4: Connecting to the PKI ApplianceStep 5: Running WebConf Wizard

2.2.1 Step 1: External Erase and Factory ResetWith a Factory Reset, the PKI Appliance is reset to factory defaults. For this defined state, all configuration files and sensitive information are deleted. This includes, for example, cryptographic keys on the Hardware Security Module (HSM) or certificates in the CA database.

You need to perform a Factory Reset in the following cases:

The PKI Appliance is set up for the first time.Access is lost to the PKI Appliance.The PKI Appliance is reinstalled.Secret data needs to be erased.The PKI Appliance switches from testing or demo system to production system.

••

Network cablesPlease connect the network cables before starting the initial setup. You will find the network interfaces on the back of the PKI Appliance:

The left port is for the Application Interface. Its default IP address is 192.168.5.161.The right port is for the Management Interface. Its default IP address is 192.168.5.160.

When you execute the external erase and factory reset, all sensitive data will immediately be erased from the HSM. You can then only restore the data from an existing backup and, if required, with Backup Key Share smart cards.



1.

2.

3.

4.

5.6.

7.

Figure 3: Placement of the External Erase button

Proceed as follows to perform a Factory Reset on the PKI Appliance:

Turn on the appliance and wait until it is booted up.When booting is complete, you will see information pages scrolling through the display at the front.Locate the External Erase button on the back of the PKI Appliance: The button is hidden in a hole underneath the integrated Hardware Security Module (see illustration above).Press the External Erase button with a pen to erase all data.For confirmation, the PKI Appliance will flash a light and you will hear a confirmation sound. Please note that an appliance already in a factory reset state will not emit a confirmation sound or a flashing light.

In the front display, together with the other information pages a new message appears: Factory Reset: Reboot Required.Briefly press the power button on the front panel to start rebooting the PKI Appliance.Confirm the Reboot option in the display by using the display buttons.The appliance reboots and clears all configuration files.After successfully rebooting, the PKI Appliance display shows a cycle of the current Management Interface IP address, the initial Transport Layer Security (TLS) Fingerprint, and additional information, like software version and the One Time Password (OTP).

••

Confirmation of External Erase: Known issuesIn most cases, pressing the External Erase button is confirmed by flashing a light and by a confirmation sound. However, we have noticed the following issues:

In some cases, there is no light flashing.In some cases, the confirmation sound may take up to 10 minutes to appear. This can happen if you press the button twice – for example, because the pen slipped off the button and was placed there again.

Even if the confirmation takes longer than expected: As soon as you press the External Erasebutton, the HSM deletes the data. To ensure that the factory reset was successful, you can scroll through the information pages of the appliance display for the message Factory Reset: Reboot Required.



•

•

1.2.

3.4.

5.

2.2.2 Step 2: One Time Password and TLS FingerprintDuring the setup process you will need the One Time Password (OTP) and the TLS Fingerprint for the following:

TLS Fingerprint: You have to confirm the TLS Fingerprint when you first connect to the PKI Applianceto run the WebConf wizard. The shortened TLS Fingerprint shown in the PKI Appliance display refers to the TLS certificate that secures the connection between your web browser and the configurator WebConf.One Time Password (OTP): You have to enter the OTP when you initially run the WebConf wizard. The OTP will become invalid after the installation has been successfully accomplished.

Proceed as follows to retrieve the 'One Time Password (OTP)' and the 'TLS Fingerprint':

Make sure the appliance is powered and booted up completely.Use the Up and Down buttons of the display to scroll to the page with the OneTimePassword:

Figure 4: Front Display showing the One Time Password

Write down the OneTimePassword. You will need it for the web-based part of the installation process.Use the Up and Down buttons of the display to scroll to the page with the TLS Fingerprint - TLS SHA 256 FP:

Figure 5: Front Display showing the TLS Fingerprint

Write down the TLS Fingerprint. When you connect to the PKI Appliance you will be asked to compare it with the fingerprint of the TLS certificate in your browser. This is to make sure that you are accessing the correct device.

Please NoteIf you need to interrupt the Initial Set-up process here, select the option Shutdown in Step 6.To resume the Initial Set-up at a later stage, power up and boot the PKI Appliance and continue with Step 2: One Time Password and TLS Fingerprint.Such a clean shutdown and reboot is required to delete the configuration. Do not perform a hard power fail, as this will not ensure a clean reboot.



1.2.

3.4.5.6.

7.

8.

2.2.3 Step 3: Changing the IP Address of the PKI ApplianceYou will always find the IP address of the Management Interface in the front display of the PKI Appliance. After a factory reset, this will default to 192.168.5.160.

Figure 6: Front Display showing the IP Address

If this default IP address of the Management Interface does not match your network configuration, you can change it to fit your needs. However, it is preset to have a network prefix of /24, resulting in a subnet mask of 255.255.255.0.

Proceed as follows to change the IP Address of the PKI Appliance:

Scroll the display pages to the IP address and press the OK button.The IP address will be presented with leading zeroes. The cursor will start at the first digit of the first byte of the IP address.

Figure 7: Changing the IP Address

Press the Up and Down buttons to adjust the digit to your target IP address.Press √ to confirm this digit. The cursor will move to the next digit.Repeat steps 3 and 4 for every digit.When you confirm the last digit by pressing √, a prompt asks you to confirm the IP address.The IP address will be shown without leading zeroes.Press √ to confirm the new IP address. You can also cancel this operation at any time by pressing the x button.Take a note of the new Management Interface IP Address. You will need it to connect to the PKI Appliance via the configurator WebConf.

Remember to write down the OneTimePassword and the TLS SHA 256 FP (TLS Fingerprint). You will need them at a later stage of the installation process.

As the 100.64.0.0/10 network range is used for the PKI Appliance's internal networking, IP addresses in this range are not allowed as external management or application network address.



1.

2.

3.4.5.6.

1.

2.2.4 Step 4: Connecting to the PKI ApplianceTo establish the connection to the PKI Appliance, you have to verify the TLS certificate by confirming the TLS fingerprint. For this, you will need the TLS fingerprint as described in Step 2: One Time Password and TLS Fingerprint.

Proceed as follows to connect to the PKI Appliance:

Open your browser and enter the IP address of the Management Interface.You have assigned this address in Step 3: Changing the IP Address of the PKI Appliance.Click Connect to management interface over TLS:

Figure 8: Connect to the PKI Appliance using TLS

Your browser will ask you to select a certificate.Click Cancel. The dialog Potential security risk ahead opens.Click Advanced. An info box on the certificate requirements opens.Click Accept the risk and continue. You will return to the WebConf page Verify TLS Certificate:

Figure 9: Verify TLS Certificate

Proceed as follows to check the fingerprint of the TLS certificate and compare it to the TLS fingerprint of the PKI Appliance:

Click the Padlock icon in the address bar of your browser.

The new IP address will be committed. Please note that this operation can take up to 10 seconds.



2.

3.4.

5.

6.

•••••••

Click > to expand the information for Connection is Not Secure. This opens information on the security of your connection.Click More Information and then View Certificate to open the Certificate Viewer. In the Certificate Viewer, find the SHA256 Fingerprint and compare it to the TLS fingerprint of the PKI Appliance.If the two fingerprints match, the appliance is connected to the correct machine.Close the Certificate Viewer panel.

Figure 10: Certificate Information

Click The fingerprints are the same in the Appliance certificate verification page (see Verify TLS Certificate).The Authenticate page will open and you can proceed with Step 5: Running WebConf Wizard.

2.2.5 Step 5: Running WebConf WizardThe 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:

Initial Log InFresh InstallationNetwork SettingsDate and Time SettingsManagement CA SettingsHardware Security Module SettingsSecurity Settings - Secrets



•••

1.2.

••••

Summary and Begin installationChoose SuperAdmin CredentialsFinalize Installation

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

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

Figure 11: Entering the OTP

Fresh InstallationAfter your login with the OTP on an unconfigured PKI Appliance you will have the following options:

Fresh installRestore system from backupConnect to clusterUpdate

Click Next in the section Fresh install.

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.



•

•

1.

2.3.

Figure 12: Installation Choices

Network SettingsAfter the Fresh Install is complete, you can configure the network settings of the PKI 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 PKI 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.

Proceed as follows to configure the Network Settings:

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

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.



1.2.

3.4.

Figure 13: Network Settings

Date and Time SettingsMany 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.

Proceed as follows to configure the Date and Time Settings:

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

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.



1.2.

a.b.

c.

3.•••

Figure 14: Date and Time Settings (NTP)

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

Proceed as follows to configure the Management CA Settings:Enter the Common Name of the EJBCA Management CA.Add the Additional Subject Fields, such as organization and country:

It is important to specify a meaningful identifier as the Additional Subject Fields.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.If you want to perform several test and/or demo installations, this is where the name can be branded.

Add the Signature Algorithm to be used by the EJBCA Management CA:SHA1withRSASHA256withRSASHA256withECDSA

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.



4.••••

5.6.

1.2.3.

4.5.6.

Enter the signing Key Specification strength:ECDSA - secp256r1 / prime256v1 / P-256RSA 1024RSA 2048RSA 4096

Enter the SuperAdmin Common Name. This is the name of the first post-install administrator.Click Next: Security.

Figure 15: Management CA Settings

Hardware Security Module Settings

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

Proceed as follows to configure the Hardware Security Module Settings:

Select the desired Appliance Security Level option. See below for more information.Select a provider for PKCS#11 Stack Generation.Select whether CryptoToken/PKCS#11 Slot Smart Card Authentication is needed or not. See below for more information.For the option Yes, require smart card ... you need to enable the appropriate further options.Select Store signed audit log, if needed. See below for more information.Click Next: Secrets.

Security settings cannot be altered after the installation.



1.2.

Figure 16: Security Settings

Appliance Security Level - Detailed information

Define 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 PKI Appliance needs to be restored from a backup:

Import the Backup Key into the HSM to decrypt with 2 of the 3 initial smart cards.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 PKI Appliance without smart cards and use software based keys, which are stored on the PKI 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 (as of PKI Appliance 2.2.0). For more information about smart card activated slots, please refer to the section PKCS#11 Slot Smart Card Activation.

Crypto Token/PKCS#11 Slot Smart Card Authentication - Detailed information

No, application start Crypto Token activation should be possible remotely:The manually generated authentication codes will enable remote activation from any device allowed to access the WebConf or the Adminweb. These codes are stored encrypted in a database.Yes, require smart card authentication for Crypto Token activation:Physical access to the appliance with a PIN PAD and the administrator's smart cards and codes are required in order to activate these crypto tokens.

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

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

Note that the smart card activation for PKCS#11 slots is not available with HSM FIPS Mode.

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



1.

2.3.

Figure 17: Security Settings - Secrets

Summary and Begin installationThe Summary step lists all configuration settings from the previous wizard steps. We highly recommend to double-check everything on this page before starting the actual installation. We also recommend to print this page for future reference.

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

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.Click Begin installation at the bottom of the page. The installation will take a few minutes.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.

•

•

If smart cards were used for setup, ensure the following:Connect the PIN pad, included in the delivery, to one of the USB ports at the front of the PKI 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.



Figure 18: Confirm installation choices

Choose SuperAdmin CredentialsYou need a client side SuperAdmin TLS certificate for managing the PKI 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:

1.2.

When using smart cards 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:

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



•

•

•

1.2.3.

4.

Figure 19: 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 PKI 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.

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:

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

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 PKI Appliance itself. Anyone in possession of this certificate can manipulate your installation. Without this certificate, you have no access to the PKI Appliance.



5.6.

7.

1.2.3.

4.5.

Figure 20: Get PKCS#12 key store

You will be prompted to save the .p12 file. Download the file to the local machine, and close the tab.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.When the .p12 has been successfully imported, click Finalize installation.

Use legacy browser enrollment

Proceed as follows to use the legacy browser enrollment:

Select Use the legacy browser enrollment and click Proceed.Click Get SuperAdmin certificate. The EJBCA page opens in a new tab.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:

Figure 21: Using legacy browser enrollment

Click OK to confirm the information message and close the tab.In the installation wizard tab, click Finalize installation.

Get certificate from CSR



1.2.

3.4.

5.

Proceed as follows to get a certificate from a CSR:

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

Figure 22: Get a certificate from a CSR Credentials

Enter the Enrollment username and Enrollment code from the previous page.Select or paste the certificate signing request you want to use to issue the initial SuperAdmin certificate.Click OK:

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.



6.7.8.

Figure 23: Get a certificate from a CSR Enrollment

Click Download certificate on the Certificate Created pageInstall the certificate using a proprietary method. Close the tab when done.In the installation wizard tab, click Finalize installation.

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

Figure 24: Certificate Selection



•••

•

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

2.3 Restore from BackupYou can only restore a backup file to a fresh and unprovisioned machine. You will need the following:

The backup file on a Network File System (NFS) shareThe Domain Master Secret that you specified when installing the first machine of your environment.The smart cards required by your Appliance Security Level.For more information about the Domain Master Secret, the Appliance Security Level, and smart cards, see Initial Set-up.

In a cluster environment, only restore a backup in an utmost emergency, for example, if all of the cluster nodes have proven to be non-operational. If at least one cluster node is still operational, you should always reconfigure a broken cluster from the last remaining node.For general information about clustering and High Availability (HA) setup, see HA Setup.For information on how to proceed with either bringing back a PKI Appliance into your cluster or, as a last resort, restore a cluster node from backup, see Backup, Restore and Update.

2.3.1 Restore Standalone System from Backup

PrequisitesDomain Master Secret.

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

Product size variationsYou can only restore a backup to a matching or bigger product size version. For example, a backup from a model M product size can only be restored to hardware of M or L product size.

As of version 2.4.0, the PKI Appliance will not be able to restore from backup data created on a PKI Appliance with versions older than 2.2.0.



•

•

1.2.3.

4.5.6.7.8.

9.

Security level requirements: PIN pad, the persons with their smart cards and their PINs.For a PKI Appliance that has been configured with a low Appliance Security Level, for example for demo and testing purposes, this is not required.Physical access to the PKI Appliance.

Restore Stand-Alone SystemProceed as follows to restore a stand-alone system from backup:

Switch on the PKI Appliance and wait for it to finish booting. This will take about 5 minutes.Configure the network settings by using the functions of the front display.Scroll through the front display screens and write down the One Time Password (OTP) and the TLS Fingerprint.Connect the Management Interface of the PKI Appliance to the network.In Firefox, go to the configured IP address and log in using the One Time Password.In the installation page of the WebConf wizard, click Restore system from backupEnter the connections details of your NFS server where your backup is stored.The restoration of the backup can take up to several hours depending on the size of your backup.Depending on the configuration of your initial system, the restore procedure will prompt you to connect a PIN pad and provide the backup protection smart cards.At the end of the restore procedure you will be asked to reboot the system. If you have not done that already, you can now safely connect the second network cable to the Application Interface.

Note that the rebooted system will have the restored configuration including for example IP address and SuperAdmin certificates.

2.4 Connect to ClusterYou can add a fresh and unprovisioned PKI Appliance to an existing cluster. You can also add it to another standalone PKI Appliance to start a cluster.

Start the procedure either on any node that is already part of the cluster or on the standalone machine that is already installed. When starting the procedure on that node, you'll be given instructions to download a so-called cluster bundle. This cluster bundle will then be needed when going through this part of the wizard.

You will also need the Domain Master Secret that you specified when installing the first machine of your environment and a copy of the Backup key share smart cards that were created when installing the first machine of your environment.

For more information on the Domain Master Secret, the Appliance Security Level, and smart cards, see Initial Set-up > Step 5: Running WebConf Wizard, sections Hardware Security Module Settings and Security Settings - Secrets.

Product size variants S - M - LDo not mix product size variants in a cluster. A filled hard disk will stop the database working. The smallest node of your setup will stop working first - and thus reduce redundancy.



1.2.3.

•

•

If you are changing a standalone setup to a multi-node cluster or extending an existing cluster with additional nodes, review the section HA Setup.

After logging in to the PKI Appliance, using the One Time Password from the front panel display, and selecting to connect to a cluster, you will be guided through a short wizard. For more information on the One Time Password, see the section Initial Set-up > Step 2: One Time Password and TLS Fingerprint.

2.5 Using external CA for installation

You can install two different PKI Appliances with the same ManagementCA certificate. For this process, the certificate is installed in a smart card. This form of installation requires the following steps:

Configure the smart card in Firefox.Install the first PKI Appliance and install the SuperAdmin certificate in the smart card.Install the second PKI Appliance with the existing ManagementCA certificate.

These steps cover the following typical use case:

The ManagementCA is the super-administrator for operating both PKI Appliances, Node A and Node B.In the logical hierarchy, ROOTCA functions as a the root certification authority which signs 3 different subCAs: SignCA, AuthCA, and SSLCA.

Compare the following illustrations:

Figure 25: Logical hierarchy

In many cases ROOTCA is required to be offline, therefore the physical infrastructure shown below differs from the logical hierarchy in the illustration above. In the first PKI Appliance Node A, the ManagementCA is installed together with the 3 subCAs:



•••

1.

Figure 26: Physical Infrastructure of Node A (online)

The second PKI Appliance Node B will host the ROOTCA. This will be offline directly after signing the subCAs:

Figure 27: Physical Infrastructure of Node B (offline)

2.5.1 Step 1: Configuring the smart card in FirefoxFor the following process description, we have used the following:

Smart card: MARX CrypToken from SafeSignOperating system: Ubuntu14.04Drivers used for the smart card: SafeSignIdentityClient-3.0-33.amd64.deb

The process can be followed analogously with smart cards from different branches.

Proceed as follows to install the super admin certificate via Firefox:

In Firefox open Preferences, navigate to the Advanced tab and click Security Devices:

For more information on general installation instructions, see the Initial Set-up sections.



2.

3.

Figure 28: Firefox: Security Devices

The Device Manager opens and lists Security Modules and Devices. Click Load to define a new security device:

Figure 29: Firefox: Device Manager

Enter Module Name and Module filename. The value for Module filename has to point to the library that the smart card is using:



4.

5.

1.

Figure 30: Firefox: Load module

The new device is now listed in the Device Manager window. To log in to the device, click Log In and provide the master password of the smart card:

Figure 31: Firefox: Smart card login

With the successful login the smart card is configured correctly with Firefox:

Figure 32: Firefox: Successful smart card login

2.5.2 Step 2: Installing the first PKI ApplianceIn Firefox, enter the IP address that you have configured for the PKI Appliance. The browser prompts you that this connection is untrusted:



2.

3.

4.

Figure 33: Appliance Login: Untrusted Connection

You can trust the connection if the TLS finger print is the same as the one the PKI Appliance display. To check this, click Add Exception and then View...:

Figure 34: Appliance Login: Add exception

In the Fingerprints section, find SHA1 Fingerprint. The first values have to match with the TLS finger print in the PKI Appliance front display:

Figure 35: Appliance Login: Check TLS fingerprint

Click The finger prints are the same to trust the TLS certificate. Through TLS fingerprint, the PKI Appliance is authenticated to you:



5.

6.

•••••

1.

Figure 36: Appliance Login: Confirm TLS fingerprint

In the Authenticate section, enter the One Time Password (OTP) in the field Authentication code. You will find the OTP in the PKI Appliance display:

Figure 37: Appliance Login: Enter OTP

Before the installation process begins, you will have to go through the following configuration steps:

Select the installation optionConfigure network settingsConfigure date and time zoneConfigure Management CACheck the pre-installation summary

For more information on these settings refer to the sections in Initial Set-up.

Getting the superadmin certificate

After the installation you need to get the superadmin certificate to finalize the process. Proceed as follows:

Click Enroll and choose the security device to be used for enrollment:

Figure 38: EJBCA: Enroll process



2.

3.

4.

5.

When prompted, enter the smart card password:

Figure 39: EJBCA: Enter smart card password

The certificate will be generated. Wait for the confirmation that enrollment is complete and that certificate is installed in the smart card:

Figure 40: EJBCA: Successful enrollment

To finalize the installation, log in to the PKI Appliance or EJBCA's Public Pages and choose the certificate to authenticate to the system:

Figure 41: Authentication to the system

Confirm the connection and then confirm the exception with Confirm Security Exception:



6.7.

8.

Figure 42: Firefox: Confirm connection

Go to IP_ADDRESS_application/ejbca in EJBCA's Public PagesIn the section Retrieve > Fetch CA Certificates click Download as PEM to download the Management CA certificate:

Figure 43: EJBCA: Public Pages > Fetch CA certificates

Go to IP_ADDRESS > WebConf > Access tab and copy the clientcert value. You will need it to install the next PKI Appliance:



1.

2.3.

4.

Figure 44: WebConf > Access tab: Copy clientcert

2.5.3 Step 3: Installing PKI Appliance with existing Management CAInstall this PKI Appliance as described in Step 2: Installing the first PKI Appliance until you reach the wizard step Management CA Settings.Activate the option Use Existing Management CA.In the field SuperAdmin full Subject DN, paste the value for clientcert that you have copied in the last step of Step 2: Installing the first PKI Appliance:

Figure 45: WebConf > Management CA Setting: Paste clientcert

You can now complete the installation.

Both PKI Appliances are now using the same certificate as super admin, the certificate that is installed in the smart card. Only the first PKI Appliance hosts the ManagementCA.

The following illustration shows the Administration page of the PKI Appliance hosting the ManagementCA.



Figure 46: First PKI Appliance: EJBCA Administration page

The Administration page of the PKI Appliance with ManagementCA looks as follows:

Figure 47: Second PKI Appliance: EJBCA Administration page

PKI APPLIANCE ONLINE HELP - APPLIANCE OPERATIONS


•••••••

•

•

•

•

3 Appliance OperationsBasic Hardware OperationsWebConf - Configurator of PKI ApplianceCertificates and trusted CAsMaintenanceSetting up a VAHA SetupPKCS#11 Slot Smart Card Activation

3.1 Basic Hardware Operations

3.1.1 Audible FeedbackFor an improved feedback, the PrimeKey PKI Appliance has the functionality of issuing some status sound tunes in situations where we found it helpful in our own testing.

The following lists example sounds:

BIOS startup sound:The BIOS (Basic Input Output System, an archaic bootloader to the x86-architecture) of the PKI Appliance does also try to give some status information through a series of short high and low-pitched beeps very soon after switching on the machine.Booting Done:The PKI Appliance has an overall boot time of about 5 minutes before any configuration can take place, during which a boot progress is shown to the front panel display as well as the WebConf. The PKI Appliance announces the end of this boot period with a 3-tone sound similar to a short fanfare; ta-ta-taaa.Factory Reset:If the concealed Factory Reset button has been pressed (see Initial Set-up), the machine will acknowledge this with a 4-tone sound similar to an alarm sound; low-high-low-high. Usually, you should be able to hear this quittance within 5 to 15 seconds after hitting the concealed button. Under certain circumstances, such as if you press that button twice in a very short time span of only a few seconds, it may take up to several minutes for the system to detect this condition. You should not try to reboot the system before having gotten any acknowledgement about the pressed Factory Reset button.PIN Pad Interaction:There is a small sound to raise your attention to the PIN pad. For some operations, you have only about 15 seconds to insert the correct smart card and enter the right PIN to it. The PKI Appliance will also try to give you a hint on which smart card operation is required by a short message on the PKI Appliance physical front display. The message will be visible only shortly though. During Wizard operations like installation, restoring of a backup or adding this PKI Appliance to an existing cluster, there will be more ample explanations in your browser. This sound is a short double; bee-beep.

The machine has more audible feedback for internal uses of manufacturing and testing.



3.1.2 Smart Card HandlingSmart cards are, essentially, Hardware Security Modules (HSM). They might also be called chip cards or integrated circuit cards. SIM cards in cellular mobile phones are also smart cards.

The smart cards that come with the PKI Appliance are preprogrammed cards with the TCOS operating system (TeleSec Chipcard Operating System) and are, as can be seen, branded by the manufacturer of the HSM that we incorporate in the PKI Appliance.

Smart cards can store some amount of information, organized in sets of so-called 'slots'. The data sets can be configured to be protected with a Personal Identification Number (PIN) or not. Also, the slots can have different PINs. This principle of different data across different slots is the PKCS#11 slot activation user smart card foundation of the PKCS#11 standard.

The principle of having the card (ownership) and the PIN (knowledge) is the foundation of Two-Factor Authorization.

Figure 48: Figure: Smart cards with branding

Smart Card Reader or PIN PadA smart card is of no good use if you cannot use it or read it. This is why there is another thing delivered with each PKI Appliance: A smart card reader or also often called PIN Pad. As a matter of fact, a simple smart card reader would be of no big help in this case, since all of the functions that we want to use of these smart cards always require a PIN to be entered. The vendor of the HSM that we incorporate recommends the Model "cyberJack e-com" from "Reiner SCT". The PIN Pad needs to be connected to one of the USB ports of the PKI Appliance. The PKI Appliance itself has two USB ports to the front and two to the back that can be used. Additionally, the HSM that we integrate into the PKI Appliance has a USB port on the back on its own. This USB port cannot be used for our and your PIN Pad purposes. There is currently no possibility to use this PIN Pad for PKI Appliance purposes connected to your workstation/web browser.



Figure 49: Figure: Smard card reader

Usage of Smart CardWith the PrimeKey EJBCA PKI Appliance, the smart cards are used to protect the cryptographic secrets of the HSM, these functionalities are offered by the vendor of the HSM. Precisely, two different functions are implemented with smart cards. These two different functions operate on different slots. These different slots have separate PINs. They are all preset to the default PIN of '123456' when delivered. In theory, one smart card can be used for both functions, but the PINs for both functions/slots need to be changed independently. We generally discourage to use one smart card for both functions since this is bound to lead to confusion.

Backup Key Share smart cards

The first usage of smart cards in the PKI Appliance is to secure the backup of the HSM. Whenever data leaves the HSM, it is encrypted with the Backup Key. They call it the "Master Backup Key" (MBK) and we make use of that, entirely transparent. When you install the PKI Appliance and opt for any of the available smart card options in the Appliance Security Level, such a Backup Key is first generated (in memory), then written to the smart cards, then read back in, from the smart cards into the HSM. From this point on, every bit of information that is downloaded from the HSM with administrative functions (such as "create backup") is encrypted with this Backup Key. This is why you need to have these smart cards at hand if you want to restore a backup: The Backup Key that encrypts the backup files needs to be uploaded to the HSM first. If you configure a PKI Appliance to be a node of a cluster, you also need to have the smart cards at hand, since we initially load the HSM. The Backup Key is spread across these smart cards using a quorum, see next section.

A Backup Key share cannot be restored if it has been overwritten by mistake. This is a good reason to change the PIN of a smart card right after a successful installation to prevent any mix-up or mistake. Another good practice might be to create copies of backup key share smart cards to be stored in a safe place. Also, it might be worth noting that the Backup Key cannot be changed after installation; this would invalidate all existing backup files.



PKCS#11 slot activation user smart card

Smart cards may also be used to store user credentials needed to activate PKCS#11 slots. There is no quorum for user credentials on smart cards. For more information about PKCS#11 slot smart card activation, see PKCS#11 Slot Smart Card Activation.

Note that the user credentials on a user smart card used for PKCS#11 slot activation cannot be copied one-to-one, unlike the backup key share on a smart card.

Quorum ('2 out of 3' or '3 out of 5')The Backup Key is distributed across multiple smart cards to increase security. This way, a potential attacker cannot even read a backup file if he is able to take possession of one smart card with the according PIN. But splitting a Backup Key across multiple smart cards would also have disadvantages: It would decrease usability or ease of handling since you would always need the presence of every single card owner in case of a disaster recovery (and you know how these kinds of things always happen in the worst of moments, think of summertime, holidays and thunderstorms). And it would effectively decrease reliability since a single lost, broken or otherwise deactivated smart card would immediately ruin all your emergency precautions. To get the best of both worlds, the Backup Key is distributed across the smart cards using a method called "Shamir's Secret Sharing" in reference to its inventor, Adi Shamir, a worldwide well known and accepted cryptographer (another reference to his name can be found in the letters of the RSA algorithm). This system is also sometimes called a Quorum or a "k out of n" or "m out of n".

In the application of this method, a cryptographic symmetric key is split into n number of shares so that every combination of k number of shares is sufficient to reconstruct the complete key.

In the case of the PrimeKey PKI Appliance, the software generates a 32 bytes long AES key (symmetric cryptography) and offers the choices of '2 out of 3' and '3 out of 5'. While the latter obviously represents higher applied security, please bear in mind that it implies that you strictly need to have three of those 5 smart card owners available for a disaster recovery, even if service availability agreements force you to bring the system back to life at 5 'o clock on a Sunday morning. This is often called the "Person Is There Always" scenario.

Installation Example for '2 out of 3' scenarioThese things are rather complex and can be confusing. Also, it is a lot of work to "just try this out" since you cannot do this from your workstation or desk. Remember: The PIN Pad needs to be connected to one of the four USB ports of the PKI Appliance itself. This is why we would like to walk you through this step in every detail possible. Furthermore, the timeout on the smart card operations does not really allow for careful reading of the documentation in the middle of the process. Any timeout will not be indicated as such on the PIN Pad display, the display will just turn blank and the information about the timeout will be shown on the WebConf.

For a '2 out of 3' scenario, the procedure includes the steps Key generation and Key reading:

Step: Preamble

After plugging in the PIN Pad, the display will read something like the following:



1.

2.

3.

4.

REINER SCTcyberJack e-com

This text will vanish with any PIN Pad operation, therefore, if you have multiple PIN Pad operations in one session, the display screen might be entirely blank if you start this operation.

Step 1: Key generation

At first, a new Backup Key needs to be generated and the Backup Key Shares need to be written to the smart cards.

Shortly after starting the installation (see Initial Set-up), the PIN Pad will read:

Write New Keypress OK/Cancel

This is only the notification that we are now going to write a new key / key shares to the smart cards. Any former Backup Key Share on these smart cards will be overwritten. A smart card cannot store more than one Backup Key Share. A smart card cannot be used to save two different Backup Key Shares for two different PKI Appliance environment. Every node in a cluster uses the same Backup Key, thus any set of Backup Key Share smart cards will work with every node in a cluster.

As soon as you acknowledge this by hitting the green OK button, the procedure will continue with:

Insert 1. cardpress OK/Cancel

This is the instruction that the first of the smart cards should be inserted.

You should proceed by inserting the first smart card of the set and pressing the green OK button again. The next message of the display will be:

Enter PIN******

Those asterisks appear for every digit of the PIN you enter. The PIN of a fresh an unused smart card delivered with the PKI Appliance is '123456' until it has been manually changed (see Change the PIN of the backup key share on a smart card in Help-HSM. The fact that you have to enter the PIN only once is an indication that you are not defining the PIN (setting the PIN or changing the PIN), but only authenticating (proving you are the legitimate owner of the smart card). You can restart the entry of the PIN by pressing the yellow Clear button or you can abort the entire operation with the red Cancelbutton. If you confirm with the green OK button, there will be a short screen indicating some ongoing operation. Do not remove the smart card while this operation is lasting.

After the short screen indicating the ongoing operation, you'll see this:



5.

6.

7.

1.

2.


This is the instruction that the second smart card of the set should be inserted. A smart card should not be removed from the PIN Pad before the display clearly shows that it is asking for the next smart card.

First, remove the smart card that is in the PIN Pad and insert the second of the smart cards and continue by pressing the green OK button.

Enter PIN******

This is where you enter the PIN of the second smart card.



This is the instruction that the third smart card of the set should be inserted.

Insert the third of the smart cards and continue by pressing the green OK button.

Enter PIN******

This is where you enter the PIN of the third smart card.

Step 2: Key Reading

After the Backup Key has been generated and the shares have been written onto the smart cards, the Backup Key needs to be loaded into the HSM, therefore the Backup Key needs to be reconstructed by reading it from the smart cards. Since the Backup Key is based on the quorum of '3 out of 5' or in this example '2 out of 3' (see Quorum), the complete Backup Key can be reconstructed by reading only 2 smart cards (or 3 smart cards in the scenario of '3 out of 5'). In consequence, it does not matter in which order the cards are read.

Read New Keypress OK/Cancel

This is the notification that we are now going to read the new key / key shares from the smart cards.

If you acknowledge this by hitting the green OK button, the procedure will continue with:

Insert 1. card press OK/Cancel



3.

4.

5.

This is the instruction that the first of the smart cards should be inserted. When reading back in the key in the '2 out of 3' scenario, any two Backup Key Share smart cards will do (as long as you insert two different smart cards rather than inserting the same smart card twice), although the display will ask for the '1.' and '2.'. In consequence, the first smart card to read the key can be the third smart card the was written to. So, for convenience, you can leave the smart card in the device and enter its appropriate PIN.

Press the green OK button again. The next message of the display will be:

Enter PIN******

This is where you enter the PIN. If you confirm with the green OK button, there will be a short screen indicating some ongoing operation.


Insert 2. card press OK/Cancel

This is the instruction that the second smart card of the set should be inserted, which again can be any other of the smart cards.

Insert the next smart card and continue by pressing the green OK button.

Enter PIN******

This is where you enter the PIN. After confirming this with the green OK button, this operation is completed.

•

••

••

Pay attention to the following:Running into a timeout (a timeout message will not be visible on the PIN Pad display, only in WebConf)Entering a wrong PIN for one smart card three times in a row (the smart card will be blocked)Failing to enter two different smart cards for the "Key Reading" part of the sequence (3 cards in case of the '3 out of 5' scenario)Accidental unplugging of the PIN PadInserting a smart card different than the smart cards delivered by PrimeKey

Any reason for the sequence of installation to abort will result in the machine to be in an inconsistent state. You will have to do a full Factory Reset as described in Initial Set-up, and then restart the installation process.



WebConf Smart Card Handling ToolsWebConf offers multiple tools to help handling smart cards properly. For more information, see the WebConf HSM section.

Make a one-to-one copy of a backup key share on a smart card

This allows you to copy the backup key share from one smart card to another smart card. This way, it will allow you to create a second set of '2 out of 3' cards for your disaster recovery site, for example. You should create a backup set of the Backup Key share smart cards. Please keep in mind that the Backup Key share smart cards should never be kept close to the backup of the PKI Appliance. Since each card is unique, this function cannot be used to recover lost cards in card set. However, if for whatever reason you need a '2 out of 2' scenario, this function allows you to copy the data from the second smart card to the third smart card, effectively overwriting the Backup Key share on the third smart card.

Change the PIN of the backup key share on a smart card

This allows you to change the PIN of the backup key share on a smart card. This should absolutely be done with each of the Backup Key Share smart cards. This is the easiest possibility to prevent a mixup or accidental overwriting of the contents of a smart card. This function can also be used if the card is being assigned to another person of the company. This function can also be used on a smart card that comes originally from another PKI Appliance.

Change the PIN of a PKCS#11 Slot User on a smart card

This allows you to change the PIN of the user credentials on a smart card. This should absolutely be done with each of the PKCS#11 slot activation user smart cards. This is the easiest possibility to prevent a mixup or accidental overwriting of the contents of a smart card. This function can also be used if the card is being assigned to another person of the company. This function can also be used on a smart card that comes originally from another PKI Appliance. For more information about PKCS#11 slot smart card activation, see PKCS#11 Slot Smart Card Activation.

3.1.3 PKI Appliance Battery AdapterPKI Appliance comes with an external connector to plug-in a so-called battery adapter. The purpose of this is to buffer the internal HSM battery and extend its lifetime when the appliance is turned off. This could be interesting when the appliance is operated as an offline (root) CA:



Figure 50: Adapter with PrimeKey product code PKL_APP_SE50_BAT

The adapter supports standard 6LR619V batteries:

Figure 51: Adapter with connected battery

The battery should be put into the metal clip of the battery adapter and connected to the appliance via the connector on the rear side of the appliance:



Figure 52: PKI Appliance with connected battery adapter

After a short while (can take up to ten minutes) the status page in WebConf should show the external battery with status and voltage:



••••••••

Figure 53: WebConf: Battery status

3.2 WebConf - Configurator of PKI ApplianceWebConf is the web-based user interface for managing the base functionality of the PKI Appliance. You will find the WebConf functions in the following tabs and their subtabs. Select a tab to see its functions together with contextual help:

StatusNetworkAccessHSMBackupClusterMonitoringPlatform



•••

3.2.1 StatusThe Status > Overview tab displays information about the overall status of your installation and provides an overview of the health status of your PKI Appliance.

Figure 54: WebConf: Status

3.2.2 NetworkThe Network tab and subtabs offer network configuration options:

Network InterfacesNetwork Time ProtocolDomain Name System

Network InterfacesUse this tab to configure the two network interfaces of the PKI Appliance:

Management:This is the interface you are currently connected to. It is used for administration and configuration tasks.

Application:This is the interface used running applications as a service.



Figure 55: WebConf: Network > Network Interfaces

You have the following options for both network interfaces:

IPv4 Configuration:

IPv4 address:Enter here the IPv6 address in CIDR format: <ipv6-address>/<prefix-length>

Netmask / Network / Broadcast:These fields are for your information. They are filled automatically after you click Apply.

Gateway:Enter here the default gateway for traffic to hosts that are not included in any of the interface's network address ranges.

IPv6 Configuration:

Enable IPv6:Activate this option to configure IPv6 settings.

IPv6 address:Enter here the IPv6 address in CIDR format: <ipv6-address>/<prefix-length>

Network:This field is for your information. It is filled automatically after you click Apply.

Gateway:Enter here the appropriate value for the gateway.

Apply:

Click this button to apply your changes to the network interface(s). There will be a short delay before the user interface is reachable again.If you have changed the IP address of the Management network interface, make sure that you reconnect to the new address.



Network Time Protocol Use this tab to configure the Network Time Protocol (NTP) server(s) for the PKI Appliance. NTP servers will be accessed through the Management network interface. With NTP, the clock of the PKI Appliance is kept in sync with a trusted time source. We recommend to use multiple trusted NTP servers if possible.

Figure 56: WebConf: Network > Network Time Protocol

You have the following options:

Source Address:Enter here the address of the NTP server, such as 129.6.15.29 for the NIST NTP server.

Add:Click this button to add the NTP server with the specified Source Address.

Remove:Click this button to remove the NTP server in that line.

Domain Name System Use this tab to configure Domain Name System (DNS) servers. This will enable host lookup by hostname instead of IP address. DNS servers will be accessed through the Application network interface. Use only trusted DNS servers to avoid that the PKI Appliance communicates with malicious hosts.

NTP is required to operate the PKI Appliance in a cluster.

The PKI Appliance time will not be changed or corrected immediately after clicking Add. Cautious migration to the time of the NTP source ensures that PKI Appliance operations remain undisturbed. Rebooting the PKI Appliance does not necessarily speed up this process.



••••

Figure 57: WebConf: Network > Domain Name System


Domain Name System

Enabled:Activate this option to configure DNS servers.

Name server:Enter here the address of the DNS server.Example of an untrusted DNS server (OpenDNS) to be used for testing: 208.67.222.222

Add:Click this button to add the DNS server with the specified Name server address.

Remove:Click this button to remove the DNS server in that line.

Apply / Cancel:Click to confirm/reject your changes.

Fully Qualified Domain Name (FQDN)This field is only visible after you specify a Name server and click Add.

Enter the Fully Qualified Domain Name that will be used by the SMTP email gateway as origin. The name must match the DNS record for the Application Interface IP address.

Apply/Cancel:Click to confirm/reject your changes.

3.2.3 AccessThe Access tab and subtabs offer access configuration options:

Server TLS certificatesClient TLS trust anchorsClient TLS OCSPAppliance Accounts



1.2.3.

4.

Server TLS certificatesServer side TLS certificates are used to authenticate the PKI Appliance to the outside world. The information in the certificate must match the information the client is using to connect and the client must trust the issuer of the certificate.

Figure 58: WebConf: Access > Server side TLS configuration

The following values are normally set in an TLS certificate (assuming that the host is hostname.example.com and the IP is always 10.10.10.10):

Subject Distinguisher Name:

CN=hostname.example.com

...

Subject Alternative Names: DNSName=hostname.example.com

IPAddress=10.10.10.10

...

Key Usage:

Digital Signature, Key Encipherment

Extended Key

Usage: TLS server

authentication (OID 1.3.6.1.5.5.7.3.1)

Setting the hostname to an IP address will also work.

The initial certificates issued for the network interfaces are self-signed. During the installation they are replaced with certificates issued by the initial Management CA.

If you already have an existing TLS CA that is trusted by browsers in your organization, you can replace the certificates in this view.

Click Generate a new key pair.Create a Certificate Signing Request (CSR).Send the CSR to your CA together with the information you would like to have in the certificate. Note that some implementations (e.g. Java) require a matching IP address or DNS entry in the certificate.Upload the issued certificate in PEM format with full certificate chain.

Note that the information in the CSR isn't set to anything useful. This is the normal EJBCA way of doing things, where the information inside the CSR is not trusted and overridden by whatever values the RA officer finds acceptable.



Client TLS trust anchorsClient side TLS certificates are used to authenticate users or external systems to the PKI Appliance. For a client certificate to even be considered by the PKI Appliance for authentication it must be issued by a CA that is trusted by the PKI Appliance. If the client certificate is trusted, the PKI Appliance or application firmware will try to match the information in the certificate to a list of rules (accounts).

Figure 59: WebConf: Access > Client TLS trust anchors

Trusted CAs for client authentication

You can configure different trusted certificates (trust anchors) for each network interface. If you want to use client TLS certificates from an external CA, you need to replace the trusted certificate. To avoid locking yourself out of the PKI Appliance, first add the appropriate matching rules in the subtab Access > Appliance accounts, so that you can reconnect and continue to administer the PKI Appliance after the trusted certificate is replaced.

To configure a new trusted certificate, simply upload the CA certificate (in PEM format) and confirm the change. After a short delay, you will be able to reconnect using the client TLS certificate issued by this trusted CA.

Client TLS OCSPUse this tab to configure whether and how the PKI Appliance performs OCSP verifications on TLS client certificates of incoming connections. Currently, the options are available for the Application interface only. The configuration for the Management interface is currently disabled. This is to avoid the danger of locking yourself out.

Note that no revocation checking has been implemented yet.



••••

Figure 60: WebConf: Access > Client TLS OCSP


None:The front proxy will not do any OCSP checking on the TLS client side certificates.

Internal: The front proxy will reach out the OCSP Responder specified in the client certificate (AIA). If that is not specified, it will fallback to the internal EJBCA Management CA.

External:The front proxy will reach out the OCSP Responder specified in the client certificate (AIA). If that is not specified, it will fallback to the specified URI.These are valid characters for the URI:

a-zA-Z0-9Special characters _ . - + / @ : .

Save / Revert:Click Save to confirm your changes, Revert to undo them.Changing the configuration results in a restart of the front end proxy. WebConf will then be unavailable for a few seconds.If the automatic reload ends up in a browser error, just reload the page.

Appliance AccountsPKI Appliance management accounts are matching rules that will be processed when a user tries to log in.



••••

••••

Figure 60: WebConf: Access > Appliance accounts


MatchType:Select the desired rule. These options are supported:

clientcert: Client TLS certificates authenticationsharedsecret: Shared secret (password) authentication

MatchValue:The required MatchValue depends on the selected MatchType:

MatchValue for clientcert: The match value is the entire subject distinguisher name of the certificate., as for example "CN=SuperAdmin,O=PrimeKey Labs C,C=DE".MatchValue for sharedsecret: The match value is the shared secret.

Add:Click this button to add the rule with the specified MatchType and MatchValue.

Remove: Click this button to remove the rule in that line.

3.2.4 HSMIn the HSM tab and subtabs, you can configure the Hardware Security Module (HSM) of the PKI Appliance.

OverviewPKCS#11 SlotsKey SynchronizationSmart card operations

The HSM configuration options offer the following:

Change the authentication codes of the PKCS#11 slotsChange the PIN of BackupKeyShareSmartCardsMake one- to-one copies of backup protection cardsChange the PIN of user credentials on smart cards for slot activation

We strongly recommend to use the clientcert option. Authentication via sharedsecret might disappear in future releases of the PKI Appliance.



••

Download a full protected backup of the HSM's key materialHandle HSM key synchronization across a cluster.

Please note that the functionality displayed might differ depending on your setup.

OverviewThis tab provides you with an overview of the HSM configuration.

Figure 61: WebConf: HSM > Overview

PKCS#11 SlotsYou can switch between automatically generated or manually specified authentication codes. By default, all slots are configured to be used with automatically generated authentication codes. Those are stored in EJBCA and have auto-activation enabled.

Figure 62: WebConf: HSM > PKCS#11 Slots



Switching from generated to manually entered authentication code

Manually entered authentication codes are not stored on the system, but known by the administrator, administrators or m out of n administrators in conjunction.Pros: Key material is not necessarily compromised in the case of lost physical access of the box.Cons: After a reboot, the PKCS#11 slot must be manually activated using the authentication code.

Changing a manually entered authentication code

Manually entered authentication codes can be updated in the WebConf by selecting Change. Note that this might destroy existing sessions to the slot and could require a re-authentication.

Switching to auto-generated authentication code

Auto-generated authentication codes are stored on the system and never shown to the user/administrator. When switching to a generated authentication code, EJBCA is re-configured to automatically activate the slot on startup.

Figure 63: Slot authentication code change from generated to manual

Figure 64: Changing the authentication code of a slot

Figure 65: Manual slot authentication code change

Pros: Highly available. Authentication code is very hard to brute force. Authentication code cannot be disclosed by administrators.Cons: Possible to extract given physical access to the machine (theft of the PKI Appliance could not rule out that the key material of the slot could not be freely accessed).



Figure 66: Slot authentication code change from manual to generated

Key Synchronization

Figure 67: WebConf: HSM > Key synchronization

Download protected HSM export

This will download the HSM key material so that you can migrate your data into another, external system. The format of the files is specific to the HSM vendor. The export is protected using the Backup Key for the higher Appliance Security Levels.

Smart card operationsThese options are only available if you initialized the PKI Appliance using smart cards for backup protection. To use these functions, connect the PIN pad to a USB port of the PKI Appliance. Please note that the USB port of the HSM (the USB port on the PCI card, only accessible from the back) will not work. Use the USB ports on the front of the PKI Appliance.

Figure 68: WebConf: HSM > Smart card operations



•

••

••

Change the PIN of the Backup Key Share on a smart card

Use this function for the following:

Change the PIN of the backup key share on a smart card. This is strongly recommended for each of the backup key share smart cards. It prevents a mixup or accidental overwriting of the contents of a smart card.Assign the card to another person of the company.Change the PIN on a smart card that comes originally from another PKI Appliance.

If you have additionally secured your PKCS#11 slots with smart card authentication, a similar functionality is offered to change the PIN of a PKCS#11 slot user on a smart card. That function can also be used to change the PIN of an HSM Admin User credential on a smart card.

Copy smart card (one-to-one)

Use this function to make an identical copy of a smart card. This will allow you to create a second set of 2 out of 3 cards for your disaster recovery site, for example. You should create a backup set of the Backup Key share smart cards. Please keep in mind that the Backup Key share smart cards should never be kept close to the backup of the PKI Appliance

Since each card is unique, this function cannot be used to recover lost cards in card set. However, if you need a 2 out of 2 scenario, this function allows you to copy the data form the second smart card to the third smart card, effectively overwriting the Backup Key share on the third smart card.

Cluster Key Synchronization Packages

Only available in a cluster environment, these sections allow you to download (and upload) an (encrypted) package with all information needed to deploy your latest key material changes to the other nodes of your cluster environment.

If you create a new key in the HSM through EJBCA (e.g. creating a new CA), the knowledge about its existence will synchronize through the database, but the key itself will not synchronize automatically. Hence, you will have to manually distribute this new key data by downloading a Key Synchronization Package on the Node where you created the new CA and uploading it to each of the other nodes. The applications (EJBCA, SignServer) will automatically be restarted, so that the key material can be used.

3.2.5 BackupIn the Backup tab and subtabs you can configure the backup behaviour of your system.

Manual backupScheduled Backup

Backups are entire snapshots of the system at a specific point in time. They guarantee that you can restore a stable state in case of disaster.



Manual backupUse this subtab for manually initiated backups.

Figure 69: WebConf: Backup > Manual Backup


Device:Select the desired backup device:

Network File System (NFS)USB

Destination Host (NFS only):Set the IPv4 address of the DNS hostname. The address must point to a record in the configured DNS that stores at least one IPv4 address.

Destination Path (NFS only):Set the base path for the NFS share to be used. This is always an absolute path.

Status (USB only):Find here information on the status of the connected USB storage device.

Backup now:Click this button to start the backup to the specified location in the background.To check whether the backup has completed, go back to the Backup > Manual backup tab at a later time. A backup on an empty or freshly installed system is usually done within minutes.

Show files:Click this button to view the files.

Delete:Click this button to delete the backup in this line.

To restore the system to the state of a backup, you need to perform a factory reset and use the initial wizard. During the restore procedure you will be prompted for the Domain Master Secret that was set during the installation of the system.



Scheduled BackupYou can schedule backups to run once per day, once per week, or once per month.

Figure 70: WebConf: Backup > Scheduled Backup


Schedule:Select the desired backup schedule. You can create daily, weekly, or monthly backups.

Day of ...:Define here on which day of the week or month the backup will be performed in weekly or monthly backups,

Time of day:Define here the time when the backup will start.

Device/Destination/Status:Use these options to specify the backup device. For more information, refer to the section Manual backup.

Test:Click this button to test your settings.

Save:Click this button to save your settings. The next backup will be performed on the specified day and time.

Show Files:Click this button to view the files.

Checking NFS destinationSave the specified destination and reload the Backup > Manual backup tab to verify that the NFS destination is readable. If this is successful continue with Backup now to ensure that the location is writable as well.



••

3.2.6 ClusterThe Cluster tab and subtabs show an overview of the cluster of the node and allows to configure cluster settings:

OperationConfiguration

For more information on how to extend your system to a cluster with multiple nodes, see High Availability.

OperationFind here status information about the cluster from the perspective of this local node. In complicated networks, the local node has a limited perspective only. In these cases, it is possible that the status information does not reflect the actual status of the cluster.

Figure 71: WebConf: Cluster > Operation

ConfigurationUse this tab to configure the cluster layout. You need to add nodes and configure the networking here if you want to add new PKI Appliances to the cluster.

Backup timeBackups will put some load on your system. We therefore recommend to choose a day and time when you expect little usage.

To access this functionality you need to configure Network Time Protocol (NTP) in the tab Network > Network Time Protocol.The clocks of all PKI Appliance nodes in the cluster must be synchronized, even if the cluster is only used for demo or testing purposes. We therefore recommend to use quality NTP sources that agree on the current time.



••

Figure 72: WebConf: Cluster > Configuration


Cluster Network Configuration:

Table with nodes:Find here information on the current network connection - network tunnels - to the other nodes in the cluster.

Application IP Address:Use this field to enter the IP address of the node you want to add.

Add node:Click this button to add the node with the specified Application IP Address.

Remove:Click this button to remove the node in this line.

Apply:Click this button to confirm your changes to the nodes' table. For newly added nodes, the setup packages will then be prepared.

Cancel:Click this button to undo your changes. This option is no longer available after you clicked Apply.

Setup packages for new nodes:This section is only visible after you added new nodes and clicked Apply.

Create and download:Click to create and download cluster bundles for that node. When you start the Connect to clusterprocess for the new node the wizard will prompt you to upload this bundle.

3.2.7 MonitoringThe Monitoring tab and subtabs allow you to configure monitoring for the PKI Appliance:

SyslogSimple Network Management Protocol



SyslogUse this tab to configure interactions with external monitoring systems. You can here specify a syslog server to which the syslog of PKI Appliance will be shipped. The syslog of the PKI Appliance contains the syslog of all internal systems as well as the EJBCA audit log. The syslog will be shipped by UDP in unencrypted, unsigned traffic.

Figure 73: WebConf: Monitoring > Syslog


Syslog target IP addresses:Enter the IP address of the syslog server.

Add:Click this button to add the syslog server with the specified IP address.

Simple Network Management ProtocolUse this tab to activate and configure Simple Network Management Protocol (SNMP) access to the PKI Appliance. SNMP allows an external monitoring system to query the state (health) of the PKI Appliance.

Figure 74: WebConf: Monitoring > SNMPv2

Your options in this tab depend on your selection for SNMP version:

SNMP Version:

Disabled:Disables the SNMP daemon.



••

•••••

•••

SNMPv2:Enables SNMP with Community string authentication. You will see the SNMPv2 options.

SNMPv3:Enables SNMP with various authentication options, including password and encryption. You will see the SNMPv3 options.Note that SNMP v3 does not support traps.

SNMPv2 options:

Credentials:

Community:The Community string for SNMP v2 authentication is mandatory. It must match the following rules:

length 4 and max. length 128 charactersValid characters:

Lower case letters [a-z]Upper case letters [A-Z]Digits [0-9]Minus sign: -Underscore sign: _

SNMPv3 options:

SNMP v3 offers the following authentication options:

Username onlyUsername and PasswordUsername, Password, and Encryption.

The minimum requirement for authentication is Username. Combining it with Password and Encryptionincreases security.

Figure 75: WebConf: Monitoring > SNMPv3



••

••

Authentication:

Username:The Username for SNMP v3 authentication is mandatory. It must match the same rules as the Community string for SNMPv2.

Method:Supported authentication methods are None, SHA-1 and MD5.

Password:The Password is mandatory for the authentication methods SHA-1 and MD5. It must match the following rules:

length 8 and max. length 64 charactersValid characters:

ASCII characters onlyNo double quotation marks: “

Encryption:

Method:Supported encryption methods are None, AES, and DES.

Secret:The Secret is mandatory for the encryption methods AES and DES. It must match the same rules as the Password.

Apply:Click this button to confirm your changes and enable/disable SNMP access.

Overview of SNMP Object Identifiers (OIDs)

All SNMP requests are combined in the public community. The PKI Appliance will answer to the two standards MIBS SNMPv2-MIB and HOST-RESOURCES-MIB. Additionally, the following parameters can be accessed with the following OIDs:

OIDExample Value Value

.1.3.6.1.4.1.22408.1.1.2.1.2.118.109.1Status of all VMs, 0 if all are running, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.1.3.99.112.117.1Temperature of the CPU 27

.1.3.6.1.4.1.22408.1.1.2.1.4.118.100.98.49.1Database usage in % 2




.1.3.6.1.4.1.22408.1.1.2.1.4.118.100.98.50.11 if space for db exceeds 80% usage, 0 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.49.1rpm of cpu fan 1025

.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.50.1rpm of system fan 1 1126

.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.51.1rpm of system fan 2 1028

.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.52.1rpm of system fan 3 982

.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.53.10 if cpu fan ok, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.54.10 if system fans are ok, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.1.5.108.111.97.100.49.1Load average of the system. Intervals are 1 min, 5 min, 15 min 0.19 0.10 0.06

.1.3.6.1.4.1.22408.1.1.2.1.5.108.111.97.100.50.1Load average of the system. Intervals is 1 min 0.19



.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.49.1Status of RAID, 0 if clean or active, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.50.1Status of RAID as string clean

.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.51.1Devices in RAID Total Devices : 2




.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.52.1Devices in RAID as int 2

.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.53.1Devices active in RAID Raid Devices : 2

.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.54.1Devices active in RAID as int 2

.1.3.6.1.4.1.22408.1.1.2.1.7.118.101.114.115.105.111.110.1Version of PKI Appliance PrimeKeyAppliance.2.3.0

.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.49.1Local node ID 1

.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.50.1Db cluster size 3

.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.51.1Currently active nodes in db cluster 3

.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.52.1Local db cluster (galera) state 4

.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.53.1Local db cluster (galera) state as string Synced

.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.54.1Last transaction ID 208

.1.3.6.1.4.1.22408.1.1.2.1.8.104.101.97.108.116.104.101.49.1EJBCA healthcheck as raw string ALLOK

.1.3.6.1.4.1.22408.1.1.2.1.8.104.101.97.108.116.104.101.50.1EJBCA healthcheck returns 0 for "ALLOK", 1 otherwise 0




.1.3.6.1.4.1.22408.1.1.2.1.8.104.101.97.108.116.104.115.49.1Signserver healthcheck as raw string ALLOK

.1.3.6.1.4.1.22408.1.1.2.1.8.104.101.97.108.116.104.115.50.1Signserver healthcheck returns 0 for "ALLOK", 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.49.1Status of HSM as string STATUS_is_OPER

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.50.1Enum of Status of HSM 0

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.51.1Status of HSM, 0 if operational, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.52.1Battery voltage of HSM 3.100 V

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.53.1Battery state, 0 if ok, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.55.1Battery voltage of external HSM battery 3.272 V

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.56.1Battery state, 0 if ok or absent, 1 otherwise 0

.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.54.1Serial Number of HSM

CS445661

Alternatively, all OIDs can be reached by the following snmpwalk commands. Replace the IP address in each command with the one of your system:



•••••

# for the standard group

snmpwalk -v2c -On -c public 192.168.5.162

# for the system group

snmpwalk -v2c -On -c public 192.168.5.162 .1.3.6.1.4.1.22408.1.1.2.1

# for the HSM group

snmpwalk -v2c -On -c public 192.168.5.162 .1.3.6.1.4.1.22408.1.1.2.2

3.2.8 PlatformThe Platform tab and subtabs allow you to view the applications running on the PKI Appliance, update the firmware, configure platform access, and perform basic troubleshooting:

ApplicationsUpdateTroubleshootingPlatform AccessSupport

ApplicationsThis tab provides an overview of the applications that are installed on your platform, along with their access URLs.

Figure 76: WebConf: Platform > Applications


Access URLs:Click a URL to open the respective page of the application.

Restart:Click this button to restart the application.

UpdateUse this tab to update the software of the PKI Appliance over network.



1.

Figure 77: WebConf: Platform > Update


Current update status:Find here information on whether an update is currently in progress. For current update processes, you will see the progress.

Search for updates:Currently, only the protocol option Network File System (NFS) share is supported.

Source Host / Source Path:Enter the host and path where the update file can be accessed.

Filter:Specify whether you want to search for Firmware or Application updates. No filter will search for everything.

Search now:Click this button to search for the update file according to the specified parameters.

Update:(only visible in list of update files) Click this button to update the firmware or application with the file in this line. The update will be started in the background. The progress is indicated in Current update status.

Update workflows

Searching for firmware and application update files

Select the Search for updates protocol.

Take special care when updating a cluster or one of its nodes. For more information on clustering, High Availability setup and instructions on updating a cluster refer to the section HA Setup.

When updating PKI Appliance firmware and Customer Operating System (COS) applications, like EJBCA or SignServer, they must be updated separately and manually. Start with updating the firmware and then update the application(s).



2.

3.4.5.6.

1.2.3.

1.2.3.

Enter the IP-address of the NFS server in the Source Host field.If you configured and activated DNS, the hostname can be used. See the section Network for more information.Enter the export path of the NFS server in the Source Path field.Use the Filter options to only show the firmware update files or the application update files.Click Search now to list the update files.If you are not in the correct directory, click Change directory to switch to the correct directory.

Updating the firmware

Click the button Install Firmware beside the file name of the firmware update file you want to use.The update process will start as a background task.You can check the status of the update in the field Current update status.

During the update process, the PKI Appliance will stay fully operational. You need to reboot the system to use the updated firmware.

Updating the application

Click the button Install Application beside the file name of the application update file you want to use.The update process will start as a background task.You can check the status of the update in the field Current update status.

During the update process, the PKI Appliance enters maintenance mode and the application is not available. When the update process is finished, the updated application can be used.

TroubleshootingThe Troubleshooting tab provides basic power cycle functionality.

Figure 78: WebConf: Platform > Troubleshooting


PKI Appliance State:

Find here information on the state of the PKI Appliance. State options are the following:

Power cycle functionality is only needed by professional services. Do not use these options unless you have expert knowledge.



Operational: All services, as for example EJBCA or SignServer, are available.

Offline: The PKI Appliance will be offline until it is rebooted. No services are available via the application interface.

Maintenance:The PKI Appliance is in maintenance mode. No services are available via the application interface. You will see a static maintenance page instead.

Actions:

Reboot:Click this button to reboot the PKI Appliance.

Power off:Click this button to power off the PKI Appliance.

Offline:Click this button to set the PKI Appliance in offline mode.

Platform AccessUse the Platform Access tab for configuring an internal maintenance access to the platform:

There is no default password configured for accessing the PKI Appliance. You have to set up your way of authentication if you need access to the platform.

Figure 79: WebConf: Platform > Platform Access


Platform access

Enable/disable SSH access:Click to enable/disable this option. Click Apply to finalize the action.

Maintenance access is only needed by professional services. Do not activate or use these options unless you have expert knowledge.

Even if if no cleartext password is defined, your SSH client will still ask you for a password. You can only define an SSH public key or a root password for SSH access when you enable SSH access.



SSH Public Key:Use the Browse button to upload a typical one-line openssh public key. Alternatively, you can also paste it in the field.

Apply:Click this button to confirm your change and enable/disable SSH access.

Revert:Click this button to undo your change.

Password authenticationUse these options to set a single password for cleartext authentication for either SSH or local console access.

Enable SSH login using password:Click to enable/disable this option. You can then upload an SSH public key or define a password for cleartext SSH authentication.

Enable local/console login using password:Click to enable/disable this option. You can then define a password for local console root access.

Root user password:Enter the password for local console root access.

Confirm password:Repeat the root user password to confirm it.

Apply:Click this button to confirm your changes.

Revert:Click this button to undo your changes.

SupportIn the Support tab, you have access to existing support packages and you can create new support packages manually. Support packages are archive files with snapshots of logfiles and configuration details.In this tab, you will also find contact information to request professional support for the PKI Appliance.

Known issueThe software also accepts a multiline public key as known from ssh.com/putty. However, such a key will fail at a later time in authentication.

Blocked slot or Admin userA slot or an Admin user will be blocked after 5 unsuccessful login attempts. You will need SSH access for unblocking slots/Admin users. Refer to the Troubleshooting section for more information.

http://ssh.com/putty



1.2.

Figure 80: WebConf: Platform > Support


Support Package > Create:Click this button to create a new support package manually. A newly created package takes up to 30 seconds to appear in the list of Available Support Packages.

Available Support Packages:Use these options to view and manage your existing support packages. Each package is listed with its creation date, and the name and size of its archive. The PKI Appliance stores a maximum of 10 packages. For every additional package the oldest package will be removed.

Download:Click this button to start downloading the support package in this line.

Delete:Click this button to delete the support package in this line.

Contact Support:Click the e-mail address to send your request to our professional support team. We recommend to use e-mail encryption for your correspondance.

3.3 Certificates and trusted CAs

3.3.1 Creating a new TLS server side certificate for Application interfaceIn this exercise we will create a new server TLS certificate for the Application Interface using WebConf.

To check the currently used TLS certificate, proceed as follows:

Open in the browser the Application Interface.Click the icon before the URL and click More information:



3.

4.

Figure 81: EJBCA TLS check

On the Info page, go to the Security tab and click View Certificate:

Figure 82: EJBCA TLS check certificate

Various information about the certificate is displayed. For Common Name (CN), you will find the value node1-tls-app:



1.2.

3.

Figure 83: EJBCA CN value for TLS

To create a new TLS server certificate for the Application Interface, proceed as follows:

Navigate to the tab Access in WebConf.In the section Server side SSL/TLS configuration > Application Interface, click Generate new key pair.

Figure 84: WebConf Access tab

Click Create CSR to create a CSR.



4.

5.6.

Figure 84: WebConf Create CSR

Click Download CSR to download the CSR.

Figure 85: WebConf Download CSR

In the EJBCA Admin Web, go to RA Functions > Search End Entities.In the Search end entity with username field, enter tls_app and click Search.



7.

••••

8.

Figure 86: EJBCA Search End Entities

In the Edit End Entity page, specify the following:

Status: Set to NewPassword: Set to foo123CN, Common name: Set to node1-tls-app-newToken (section Main certificate data): Set to User Generated

Figure 87: EJBCA Edit End Entity

Navigate to the Public Web and click Create Certificate from CSR in the section Enroll.



9.

••••

10.

Figure 88: EJBCA Create Certificate from CSR

In the Enroll page, specify the following and click OK:

Username: Set to tls_appEnrollment code: Set to foo123Request file: Click Browse and select the file appliance-app.csr.pemResult type: Set to PEM - full certificate chain.

Figure 89: EJBCA Enroll

Save the PEM file with name node1tlsappnew.pem.

Figure 90: EJBCA Save certificate chain



11.

12.

13.

14.

Navigate to Access > Server side SSL/TLS configuration in Web Conf and click the Browse button for Next chain to upload the file node1tlsappnew.pem.Click the action Activate new cert to activate the certificate chain to the server. The procedure will take a while until the new TLS certificate will be active.

Figure 91: WebConf: Activate certificate chain

Confirm that the server is using the new certificate by refreshing the application pages and then trust the new connection when promped. The new certificate is displayed as shown in figure EJBCA TLS check.Verify the certificate used for the TLS connection and confirm that it is the new certificate with the new CN node1-tls-app-new.

Figure 92: EJBCA TLS cert CN

This new TLS certificate will now be used each time you login to the application interface.

3.3.2 Changing client certificate and trusted CA for Management interfaceThe following example shows how to change the client certificate and update the trusted CA for Management Interface using WebConf.



1.

2.

3.

The new superuser certificate has to be issued from the same CA (MyCustomCA) that we will install for TLS authentication. First we have to provide the information about the certificate (MyUsername.pem) that will be used as superuser.

Open the WebConf Access tab:

Figure 93: WebConf Access

Check the SubjectDN of the certificate using openssl.Run the following command as 'user':

\$ openssl x509 -in MyUsername.pem -subject

subject= /C=MyCountry/O=MyCompany/SN=MyLastName/GN=MyFirstName \

/serialNumber=G824734/CN=MyFirstName MyLastName/UID=R4501ZHE

-----BEGIN CERTIFICATE-----

MIID3zCCAsegAwIBAgIIdzHlq8R4dnAwDQYJKoZIhvcNAQELBQAwPTETMBEGA1UE

AwwKTXlDdXN0b21DQTESMBAGA1UECgwJTXlDb21wYW55MRIwEAYDVQQGEwlNeUNv

dW50cnkwHhcNMTUwMTEzMDkxOTIzWhcNMTYwMTEzMDkyNjAzWjCBoDESMBAGA1UE

BhMJTXlDb3VudHJ5MRIwEAYDVQQKDAlNeUNvbXBhbnkxEzARBgNVBAQMCk15TGFz

dE5hbWUxFDASBgNVBCoMC015Rmlyc3ROYW1lMRAwDgYDVQQFEwdHODI0NzM0MR8w

HQYDVQQDDBZNeUZpcnN0TmFtZSBNeUxhc3ROYW1lMRgwFgYKCZImiZPyLGQBAQwI

UjQ1MDFaSEUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5Dr5dRsio

TvihzdeQQ1cCbDDM/KqN729+wuNcfO3btlMhXMRMrSdBz2gZgfIDfbNjWnmOmkF5

...

qqh6BtM4h2SpLlzcpELvOA6ySUEsfvaVpK4I7ebLFDFhtTM=

-----END CERTIFICATE-----

In the section PKI Appliance Management Accounts, select clientcert, provide the following SubjectDN and click Add:

C=MyCountry, O=MyCompany, SURNAME=MyLastName, GN=MyFirstName,

serialNumber=G824734, CN=MyFirstNameMyLastName, UID=R4501ZHE

In the subject value, slashes / have to be replaced with commas (,)



4.

5.6.

Figure 94: WebConf Access add a new client certificate for TLS authorization

In the section Trusted CAs for TLS client authentication , click Browse and select the MyCustomCA-chain.pem file.

Figure 95: WebConf Upload the new trusted CA chain

Click Activate new CA certificate to allow TLS to update the new trust of CA.Once the update is made, the new trusted configuration is used for authentication in the Management Interface.

CautionEJBCA is using org.bouncycastle.asn1.x500.style.BCStyle which interprets SN as serialNumber. We inherit this in org.cesecore.util.CeSecoreNameStyle (Legacy reasons). This means that you have to replace SN with SURNAME otherwise there is the danger of getting locked out.

The whole chain from the issuer CA of the client certificate up to the trusted RootCA is required.



1.

Figure 96: WebConf New configuration for Management Interface is in use

3.3.3 Changing client certificate and trusted CA for Application interfaceIn this exercise we will change the client certificate and update the trusted CA for Application Interface using WebConf. First we will configure EJBCA and then WebConf.

The new superuser certificate has to be issued from the same CA (MyTrustedSubCA signed by MyTrustedRootCA) that we will install for TLS authentication. First we have to provide the information about the certificate (MyClientAuthenticationCertificate.pem) that will be used as superuser.

In EJBCA Admin Web > Certification Authorities, click Import CA certificate and upload the CA certificates MyTrustedRootCA and MyTrustedSubCA.

Figure 97: Import new trusted CAs as External ones in EJBCA



2.

3.

4.

••••

5.

Select Administrator Roles and click Administrators next to the Super Administrator Role.

Figure 98: Add a new trusted client certificate as superadmin in EJBCA

Check the SubjectDN of the client certificate used to authenticate using openssl.Run the following command as 'user':

> openssl x509 -in MyClientAuthenticationCertificate.pem -serial -\

noout

serial=2b4306acbf69224

In the Edit Administrators page, specify the following and then click Add:

CA: MyTrustedSubCAMatch with: X.509: Certificate serial number (Recommended)Match type: Equal, case sens.Match value: 2b4306acbf69224

Figure 99: Configure the serial number of the trusted certificate in EJBCA

EJBCA is now configured to use this certificate and the last step is to configure WebConf to allow the Application Interface to also authenticate MyTrustedSubCA-chain.pemFollow the same process but for the Application Interface as described in Changing client certificate and trusted CA for Management interface



•••

3.4 MaintenanceThe PKI Appliance may not be able to operate its services due to specific events like update installation, RAID failing or similar. In order to avoid showing a customer endless long error messages during usage the PKI Appliance will be set into a state that we call maintenance.

During maintenance all access to EJBCA/SignServer over HTTP(S) will be disabled and each request will serve a message giving information that the system is under going maintenance and cannot be accessed right now.

3.4.1 PKI Appliance StateThe PKI Appliance has three different states:

OperationalMaintenanceOffline

To find out which state the PKI Appliance is in check WebConf (going to 'WebConf Platform Troubleshooting'. The three states will be described briefly by the following sections.

'Operational' StateThe PKI Appliance is fully operational. All subsystems are working as expected.

'Maintenance' StateThe PKI Appliance is in 'Maintenance' and application services are cut off due to an automatically detected reason.'Maintenance' can superseed the state 'Offline'.

'Offline' StateThe PKI Appliance is in maintenance and application services are cut off due to a manual setting in WebConf.



•••••

3.4.2 Reasons for MaintenanceThe PKI Appliance will be set to 'Maintenance' automatically for various reasons:

Factory Reset During OperationalRAID FailureHSM AlarmDatabase is DownApplication Update

Factory Reset During OperationIf the Factory Reset procedure has been triggered during operation the PKI Appliance will be set to 'Maintenance' automatically until the next reboot which finished the Factory Reset.This event is not recoverable.

RAID FailureIf both SSD hard disk drives fail the PKI Appliance would enter an in consistent state that could even not trigger any error message until caches are finally flushed. Detection of a fatally broken RAID therefor enables 'Maintenance' and prevents any data from being created that cannot be recovered later.This event is not recoverable.

HSM AlarmIf the embedded HSM has detected an alarm the PKI Appliance will enter 'Maintenance'. It does not make sense to run EJBCA/SignServe rwithout a working HSM because all key materials are erased by the HSM due to the alarm.This event is not recoverable.

•

•

•

This state will be entered only if the manual setting has been activated and no other automatically detected reason appears. Any automatically detected reason will change the state from "Offline" to" Maintenance". The "Offline" setting would still be active but invisible. If all automatically detected reasons disappear the PKI Appliance would still bein maintenance but again be in "Offline"state.A customer can not see a difference between "Offline" and "Maintenance" but an operator knows that an "Offline" state indicates a maintenance set manually in WebConf. A "Maintenance" state indicates a real world problem and not a choice to take the PKI Appliance services offline.Setting the PKI Appliance "Offline" in WebConf during a "Maintenance" that has been detected automatically can make sense. For example an operator wants to check the integrity of the PKI Appliance on his own after an incident before he exposes services to customers.



Database is DownIf the embedded database system stops operating (disk fill,…) the PKI Appliance enters 'Maintenance' until the database is available again.This event is recoverable.

Application UpdateIf an operator updates an application using WebConf the PKI Appliance will enter 'Maintenance' until the update procedure has been finished.This event is recoverable.

Manual Setting 'Offline'Setting the PKI Appliance 'Offline 'using'WebConf PlatformTroubleshooting'means activating maintenance manually without any real world reason. This functionality can be used to disable customer access to EJBCA/SignServer without shutting down the whole PKI Appliance. A customer will see the Notification page that is described in the section below.

3.4.3 EffectsThe following sections describe changes and information shown when the PKI Appliance is operating in maintenance.

Notification PageEvery HTTP(S) request to EJBCA/SignServer will lead to a HTTP 501 status code response showing a web page giving information that the PKI Appliance is currently not operational and running in maintenance.

Front DisplayEach time the PKI Appliance enters maintenance the messages set on the front display will include a message showing 'MAINTENANCE (line break) Services unavail'.

The message will be removed from the set when the PKI Appliance State will switch back to operational.

WebConf

Troubleshooting Section

In WebConf>Platform>Troubleshooting all maintenance reasons will be listed. Setting the PKI Appliance 'Offline' will be reflected in a change of the button 'Offline' to 'Online' only.

'Offline' state setting will not persist a reboot of the PKI Appliance.

OCSP requests will also receive an HTTP 501 status code with that notification page inside the responses body.



Warning Messages

During maintenance each time an operator opens a page in WebConf a white on red message appears in the upper left that shows 'Services Unavailable'. This message will disappear when leaving maintenance only if the page gets reloaded or a new page is opened.

SNMPIf SNMP is enabled it will indicate the PKI Appliance state and also give a human readable combined message of all reasons for maintenance. Further details can be found in section Monitoring > SNMP.

SyslogSyslog and avm server. Log will contain detailed messages about changing events leading to state changes of the PKI Appliance.

Support PackageEach time the PKI Appliance enters maintenance a 'Support Package' will be created. This even happens if the PKI Appliance has been set 'Offline 'manually. Note: If the PKI Appliance is already in maintenance no additional 'Support Package 'will be created. For example, if the SSD harddisk drives all fail and minutes later the factory reset is triggered only one 'Support Package 'will be created. For more information, see Support Package.

3.4.4 Support PackagesA Support Package is generally an archive file containing a snapshot of all relevant PKI Appliance subsystem logging files and other additional configuration and debugging details.

A Support Package is created automatically when the PKI Appliance enters maintenance and the package can also be created manually in the Support section on the WebConf Platform tab (WebConf>Platform>Support).

Support Packages are created and stored on the PKI Appliance. Up to ten packages are stored and any additional created packages will then delete the oldest one stored. A completed Factory Reset will remove any stored Support Packages.

To download a stored Support Package, use the Support section of the WebConf Platform tab (WebConf>Platform>Support).

A Support Package contains the following files:

File Description

all_sysinfo.txt Runtime information for all subsystems

cluster_status.txt Runtime information for current cluster setup



File Description

cos-ejbca_server.log EJBCA JBoss logfile

sfp_audit.log auditd logfileformSFP

sfp_avmserver.log AVM subsystem logging file

sfp_dom-vm-PrimeLFSversion.txt Firmware version information

sfp_ips_client_stderr.txt Network configuration

sfp_ips_client_stdout Network configuration

sfp_ntp_debug.txt NTP time server debugging information

sfp_virsh_list_all.txt List of all running virtual subsystems

vadm_etc-webconf-machineID.properties Version information

vadm_server.log WebConf JBoss logfile

vdb_df-h.txt Disk fill information

vgw_var-log-httpd-error.log Webserver logging files

vgw_var-log-syslog.txt Syslog of virtual gateway subsystem

vhsm_hsm_diag_stderr.txt HSM's diagnostic output

vhsm_hsm_diag_stdout HSM's diagnostic output



•

•

3.5 Setting up a VA

3.5.1 Online Certificate Revocation ProtocolThe Online Certificate Status Protocol (OCSP) provides a mechanism by which the revocation status of a certificate may be checked via an online protocol, called OCSP. OCSP also provides administrators and programmers with a method to get revocation information on a specific certificate in real time rather than rely on a CRL that might not have the latest information or may become large and unwieldy over time.

OCSP communication is very bandwidth efficient and uses a fraction of the bandwidth compared to downloading a large CRL file potentially can.

Some disadvantages when implementing OCSP responders are that communication to the OCSP responders is required when performing the check. Software or services cannot cache the OCSP requests. To overcome this limitation, some organizations implement a hybrid model that includes OCSP and CRL technologies. Another disadvantage of OCSP technology is that it is inherently more complex than CRLs which are simple signed text files or LDAP records.

3.5.2 CRL Distribution PointA CRL distribution point is an attribute of a certificate that allows the retrieval and checking of a CRL over the internet by an application. Some compliance standards state the need for a CRL distribution point in issued subscriber certificates.

3.5.3 VA Setup ScenariosThere are two basic options for VA/OCSP setups:

Peer Connector CA-VA setup: The CA-Appliance connects directly with VA-Appliance via the Peer Connector.VA setup for CRL Downloader service: The CA-Appliance publishes CRLs in an external server and VA-Appliance uses CRL Downloader service to fetch CRLs from the external server.

The following sections guide you through both setup options.

3.5.4 Peer Connector CA-VA setupThe Peer Connector CA-VA setup covers the process where a CA-Appliance connects directly with the VA-Appliance via a Peer Connector.



•••

••••

1.2.3.

Figure 100: Peer Connector CA-VA setup

The configuration steps are described in the following sections:

Step 1: Install PKI Appliance as Dedicated VAStep 2: Create OCSP Keys in VA-ApplianceStep 3: Create OCSP Key Binding in VA and Publisher in CA-Appliance

Step 1: Install PKI Appliance as Dedicated VAThese are the actions you have to perform:

Renaming the Management CAInstalling the VA-ApplianceChanging the Application Interface TLS certificateRenaming the Management CA and configuring peer systems

Renaming the Management CA

In the CA-Appliance, rename ManagementCA to PeerMgmtCA by proceeding as follows:

Navigate to AdminWeb and open CA Functions > Certification Authorities in the CA-Appliance.In the List of Certification Authorities, select Management CA.In the field Add CA enter PeerMgmtCA and click Rename.



4.

5.

1.

2.

Figure 101: Rename ManagementCA to PeerMgmtCA

Open Public Web > Retrieve > Fetch CA Certificates to get the certificate of the PeerMgmtCA that will be used for the installation of the VA-Appliance instance.Click Download as PEM next to CA Certificate to download the certificate.

Installing the VA-Appliance

You will now install the VA-Appliance. The installation steps are described in the Using External CA for Installation section. Some of the steps are detailed below:

When prompted to configure Network settings, use a name that defines the functionality of the PKI Appliance like in the following example:

Figure 102: VA network settings

In the Management CA Settings configuration, an existing configuration from CA-Appliance will be used.Select Use existing Management CA and click Browse to select the previously downloaded .pem file:



3.

1.

Figure 103: Install VA with existing ManagementCA

Once the PEM file is uploaded, specify the Subject DN used in the CA-Appliance in the SuperAdmin full Subject DN field. The value can be obtained from the CA-Appliance WebConf, in the MatchValuefield on the Access tab:

Figure 104: Upload external CA

Complete the rest of the Appliance Web Configuration Wizard steps to finish the VA-Appliance installation.

Changing the Application Interface TLS certificate

You will now change the Application Interface TLS certificate in the VA-Appliance.

In VA-Appliance, select WebConf > Access and copy the value in the Issuer field:

In this example, you will create a new one that will be signed by PeerMgmtCA.



2.

•••••••••

3.a.

Figure 105: Copy issuer value from VA-WebConf

Back in CA-Appliance, create an end entity which will be issued the new TLS certificate.In the CA-Appliance AdminWeb, select Add End Entity under RA Functions, enter the following values and click Add:

EndEntityProfile: Select SslServerProfileUsername: Enter ssl_va_appPassword (or Enrollment Code): Enter foo123Confirm Password: Enter foo123CN, Common name: Enter <the_value_you_copied_in_the_previous_step>IP Address: Enter <the_value_you_copied_in_the_previous_step>Certificate Profile: Select SslServerProfileCA: Select PeerMgmtCAToken: Select User Generated

Figure 106: Create End Entity in CA-Appliance for VA TLS connections

Create a CSR in the VA-Appliance as follows:In VA-Appliance WebConf, open the Access tab.



b.c.

4.5.

6.

7.8.9.

In the Application Interface section, click Generate new key pair.Click CreateCSR > DownloadCSR and save the file:

Figure 107: Download CSR for Application Interface in VA

In the CA-Appliance PublicWeb, select Enroll > Create Certificate from CSR.Provide the same Username and Enrollment code used when adding the end entity, and click Browseto select the previously downloaded .crs.pem file.In Result type select PEM – full certificate chain and click OK:

Figure 108: Sign certificate for VA Application Interface from CSR

Click Save File to save the received certificate .pem file.In VA-Appliance, click Browse to select and upload the signed request .pem file.Confirm that the Next Issuer is displayed, click Activate new cert and wait a few seconds for the configuration to be updated.



1.2.3.

4.

5.

••••

6.

7.

8.

Figure 109: Activate new certificate for VA Application Interface

Renaming the Management CA and configuring peer systems

In the beginning, you renamed the ManagementCA to PeerMgmtCA in the CA-Appliance instance. In the next steps, you will do the same for the VA-Appliance and configure the peer systems.

Open VA-Appliance AdminWeb > Certification Authorities and select ManagementCAIn the Add CA field enter PeerMgmtCA and click Rename.Open VA-Appliance AdminWeb > System Functions > Peer Systems and make sure only Allow Incoming connections is selected.Open CA-Appliance AdminWeb > System Functions > Peer Systems and make sure only Allow outgoing connections is selected.In the section Outgoing Peer Connectors, click Add, enter the following values and click Create:

Name: Enter VA1URL: Enter https://<application_VA_IP>:443/ejbca/peer/v1Authentication Key Binding: Identify created during installationEnabled: Enable this option

Click Ping to ping the connector.No privileges have been configured yet, so you will receive the following message: Unable to connect to peer. Unauthorized.

Figure 110: Ping to test the connection

In the VA-Appliance, the page VA-Appliance AdminWeb > Peer Systems indicates that the CA-peer tried to connect with it. Click Create authentication to create authentication for the CA-peer.For Role, select Create new role to create a new role for the connection, and click Select:



9.

••••

10.11.

•••••

12.

Figure 111: Create a new role for incoming request

For the Authorize incoming connections, specify the following and click Create authorization:

Role: Specify CA_Peer to rename the role.Generic rules: Enable Role is intended for peer connections.CAs: Enable Access 'PeerMgmtCA'.Publishing: Enable all Publishing options.

In the page CA-Appliance AdminWeb > Peer Systems, click Manage to manage the peer connector.In the form Management Operations for 'VA1', specify the following and click Start:

Push certificate: Enable this option.Push integrity protection Enable this option.Only check for discrepancies (dry run): Enable this option.Filter: Select Certificate Profile.Certificate Profiles: Select SslServerProfile.

The CA-peer is now authorized to connect to the VA- peer and perform the actions configured in the previous step, indicated in the Status field, displaying Status Added:3:

Figure 112: Check status of data synchronization in CA



1.2.3.

•••

••••

4.5.

6.

••

Step 2: Create OCSP Keys in VA-ApplianceTo create a crypto token and generate a public key (in the VA-Appliance) to be used from OCSP to sign responses, proceed as follows:

Go to the EJBCA Admin Web and open CA Functions > Crypto Tokens.Click Create New.Specify the following and click Save:

Name: Enter OCSP keyType: Select PKCS#11Authentication Code: Enter foo123 (the previously set password).Ensure that you have manually generated a slot password for the slot.Auto-activation: Enable this optionPKCS#11Library: Select Internal HSMPKCS#11 ReferenceType: Select Slot IDPKCS#11 Reference: Enter 3The index numbers differ depending on the installation.

Figure 113: Crypto Token for OCSP

The Settings page displays the message CryptoToken created successfully.To create the key for signing OCSP responses, specify the SignKey: RSA 2048 and click Generate new key pair.Click Test to test the key. If successful, the following message is displayed: signKey tested successfully.

Step 3: Create OCSP Key Binding in VA and Publisher in CA-ApplianceThese are the actions you have to perform:

Creating a key binding in VACreating a publisher in CA



1.2.

3.

••••••••

4.

Creating a key binding in VA

In VA-Appliance, navigate to Administration pages and click Internal Key Bindings.Click Create new to create a new key binding:

Figure 114: Create new OCSP key binding

To set up the key binding, specify the following values and click Create:

Name: Enter VAOcspKeyBinding.Crypto Token: Select OCSP key.Key PairAlias: Select signKey.SignatureAlgorithm: Select SHA256WithRSA.CertificateAuthority: Select PeerMgmtCA and click Add.ResponderID: Select KEYHASH.Include signing certificate in response: Enable this option.Include certificate chain in response: Enable this option.

Figure 115: Configure OCSP Key Binding

The key binding is created and you will get the following message: VA OcspKeyBinding created with id 1255634201:



5.6.

1.2.3.

Figure 116: Created OCSP key binding

Click Back to OcspKeyBinding overview.Click CSR to download the CSR and save the file:

Figure 117: Download the CSR for OCSP key binding

Creating a publisher in CA

In CA-Appliance, open RA Functions > End Entity Profiles.In the field Add profile enter OCSPEndEntityProfile and click Add.Select OCSPEndEntityProfile and click Edit End Entity Profile:



4.

•

••

••••••

5.

••••••

Figure 118: Edit OCSPEndEntityProfile

Edit the profile as follows and click Save:

End Entity E-mail: Disable this option.

Section Subject DN Attributes:O, Organization: Select Required and enter PrimeKey LabsC, Country: Select Required, and enter SE

Section Main certificate data (not visible in screenshot):Default Certificate Profile: Select OCSPSIGNERAvailable Certificate Profile: Select OCSPSIGNERDefaultCA: Select PeerMgmtCAAvailableCAs: Select PeerMgmtCADefaultToken: Select User GeneratedAvailableTokens: Select User Generated

Figure 119: Edit OCSPEndEntityProfile

In the CA-Appliance, open Add End Entity, specify the following, and click Add:

End Entity Profile: Select OCSPEndEntityProfileUsername: Select OCSP_end_entityPassword(orEnrollmentCode): Enter foo123Confirm Password: Enter foo123CN, Common Name: Enter OCSPCertificate Profile: Select OCSPSIGNER



••

6.

••••

7.

CA: Select PeerMgmtCAToken: Select User Generated

Figure 120: Add OCSP End Entity in CA-Appliance

In CA-Appliance>Public Web, click Create Certificate from CSR, specify the following, and click OK:

Username: Enter OCSP_end_entityEnrollment code: Enter foo123Request file: Click Browse and select the CSR you downloaded in the previous step.Result Type: Select PEM - full certificate chain

Figure 121: Create Certificate from CSR

Save the signed CSR:



8.9.

10.

11.

Figure 122: OCSP CSR is signed successfully

In the VA-Appliance, open the Internal Key Binding page.In the section Import externally issued certificate, click Browse to upload the signed CSR, and click Import:

Figure 123: Upload the signed OCSP CSR in VA

In the same page, click Enable to enable the key binding:

Figure 124: Enable OCSP key binding

Under Set Default Responder, select VA OcspKeyBinding, and click Set:



12.13.14.

15.

•••

••••

16.

Figure 125: Set default responder

In the Admin Web of the CA-Appliance, open CA Functions>Publishers.In the Add Publisher field enter VA1 Publisher and click Add.Select the entry VA1 Publisher in the List of Publishers and click Edit Publisher:

Figure 126: Add a publisher in the CA-Appliance

Configure the publisher as follows:

Publisher Type: Select Validation Authority Peer PublisherRemote System: Select VA1 (XXXXXXXX)Enable the following options:

Store certificate at the ValidationAuthorityStore CRL at the Validation AuthorityUse queue for CRLsUse queue for certificates

Click Save and Test Connection, and then click Save:



17.

18.

19.

Figure 127: Configure the publisher in CA-Appliance

In the CA-Appliance click the Search End Entities link to view a certificate that belongs to the end entity and download it as <certificate_to_be_controlled>.pem.Run the following command as user to check its validity towards the OCSP setup:

openssl ocsp -issuer <issuer>.pem -CAfile <issuer>.pem -cert {color} <certificate_to_be_controlled>.pem -req_text -url \ http://<VA_application_interface>:80/ejbca/publicweb/status/ocsp {color} -resp_text

The output looks like the following:

OCSP Request Data :

V e r s i o n : 1 ( 0 x0 ) R e q u e s to r L i s t :

C e r t i f i c a t e ID :

Hash Alg o r i th m : sha 1

I s s u e r Name Hash : C45788773EDFD1434ED1D8A3C6E3CF176D78B82A I s s

u e r Key Hash : EE5D0AE56A64E9001423A2F6FBFDBFF8BC4266E3

S e r i a l Number : 41DC620FBFCB39C6 Request E x te n s i o n s :

OCSP Nonce :

04104775 FF9F9A74069EE07ED378AEA83E99

OCSP Response Data :

. . .

Xu40z8I796Luq Zx99W7e Yy AutEir+ZLo31szYuDI+Q==

OCSP Response Data :

...

Xu40z8I796LuqZx99W7eYyAutEir+ZLo31szYuDI+Q==

−−−−−END CERTIFICATE−−−−−

Response verify OK

ssl_app .pem: good

This Update: Dec 4 14:22:17 2014 GMT



1.

2.

3.5.5 VA setup for CRL Downloader serviceIn the VA setup for CRL Downloader service setup, the CA-Appliance publishes CRLs in an external server and the VA-Appliance uses the CRL Downloader service to fetch CRLs from the external server.

Figure 128: VA setup for CRL Downloader service

The following instructions describe the configuration. They apply to the VA using the CRL Downloader service to fetch and store those CRLs. The assumption is that the CA is already publishing CRLs in the external server. This paradigm is for ManagementCA but it holds in analogous ways for other CAs too.

In the VA-Appliance, proceed as follows:

In the CA-Appliance, import the ManagementCA as ExternalCA according to instructions in the Use-Case: Import RootCA as External CA in node A section.Click Certification Authorities, select ManagementCA, (External CA), and click Edit CA:

Figure 128: Import external CA in VA-Appliance



3.

•

4.5.6.

7.

•••

•••

In the section CRL Specific Data of the Edit CA form, make the following entry:

ExternalCRLDistributionPoint: Enter the URL from the external server where the CLR is located.

Figure 129: Configure the CDP of the CA

Open System Functions > Services.In the field Add Service enter CRL Downloader and click Add.Select CRL Downloader (Inactive) and click Edit Service:

Figure 130: Add CRL Downloader service

Setup the service with the following values and click Save:

Select Worker: Select CRL DownloaderCAs to Check: Select ManagementCAIgnore nextUpdate and always download the CRL: Enable this option.By enabling this option CRL will be downloaded ignoring the nextUpdatevalues which is configured in the CA.Period: Specify 1 DaysActive: Enable this option.Pin to Specific Node(s): Enter cos-ejbca



••

Figure 131: Configure CRL Downloader service

You have finished configuring the service to download CRLs from the external server. Now you need to configure OCSP key binding to authenticate VA-Appliance to sign the responses of OCSP requests. The procedure is described in Use-Case: Create OCSP Key Binding in VA and publisher in CA-Appliance (steps 1-16). Follow the steps and consider the following changes in naming references:

ManagementCA instead of PeerMgmtCAThe CA-Appliance is analogous to the CA where ManagementCA is installed.

When OCSP key binding is configured, the VA-Appliance is ready to respond in OCSP requests like the following (<unknown_status_certificate>.pem is a certificate signed from ManagementCA):

Run as user:

openssl ocsp -issuer ManagementCA.pem -CAfile ManagementCA.pem -cert {color} <unknown_status_certificate>.pem -req_text -url \ http://<VA_application_interface>:80/ejbca/publicweb/status/ocsp

The output looks like the following:

OCSP Re que s t Data :

V e r s i o n : 1 ( 0 x0 ) R e q u e s to r L i s t :

C e r t i f i c a t e ID :

Hash Alg o r i th m : s ha 1

I s s u e r Name Hash : C45788773EDFD1434ED1D8A3C6E3CF176D78B82A I s s u

e r Key Hash : 320 A617F62005EF984C12ADA0D981A899A300F68

S e r i a l Number : 0758 A7080983F917 Re que s t E x te n s i o n s :

OCSP Nonce :

04106 C08FFAF175C99CC261E9543CBA525C3

Re s pons e v e r i f y OK

<u n k n o w n _ s ta tu s _ c e r t i f i c a te >.pem : good

This Update : Dec 18 1 0 : 3 7 : 2 2 2014 GMT



•••••••

3.6 HA SetupThe High Availability (HA) setup is described in the following sections:

Scope of AvailabilityContinuous Service AvailabilityLevels of AvailabilityHigh AvailabilityBackup, Restore and UpdateCluster shutdown and startupOperational Caution

3.6.1 Scope of AvailabilityFor the PKI Appliance, the availability is defined as being able to keep the service running with full data integrity for the applications running on the PKI Appliance that use the internal SQL database.

How it worksThe cluster implementation used on the PKI Appliance uses regular network connectivity over the Application Interface for all cluster communication. This means that cluster nodes don’t have to be placed physically close to each other as long as they have good network connectivity.

However, this also means that a node cannot distinguish between the failure of another node and broken network connectivity to the other node. To avoid the situation where the cluster nodes operate independently and get diverging data sets (a so called split brain situation), the cluster nodes take a vote and will cease to operate unless they are part of the majority of connected nodes. This ensures that there is only one data set that is allowed to be updated at the time. In the case of a temporary network failure, disconnected nodes can easily synchronize their data to the majority’s data set and continue to operate.

Synchronization of key materialKey material stored in the HSM is not automatically synchronized after the cluster has been set up. Manual synchronization is however possible.

Pre-cluster setup generation of keys

If suitable for your use-case, you could generate all keys that will be used during the installations life-time after installing the first node, but before starting the cluster configuration for the additional nodes. This way, all additional cluster nodes will be provisioned with the complete key material on installation and no additional manual key synchronization will be necessary.

Post-cluster setup generation of keys

When generating new keys (or in any other way modifying the key material) after the cluster has been setup, you need to manually synchronize the key material. Note that applications that are connected to the shared database may malfunction if they try to use references to keys that are not yet synchronized. For example, if



1.2.

3.4.5.

a Certificate Authority in EJBCA is renewed with new key generation, other cluster nodes shortly after the renewal will try to use the new key. This will fail since the key generation was local to the node where it was performed.

Use-Case: Synchronize key material

On Node 1: Generate the key pair(s) on the first node.On Node 1: Go to the HSM tab of the PKI Appliance WebConf and download a Cluster Key Synchronization Package by clicking Download protected HSM backup.On Node n: Go to the HSM tab of the PKI Appliance WebConf and upload the package.Repeat step 3 for each node (n>1).Configure the application to start using the new key pair(s).

Since node 1 has higher database quorum vote weight, it is generally advised to generate the keys there to avoid a reboot and potential downtime in a two node setup.

Network topologyAll cluster nodes should have a dedicated connection to all other nodes in the cluster. However the cluster can propagate the data as long as all nodes are connected to at least one other node.

The network connection is done via the GRE protocol (IP protocol number 47. For more information, refer to Wikipedia: List of IP protocol numbers. Since GRE is an IP protocol, it is not based on either TCP or UDP and has no concept of ports. It is an IP protocol by itself. That means that it can not simply be made available with a port forwarding behind a NAT (Network Address Translation). A fully transparent VPN solution will be required if the cluster is supposed to be installed over different locations.

If you do have network equipment that is able to encapsulate the protocol, you might still run into the issue of network address complications. This is easiest worked around by setting up the systems in a simpler network configuration (e.g. same site) and later shipment/reconfiguration.

A cluster node will never forward traffic between two other nodes to avoid networking loops. Compared to using the spanning tree protocol (STP), this means that a broken network connection between two nodes will not trigger any downtime of other connections.

If you prefer the dynamic loop prevention behavior, you could add managed switches in front of the Application Interfaces of the PKI Appliances. Please note that if the network topology change prevents network traffic between the nodes for too long, your cluster nodes might stop operation and require manual interaction. Rapid Spanning Tree Protocol (RSTP) might be an interesting alternative to STP in this case.

Cluster traffic security considerationsThe current version of the PKI Appliance uses no protection for the cluster traffic. IPSec will be used in a later release, but for now, you need to ensure that this sensitive traffic is protected by other means.

3.6.2 Continuous Service AvailabilityTo ensure that service clients always connect to an operational node in the cluster, an external load-balancer should be used for automatic fail-over and/or load distribution.

https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers

https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers



••

In the case a custom application is being developed for consumption of the services provided by the PKI Appliances’ external interfaces, this could also be handled by making the custom application connect to any of the nodes that is found to be operational.

If lower availability and manual interaction is acceptable in case of a node failure, this could also be solved by redirecting a DNS name to the service.

3.6.3 Levels of Availability

Stand-alone instanceThis is a basic single node installation of the PKI Appliance. In case of a node failure, a new PKI Appliance needs to be reinstalled from a backup. All data between the time of the latest backup and the failure will be lost. If a cold standby (spare) PKI Appliance is not available, the time of delivery of a new box needs to be taken into account when calculating the acceptable downtime.

Hot standby with manual failoverIn this setup, two nodes are connected as a cluster where the first installed node has a higher quorum vote than the second node.

In case the second node fails, the first node will continue operating but the second node will be set into maintenance. In the case the first node fails, the second node will cease to operate and will be set into maintenance. To bring back the second node into service it requires manual interaction via the PKI Appliance administrative interface (WebConf).

To avoid data loss, the manual interaction is required and the second node should only be Forced into Active if the first node really is dead and will be replaced.

High availability with automatic failoverThis is a setup with three or more nodes. In case of a node failure, the remaining nodes will still be able to form a cluster through a majority quorum vote and continue to operate. If the PKI Appliance that has failed is still switched on it will be set into maintenance.

To ensure that quorum votes never result in a tie, all nodes are assigned unique quorum vote weights according to their assigned node number (Weight=128−NodeNumber).

In a setup where an even number of nodes N are distributed equally over two sites, the site that is intended to remain Active if connectivity between the sites fails should have a larger sum of quorum vote weights than that of the other site. Since cluster nodes with lower node numbers have higher weights you should deploy nodes 1 to N/2 on the primary site.

3.6.4 High AvailabilityThis section includes step-by-step instructions for the following use cases:

Use case: Setting up a two node clusterUse case: Setting up a three node cluster



•

1.2.

3.

4.5.6.7.8.

1.2.

3.

4.5.6.7.8.

9.

10.11.12.

Use case: Extending a cluster from n to n+1 nodes

Use case: Setting up a two node clusterTo set up a two node cluster from scratch, do the following:

Make a fresh install according to the normal installation procedure or restore a node from backup.If possible, generate all keys in the HSM that will be used during the installations life-time to avoid manual key synchronization later.Go to the Cluster subtab Configuration on the initial node in the PKI Appliance WebConf and add a connection to where the next node’s Application Interface will be.From the Cluster subtab Configuration, download the setup bundle for the second node. Factory reset the second node and connect to the web based installerSelect Connect to cluster and upload the setup bundle.Start the installation procedure.After installation completes, you should be able to manage the new node using the same credentials as the first one.

If the first node has been used for a while before the second node was connected, you might need to wait until the data is fully synchronized, even after the cluster connection has completed. When the Local node state in the WebConf’s Status tab shows Active, the node is ready for use.

Use case: Setting up a three node clusterTo set up a three node cluster from scratch, do the following:

Make a fresh install according to the normal installation procedure or restore a node from backup.If possible, generate all keys in the HSM that will be used during the installations life-time to avoid manual key synchronization later.Go to the Cluster subtab Configuration on the initial node in the PKI Appliance WebConf and add the two connections to where the next nodes’ Application Interface will be.From the Cluster subtab Configuration, download the setup bundle for the two new nodes.Factory reset the second node and connect to the web based installerSelect Connect to cluster and upload the setup bundle for node 2.Start the installation procedure.After the installation completes, you should be able to manage the new node using the same credentials as the first one.Even if a full synchronization between the first and second node is still running at this point, you can proceed with the cluster connection of the third node.Factory reset the third node and connect to the web based installerSelect Connect to cluster and upload the setup bundle for node 3.After the installation completes, you should be able to manage the new node using the same credentials as the first one.



1.

2.3.4.5.6.

If the first node has been used for a while before the two new nodes were connected, you might need to wait until the data is fully synchronized, even after the cluster connection has completed. When the Local node state in the WebConf’s Status tab shows Active, a node is ready for use.

Use case: Extending a cluster from n to n+1 nodesTo extend a cluster from two to three nodes, do the following:

Go to the Cluster subtab Configuration on all of the existing (n) nodes in the PKI Appliance WebConf and add a connection to where the next node’s Application Interface will be.From the same subtab on one of the nodes, download the setup bundle for the third node.Factory reset the new node (3) and connect to the web based installerSelect Connect to cluster and upload the setup bundle.Start the installation procedure.After the installation completes, you should be able to manage the new node (n+1) using the same credentials as the previous node(s).

When the Local node state in the WebConf’s Status tab shows Active, the new node is ready for use.

3.6.5 Backup, Restore and UpdateIn the domain of High Availability/Clustering, the topics of backup, restore and update have to be handled differently as compared to stand alone instances of the PKI Appliance to not disrupt operation.

Backing up a clusterAlthough that you have set up a High Availability Setup to prevent any outages, you should always take full-out scenario into consideration. In this case, and only in this case, you will have to recover your cluster from a backup. From operational perspective, it might make sense to decide to take backups only from node 3 (which is designed to be at a disaster recovery site off-location) to reduce load and network traffic on the nodes at the main site.

We recommend setting up an automated backup schedule on all of your nodes to make sure to be able to recover everything, out of every situation, even if perhaps a failure takes a long time to be discovered.

Generally, a backup always contains all information of a cluster node (configuration and database), including its node identity. For example, a backup file taken from node 3 will not just create any node of a cluster, but exactly node 3 when restored.

Restoring a cluster from backupA backup file of a cluster node should only be used in the highest emergency of a full-out scenario. If at least one node remains operational, the cluster should always be reestablished from the last good node.

To recover as much of your data as possible, start by identifying the last good backup you have available from an Active node by analyzing the outage. For example, if the connection to a disaster recovery site went down long before a backup was made there, you might be better off with an older backup from the primary site after such outage.



Once you have identified the best possible backup from a previously Active node N, restore the backup to the PKI Appliance designated to be node N and then reconnect the other nodes to this node.

For information on how to restore a backup to a PKI Appliance, see Restore from Backup.

After reboot, the WebConf will be reachable and operational, but the database will refuse to start up in this situation, hence the applications will not yet be operational. Use the WebConf button Force into Active to force the cluster to continue operations from the restored data set.

Updating the software (firmware/applications) on a clusterUpdating the software of the PKI Appliance will always require a reboot. A reboot of a PKI Appliance in a cluster should always be scheduled with care as to not accidentally degrade cluster performance. It is a common mistake to ease up on the operational caution when it is known that some technical measures are in place to take care of outages and thus give away any safety margins. In a cluster, software update should be applied on a single node at a time. Only if the node you are currently working on is completely done with the update and confirmed to be back up and running should you proceed to updating the next node.

As of version 2.2.0, the PKI Appliance firmware should be updated separately from the applications installed on the platform of the PKI Appliance. Upgrade both the firmware and the application, starting with the firmware. A PKI Appliance on a version older than 2.2.0 cannot simply be customer-upgraded due to major architectural changes. Please contact PrimeKey Support or your local PrimeKey partner for support.

For instructions on how to update a cluster on PKI Appliance version 2.3.0 to an even newer version, refer to the later documentation delivered with the new software version.

Use-Case: Software update on a three-node cluster from 3.3 to 3.4

To update a three-node cluster from PKI Appliance version 3.3 to 3.4, do the following:



1.

2.3.

•

••

4.

5.6.

7.8.

Before starting any configuration changes on a cluster node, confirm that the node has been running fine up to now. This is the only way to know for sure whether you actually broke anything if the procedure does not succeed as expected.You might also want to make a last manual backup of the PKI ApplianceMake sure this cluster node is declared as not operational, (e.g. disabling in load balancing frontend), so that:

No other operator does any maintenance on any other node while we deliberately reduce redundancy on the cluster.Nobody relies on the availability of this node during maintenance downtime.No alarm is raised if this node gets unavailable.

Start the software update procedure on this node by updating the PKI Appliance firmware first, then updating the COS applications. This should generally be the same procedure as described in the Platform section: Install firmware, reboot, install application.After the cluster node has been rebooted, check that the node is operating correctly.After you asserted that this node is up and running, verify that the entire cluster is in good shape, i.e. that all of the cluster nodes of your cluster confirm that your cluster is back up and running with redundancy.Announce this cluster node to be operational back again or whatever you need to undo from step 3.Continue with updating your cluster by applying the same steps on the next cluster node, restarting at step 1.

3.6.6 Cluster shutdown and startupThe following describes how to do a controlled shutdown of the whole cluster and get back to a fully running state.

Shutting down the clusterWhen shutting down an N node cluster, start with a graceful shutdown of the node with the highest node number (usually number 3) and wait until the node is fully shutdown before proceeding with the next one. This ensures that the quorum is kept as long as possible and in the end node 1 is the most up to date node.

Starting a fully shutdown clusterAfter a controlled shutdown as described in Shutting down the cluster, the cluster nodes should automatically become Active starting with the most up to date node after startup.

If the cluster is unable to automatically become Active, the administrator needs to manually bootrap the cluster from the node with the most up to date data set. The administrator can identify the node that had an Active database status last before the shutdown by comparing the Last Transaction ID shown under the Cluster tab in WebConf of all the nodes.

Even after a power outage that seems instantaneous, the Last Transaction ID of all nodes should be compared before selecting a node to Force into Active.

Do the following:



1.2.3.

4.

1.

2.3.

4.

5.

6.

7.

8.9.

10.

Power up all nodes.Wait a minute after all nodes have started to see if the cluster automatically becomes Active.If manual intervention is needed, select the node with the highest Last Transaction ID and use Force into Active on this node (and only this node).Wait until all N nodes are fully started, and the database status is Active on each node.

3.6.7 Operational CautionAn operational cluster will continuously answer requests and synchronize data. It will also evaluate its health in order to ensure availability as well as data integrity. As described earlier, a node will rather stop working than risk a split-brain situation. A split-brain situation develops when two nodes believe they are lone survivors and continue to serve requests, resulting in two different data sets.

To prevent accidental degradation of the cluster health, some precautions need to be taken. A planned network reconfiguration could be mistaken to be an emergency by the cluster, for example.

Maintenance operations on the cluster such as rebooting, updating, network reconfiguration, should be restricted to only one node at a time, with ample time for the node to reconnect and synchronize after the task is completed. Before you proceed to the next node, make sure that your cluster is back to full health.

Use-Case: Changing the IP Address of the Application Interface of a node in a three-node clusterIn a PKI Appliance cluster, the internal communication is being transferred over the Application Interface. Hence, if you need to change the IP address of the Application Interface, cluster communication will fail at first and you will have to take some manual configuration steps to bring back the node into play:

Before starting any configuration changes on a cluster node, it is good practice to assert that the node has been running fine up to now. This is the only way to know for sure whether you actually broke anything if the procedure does not succeed as expected.You might also want to make a last manual backup of the PKI Appliance.We’ll assume here that you have announced this cluster node as being not operational (e.g. disabled in a front-end load balancer) for the time of the change.Now start the actual change by changing the Application Interface IP address on the cluster node in WebConf, see Network.Navigate your browser to the Cluster Configuration subtab of the WebConf on all of the other cluster nodes.Wait for the cluster node to appear offline/not connected in the cluster connections table, the IP address should now be in an editable input field.On every of the other cluster nodes, correct the application IP address of the cluster node in the cluster table.Confirm the operation by clicking Apply.After the cluster reconfiguration has finished, all cluster nodes should be connected to all of the other cluster nodes.When everything works as expected, you should not forget to bring back the node into the load balancer.



1.2.

3.

4.5.

Replacing a failed cluster nodeTo replace a failed cluster node, proceed as follows:

Go to the Cluster Status page and make sure the other two nodes are Active.Shut down the node that you want to replace. To avoid later accidental reconnection with the cluster, you can reset it to factory defaults.After a few moments, you can download a Cluster Setup Bundle from one of the other nodes. The cluster configuration doesn't need any changes. If the Application IP of the replacement node is different, change the cluster configuration on both nodes:Wait 1 minute between nodes and download a new Cluster Setup Bundle.Connect the replacement node to the cluster with the Cluster Setup Bundle.Check the Cluster Status page on the other nodes if the replacement node has synced up and is Active.

Restoring the node from a backup will not work because the database content in the backup file will be outdated.

3.7 PKCS#11 Slot Smart Card Activation

3.7.1 IntroductionAll sensitive cryptographic material of the PKI Appliance is stored on a Hardware Security Module (HSM). This HSM protects your key material against physical attacks. The keys required by the PKI Appliance and your infrastructure are organized in so-called slots, commonly used with the cryptographic API PKCS#11. To operate on these keys, these slots must be activated with some authentication code. Depending on your requirements for availability, usability and security, you can select whether those authentication codes should be stored on the PKI Appliance or not. This can be chosen per slot. Slots with stored authentication codes can be auto-activated for immediate availability. The generated and automatically stored authentication codes are of very high quality. This choice can be changed even later during the operation of the PKI Appliance.

For cases where manually entered authentication codes do not meet the security requirements, there is an option for two-factor authentication: It is possible to additionally require an activation with smart cards for one or more slots. This choice has to be done during the installation.

3.7.2 Installation/ConfigurationDuring the installation of the PKI Appliance it is possible to enable PKCS#11 slot smart card activation per slot . In order to do so, clear (Automatically generated) Authentication Code for the slot you want to give more security, and an option to use smart card activation will be provided. Go through the available options and choose smart card activation. Next, continue to set an authentication code per slot. This authentication code will be required upon activation of the slot, make sure to keep that code safe and always available when deactivating/activating the slot.



••

•

••••

••••

Number of users requiredTo further secure your installation you can choose how many smart cards are required to activate a slot. However, there is no quorum (such as "3 out of 5") available for this function. If Number of users required:5 is selected, then 5 different user credentials will be generated and written to 5 different smart cards, all of which need to be present when activating a slot. The default setting of the PKI Appliance is to create only one user credentials.

Number/copies of user smart cards

The default setting of the PKI Appliance is to create 2 smart cards with the same user credential.

Require smart cards to activate system after bootFor highest security concerns, smart card activation can also be enabled for PKCS#11 slot 0, which contains the key that is used to sign the audit log. Since EJBCA produces an audit log entry for every single action, it needs access to slot 0 for every single action, including start-up. This effectively means that EJBCA will not be reachable after a system startup unless slot 0 has been successfully activated by smart card.

ProcedureFor every slot activation user that has been chosen, the following procedure will run during the installation:

The user credentials are generated in memory.For every copy that has been chosen, the user credentials will be written to a smart card. It is required to enter the PIN (default PIN on delivery: 123456) and acknowledge with OK.The user credentials (only public key) are read into the HSM, it will only be required to press the OKbutton.

Example with default values

After the installation, it is strongly advised to change the PINs of the smart cards through the WebConf.

The procedure with an PKI Appliance Security Level of "2 out of 3" and slot smart card activation on slot 7 with default values 1 user and 2 copies will look like this:

Backup key shares handlingOne audible alert (bee-beep)Generation of the backup key and writing to three cards (with PIN and OK)Reading of the backup key from two cards (with PIN and OK)

Handling of one slot activation userGeneration of user credentialsOne audible alert (bee-beep)User credential being written to one card (with PIN and OK)

Unlike the backup key share on the smart cards, the user credentials cannot be copied from card to card. A lost, broken or blocked smart card cannot be replaced. Therefore, the PKI Appliance offers to create sufficient copies, once and for all.



••••

One audible alert (bee-beep)User credential being written to one card (with PIN and OK)One audible alert (bee-beep)Creation of the user within the HSM by reading the public key, (only OK)

Slots 0 and 1

If the installation is configured to have smart card activation on slot 0 and slot 1 (Management CA) Require smart cards to activate system after boot the installation procedure will be extended by more PIN pad operations since the installer needs access to these slots to create the keys needed for operation, audit log signature and Management CA respectively.

These extensions will be activation procedures as described in the next section.

3.7.3 Application/Activation of a slotWhenever the application will attempt a "Login" to the slot (as when activating a Crypto- Token in EJBCA), the PKI Appliance will automatically and immediately request the smart card(s) to be inserted to the PIN pad. This can be noticed by a small audible alert (bee- beep). The PKI Appliance physical front display will give a short hint at which slot is being activated and user card is required to be inserted.

Whenever some PKCS#11 slot activation with smart card goes wrong, the internal PKI Appliance mechanism will restart all applications, which in turn requires that all slots need to be activated again.

Activation on boot/slot 0If Require smart cards to activate system after boot was enabled during the installation, on every system start/boot, the PKI Appliance will first require the successful activation of slot 0 before it can continue with startup. Smart card and PIN have to be entered within one hour after system start.

The user cards will always be required in ascending order, always starting with User 1.

PKI APPLIANCE ONLINE HELP - EJBCA


4 EJBCAThe following provides a brief introduction to EJBCA with references to the EJBCA Documentation. For more information on EJBCA, refer to the latest EJBCA product documentation on https://doc.primekey.com/ejbca.

4.1 EJBCA IntroductionEJBCA is one of the longest running CA software projects, providing time-proven robustness and reliability. EJBCA is platform independent, and can easily be scaled out to match the needs of your PKI requirements, whether you're setting up a national eID, securing your industrial IOT platform or managing your own internal PKI.

EJBCA covers all your needs - from certificate management, registration and enrollment to certificate validation.

4.1.1 Certificate Lifecycle ManagementEJBCA provides full capabilities for managing your certificate lifecycles, from powerful profiles that give you fine-grained and easily configured control over the identities and properties of your cryptographic certificates, automated validation of submitted keys and certification requests and multiple enrollment vectors through our own Registration Authority UI and all common enrollment protocols, to advanced administrative workflows to ensure that your organization retains control and oversight of your certificates.

EJBCA provides easy to use tools to allow administrators to easily revoke and renew certificates, ensuring that lost keys are immediately contained and that your organization suffers no downtime.

4.1.2 Integration and DevOpsEJBCA is built from the ground up to be easy and painless to deploy and maintain. A frequent release cycle ensures that bugs are quickly fixed and mitigated, and through clustering we allow upgrades to take place over an entire PKI with zero downtime. We have provided migration guides from several legacy PKIs, and integration guides to multiple third-party applications and guides for most Hardware Security Module vendors.

4.1.3 Dynamic and ScalableEJBCA is your one-stop shop, from setting up your own self-contained PKI to setting up a complex infrastructure with 100% uptime requirements and extreme performance demands. EJBCA instances can easily be couple securely over TLS in order to secure your CA infrastructure as much as possible while providing accessibility to registration and validation nodes. By clustering nodes, high levels of reliability and performance can be achieved, achieving high degrees of availability regardless of external circumstances.

4.2 EJBCA ConceptsEJBCA implements Public Key Infrastructure (PKI) according to standards such as X.509 and IETF-PKIX, and thus follows the general PKI concepts closely. The administration of the PKI includes some EJBCA specific

https://doc.primekey.com/ejbca

http://doc.primekey.com/display/EJBCADS/Migrating+from+other+CAs+to+EJBCA

http://doc.primekey.com/display/EJBCADS/Integrating+with+Third-Party+Applications

http://doc.primekey.com/pages/viewpage.action?pageId=6029878




••••

•

concepts in order to implement unique flexibility. For definitions for general and EJBCA specific concepts and key terms, see EJBCA Concepts.

4.3 EJBCA ArchitectureThere are multiple ways that you can implement and architect a PKI solution, ranging from simple and low cost, to very complex and costly. EJBCA allows implementing virtually any type of PKI architecture, for information on a selection of common PKI architectures deployed, see EJBCA Architecture.

4.4 Interoperability and CertificationsFor an overview of EJBCA's capabilities and support, with relevant links to documentation and external standards, see Interoperability and Certifications.

4.5 EJBCA AdministrationThe EJBCA administration interface allows configuring and administrating EJBCA.

4.5.1 Accessing EJBCATo access EJBCA from the Appliance WebConf, go to the Platform tab. The Applications section lists applications installed on your platform, along with their access links. Click the EJBCA link to access EJBCA.

EJBCA can also be accessed directly using the IP address according to the following example, http://<IPAddress>/ejbca/adminweb.

4.5.2 EJBCA AdministrationThe EJBCA Administration user interface allows configuring, administrating, and managing EJBCA on the PKI Appliance.

The administration interface is divided into the following menu sections based on administration operational tasks:

CA FunctionsRA FunctionsSupervision FunctionsSystem Functions

For information on how to perform day to day administrative tasks in EJBCA, refer to the EJBCA documentation EJBCA Operations Guide. For an overview of EJBCA operations in general, see EJBCA Operations

The EJBCA Operations Guide is divided into separate sections for CA operations and RA operations:

CA Operations Guide: Information on setting up CAs and profiles, and for general configuration of the EJBCA instance.

http://doc.primekey.com/display/EJBCADS/EJBCA+Concepts

http://doc.primekey.com/display/EJBCADS/EJBCA+Architecture

http://doc.primekey.com/display/EJBCADS/Interoperability+and+Certifications

https://doc.primekey.com/ejbca/ejbca-operations/ejbca-operations-guide

https://doc.primekey.com/ejbca/ejbca-operations

https://doc.primekey.com/ejbca/ejbca-operations



•

•

•

•

•

•

RA Operations Guide: Covers enrolling for certificates, managing approvals, and certificate life-cycle.

For Administrators responsible for configuring and maintaining EJBCA installations, see the EJBCA CA Concept Guide for information on EJBCA concepts and configuration.

4.5.3 CA Operations GuideThe CA Operations Guide covers Certificate Authority Operations such as how to create, edit, and manage CAs, and information on End Entities, and setting up End Entity Profiles and Certificate Profiles.

4.5.4 RA Operations GuideThe RA Operations Guide covers EJBCA RA Management tasks and describes the EJBCA menu sections and the functions you can perform in the EJBCA RA GUI.

4.5.5 Command Line InterfacesThe Command Line Interfaces section includes information on the following EJBCA Command Line Interfaces (CLIs):

EJBCA Client Toolbox: Set of tools built as a stand-alone package, which can be put on any machine and run independently of EJBCA. Includes a Web Service Interface.

EJBCA Validation/Conformance Tool: Allows running tests on issued certificates or OCSP responses to see that they match the configured criteria.

Local Command Line Interface (EJBCA CLI): The Local CLI can be run directly on the CA machine and contains many functions that can be used in scripts, or come to rescue when your Admin certificate has expired, or you have accidentally revoked your Admin privileges for the Admin GUI.

Local Database CLI: Accessing a database, export, and import, copy, verify audit log and OCSP monitoring.

CAA Lookup Tool: Providing additional verification, fallback and troubleshooting for the built-in CAA Validator.

4.5.6 EJBCA Batch Enrollment GUIInformation on the EJBCA Batch Enrollment GUI, a standalone Java desktop application used to enroll multiple end entities from certificate signing requests at once

4.5.7 ConfigDump Export and Audit ToolThe ConfigDump tool produces a human-readable YAML output, which allows you to hand-modify exports, and the tool is useful for change handling and auditing.

http://doc.primekey.com/display/EJBCADS/EJBCA+CA+Concept+Guide

http://doc.primekey.com/display/EJBCADS/EJBCA+CA+Concept+Guide

http://doc.primekey.com/display/EJBCADS/CA+Operations+Guide

https://doc.primekey.com/ejbca/ejbca-operations/ejbca-operations-guide/ca-operations-guide/managing-cas

http://doc.primekey.com/display/EJBCADS/End+Entities+Overview

http://doc.primekey.com/display/EJBCADS/End+Entity+Profiles+Overview

http://doc.primekey.com/display/EJBCADS/Certificate+Profiles+Overview

http://doc.primekey.com/display/EJBCADS/RA+Operations+Guide

http://doc.primekey.com/display/EJBCADS/Command+Line+Interfaces

http://doc.primekey.com/display/EJBCADS/EJBCA+Client+Toolbox

https://doc.primekey.com/ejbca/ejbca-operations/ejbca-ca-concept-guide/protocols/web-service-interface





https://doc.primekey.com/ejbca/ejbca-operations/ejbca-ca-concept-guide/validators-overview/certificate-field-validators

https://doc.primekey.com/ejbca/ejbca-operations/ejbca-ca-concept-guide/validators-overview/certificate-field-validators

http://doc.primekey.com/display/EJBCADS/EJBCA+Batch+Enrollment+GUI

http://doc.primekey.com/display/EJBCADS/ConfigDump+Export+and+Audit+Tool



••••

4.6 EJBCA OperationsEJBCA is a multipurpose PKI software that supports multiple CAs and levels of CAs to enable you to build a complete infrastructure (or several) for multiple use cases within one instance of the software. For more information, refer to the EJBCA Documentation.

The following sections provide an introduction to Certificate Life Cycle Management, followed by step-by-step instructions for creating a Certificate Authority (CA) hierarchy and managing End Entities.

Certificate Life Cycle ManagementCreating CA HierarchyManaging End EntitiesCreating Java Truststore

For a general introduction to EJBCA and to find definitions for concepts and key terms, refer to EJBCA Introduction.

4.6.1 Certificate Life Cycle Management

Introduction to Certificate Life Cycle ManagementLife cycle management, in the context of PKI, is the process by which entities and certificates are managed from creation ,revocation, re-issuance, revocation and deletion. Simply stated, the life of an end entity or certificate should be managed from inception through archival or purging from your PKI infrastructure. These functions are easily performed in the administrative web interface or from the command line interface ( CLI ).

The following covers managing an end entity through its life cycle from the CLI.

Entity Issuance and Maintenance

During the life cycle of an end entity or certificate there are several required tasks and other tasks which are specific to certain situations. For instance, when creating an end entity several steps must be employed and are required for the creation of the end entity. However, once an end entity is created, you are not required to verify it, create certificates for it, nor revoke or re-issue it. These tasks will be situation specific.

Creation of Entity and Certificates

Creating an end entity and its associated certificates is the main function of a certificate authority. An administrator must be aware that issuance of an endentity in no way attests to the identity of that end entity. The function of verifying an end entity’s identity (whether an individual or a piece of equipment) should be performed prior to allowing issuance of the end entity or any associated certificates and is usually performed by some external function that is interfaced into the registration authority. For instance, when issuing an end entity to a user for authentication an administrator should take either physical or digital precautions to

https://doc.primekey.com/ejbca

https://doc.primekey.com/ejbca/ejbca-introduction

https://doc.primekey.com/ejbca/ejbca-introduction



ensure the identity of that user prior to providing the user with an end entity and the associated certificates. This can be done in a myriad of ways depending on the requirements of your organisation.

Verification

Once an end entity or certificate is issued, administrators can verify the information related to that end entity or certificate prior to delivering them to the end entity for use. While this is an optional step, it is recommended during initial testing and deployment to ensure proper configuration of end entity profiles and other operational functions, via a quick command line verification of the information being issued.

Revocation, Re-issuance, Un-Revoke

Situation specific revocation, re-issuance, revocation and un-revoking an end entity is per-formed by an administrator or an automated process as a reaction or proactionto an event. For instance, if an employee of an organisation goes on an extended leave, the administrator can revoke the certificate with a status of ’On Hold’ essentially suspending the certificate which can then be un-revoked when the employee returns. Re-issuance and un-revoking are two entirely separate and distinct tasks. Re-issuance is the process in which new keys and certificates are generated for a specific end entity. Un-revoke is used for one task only to restore a certificate that has been put in an On Hold status during revocation. Lastly, revocation is used to deactivate a certificate’s usefulness, making it invalid for its intended or other uses. Revoking a certificate does not delete the certificate, it simply invalidates it.

Deletion of an End Entity

Deletion of an end entity sounds like a simple enough task of removing that entity from the PKI infrastructure, but this must be done with extreme care. In many situations the PKI infrastructure is being used for authentication, digital signing or other tasks that have legal implications. Maintaining the end entity and its associated audit trail of PKI activity is commonly desirable. It is better practice to use revocation to suspend or remove rights than to simply delete an end entity because you will retain the entity, its audit trail and other essential data that may be required for compliance or legal reasons.

Certification AuthoritiesCertificate authorities are often organized in a hierarchic model, similar to a business organisational chart. A root CA is the top level CA. This Ca can be used to issue all end entity certificates or issue an Intermediate CA that will issue all end entity certificates. If the root CA’s keys become compromised, all of the certificates issued become invalid. Therefore, protecting the root CA’s keys is highly crucial. Intermediate CAs are CAs issued and signed by the root CA. These CAs will issue the end entity certificates. The main purpose for this separation is to physically and digitally protect the root CA’s keys by taking it offline and off the network. If an intermediate CA is compromised it can be resigned without affecting the entire infrastructure.

Types of Certification Authorities

Certification authorities(CAs) can be classified using various taxonomies. The primary of these is by hierarchy. Using this classification, certification authorities can be classified as the following:



•••

•••

••

•

••

••

•

Root CA

These CAs are self signed and usually offline. As there is no CA above these CAs, they are based on the notion of self trust. The root CA is the pen ultimate trust entity and hence trusts itself.

Subordinate CA

A subordinate CA (sub CA) is an entity that is trusted by the root. A sub CA is usually created for organisational, functional, security or other commercial and non commercial reasons. While it may be functionally possible to issue all possible certificates from a single CA, this may not be desirable for security and organisational reasons. For examples, a Qualified CA(QC) is one that issues certificates for digital signatures that have the equivalence of normal digitally binding signatures. The compliance requirements of these certification authorities require that a dedicated CA be used for issuing qualified certificates. Sub CAs may be created on a functional basis. For example:

Authentication CASigning CAEncryption CA

Alternatively, sub CAs may be created on an organisational basis:

Human resources CAFinance CADocument Verifier CA

Sub CAs can also be created in a hybrid fashion:

Finance Signing CAFinance Authentication CA

Electronic travel documents have a clearly documented acceptable hierarchy. The ICAO standard for travel documents stipulates the following hierarchy:

Country Signing Certification Authority (CSCA) that issues Document Signer Certificates

For second generation electronic documents, the following certification authority hierarchy applies:

Country Verifier Certification Authority(CVCA)Document Verifier Certification Authority (DVCA)

Certification authorities can also be classified based on the format of certificates issued:

X.509 CA based on the X.509standardCVC CA based on the card verifiable standards

4.6.2 Creating CA HierarchyThis section and its subsections describe the creation of several CAs to illustrate the manner in which authorities are created. To illustrate certificate life cycle management using EJBCA, the following CAs are created:

Root CA named 'RootCA' as ROOTCA



•••

••••••••••

SSL CA named 'SSLCA' as SubCAAuthentication CA named 'AuthCA' as SubCASigning CA named 'SignCA' as SubCA

The scenario that is about to be implemented is also described in the section Using External CA for Installation. The PKI Appliance that hosts ROOT CA (node B) will be offline after is finished with signing SubCAs in node A. Compare the following illustrations:

Figure 132: Node B with RootCA installed

Figure 133: Node A with SubCAs and ManagementCA installed

The individual steps you have to perform are described in the following sections:

Step 1: Create the RootCAStep 2: Create Certificate Profile for SubCAsStep 3: Create End Entity Profile for SubCAsStep 4: Import RootCA as External CA in Node AStep 5: Create SignCA as SubCA in Node AStep 6: Create AuthCA as SubCA in Node AStep 7: Create SSLCA as SubCA in Node AStep 8: Create Certificate Profiles for End Entities that use the SubCAsStep 9: Create End Entity Profiles for SubCAsStep 10: Create End Entities that use the SubCAs



•••

1.2.

3.

Step 1: Create the RootCAInstructions below will guide you on how to create a ROOT Certification Authority with the name RootCA in node B PKI Appliance.

These are the actions you have to perform:

Create a Certificate Profile for the RootCACreate Crypto Token for RootCACreate a RootCA

Create a Certificate Profile for the RootCA

The first step is the creation of a certificate profile for the RootCA using Administration web-pages of EJBCA. We will use a template (ROOTCA) for that which we’ll clone.

When the CA is renewed it will look in the profile for the default values, simplifying the renewal process.

Click Certificate Profiles in the section CAFunctions.Click Clone for ROOTCA:

Figure 134: Certificate Profiles

Set Name of new certificate profile to RootCACertificateProfile:



4.

5.

••••

6.

1.2.3.

Figure 135: Clone a certificate profile

Click Create from template. The new profile is now displayed in the List of Certificate Profiles:

Figure 136: Certificate Profiles

Click Edit for the newly created profile and make the following changes:

Available bit lengths: Set to 4096Validity: Set to 3650dPath Length Constraint: Enable and set Value to 1Available CAs: Select Any CA

Click Save.

Create Crypto Token for RootCA

Create a CryptoToken and generate public keys which will be used from RootCA.

Access the EJBCA Administration GUI.Navigate to CA Functions > CryptoTokens.Click Create New...



4.

•••

••

•5.

1.2.3.4.5.6.7.

Figure 137: Crypto Tokens

In the form New Crypto Token, enter the following values and then click Save:

Name: Set to RootCA CryptoTokenType: Set to PKCS#11Authentication Code: Set to foo123(which was the password previously set)Make sure that you have manually generated slot pass word for that slot!PKCS#11 Reference Type: Set to Slot IDPKCS#11 Reference: Set to 2The index numbers will be different, depending on the installationAuto-activation: Leave the box unchecked.

In the Settings page the following message will be visible : Crypto Token created successfully..

To create the keys proceed as follows:

Enter default Key as the key Alias.Click RSA 4096 and then the Generate new key pair button.Click the Test button.You should see the message "default Key tested successfully".Enter sign Key with RSA 4096 and click the Generate new key pair button.Click the Test button. You should see the message "sign Key tested successfully".Enter test Key with RSA 1024 and click the Generate new key pair button. The following message should be visible "test Key tested successfully".



1.2.

3.

••••••

Figure 138: Keypair creation

Create a RootCA

This section involves the actual creation of the RootCA.

Click Certification Authorities.Enter RootCA in the field AddCA and click Create:

Figure 139: Certification Authorities

In the Create CA form, make the following settings:

Signing Algorithm: Set to SHA256WithRSACryptoToken: Set to RootCA Crypto TokenValidity(*y *mo *d): Set to 10ySubject DN: Set to CN=RootCA, O=EJBCA Course,C=SECertificate Profile: Select RootCACertificateProfileCRL Expire Period (*d *h *m): Set to 2d. The value defines how long a CRL is valid for. The letter d specifies days.



•

•

4.

1.2.3.

4.5.

CRL Issue Interval (*d*h*m): Set to 0d. The value defines how often the CRLs are to be issued. In this case the CRLs will be issued once everyday but will be valid for two days.CRL Overlap Time (*d*h*m): Set to 6h. The value defines the number of minutes both CRLs are valid for. For example, thirty minutes before the first CRL will expire it will issue a new CRL.

Click Create.

Step 2: Create Certificate Profile for SubCAsIn this step we will create a Certificate Profile for SubCAs which will be created in another PKI Appliance. This profile will be used when RootCA will sign SubCA’s certificate.

Navigate to Administration pages.Click Certificate Profiles in the section CA Functions.For the SUBCA profile click Clone:

Figure 140: Clone SUBCA

Set Name of new certificate profile to SubCACertificateProfile.Click Create from template:

The values in this profile are for renewal.



6.

7.

•••••

8.

1.2.

Figure 141: Create from template

In the List of Certificate Profiles click Edit for SubCACertificateProfile:

Figure 142: Edit Certificate Profile

In the Edit form, make the following settings:

Available bit lengths: Set to 409Validity(*y*mo*d) or end date of the certificate: Set to 5yPath Length Constraint: Enable and set Value to 0Key Usage: Enable Key certificate sign and CRL sign.Available CAs (in section Other data): Select RootCA

Click Save.

Step 3: Create End Entity Profile for SubCAsIn this step we will create an End Entity Profile for SubCAs which will be created in another PKI Appliance. This profile will be used when we will create end entities for SubCAs.

Navigate to the Administration pages.Click End Entity Profiles in the section RA Functions.



3.

4.5.

•

•••

••••••

Enter SubCAEndEntity Profile in the text field and click Add:

Figure 143: Create End Entity profile for SUB CAs

Highlight SubCAEndEntityProfile and click Edit End Entity Profile.In the Edit End Entity Profile form, specify the following:

End Entity E-mail: Disable this option.

Section 'Subject DN Attributes'CN, Common name: Add the value and select the options Required and Modifiable.O, Organization: Add the value and select the options Required and Modifiable.C, Country: Add the value and select the options Required and Modifiable.

Section 'Main certificate data'(not visible in screenshot)Default Certificate Profile: Select the option SubCACertificateProfileAvailable Certificate Profiles: Select the option SubCACertificateProfileDefault CA: Select the option RootCAAvailable CAs: Select the option RootCADefault Token: Select the option User GeneratedAvailable Tokens: Select the option User Generated



6.

•

•

•

1.2.

Figure 143: Edit End Entity Profile for SubCAs

Click Save.

Step 4: Import RootCA as External CA in Node AImplementation of PKI infrastructure that is described in the current guide has an online and one offline PKI Appliance. Now that RootCA is setup, there is the possibility to install it in the one that is online. The reasons to do it are:

It is easy to understand the logical hierarcy when navigating to Certification Authorities. There you can see that the SubCAs are installed locally but also that there is a ROOTCA which signed them, having the indication External CA. This means that is installed in the offline PKI Appliance.When CSRs are created and have to be signed by RootCA, no other import is needed (RootCAs certificate). The chain is auto generated.When you do certificate enrollment from a CSR you just need to set PEM - Certificate only as Result type.

To import RootCA’s certificate in the PKI Appliance that is online, proceed as follows:

In Public Web of node B, where the RootCA is installed, open Retrieve > Fetch CA Certificates.In the section CA:RootCA, you will find the the options for downloading CA certificate or CA certificate chain:



3.4.

5.6.7.8.9.

Figure 144: Fetch RootCA certificate

Select the option Download as PEM for CA certificate chain.Save the file:

Figure 145: Save RootCA pem file

Navigate to Certification Authorities in PKI Appliance node A where the pem file will be imported.Click Import CA certificate...Enter RootCA in the field The name this CA will be givenBrowse for the file RootCA-chain.pem.Click Import CA certificate.



••

1.2.

3.

•••

•

Figure 146: Import RootCA as External CA

Step 5: Create SignCA as SubCA in Node AYou will create the first of the SubCAs, that is, SignCA. To get this CA with the other SubCAs, it will be installed in the PKI Appliance node A (where Management CA is installed) and will be signed by RootCA.


Create Crypto Token for SignCACreate SignCA

Create Crypto Token for SignCA

Proceed as follows to create a CryptoToken and generate public keys which will be used from AuthCA.

In the EJBCA Administration GUI, open CA Functions > Crypto TokensClick Create New... to open the New Crypto Token form:

Figure 147: Crypto Token creation for SignCA

Specify the following values:

Name: Enter SignCA Crypto TokenType: Select PKCS#11Authentication Code: Enter foo123Make sure that you have manually generated the slot password for that slot.Auto-activation: Activate this option.



••

4.

5.

6.

7.8.

9.10.

1.2.

PKCS#11 Reference Type: Select Slot IDPKCS#11 Reference: Enter 2The index numbers will be different depending on the installation.

Click Save. In the settings page the following message will appear: Crypto Token created successfully. Continue with creating the following keys.Underneath the table, enter defaultKeySignCA (value for Alias) and RSA 4096 (value for Key Algorithm and Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear: defaultKeySignCA tested successfully.Underneath the table, enter KeySignCA with RSA 4096 and click Generate new key pair. Click the Test button in the table. The following message will appear: signKeySignCA tested success-fully.Underneath the table, enter test KeySignCA with RSA 1024 and click Generate new key pair.Click the Test button in the table. The following message will testKeySignCA tested successfully.

Figure 148: Create keys for SignCA

Create SignCA

Proceed as follows to actually create the SignCA:

Open CA Functions > Certification Authorities.Enter SignCA in the field Add CA and click Create:



3.

••••

•

•

•

4.

Figure 149: Create SignCA in Certification Authorities

In the Create CA form, specify the following:

Signing Algorithm: Select the option SHA256WithRSACrypto Token: Select the option SignCA CryptoTokenSubject DN: Enter the values CN=SignCA,O=EJBCA Course,C=SESigned by: Select the option External CAWhen this option is selected, some fields will become read-only.CRL Expire Period (*d *h *m): Enter the value 12hThis option defines how long a CRL is valid for.CRL Issue Interval (*d *h *m): Enter the value 0This option defines how often the CRLs are to be issued. In this case the CRLs will be issued once every day but will be valid for two days.CRL Overlap Time (*d *h *m): Enter the value 2h

Note that only some options are visible in the screenshot below.

Figure 150: SignCA settings

In the section Externally signed CA creation/renewal click Browse... and upload the RootCA.pem file.



5.

6.7.

8.

•••••••••

9.10.

Click Make Certificate Request:

Figure 151: Create CSR for SignCA

Save the .csr file with Save File.To check the status of the CAs, click Certification Authorities in the section CA Functions. Status for SignCA is Waiting for Certificate Response.In the PKI Appliance where RootCA is installed (node B), you have to create an end entity which will be binded with SignCA certificate. Navigate to RA Functions > Add End Entities and provide the following values:

End Entity Profile: Select the option SubCAEndEntityProfileUsername: Enter the value signCAPassword and Confirm Password: Enter the value foo123CN, Common name: Enter the value SignCAO, Organization: Enter the value EJBCA CourseC, Country (ISO 3166): Enter the value SECertificate Profile: Select the option SubCACertificateProfileCA: Select the option RootCAToken: Select the option User Generated

Figure 152: Create an End Entity for SignCA in the PKI Appliance where RootCA is installed

Click AddOpen Enroll >Create Certificate from CSR and enter the following values:

This step is NOT neededif you have imported RootCA as an External CA. Otherwise, RootCA.pem can be downloaded from the Public Web of the PKI Appliance which is installed the RootCA.



•

•••

11.12.

13.

14.

15.

Username: Enter the value signCAThis is the end entity you just created.Enrollment code: Enter the value foo123Request file: Click Browse and upload SignCA_csr.pemResult type: Select the option PEM - full certificate chainThe chain is NOT needed if you have RootCA as External CA. Then it is enough to select PEM - certificate only.

Figure 153: Sign CSR request for SignCA

Click OKSave the SignCA.pem file:

Figure 154: Download signed .pem for SignCA

In the PKI Appliance where SignCA is installed (node A), click Certification Authorities, select SignCA, (Waiting for Certificate) and press Edit CA.In the section Externally signed CA creation/renewal > Step 2, click Browse and search for the SignCA.pem.Click Receive Certificate Response:



16.

••

1.2.

Figure 155: Upload signed CSR for SignCA

In the section CA Functions > Certification Authorities you will see that SignCA is now active:

Figure 156: Activated SignCA

Step 6: Create AuthCA as SubCA in Node AHere we will create the second of the SubCAs which is AuthCA. This CA together with the other SubCAs will be installed in PKI Appliance node A (where ManagementCA is installed) and will be signed by RootCA.


Create Crypto Token for AuthCACreate AuthCA

Create Crypto Token for AuthCA

At that point we will create a Crypto Token and generate public keys which will be used from AuthCA.

In the EJBCA Administration GUI, navigate to CA Functions > Crypto Tokens.Click Create New....



3.

•••

•••

4.

5.

6.

7.

In the New Crypto Token form specify the following:

Name: Auth CryptoTokenType: PKCS#11Authentication Code : foo123(STOP) Make sure that you have manually generated slot password for that slot!PKCS#11 Reference Type: Slot IDPKCS#11 Reference: 3 - The index numbers will be different depending on the installationClick the Auto-activation box

Click Save

Figure 157: Crypto Token creation for AuthCA

In the settings page, the message CryptoToken created successfully will be displayed. Continue with creating the following keys.Underneath the table, enter defaultKeyAuthCA (value for Alias) and RSA 4096 (value for Key Algorithm and Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear: defaultKeyAuth tested successfully.

Figure 157: Create keys for AuthCA



8.

9.

10.

11.

1.2.3.

4.

••

••

•

•

Underneath the table, enter signKeyAuthCA (value for Alias) and RSA 4096 (value for Key Algorithmand Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear: signKeyAuthCA tested successfully.Underneath the table, enter testKeyAuthCA (value for Alias) and RSA 1024 (value for Key Algorithmand Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear: testKeyAuthCA tested successfully.

Create AuthCA

This section describes the actual creation of the AuthCA.

Click Certification Authorities.Enter AuthCA in the Add CA field.Click Create...

Figure 157: Create AuthCA in Certification Authorities

In the Create CA form, make the following entries:

Signing Algorithm: Select SHA256WithRSACrypto Token: Select Auth CryptoToken

Section 'Ca certificate data' (not visible in screenshot):Subject DN: Enter CN=AuthCA,O=EJBCA Course,C=SESigned By: Select External CA

Section 'CRL specific data' (not visible in screenshot):CRL Expire Period (*d *h *m): Enter 12hThis field defines how long a CRL is valid for. The letter d specifies days.CRL Issue Interval (*d *h *m): Enter 0This field defines how often the CRLs are to be issued. In this case the CRLs will be issued once every day but will be valid for two days.



•

5.

6.

7.

CRL Overlap Time (*d *h *m): Enter 2hThis value defines the number of minutes both CRLs are valid for. For example, thirty minutes before the first CRL will expire it will issue a new CRL.

Figure 158: Create CA settings



Figure 159: Create CSR for AuthCA

You will be asked to download or copy the request. Save the .csr file with Save File:

This step is NOT needed in the case that you have imported RootCA as an External CA. Otherwise, RootCA.pem can be downloaded from the Public Web of the PKI Appliance which is installed the RootCA (check Use-Case: Import RootCA as External CA in node A).



8.

9.

••••••••

10.

Figure 160: Generation of CSR

Check the status of the CAs: Click Certification Authorities in the section CA Functions. The status for AuthCA is Waiting for Certificate Response:

Figure 161: Certification Authorities status

In the PKI Appliance where RootCA is installed (node B), you need to create an End Entity which will be binded with AuthCA certificate. Navigate to RA Functions > Add End Entities and provide the following values:

Username: Enter authCAPassword and Confirm Password: Enter foo123CN, Common name: Enter AuthCAO, Organization: Enter EJBCA CourseC, Country (ISO 3166): Enter SECertificate Profile: Enter SubCACertificateProfileCA: Select RootCAToken: Select User Generated

Click Add:



11.

•

•••

12.

13.

Figure 162: Create an End Entity for AuthCA in the PKI Appliance where RootCA is installed

Click Enroll > Create Certificate from CSR and enter the following:

Username: Enter authCAThis is the End Entity you created before.Enrollment code: Enter foo123Click Browse... and upload the AuthCA_csr.pemResult type: Select PEM - full certificate chainThe chain is NOT needed if you have RootCA as External CA. Then it is enough to choose PEM - certificate onlyCheck Use-Case: Import RootCA as External CA in node A

Click OK.

Figure 163: Sign CSR request for AuthCA

Save the AuthCA.pem file:



14.

15.

16.

Figure 164: Download signed .pem for AuthCA

In the PKI Appliance where AuthCA is installed (node A), click Certification Authorities, highlight AuthCA, (Waiting for Certificate) and press Edit CA:

Figure 165: EditAuthCA

In the section Externally signed CA creation/renewal > Step 2, click Browse... and select the file AuthCA.pem.Click for Receive Certificate Response:



17.

••

1.2.

Figure 166: Upload signed CSR for AuthCA

Navigate to Certification Authorities to see that AuthCA is now active:

Figure 167: Activated AuthCA

Step 7: Create SSLCA as SubCA in Node AThis section describes how to create the third of the SubCAs which is SSLCA. This CA together with the other SubCAs will be installed in PKI Appliance node A (where ManagementCA and other SubCAs are installed) and will be signed by RootCA.


Create Crypto Token for SSLCACreate SSLCA

Create Crypto Token for SSLCA

Create a Crypto Token and generate public keys which will be used from SSLCA:

Open the EJBCA Administration GUI and navigate to CA Functions > Crypto Tokens.Click Create New... .



3.

•••

••

4.

5.

6.

7.

8.

9.

10.

11.

In the form New Crypto Token, enter the following values:

Name: Enter SSLCA CryptoTokenType: Select PKCS#11Authentication Code : Enter foo123Make sure that you have manually generated slot password for that slot.PKCS#11 Reference Type: Select Slot IDPKCS#11 Reference: Enter 4

Click Save

Figure 168: Crypto Token creation for SSLCA

In the settings page, the following message will be visible: CryptoToken created successfully.Continue with creating the following keys.Underneath the table, enter defaultKeySSLCA (value for Alias) and RSA 4096 (value for Key Algorithmand Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear: defaultKeySSLCA tested successfully.Underneath the table, enter signKeySSLCA (value for Alias) and RSA 4096 (value for Key Algorithmand Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear: signKeySSLCA tested successfully.Underneath the table, enter testKeySSLCA (value for Alias) and RSA 1024 (value for Key Algorithmand Key Specification) and click Generate new key pair.Click the Test button in the table. The following message will appear testKeySSLCA tested successfully.



1.2.

3.

••

••

Figure 168: Create keys for SSLCA

Create SSLCA

This section describes the actual creation of the SSLCA:

Open CA Functions > Certification Authorities.Enter AuthCA in the field Add CA and click Create...:

Figure 169: Create SSLCA in Certification Authorities

In the Create CA form, make the following entries:

Signing Algorithm: Select SHA256WithRSACrypto Token: Select SSLCA CryptoToken

Section 'CA certificate data' (not visible in screenshot)Subject DN: Enter CN=SSLCA,O=EJBCA Course,C=SESigned By: Select External CA

Section 'CRL specific data' (not visible in screenshot)



•

•

•

4.

5.

6.

CRL Expire Period (*d *h *m): Enter 12hThis field defines how long a CRL is valid for.The letter “d” after the number specifies days.CRL Issue Interval (*d *h *m): Enter 0This defines how often the CRLs are to be issued. In this case the CRLs will be issued once every day but will be valid for two days.CRL Overlap Time (*d *h *m): Enter 2hThis value defines the number of minutes both CRLs are valid for. For example, thirty minutes before the first CRL will expire it will issue a new CRL.

Figure 170: SSLCA settings



Figure 171: Create CSR for SSLCA

You will be asked to download or copy the request. Save the .csr file with Save File:

This step is NOT needed in case you have imported RootCA as an External CA. Then RootCA.pem can be downloaded from the Public Web of the PKI Appliance which is installed the RootCA (check Use-Case: Import RootCA as External CA in node A).



7.

••••••••

8.

9.

•

Figure 172: Generation of CSR

In the PKI Appliance where RootCA is installed (node B), you have to create an End Entity which will be binded with SSLCA certificate. Navigate to RA Functions >Add End Entities and provide the following values:

Username: Enter sslCAPassword and Confirm Password: Enter foo123CN, Common name: Enter SSLCAO, Organization: Enter EJBCA CourseC, Country (ISO 3166): Enter SECertificate Profile: Select SubCACertificateProfileCA: Select RootCAToken: Select User Generated

Click Add

Figure 173: Create an End Entity for SSLCA in the PKI Appliance where RootCA is installed

Click Enroll > Create Certificate from CSR and make the following entries:

Username: Enter sslCAThis is the End Entity you created before.



•••

10.

11.

12.

Enrollment code: Enter foo123Click Browse... and upload the SSLCA_csr.pemResult type: Select PEM - full certificate chainThe chain is NOT needed if you have RootCA as External CA. Then it is enough to choose PEM - certificate onlyCheck Use-Case: Import RootCA as External CA in node A

Click OK:

Figure 174: Sign CSR request for SSLCA

Save AuthCA.pem file:

Figure 175: Download signed .pem for SSLCA

In the PKI Appliance where SSLCA is installed (node A), click Certification Authorities , highlight SSLCA, (Waiting for Certificate) and press Edit CA:



13.

14.

15.

Figure 176: Edit SSLCA

In the section Externally signed CA creation/renewal > Step 2, Browse... and select the file SSLCA.pem.Click Receive Certificate Response:

Figure 176: Upload signed CSR for SSLCA

Navigate to Certification Authorities to see that SSLCA is now active:



•••

1.2.3.

Figure 177: Activated SSLCA

Step 8: Create Certificate Profiles for End Entities that use the SubCAsCertificate Profiles define different types of certificates, with regards to DN-contents, extensions etc.Create Certificate Profiles for the End Entities that will use the SubCAs (SignCA, AuthCA, SSLCA) you created in the previous steps.


Create Certificate Profile for End Entities that will use AuthCACreate Certificate Profile for End Entities that will use SignCACreate Certificate Profile for End Entities that will use SSLCA

Create Certificate Profile for End Entities that will use AuthCA

This section describes the creation of the Certificate Profile for the End Entities that will use AuthCA.

Open CA Functions > Certificate Profiles.Enter AuthCAEndEntityCertificateProfile in the text field underneath the table.Click Add:



4.

••••

••

•

•

5.

Figure 177: Create Certificate Profile for AuthCA

Make the following entries:

Type: Select End EntityAvailable bit lengths: Select 2048 bitsSignature Algorithm: Select Inherit from issuing CAValidity: Enter 730d

Section 'Key usage'Enable Digital SignatureEnable Key ecipherment

Section 'Key usage'Enable Use and select Client Authentication

Section 'Other data'Available CAs: Select AuthCA

Figure 178: Certificate Profile Settings for AuthCA

Click Save:



1.2.3.

4.

••••

•

Figure 178: Certificate Profile Settings for AuthCA 2

Create Certificate Profile for End Entities that will use SignCA

This section describes the creation of the Certificate Profile for the End Entities that will use SignCA

Open CA Functions > Certificate Profiles.Enter SignCAEndEntityCertificateProfile in the text field underneath the table.Click Add:

Figure 179: Create Certificate Profile for SignCA

Make the following entries:

Type: Select End EntityAvailable bit lengths: Select 2048 bitsSignature Algorithm: Select Inherit from issuing CAValidity: Enter 730d

Section 'Key Usage'Enable Digital Signature



•

•

•5.

1.2.3.4.

Enable Non-repudiation

Section 'Extended Key Usage'Disable Use

Section 'Other data'Available CAs: Select SignCA

Click Save

Figure 180: Certificate Profile Settings for SignCA cont

Create Certificate Profile for End Entities that will use SSLCA

This section describes the creation of the certificate profile for the end entities that will use SSLCA. For that purpose you will clone a template.

Open CA Functions > Certificate Profiles.Click Clone for SERVER.In the field Name of the new certificate profile enter SSLCAEndEntityCertificateProfile.Click Create from template:



5.6.

••••••

•7.

Figure 181: Clone Certificate Profile for SSLCA

In Certificate Profiles, click Edit for the newly created profile.Make the following entries:

Type: Select End EntityAvailable bit lengths: Select 2048 bitsSignature Algorithm: Select Inherit from issuing CAValidity: Enter 730dKey Usage: Enable Digital SignatureExtended Usage: Select Server Authentication

Section Other dataAvailable CAs: Select SSLCA

Click Save:

Figure 182: Certificate Profile X.509 extensions Settings for SSLCA



•••

1.2.3.4.5.

6.

••••

•

Step 9: Create End Entity Profiles for SubCAsEnd entity profiles define which parts of the user DN will be registered for various types of end entities. It defines, for example, the preset part and the part that can be altered. It also contains other information for issuing certificates, that is specific to each individual end entity. For each SubCA you will configure a different end entity profile.


Create End Entity Profile for AuthCACreate End Entity Profile for SignCACreate End Entity Profile for SSLCA

Create End Entity Profile for AuthCA

This section describes the creation of the end entity profile for the end entities that will use AuthCA.

Open RA Functions > End Entity Profiles.In the field Add Profile enter AuthCAEndEntityProfile .Click Add.In the list List of End Entity Profiles select AuthCAEndEntityProfile.Click Edit End Entity Profile:

Figure 183: Create End Entity Profile for AuthCA

In the Edit form make the following entries:

Subject DN Attributes: Enter the appropriate value and click AddCN, Common name: Enable ModifiableO, Organization: Enable Required and enter EJBCA CourseC, Country (ISO 3166): Enable Required and enter SE

Section Main Certificate DataDefault Certificate Profile: Select AuthCAEndEntityCertificateProfile



•••••

7.

1.2.3.4.5.

6.

•••

Available Certificate Profile: Select AuthCAEndEntityCertificateProfileDefault CA: Select AuthCAAvailable CA: Select AuthCADefault Token: Select User generatedAvailable Tokens: Select User generated and P12 file

Figure 184: Subject DN Attributes for AuthCA End Entity Profile

Click Save:

Create End Entity Profile for SignCA

This section involves the creation of the End Entity Profile for the End Entities that will use SignCA.

Click on End Entity Profiles under RA Functions.Write SignCAEndEntityProfile in Add Profile text field.Click Add .Highlight SignCAEndEntityProfile from List of End Entity Profiles.Click Edit End Entity Profile:

Figure 184: Create End Entity Profile for SignCA

In the Edit form make the following entries:

Subject DN Attributes: Enter the appropriate value and click AddCN, Common name: Enable ModifiableO, Organization: Enable Required and enter EJBCA Course



•

••••••

7.

1.2.3.4.

C, Country (ISO 3166): Enable Required and enter SE

Section Main Certificate DataDefault Certificate Profile: Select SignCAEndEntityCertificateProfileAvailable Certificate Profile: Select SignCAEndEntityCertificateProfileDefault CA: Select SignCAAvailable CA: Select SignCADefault Token: Select User generatedAvailable Tokens: Select User generated

Figure 185: Subject DN Attributes for SignCA End Entity Profile

Click Save

Create End Entity Profile for SSLCA

This section describes the creation of the end entity profile for the end entities that will use SSLCA.

Open RA Functions > End Entity Profiles.In the Add Profile field enter SSLCAEndEntityProfile.Select SslServerProfile and click Use selected as template.Select SSLCAEndEntityProfile from the list List of End Entity Profiles and click Edit End Entity Profile:

Remember that we have used Non-repudiation in its certificate profile. That ensures that users only are responsible for the creation and storage of their public key in a smart card. Compare section Create Certificate Profile for End Entities that will use SignCA.



5.

••••

••••••

6.

Figure 185: Clone End Entity Profile for SSLCA

In the Edit form, make the following entries:

Subject DN Attributes: Enter the appropriate value and click AddCN, Common name: Enable ModifiableO, Organization: Enable Required and enter EJBCA CourseC, Country (ISO 3166): Enable Required and enter SE

Section Main Certificate DataDefault Certificate Profile: Select SSLCAEndEntityCertificateProfileAvailable Certificate Profile: Select SSLCAEndEntityCertificateProfileDefault CA: Select SSLCAAvailable CA: Select SSLCADefault Token: Select User generatedAvailable Tokens: Select P12 file, User Generated, JKS file, and PEM file

Figure 185: Subject DN Attributes for SSLCA End Entity Profile

Click Save



•••

1.2.

•••••••••

3.

4.5.

•

Step 10: Create End Entities that use the SubCAsAfter configuring CAs and profiles you can proceed with adding end entities that will use those SubCAs.In a first step, end entities will be created with the values that are required depending on the End Entity Pofile. In a next step, you will go through the steps to Create Browser Certificate or to Create Keystore.


Create an End Entity that will use SSLCACreate an End Entity that will use AuthCACreate an End Entity that will use SignCA

Create an End Entity that will use SSLCA

This section describes the creation of the end entities that will use SSLCA.

Open RA Functions > Add End Entity.In the Add End Entity form enter the following values:

End Entity Profile: Select SSLCAEndEntityProfileUsername: Enter testsrv.coursePassword: Enter foo123Confirm Password: Enter foo123CN, Common name: Enter testsrv.courseDNS Name: Enter testsrv.courseCertificate Profile: Select SSLCAEndEntityCertificateProfileCA: Select SSLCAToken: Select P12 file

Click Add:

Figure 185: Create End Entity for SSLCA

Navigate to Public WebOpen Enroll > Create Browser Certificate and enter the following credentials:

Username: Enter testsrv.course



•6.

7.8.

9.

Password: Enter foo123Click OK:

Figure 185: Keystore Enrollment for testsrv.course

For Key length select 2048 bits.Click Enroll:

Figure 185: Enrollment for testsrv.course

Save the testsrv.course.p12 keystore:



1.2.

••••••••

3.

Figure 186: Save testsrv.course.p12 file

Create an End Entity that will use AuthCA

This section describes the creation of the end entities that will use AuthCA.

Open RA Functions > Add End Entity.In the Add End Entity form enter the following values:

End Entity Profile: Select AuthCAEndEntityProfileUsername: Enter Auth_User_1Password: Enter foo123Confirm Password: Enter foo123CN, Common name: Enter Auth User 1Certificate Profile: Select AuthCAEndEntityCertificateProfileCA: Select AuthCAToken: Select P12 file

Click Add:

Figure 186: Create End Entity for AuthCA



4.5.

••

6.

7.8.9.

1.2.

••••••••

3.4.5.

••

6.7.

Navigate to Public Web.Open Enroll > Create Keystore and enter the following credentials:

Username: Enter Auth_User_1Password: Enter foo123

Click OK:

Figure 186: Browser Certificate for Auth_User_1

For Key length select 2048 bits.For Certificate Profile select AuthCAEndEntityCertificateProfile.Click Enroll.

Create an End Entity that will use SignCA

This section describes the creation of the end entities that will use SignCA.

Open RA Functions > Add End Entity.In the Add end entity form enter the following values:

End Entity Profile: Select SignCAEndEntityProfileUsername: Enter Sign_User_1Password: Enter foo123Confirm Password: Enter foo123CN, Common name: Enter Sign User 1Certificate Profile: Select SignCAEndEntityCertificateProfileCA: Select SignCAToken: Select User Generated

Click Add.Navigate to Public WebOpen Enroll > Create Browser Certificate and enter the following credentials:

Username: Enter Sign_User_1Password: Enter foo123

Click OKFor Key length select 2048 bits



8.9.

1.2.3.

1.2.3.4.5.6.

For Certificate Profile select SignCAEndEntityCertificateProfileClick Enroll.

4.6.3 Managing End EntitiesManaging End Entities is a task performed by administrators on a regular basis. In larger PKI deployments, dedicated staff is assigned the management of end entities and associated CRL lists.

Use-Case: Search for end entitiesTo search for end entities, proceed as follows:

Click Search End Entities.In the field Search end entity with username enter Auth_User_1.Click Search.

Certificate RevocationAs described previously, there is no mechanism for recalling a certificate once it has been issued. Although there would be a business need to disable use of the certificate once it has been issued. This could be for a number of reasons.

As an example, if a user loses a token that contains their certificate, this needs be revoked so that a person who finds this cannot use it in the digital environment.

In the real world, black lists serve this purpose. If for example, a user loses their passport, the passport number is added to a blacklist of lost passports. Thus this passport cannot be used in the future.

In a similar manner if a certificate is to be revoked, this is added to a black list. This black list is updated on a regular basis and circulated and published in a manner accessible to subscribers. This list is referred to as a certificate revocation list (CRL)

It may also be possible to provide a service for online checking where by a third party that wishes to check the validity of a certificate.

Use-Case: Revoke a Certificate

To revoke a certificate using EJBCA, proceed as follows:

Click Search End Entities.In the field Search end entity with username enter Auth_User_1 and click Search.Click View Certificates for Auth_User_1.Select Unspecified as the revocation reason, and click Revoke.A message will appear asking if you are sure you want to revoke the certificate. Click OK to accept.Close the popup window.



1.2.3.4.5.6.7.8.9.

••••

Use-Case: Re-issue a Certificate

To re-issue a certificate using EJBCA, do the following:

Click Search End Entities.In the field Search end entity with username enter Auth_User_1 and click Search.Click Edit End Entity for Auth_User_1.In the fields Password and Confirm Password enter foo123.Set Status to New and click Save.Select Public Web > Create Browser Certificate.Enter Auth_User_1 as the username, enter the password, and click OK.Select 1024 (Medium Grade in Firefox) as Key length.Click OK and close the window.

4.6.4 Creating Java TruststoreThe following describes how to create a Java truststore for the PrimeKey PKI Appliance.

BackgroundCreate Truststore of Publicly Trusted CA CertificatesAdd New CA CertificatesInstall Truststore on PKI Appliance

Background

Missing Truststore

If you attempt to establish an outgoing TLS connection from EJBCA running on the PrimeKey PKI Appliance to another system, for example, when using an LDAP Publisher with the StartTLS extension enabled, or when trying to publish to a CT log server, you may get the following error message in the Wildfly log file:

ERROR: Error binding to LDAP server. Connect Error: LDAPException: Could not

negotiate a secure connection (91) Connect Error

javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error:

java.security.InvalidAlgorithmParameterException: the trustAnchors parameter

must be non-empty

The reason for this error message is that appliance version 3.0 to 3.4.4 shipped without a Java truststore.

Solution

The solution is to create your own Java truststore and add it to the PrimeKey PKI Appliance. You need to access the appliance over SSH to do this. There is functionality to add and remove trust anchors in WebConf, but they only affect the trust of incoming TLS connections.



Peer connectors are not affected, because a truststore of CAs installed in EJBCA is dynamically created when a pool of TLS connections for a peer connector is created. This means that you will be able to verify server certificates of upstream peers as long as the issuer of the server certificate is present as a CA in EJBCA.

Add Trust for your Internal CA

Even if you already have a Java truststore installed on the appliance, you may still want to add additional CA certificates to it, to be able to establish TLS connections to servers secured by your internal PKI.

What is keytool?

Keytool is a utility for managing Java keystores (JKS files). Keytool is part of your Java distribution. If you do not have Java installed on your machine, you can run the keytool commands on the appliance instead.

Create Truststore of Publicly Trusted CA CertificatesThe following describes how to create a truststore of publicly trusted CA certificates that you can use for an appliance that was shipped without a default truststore. This allows you to create outgoing TLS connections to servers on the internet (e.g. to publish to CT logs).

The easiest way to do this is to grab the truststore from an existing installation of Java. The truststore is located in:

<java-home>/lib/security/cacerts

For example, on Linux:

/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security/cacerts

To inspect the list of CA certificates in this truststore, use the following keytool command:

> keytool -list -keystore <path-to-truststore> -storepass changeit

Add New CA CertificatesThe following describes how to import a new CA certificate (e.g. the CA certificate of your internal root CA) to a truststore. This allows you to create outgoing TLS connections to servers on your intranet.

To add a new CA certificate to an existing truststore, or create a new truststore from an existing CA certificate, use the following keytool command

When adding CA certificates, add only the root CA (self-signed certificate) to the truststore to minimize truststore maintenance.



1.

2.

> keytool -keystore cacerts -alias <some-alias> -importcert -file <some-certificate.crt> -storepass changeit[...]Certificate fingerprints: MD5: A2:D6:B8:88:46:C7:52:75:26:5F:C4:8F:71:AC:2B:D5 SHA1: 10:EE:BA:61:8B:66:49:DC:07:87:AF:7E:F6:B8:87:56:6B:C2:CE:74 SHA256: 17:9B:F9:DB:97:7C:67:13:C0:9D:BD:23:E8:83:4F:7E:65:23:84:C2:0C:20:2C:B9:2C:56:EA:C0:F6:69:F4:09[...]Trust this certificate? [no]: yesCertificate was added to keystore

The command prints some information about the certificate. Inspect the certificate and enter yes to add it.

Install Truststore on PKI ApplianceThis section describes how to transfer a truststore you have created and install it on the PKI Appliance.

Go to the Appliance WebConf, click Platform > Platform access and select Enable SSH access.

Connect to the appliance using, for example, WinSCP (Windows) or SCP (Linux). Connect to the appliance using the IP address of the management interface and use the root user to log in.

The truststore must be installed again after a factory reset of the appliance and if you have a cluster of appliances you must add the truststore to each node in the cluster (files you add to /etc are not synchronized between the nodes).



3.

4.

5.

Assuming the IP address of the box is 192.168.31.12, this is what it would look like in WinSCP.

Transfer the cacerts truststore file to the appliance.

Get terminal access to the appliance by connecting to it using for example PuTTY (Windows) or SSH (Linux).Run the following commands to install the cacerts file.

scp cacerts cos-ejbca:ssh cos-ejbcamkdir /etc/ssl/javamv cacerts /etc/ssl/java/cacertsreboot



6. Wait for a minute until cos-ejbca has rebooted. This is usually quick (only a part of the appliance is rebooting, not the whole machine).

PKI APPLIANCE ONLINE HELP - SIGNSERVER


••••

5 SignServerThe following provides a brief introduction to SignServer and information on how to access SignServer from the Appliance WebConf. For more information on SignServer, refer to the latest SignServer product documentation on https://doc.primekey.com/signserver.

5.1 SignServer IntroductionSignServer is a framework designed to perform different kinds of digital signatures for different applications.

SignServer digitally signs your documents, code, time-stamping, and ePassports. It keeps signature keys secure, and your workflows easy, secure and auditable.

Code Signing: MS Authenticode, Java including Android APK and Generic.Document Signing: PDF, XML, XAdES (BES and T).Time Stamping: RFC 3161 and MS Authenticode time stamps, ETSI compliant.ePassports: ICAO compliant MRTD signer.

For more information, refer to the SignServer product documentation section SignServer Introduction.

5.2 Accessing SignServerTo access SignServer from the Appliance WebConf, go to the Platform tab. The Applications section lists applications installed on your platform, along with their access links. Click the SignServer link under Service Access to access the SignServer Public Web.

Figure 187: Accessing SignServer from Appliance WebConf

SignServer can also be accessed directly using the IP address according to the following example, http://<IPAddress>/signserver/.

SignServer is an optional feature on the PKI Appliance. The following sections are only relevant for PKI Appliances with the SignServer application enabled.

https://doc.primekey.com/signserver

https://doc.primekey.com/signserver/signserver-introduction



•

••

•

•

•

In the displayed SignServer Public Web, the following resources are available:

Client Web: Upload forms for requesting signing (or validation) of documents or files of different types.Health Check: Page providing the status for configured workers.Documentation: SignServer product documentation with instructions on how to install, set up, and use SignServer.Client CLI Download: Allows downloading the SignServer Client CLI SignClient, a tool used for sending signing requests to SignServer.Administration Web: The SignServer Administration Web (AdminWeb) allows configuring, administrating, and managing SignServer on the PKI Appliance.SignServer Web site: Links to signserver.org.

5.3 SignServer Administration Web The SignServer Administration Web allows configuring, administrating, and managing SignServer on the PKI Appliance.

To access the SignServer Administration Web, click the Administration Web link in the SignServer Public Web (http://<IPAddress>/signserver/).

The SignServer Administration Web lists status information in the top-right and the menu bar provides access to the different Administration Web pages (listed below).

Figure 188: SignServer Administration Web

Note that your web browser needs access to your client certificate obtained during the PKI Appliance installation.

Note that your web browser needs access to your client certificate obtained during the PKI Appliance installation.



••

•

•

•

•

•••

5.3.1 Administration Web pagesThe following lists the Administration Web pages (available for selection in the menu bar) and links to more information in the SignServer product documentation.

Workers: Lists configured workers and their status.Global Configuration: Lists global configuration properties and allows adding new properties, and edit or remove existing properties.Administrators: Lists administrator certificates that have been explicitly granted access and specific roles.Audit Log: Allows querying the audit log. Note that audit log access is only allowed for administrators explicitly granted the Auditor role. To edit the authorized administrators, go to the Administrators tab, click Add and then Load Current to use the values from your administrator certificate, and select the Auditor role. For more information, see Administrators.Archive: Allows querying the archive. Note that the log is only available for administrators explicitly granted access. For more information, see Administrators.Documentation: Links to the SignServer product documentation, such as instructions on how to install, set up, and use SignServer. Also includes information on features and improvements in each SignServer release and requirements for upgrading to a newer version.

For more information on the SignServer Administration Web, see the SignServer Documentation section Administration Web.

5.4 SignServer OperationsSignServer is a server-side digital signature engine that gives maximum control and security and provides built-in modules, SignServer workers, for flexible and scalable implementations. The use cases include document signing, code signing, time-stamping and ePassport. For more information, refer to the SignServer Documentation.

The SignServer Administration Web (AdminWeb) allows managing SignServer on the PKI Appliance andsupports configuring workers and associated key management.

The following covers how to manage SignServer workers using the Administration Web.

Use-Case: Setting up a PDF SignerUse-Case: Signing and Verifying PDFUse-Case: Rekeying Signer

5.4.1 Use-Case: Setting up a PDF SignerThe following example describes setting up a worker for signing PDF documents but the process is similar for other types of SignServer workers.

The SignServer PDF Signer signs PDF documents and supports adding visible or invisible signatures. Applying a visible signature adds a signature image to the document, allowing you to display signature

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/workers-page

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/global-configuration-page

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/administrators-page

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/audit-log-page



https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/archive-page



https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web





1.

2.3.4.

5.

1.2.

a.b.

3.

properties using Adobe Acrobat Reader. For more information on the PDF signer, refer to the SignServer Documentation PDF Signer.

Add PDF SignerThe following describes adding a worker configuration by loading a template.

To create a PDF Signer, do the following:

Go to the SignServer Administration Web Workers page and click Add.

Figure 189: SignServer Administration Web

Click From Template to add a worker.In Load from Template, select pdfsigner.properties and click Next.The Configuration displays the sample properties for the worker that can be edited if needed. Click Apply.The PDFSigner is added to the workers list.

Generate Keys for the Signer

To generate keys for the added PDF signer, do the following:

Select the offline PDFSigner in the Workers list and click Renew key.Under Renew Keys, specify the following:

Key Algorithm: RSAKey Specification: 2048

Click Generate.

Generate CSR for the SignerTo generate the CSR for the PDFSigner, do the following:

If the crypto token of the HSM is not already activated, activate it by selecting the HSMCryptoToken10 from the list of workers, click Activate and provide the authentication code.

https://doc.primekey.com/signserver/signserver-reference/signserver-workers/signserver-signers/pdf-signer



1.a.b.c.

2.3.

1.2.3.4.

5.6.

a.b.c.

7.

1.2.3.4.

a.b.

5.

1.2.

a.b.c.

Select the PDFSigner in the Workers list, click Generate CSR and then specify the following:Key: Next key.Signature algorithm: SHA256WithRSA.DN: CN=My PDF Signer 1.

Click Generate and then Download to save the file as pdfSigner_req.p10.Click Cancel to leave the page.

Next, you need to bring the request to the CA, in this case using EJBCA, to obtain the certificate issued for it. From the CA, you get the signer certificate file as well as the CA certificates (either in two separate PEM files or in one PEM file including all certificates).

Configure EJBCA for CSR SigningTo configure EJBCA for CSR signing from SignServer workers, do the following.

Create Certificate Profile

Go to the EJBCA Admin Web. Click Certificate Profiles under CA Functions.Click Clone for the ENDUSER profile to copy the profile to use as template.Specify SignerCertificateProfile as the name for the new certificate profile, and then click Create from template.The newly created SignerCertificateProfile is listed on the Manage Certificate Profiles page.Click Edit for the SignerCertificateProfile, and specify the following:

CRL Distribution Points: Enable.CRL Distribution Point: Specify URL.CRL Issuer: Clear.

Click Save.

Create End Entity Profile

Click End Entity Profiles under RA Functions.Specify the Add profile name SignerEndEntityProfile and click Add.Select the SignerEndEntityProfile and click Edit End Entity Profile.Specify the following:

Default Certificate Profile: SignerEndEntityProfile.Available Certificate Profiles: SignerEndEntityProfile.

Click Save to save the SignerEndEntityProfile.

Create End Entity

Click Add End Entity under RA Functions.Specify the following:

End Entity Profile: SignerEndEntityProfile.Username: pdfsigner.Password (or Enrollment Code): foo123.



d.e.

3.

1.2.

••

3.4.

5.

1.2.

3.4.

1.

2.3.4.

Confirm Password: foo123.CN, Common name: PDF Signer.

Click Add to create the user.

Generate Certificate

To generate a certificate from the CSR, do the following.

Go to the EJBCA Public Web, select Enroll >Create Certificate from CSR.Enter the username and Enrollment Code previously entered into the End Entity, in this example:

Username: pdfSignerPassword: foo123

Click Browse and upload the pdfSigner_req.csr file.Select the Result type=PEM - full certificate chain to allow downloading the full certificate chain, and then click OK.On the Certificate Created confimation screen, click Download PEM and save the PDFSigner.pem file.

Install Certificates in SignServerTo install the signer certificates issued using EJBCA, do the following:

Go to the SignServer AdminWeb, select the PDFSigner in the workers list, and click Install Certificates.Browse for the PDFSigner.pem certificate and click Add.

If the CA certificates would not have been included in the first PEM file, you would need to repeat this step for each issuing CA certificate. Since you downloaded the full certificate chain in the PEM when generating the certificate using EJBCA, you do not have to repeat this step.Click Install.To activate the new signer, select the link to the new signer in the workers list, and click Activate.

The PDF signer is now set up for signing PDF documents and the next example shows how to sign and verify a PDF document.

5.4.2 Use-Case: Signing and Verifying PDFThe following example of signing and verifying a PDF document requires that a PDF signer has been added with the name PDFSigner. For instructions, see Setting up a PDF Signer.

Sign PDF using the PDF SignerTo submit and sign a PDF file using the Demo Web, do the following:

Go to SignServer on https://<Application_IP>/signserver/ and click Client Web (previously Signing and Validation Demo).Click Browse, select the PDF and click Submit.A prompt will be given to save the signed PDF file.Open the signed PDF in Adobe Acrobat Reader to display the signature.



1.2.

1.

2.3.4.5.

1.2.3.4.

Verify Signed PDFIf certificates from your own CA are used and not from a CA already trusted by Adobe Acrobat Reader, your CA certificates have to be imported in the application.

Generally, it is recommended to use certificates issued by a CA already trusted by the application or have a strategy for how to distribute your CA certificate within your organization.

Download CA Certificates in EJBCA

To obtain the Management CA certificate, do the following:

Browse to EJBCA Public Web and select Fetch CA Certificates.Click Download as PEM to download the CA certificate as ManagementCA.pem.

As Adobe Acrobat Reader does not support the .pem file extension, rename the file ManagementCA.cer.

Import and Trust Certificate

To import and trust the certificate in Adobe Acrobat Reader, do the following:

In Adobe Acrobat Reader, open Preferences>Signatures and click More next to Identities & Trusted Certificates.Select Trusted Certificates and click Import.Browse for the ManagementCA.cer file and click Import.Select the Management CA certificate in the list and click Edit Trust.Select Use the certificate as a trusted root and Certified documents and click OK.

Validate Signature

To validate the signature using Adobe Acrobat Reader, do the following:

Open the signed document and select Validate All Signatures.Click OK when prompted to verify the signatures.A prompt is given that Completed validating all signatures. Click OK.Click Certificate Details to open the Certificate Viewer, and then click Revocation to view information about the CRL.

5.4.3 Use-Case: Rekeying SignerWhen a signer certificate expires, a new certificate is needed for it to continue working.

To view the current validity of a signer, open SignServer Administration Web Worker page and click the Status Properties tab. The Validity not after field shows the date after which the signer cannot be used due to that the certificate has expired or its private key usage period is ended. For reference information on the Worker page and its menu options, refer to the SignServer documentation Worker Page.

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/workers-page/worker-page



1.2.

a.b.

3.

1.2.

a.b.c.

3.

1.2.

3.

4.

Generate New KeyTo generate a new key, do the following:

Go to the Workers page, select the worker and click Renew key.On the Renew Keys page, specify the following:

Key algorithm: RSAKey specification: 2048

SignServer suggests the new key name in the format current name with its numeric suffix increased by one.

Click Generate.

A new key is available in the HSM slot but the signer is still using the old key as pointed out with its DEFAULTKEY property. A new property called NEXTCERTSIGNKEY has been created with the name of the new key so that the GUI will remember it.

For reference information, refer to the SignServer documentation Workers Key Generation Page.

Generate CSRTo generate a certificate signing request (CSR) for the new key, do the following:

Go to the Workers page, select the worker and click Generate CSR.Specify the following:

Key: Next key.Specify a Signature Algorithm, for example SHA256withRSA.Specify DN, for example CN=My Signer 1,O=My Organization,C=SE.

Click Generate, and then click Download and save the file as mysigner_req.csr.

For reference information, refer to the SignServer documentation Workers CSR Page.

Next, bring the request to the CA to obtain the signer certificate and any CA certificates, see Generate Certificate.

Install CertificatesTo install the certificates, do the following.

Go to the Workers page, select the worker and click Install Certificates.Browse for the PDFSigner.pem certificate and click Add.

If the PEM certificate contains both the signer certificate followed by the CA certificate(s), browse for the PEM file and click Add. However, if you have one signer certificate file and the CA certificate(s) separately, first browse and add the signer certificate, and then each of the issuing CA certificates in sequence.Click Install to install all of the added certificates.

The DEFAULTKEY property will now point to the new key and the NEXTCERTSIGNKEY property will be removed. The worker status should now switch to ACTIVE.The worker status should now be Active. If not, activate the new signer by selecting the link to the new signer in the workers list, and click Activate.

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/workers-page/workers-key-generation-page

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/workers-page/workers-csr-page



For reference information, refer to the SignServer documentation Workers Install Certificates Page.

https://doc.primekey.com/signserver/signserver-reference/signserver-user-interfaces/administration-web/workers-page/workers-install-certificates-page

Online Help · © 2020 PrimeKey Published by PrimeKey Solutions AB Solna Access, Sundbybergsvägen...

Documents

Transcript of Online Help · © 2020 PrimeKey Published by PrimeKey Solutions AB Solna Access, Sundbybergsvägen...