pki appliance online help€¦ · 1.releasenotes ver: 3.0.0 chapter1 releasenotes pki appliance...

PKI Appliance

Online Help

Public Key Infrastructure by PrimeKey

Ver: 3.0.0

2018-04-30

Copyright ©2018 PrimeKey SolutionsPublished by PrimeKey Solutions ABLundagatan 16171 63 SolnaSweden

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

Notice of RightsAll 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 thepublisher. For more information on getting permission for reprints and excerpts, contact [email protected]

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

TrademarksMany of the designations used by manufacturers and sellers to distinguish their products are claimed astrademarks. 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 servicesidentified throughout this book are used in editorial fashion only and for the benefit of such companies withno intention of infringement of the trademark. No such use, or the use of any trade name, is intended toconvey endorsement or other affiliation with this book.

Contents

I Preamble 1

1 Release Notes 2

2 Introduction 42.1 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.1.1 Styling Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.1.2 Daily operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 PKI Appliance Overview 63.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

II Appliance Installation 7

4 PKI Appliance Unboxing 84.1 Included in delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.2 Opening the box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.3 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.3.1 Front View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.3.2 Back View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.4 Taking into Operation / Powering Up . . . . . . . . . . . . . . . . . . . . . 13

5 Initial Set-up 145.1 External Erase and Factory Reset . . . . . . . . . . . . . . . . . . . . . . . . 155.2 One Time Password and SSL Fingerprint . . . . . . . . . . . . . . . . . . . . 165.3 Changing the IP Address of the PKI Appliance . . . . . . . . . . . . . . . . . 175.4 Connecting to the PKI Appliance . . . . . . . . . . . . . . . . . . . . . . . . 185.5 Logging in for the first time . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.6 Fresh Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.7 Network Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.8 Date and Time Settings (NTP) . . . . . . . . . . . . . . . . . . . . . . . . . 245.9 Management CA Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.10 Security Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.10.1 Domain Master Secret . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.10.2 Appliance Security Level . . . . . . . . . . . . . . . . . . . . . . . . 265.10.3 PKCS#11 Slot Configuration . . . . . . . . . . . . . . . . . . . . . . 275.10.4 Audit Log Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285.10.5 HSM FIPS Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.11 Confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285.12 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.12.1 Get PKCS#12 key store . . . . . . . . . . . . . . . . . . . . . . . . 325.12.2 Using legacy browser enrollment . . . . . . . . . . . . . . . . . . . . 355.12.3 Get certificate from CSR . . . . . . . . . . . . . . . . . . . . . . . . 37

5.13 Finalize Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

6 Restore from Backup 426.1 Restore Stand-Alone System from Backup . . . . . . . . . . . . . . . . . . . 42

7 Connect to cluster 44

III WebConf 45

8 WebConf 468.1 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468.2 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

8.2.1 NTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478.2.2 DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.2.2.1 Fully Qualified Domain Name (FQDN) . . . . . . . . . . . 488.3 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.3.1 TLS certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488.3.1.1 Server side TLS certificates . . . . . . . . . . . . . . . . . . 488.3.1.2 Client side TLS certificates . . . . . . . . . . . . . . . . . . 498.3.1.3 Trust CA certificates for client authentication . . . . . . . . 49

8.3.2 PKI Appliance Management Accounts . . . . . . . . . . . . . . . . . 49Use-Case: Create a new TLS server side certificate for Application Interface . 50Use-Case: Upload a new trusted CA for TLS authentication and new super-

admin certificate for Management Interface . . . . . . . . . . . . . . 58Use-Case: Configure a new trusted CA for TLS authentication and new su-

peradmin certificate for Application Interface . . . . . . . . . . . . . 628.4 HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

8.4.1 Changing HSM PKCS#11 slot authentication codes . . . . . . . . . 658.4.1.1 Switching from generated to manually entered authentica-

tion code . . . . . . . . . . . . . . . . . . . . . . . . . . . 658.4.1.2 Changing a manually entered authentication code . . . . . . 658.4.1.3 Switching to auto-generated authentication code . . . . . . 65

8.4.2 Backup Key Share Smart Card Handling . . . . . . . . . . . . . . . . 678.4.2.1 Make a one-to-one copy of a smart card . . . . . . . . . . . 67

8.4.2.2 Change the PIN of the backup key share on a smart card . . 678.4.3 Download protected HSM export . . . . . . . . . . . . . . . . . . . . 678.4.4 Cluster Key Synchronization Packages . . . . . . . . . . . . . . . . . 67

8.5 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688.6 Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708.7 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

8.7.1 Syslog shipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708.7.2 SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.8 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738.8.1 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738.8.2 Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738.8.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758.8.4 Platform Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

8.8.4.1 SSH public key . . . . . . . . . . . . . . . . . . . . . . . . 758.8.4.2 Password authentication . . . . . . . . . . . . . . . . . . . 75

8.8.5 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

IV Advanced 77

9 HA Setup 789.1 Scope of availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

9.1.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789.1.2 Synchronization of key material . . . . . . . . . . . . . . . . . . . . . 78

9.1.2.1 Pre-cluster setup generation of keys . . . . . . . . . . . . . 789.1.2.2 Post-cluster setup generation of keys . . . . . . . . . . . . . 79

Use-Case: Synchronize key material . . . . . . . . . . . . . . . . . . . . . . 799.1.3 Network topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799.1.4 Cluster traffic security considerations . . . . . . . . . . . . . . . . . . 80

9.2 Continuous service availability . . . . . . . . . . . . . . . . . . . . . . . . . . 809.3 Levels of availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

9.3.1 Stand alone instance . . . . . . . . . . . . . . . . . . . . . . . . . . 809.3.2 Hot stand-by with manual fail-over . . . . . . . . . . . . . . . . . . . 809.3.3 High availability with automatic fail-over . . . . . . . . . . . . . . . . 81

9.4 High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Use-Case: Setting up a 2 node cluster from scratch . . . . . . . . . . . . . . 81Use-Case: Setting up a 3 node cluster from scratch . . . . . . . . . . . . . . 82Use-Case: Extending a cluster from n to n+1 nodes . . . . . . . . . . . . . . 82

9.5 Backup, Restore and Update . . . . . . . . . . . . . . . . . . . . . . . . . . 839.5.1 Backing up a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . 839.5.2 Restoring a cluster from backup . . . . . . . . . . . . . . . . . . . . 839.5.3 Updating the software (firmware/applications) on a cluster . . . . . . 84

Use-Case: Software update on a three node cluster from 2.2.0 to 2.3.0 849.6 Controlled full cluster shutdown and startup . . . . . . . . . . . . . . . . . . 85

9.6.1 Shutting down the cluster in controlled manner . . . . . . . . . . . . 859.6.2 Starting a fully shutdown cluster . . . . . . . . . . . . . . . . . . . . 85

9.7 Operational Caution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Use-Case: Changing the IP Address of the Application Interface of a

node in a three node cluster . . . . . . . . . . . . . . . . . 86Replacing a failed cluster node . . . . . . . . . . . . . . . . . . . . . . . . . 87

10 Smart Card Handling 8810.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8810.2 Smart Card Reader or PIN Pad . . . . . . . . . . . . . . . . . . . . . . . . . 8810.3 Usage of Smart Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

10.3.1 Backup Key Share smart cards . . . . . . . . . . . . . . . . . . . . . 8910.3.2 PKCS#11 slot activation user smart card . . . . . . . . . . . . . . . 90

10.4 Quorum (’2 out of 3’ or ’3 out of 5’) . . . . . . . . . . . . . . . . . . . . . . 9010.5 Procedure (Installation, Example for ’2 out of 3’) . . . . . . . . . . . . . . . 9110.6 WebConf Smart Card Handling Tools . . . . . . . . . . . . . . . . . . . . . . 94

10.6.1 Make a one-to-one copy of a backup key share on a smart card . . . . 9410.6.2 Change the PIN of the backup key share on a smart card . . . . . . . 9510.6.3 Change the PIN of a PKCS#11 Slot User on a smart card . . . . . . 95

11 PKCS#11 Slot Smart Card Activation 9611.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9611.2 Installation/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

11.2.1 "Number of users required" . . . . . . . . . . . . . . . . . . . . . . . 9711.2.2 "Number/copies of user smart cards" . . . . . . . . . . . . . . . . . . 9711.2.3 "Require smart cards to activate system after boot" . . . . . . . . . . 9711.2.4 Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

11.2.4.1 Example with default values . . . . . . . . . . . . . . . . . 9811.2.4.2 Slots 0 and 1 . . . . . . . . . . . . . . . . . . . . . . . . . 98

11.3 Application/Activation of a slot . . . . . . . . . . . . . . . . . . . . . . . . . 9811.3.1 Activation on boot/slot 0 . . . . . . . . . . . . . . . . . . . . . . . . 99

12 Audible Feedback 100

PKI ApplianceOnline Help – Public Key Infrastructure by PrimeKey

Ver: 3.0.0

Part I

Preamble

1 (101)


1. RELEASE NOTES Ver: 3.0.0

Chapter 1

Release Notes

PKI Appliance 3.0.0 Release Notes

This major release brings an overhauled technology stack for the PKI Applianceplatform. Beside the updates of EJBCA and SignServer the majority of componentsand services have been updated.

New Features:* Support for hardware version 2* EJBCA Enterprise 6.11.1.1 - Please check out EJBCA release notes for more

detailed information* SignServer 4.2.2 - Please check out SignServer release notes for more details

Improvements:* PrimeLFS is now based on LFS 7.9 with updated components and services:

- MariaDB to 10.2.13 and Galera provider 25.3.23- OpenSSL 1.0.2.n- Apache 2.4.29

* Adjust quorum weights (127,126,125) for cluster nodes for graceful degradationof service

* Improved "Force into Active" handling of cluster nodes* Improve database scalability by using database.useSeparateCertificateTable=true* Newly structured security/secrets page in the installation wizard

Security Patches:* Mitigation for Meltdown, Spectre and zombie Dirty COW vulnerability* Openssl has been updated to 1.0.2* Apr-Util to 1.6.1* curl to 7.58.0

2 (101)


1. RELEASE NOTES Ver: 3.0.0

Known Issues and Limitations:

* Only two of the four available ethernet ports are usable at the moment.Support for the the disabled ethernet ports will be added in future versions.

* Due to a firmware limitation the appliance only becomes reachable when bothethernet ports are successfully connected to a switched network.

* Ethernet ports might not establish the link if the network cables have not beenconnected before booting the device.

* PKI Appliance 3.0.0 firmware can only be installed on appliances of the latestgeneration (hardware version >= 2.0 required). Support for older hardware willbe added in a future version.

* Backups taken on version < 3.0 cannot be restored. Support to restore backupstaken on previous versions will be added in future releases.

* "FIPS restrictions applied" mode is not available for CryptoServer Se52.Operation in FIPS mode will be added in a future version.

* It is not possible to set up a cluster with nodes running a mix of firmwareversion 2 and version 3.

3 (101)


2. INTRODUCTION Ver: 3.0.0

Chapter 2

Introduction

This manual provides an in depth understanding of the public key infrastructure (PKI) prod-ucts and services provided by PrimeKey and is intended to serve as a guide to understandingand implementing PKI as a product and service within the PKI Appliance.

2.1 AudienceThis guide is intended for use by Information Technology (IT) professionals with an interestin implementing the PKI products provided by PrimeKey in their environment using thePKI Appliance. The guide is presented in a structured manner so that it begins with anintroduction to the subject and progressively moves into more deeper technical topics. Thisallows the guide to be useful for a wide variety of personnel from managers to integrators.The lowest common denominator between the various groups of audiences is the sharedinterest in implementing PKI using PrimeKey products.

2.1.1 Styling Conventions

The following items explain the styling conventions that are used throughout this document,together with an example below each description:

• Buttons on the GUI are represented like Create .

• Options from popup menus or values that can be choosen like RSA 2048

• Links in the GUI that need to be selected/clicked upon are displayed in blue like:Search End Entities.

• Values that has to provided in text fields are presented as: a new value.

• Group titles or GUI text that is not selectable is represented as: RA Functions.

• Informative messages provide additional explanation of the steps being performed, orthe configuration being applied. For example:

4 (101)


2. INTRODUCTION Ver: 3.0.0

i This is an informative message containing extra information.

• Warning messages are used to draw the attention to a critical or sensitive step thathas to be performed, or to critical piece of information that has to be provided. Forexample:

! This is a warning message.

• Shell listings are used to specify commands that should be run on a server in a terminal,by a specific operating system user. For example:

Run as user

df -h

2.1.2 Daily operations

Exercises are indicated by the "Use-Case" prefix as illustrated below. Exercises provide a stepby step approach to perform an activity and require the practical environment:

Use-Case: Install PKI Appliance

While following the exercises outlined in this document, the following guidelines apply:

i Unless the instructions explicitly state so, do not deviate from the instruc-tion order. All steps should be performed in the sequence that they areoutlined in. Do not jump back and forth between different exercises, unlessthe instructions explicitly state so.

5 (101)


3. PKI APPLIANCE OVERVIEW Ver: 3.0.0

Chapter 3

PKI Appliance Overview

3.1 DescriptionEJBCA Enterprise Appliance is a PKI-in-a-box and combines the flexibility, reliability andfeature set of EJBCA Enterprise software, with a secure technology stack and enterprise-grade hardware including a FIPS 140-2 Level 3 certified HSM. Through the combination ofbuilt in CA, RA and VA functionality and a variety of interfaces like OCSP, CMP, SCEP andWebServices, EJBCA Enterprise Appliance provides a unique turn-key PKI solution.EJBCA Enterprise Appliance is based on an unified and controlled technology stack whichreduces technical risks for the entire PKI project and reduces patch management effortsduring operation. Simplified management and maintenance workflows lower the setup timeand operational costs and reduce the TCO.High flexibility, performance, support for high-availability and load-balancing make the EJBCAEnterprise Appliance suitable for critical infrastructure setups within commercial and gov-ernmental organization of all sizes.

As of version 2.4.0 the EJBCA Enterprise Appliance (or PKI Appliance) exists in threedifferent product sizes, designated as S, M or L. Previous unlabeled versions are equivalentto the M size. While the L version takes advantage of recently available bigger hard disksto provide for more database space, the S version is a highly reduced version with smallerdatabase size and also a reduced speed HSM.

6 (101)


Ver: 3.0.0

Part II

Appliance Installation

7 (101)


4. PKI APPLIANCE UNBOXING Ver: 3.0.0

Chapter 4

PKI Appliance Unboxing

Congratulations! You have obtained the PKI Appliance from PrimeKey Solutions AB.Illustrated below are the items that can be found while unboxing the PKI Appliance package.

4.1 Included in delivery• One PKI Appliance.

• One set of mounting rails, a mounting instruction and a set of screws.

• Four mains cables, one pair for each Europe and American standard.

• Optionally: One PIN pad and ten smart cards.

• A Quality Assurance Test Report

• A Packing List

8 (101)



4.2 Opening the boxBy opening the box you should find a PKI Appliance Test Report signed by PrimeKeyauthorized personnel showing the quality checks that have been performed.

Figure 4.1: Opening the box.

You will find 4 cables and rack mount sliding rails (see fig. 4.2).

Figure 4.2: Components inside the box.

9 (101)



Also there is a PIN pad with 10 smart cards (see fig. 4.3).

Figure 4.3: PIN pad with smart cards.

Finally the second layer reveals the packed PKI Appliance as shown in figure 4.4.

Figure 4.4: PKI Appliance packed in the cardboard box.

10 (101)



4.3 Overview

4.3.1 Front View

Figure 4.5: Front View of the PKI Appliance

1. Four bays for customer serviceable hard disks (Solid State Disks, SSD) for database,RAID1, two disks are provided

2. SSD Slot 0

3. SSD Slot 1

4. SSD Slot 2, empty

5. SSD Slot 3, empty

6. Cooling vents. Do not obstruct!

7. Status LED row: Power (green), Hard Disk (red), Info (yellow)

8. Front display for status information and IP address configuration with menu buttons:Up, Down, Enter, Cancel

9. Front USB ports, suitable for PIN pad connection

10. Safeguarded reset button

11. Power button (ATX)

11 (101)



4.3.2 Back View

Figure 4.6: Back View of the PKI Appliance

1. Two redundant Power Supply Units (PSU)

2. PSU Alarm mute button

3. IPMI Network port, to be not used, blocked in future versions

4. Mainboard USB ports, suitable for PIN pad connection

5. Application Network Interface

6. Management Network Interface

7. Hardware Security Module (HSM). USB and serial interface to be not used

8. optional: Connector for external battery and test automation

9. Safeguarded External Erase button for Factory Reset

10. Mainboard VGA connector, not required for operation

11. Mainboard Serial connection, not operational

12. Mainboard PS/2 connection, not required for operation

13. PKI Appliance serial number

12 (101)



4.4 Taking into Operation / Powering Up1. Make sure the seal at the right side of the PKI Appliance is intact and untampered

2. Make sure the serviceable hard disks are sitting properly in their bay

3. Make sure the PSUs are properly seated

4. Connect power cord

5. Do not yet connect the network cables

6. Power on the machine, booting will take about 5 minutes

13 (101)


5. INITIAL SET-UP Ver: 3.0.0

Chapter 5

Initial Set-up

The initial setup of the PKI Appliance transfers the device from the delivery state to aproduction setup by configuring all components of the system. The initial setup routinerequires four steps:

• Performing a Factory Reset

• Setting the initial management IP address using the control panel at the front

• Obtaining the One Time Password (OTP) from the display to access WebConf

• Running the WebConf and completing the setup

We recommend to not yet connect the network cables. As a general rule of precaution,we suggest that you first configure the IP addresses before connecting the PKI Appliance toyour network. Any previously configured IP address or the default IP addresses could alreadybe assigned to another network device in your network and thus disrupt service.

The network interfaces are:

• To the very left, next to a pair of USB connections, you will find a single networksocket which is not in service. To be not used. Never.

• Of the two network ports next to each other, the left one is the interface for theApplication Interface. It’s default IP address is 192.168.5.161.

• The right one of the two network ports is the Management Interface, which defaultsto 192.168.5.160.

14 (101)



5.1 External Erase and Factory ResetA Factory Reset resets the machine into factory defaults, a defined state deleting all con-figuration files and sensitive information like cryptographic keys on the Hardware SecurityModule (HSM) or certificates in the CA database. Performing a Factory Reset is necessaryin the following cases:

• you lose access to the PKI Appliance,

• you need to reinstall the PKI Appliance,

• you need to make sure that possibly secret data needs to be erased or

• you want to switch from testing or demo to a production system.

Figure 5.1: Placement of the External Erase button.

The following steps describe the procedure to perform a Factory Reset with the PKIAppliance:

! The next step is a definite action. All sensitive data will immediately beerased from the HSM. The only possibility to restore the data is from abackup (if one exists) and Backup Key Share smart cards, where required.

1. On the back of the PKI Appliance there is a hole underneath the integrated HardwareSecurity Module (HSM) with a hidden button (see figure 5.1). This is the buttonfor External Erase. Press that button for one second using a pen while the machineis powered, switched on, finished booting and make sure you hear a confirmationsound that should be played within 15 seconds (but might take up to ten minutesunder certain circumstances, e.g. if you slipped off the button and pressed it a secondtime).

15 (101)



i It is ensured that the HSM deletes the data as soon as the button is pressed.Under certain circumstances (as described above), the feedback (audibleand PKI Appliance front display) might take longer.

2. If the machine acknowledged that you pressed the button either by the audible feedbackor by the message on the front panel display, you will have to reboot the PKI Applianceto actually execute the Factory Reset by briefly pressing the power button on the frontpanel and then confirming the reboot via the display buttons. The machine will rebootand clear all configuration files. It should be clearly stated that a clean shutdown andboot is required for the configuration to be deleted. A hard power fail will not do.

3. After rebooting, the PKI Appliance display should show a cycle of the current Man-agement Interface IP address, the initial TLS fingerprint, some additional informationlike software version and the One Time Password. Seeing the One Time Password isproof that the Factory Reset was successfull.

i As soon as OTP is displayed, the PKI Appliance is in Factory Reset state,ready for installation.

5.2 One Time Password and SSL FingerprintAfter powering up the system, the display will give you the information you need to accessthe system through your web browser (see figure 5.2). The One Time Password (OTP) isrequired to initially access the WebConf and will become invalid after the installation hasbeen successfully accomplished. Please take note of this OTP as it will be required for theweb based installation procedure.

Figure 5.2: Front Display showing the One Time Password

The shortened TLS fingerprint indicated on the display shows the first characters of thefingerprint of the TLS certificate used to secure the connection from your web browser tothe PKI Appliance WebConf (see figure 5.3). The WebConf will ask you to compare thisfingerprint with the fingerprint of the TLS certificate presented to you by the browser tomake sure that you are accessing the right machine.

16 (101)



Figure 5.3: Front Display showing the TLS Fingerprint

5.3 Changing the IP Address of the PKI ApplianceAfter a factory reset and also later during normal operation the display will show you theIP address of the Management Interface of the PKI Appliance. After a factory reset, thiswill default to 192.168.5.160 (see figure 5.4).

Figure 5.4: Front Display showing the IP Address

If the default IP address of the Management Interface of the PKI Appliance does notmatch your network configuration, you can easily change it according to your needs. However,it is preset to have a network prefix of /24 (resulting in a subnet mask of 255.255.255.0).

i As the 100.64.0.0/10 network range is used for internal networking, IP ad-dresses in this range are not allowed as external management or applicationnetwork address.

Pressing the "OK" button when the IP address is shown will allow you to change the IPaddress (see figure 5.5). The IP address will be presented with leading zeroes. The cursorwill start at the first digit of the first byte of the IP address. You can abort this operationat any time by pressing the x button.

17 (101)



Figure 5.5: Changing the IP Address

1. use the up and down buttons to adjust the digit to your target IP address.

2. then press the v button to confirm this digit

3. the cursor will move to the next digit

4. repeat steps 1 to 3 for every digit

5. when confirming the last digit with the v button, the display will ask you to confirmthe IP address. This time, the IP address will be shown without leading zeroes.

6. confirm your entry with the v button.

The chosen IP address will be committed. Please note that this operation can take up to10 seconds. After that time, it is safe to connect the first network cable to the ManagementInterface (the right one, as seen from behind).

5.4 Connecting to the PKI ApplianceThe next and last step of the initial configuration of the PKI Appliance is to run the webbased configurator. During this procedure all components of the system will be configuredaccording to the parameters you provide.

i The WebConf is designed and tested to work with Firefox 26.0+. Otherbrowsers like Chrome or Safari are working but are not officially supportedand you may observe minor incompatibilities. Internet Explorer is currentlynot officially supported and depending on the version you might not be ableto finish the configuration process successfully.

1. Navigate your browser to the IP address of the Management Interface of the PKIAppliance. A simple web page will instruct you to connect through TLS (see figure5.6).

2. Follow that link and your browser will respond with a TLS warning because the servers

18 (101)



Figure 5.6: Instruction to connect to the PKI Appliance using TLS

TLS certificate is not signed from any CA your browser knows already (see figure 5.7).

Figure 5.7: Browser TLS Warning

3. Open the I Understand the Risks section by clicking that link

4. then click the button Add Exception... :

5. Untick Permanently store this exception if you plan to install the machine now. Thecertificate will be regenerated during installation and the permanently stored certificatewould be obsolete. Confirm the Security Exception by clicking Confirm Security Exception(see figure 5.8).

i If you don’t wont to be prompted again to confirm don’t untick.

19 (101)



Figure 5.8: Confirm Security Exception

6. You will be greeted by the WebConf (see figure 5.9).

Figure 5.9: Instruction to compare and confirm the TLS certificate fingerprint

7. Check the fingerprint of the TLS certificate and compare the first characters to thefingerprint shown on the display of the PKI Appliance.

(a) Click the little padlock icon in the address bar of your browser (see figure 5.10).

20 (101)



Figure 5.10: Firefox padlock information window

(b) Click on More Information... (see figure 5.11).

Figure 5.11: Security Information

(c) Click on View Certificate . You will be shown the SHA1 fingerprint. Thefingerprint should correspond as much as was visible on the display (see figures5.12 and 5.3).

21 (101)



Figure 5.12: Certificate Information

8. If the two fingerprints match, then you can be sure to be connected to the correctmachine. Click The fingerprints are the same as in 5.9.

22 (101)



5.5 Logging in for the first timeNow you will need the One Time Password (OTP) that is displayed on the front of the PKIAppliance. This password changes every time the machine is started, until the system hasbeen installed. Click Login when you have entered the authentication code (see figure5.13).

Figure 5.13: Entering the OTP

5.6 Fresh InstallationAnytime you use the OTP to log in to an un-provisioned PKI Appliance, you will be giventhe choice to

1. Fresh install

2. Restore system from backup

3. Connect to cluster

For now we will do a fresh install, so click the Next button below Fresh install (seefigure 5.14)

5.7 Network SettingsYou will be asked to configure the network settings of the PKI Appliance. All of this can becorrected at a later point in time, if needed.

You might want to make up your mind about the network configuration beforehand: Ofthe two physical interfaces, one is designed to be a Management Interface, through whichyou can access the WebConf and the AdminGUI of EJBCA. The other interface is designed

23 (101)



Figure 5.14: Installation Choices

Figure 5.15: Network Settings

to be the Application Interface, through which the operational payload will be routed. It’sperfectly fine to set up two separate networks if you want to separate those tasks. For thetime being, the Management Interface IP address has been configured at the front paneldisplay and is preset to have a network prefix of /24 (subnet mask 255.255.255.0). On theapplication network however, you are free to chose the IP address, network prefix anddefault gateway. You will also be asked to enter the designated hostnames, if you plan tomake the PKI Appliance available through DNS name resolution.

After the installation, you will be given the possibility to change the IP address of theManagement Interface.

To confirm the configuration and proceed to the next step, click on Next: Time (seefigure 5.15).

5.8 Date and Time Settings (NTP)For many of the applications of a Public Key Infrastructure (PKI), it is very important tohave a correct date and time. You might consider using a Network Time Protocol (NTP)

24 (101)



time source. If you plan to build a cluster, you have to use NTP.

Figure 5.16: Date and Time Settings (NTP)

Proceed to the next page of the configuration by clicking the Next:Management CAbutton.

! In case that you will use NTP this is the right time to do it! If you configureit later and there is a difference between the NTP server and current systemtime, the synchronization will not happen directly. It can take up to severalhours.

5.9 Management CA SettingsThese are settings that should be carefully considered, because they cannot be altered afterthe installation. You should take the time to think of some meaningful identifier to be addedto the Additional Subject Fields, as shown in the picture. The Additional Subject DNwill be reflected in the TLS certificates that are stored in your browser and in the name ofthe backup files. If you plan on doing several test/demo installations, this is where you canbrand them.

Figure 5.17: Management CA Settings

If you have already an TLS PKI somewhere, you can opt to not generate a new Man-agement CA but use an existing Management CA. You will be prompted to upload thePEM-encoded CA certificate. In case you need the Management CA to be created now, youwill be asked to configure it:

25 (101)



• Common Name of the EJBCA Management CA

• Additional Subject Fields like organization and country

• Signature Algorithm that shall be used by the EJBCA Management CA

– SHA1withRSA

– SHA256withRSA

– SHA256withECDSA

• Signing Key Specification

– ECDSA - secp256r1 / prime256v1 / P-256

– RSA 1024

– RSA 2048

– RSA 4096

• EJBCA SuperAdmin Common Name

Continue by clicking on Next: Security .

5.10 Security SettingsThis is another page of immutable settings. The security section helps you to configure allsecurity relevant aspects of the PKI Appliance.

5.10.1 Domain Master Secret

The first step is to set a secret for your Domain Master Secret. This passphrase is usedto derive a symmetric key which is used to encrypt backup archives created by the PKIAppliance. It is your choice whether you specify it manually or whether you prefer to haveit generated by the system. If generated, you will be given the possibility to print the highlysecure Domain Master Secret. In both cases it is very important to write down the secretand keep it in a safe place. If lost, the device will not be able to be restored from a backup.Also you would not be able to extend this system to a cluster.

5.10.2 Appliance Security Level

There are three options for the Appliance Security Level:

• Soft key files

• 2 out of 3 Backup key share smart cards

26 (101)



Figure 5.18: Security Settings

• 3 out of 5 Backup key share smart cards

This option defines if and how many smart cards shall be used to protect the HSM keymaterial. As an example, if 2 out of 3 Backup key share cards is chosen, you will beasked to insert 3 smart cards during installation where on each a share of a symmetric key(the Backup Key) will be stored. The symmetric key will be used to encrypt the backups.As the Backup Key is also securely stored on the HSM you will not need to provide thesmart cards for every backup operation. Should it be necessary to restore the PKI Appliancefrom a backup you will need to provide 2 of the initially created 3 smart cards to importthe Backup Key into the HSM to decrypt and import the backup data. Likewise for the3 out of 5 Backup key share smart cards scenario.

For low security or testing scenarios it is also possible to operate the PKI Appliance with-out 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 additionally se-cured by the Backup Key Share smart cards, but only by the Domain Master Secret, thatencrypts all data in a backup file.

5.10.3 PKCS#11 Slot Configuration

The next option on this page is to change the authentication codes for the PKCS#11slots of the HSM. Automatically generated authentication codes are stored on the systemso that applications can run unattended while still offering a decent security. Manuallygenerated authentication codes allow for applications that should only be available aftermanual activation. Even higher security can be achieved by enabling smart card activationon slots. (Minimum PKI Appliance Version 2.2.0, please refer to chapter 11 on page 96for more information about smart card activated slots. Please notice that the smart card

27 (101)



activation for PKCS#11 slots is not available with HSM FIPS Mode, see below.)

5.10.4 Audit Log Storage

This option allows you to choose whether you want to store signed log records of securityoperations to the clustered storage. Default is enabled. Audit log records consume databasedisk space. For a typical installation, the creation of a single certificate issues approximately10 audit log records. For all typical installations, the audit log database table will be at leastdouble the size of the other database tables. If you disable the storage of the signed auditlog, you will still be able to receive and store the audit log records externally, over syslogshipping (unsigned, unencrypted).

5.10.5 HSM FIPS Mode

This last option offers you to load and activate the HSM FIPS Mode firmware module.It will enforce restrictions required by the FIPS 140-2 standard. This means that someknown unsecure mechanisms and algorithms will be disallowed, but also new or modernmechanisms and algorithms will not be available because they have not yet been approved.A known limitation is that the PKCS#11 slots cannot be authenticated with smart cardswhen FIPS restrictions have been requested.

To continue, click on Next: Summary to see an overview of all configuration optionsdone so far.

5.11 ConfirmIt is highly recommended that you double check everything on this summary page. Youmight even want to print this page. If you spot an error, you can easily navigate backwardswith the Previous buttons or use the breadcrumbs at the top of the screen.

i In case you have decided to use smart cards for your setup, please make surethat the PIN pad included in the delivery is connected to one of the USBports in the front of the PKI Appliance and you have a sufficient amountof smart cards at hand. The smart cards are delivered with the default PIN"123456". You will be given an opportunity to change the PIN of a smartcard after installation has finished, see chapter 8.4.2.2 on page 67

When you are ready to continue the installation click on Begin installation . Theinstallation will take a few minutes (see figure 5.19).

28 (101)



Figure 5.19: Confirm installation choices

5.12 InstallationThe installation process will take a few minutes. During this time you can follow the installa-tion and configuration steps shown below the progress bar which will include the configurationof the HSM, the database and the applications, like EJBCA.

i In the case you have decided to use smart cards, please mind the outputfrom the PIN pad during the installation process which will request you toinsert the smart cards and enter the PIN. You will be asked to enter thesmart cards in two steps using the k out of n schema:

1. Key generation: Insert all (n) smart cards you have chosen to use,always providing the PIN.

2. Key import (to HSM): Insert again the amount of smart cards thatis needed to restore the Backup Key (k)

29 (101)



At the end of the installation, you will find the following screen (see figure 5.20).

Figure 5.20: End of Installation

30 (101)



To manage the PKI Appliance you need to get a client side SuperAdmin TLS certificateissued by the Management CA that can be used from your browser. This certificate will beyour one and only authentication to the system, unless you configure other access meth-ods. Configuration of further users and other authentication methods are described in theWebConf chapter (see page 48).

Select the option that suits your current client environment.

1. Get PKCS#12 key store: The SuperAdmin certificate and corresponding key pair isgenerated on the PKI Appliance and manually imported into the browser.

2. Using legacy browser enrollment: The SuperAdmin key pair is generated in thebrowser and the SuperAdmin certificate is automatically imported into the browser.

3. Get certificate from CSR: The SuperAdmin key pair is generated outside the browsercontext and the SuperAdmin certificate will be created from a Certificate SigningRequest.

The certificate and corresponding key pair is a vital component of your system. Youneed to protect and backup it with the same care that you apply to the backups and dataof the PKI Appliance itself: Anyone in possession of this certificate can manipulate yourinstallation. Without this certificate, you have no access whatsoever to the PKI Appliance.

31 (101)



5.12.1 Get PKCS#12 key store

A PKCS#12 key store is a format for storing both private keys and certificates protectedby a password. By selecting this option you will be able to download such key store thatcontains both a SuperAdmin certificate and the corresponding key pair. The .p12-file thenneeds to be manually imported into the browser using the PKCS#12 protection passwordshown to you.

Start by pressing Confirm enrollment option when "Get PKCS#12 key store" isselected (see figure 5.21).

Figure 5.21: Get PKCS#12 key store - step 1

32 (101)



Next, press Get SuperAdmin PKCS#12 key store (see figure 5.22). A new tabwill open.


33 (101)



In the newly opened tab, select a Key Specification matching your organization’s securityrequirements an click Enroll (see figure 5.23). You will be prompted to save .p12-file.Download it to the local machine.


Close the newly opened tab. Back in the installation wizard tab (see figure 5.22), makea note of the PKCS#12 protection password. Use your browser’s proprietary mechanism forimporting the .p12-file using the PKCS#12 protection password before proceeding.

Once the P12 has been successfully imported, click Finalize installation .

34 (101)



5.12.2 Using legacy browser enrollment

Start by pressing Confirm enrollment option when "Using legacy browser enrollment"is selected (see figure 5.24).

Figure 5.24: Using legacy browser enrollment - step 1

Click that link labeled Get SuperAdmin certificate (see figure 5.25). A new tab willopen.


35 (101)



In the newly opened tab, click Enroll . Your browser will then generate a key pair,request the certificate from the Management CA and automatically install the certificate inyour browser (see figure 5.26). Confirm the popup and close the tab.


Back in the installation wizard tab (see figure 5.25), click Finalize installation .

36 (101)



5.12.3 Get certificate from CSR

Enrolling the initial SuperAdmin certificate using a Certificate Signing Request/PKCS#10should only be used when you can’t use any of the other methods. Creation of the CSR andinstalling the resulting certificate in such a way that it is usable for client TLS authenticationis outside the scope of this document.

Start by pressing Confirm enrollment option when "Get certificate from CSR" isselected (see figure 5.27).

Figure 5.27: Get certificate from CSR - step 1

37 (101)



Make a note of Enrollment username and Enrollment code. Click that link labeledGo to SuperAdmin enrollment page (see figure 5.28). A new tab will open.


38 (101)



In the newly opened tab, enter Enrollment username and Enrollment code from theprevious page. Select or paste the certificate signing request you want to use to issue theinitial SuperAdmin certificate. Click OK . (See figure 5.29.)


39 (101)



Download the certificate (see figure 5.30) and install it (using some proprietary method).Close the tab when done.


Back in the installation wizard tab (see figure 5.25), click Finalize installation .

40 (101)



5.13 Finalize InstallationAs the very latest step of our installation, you have to finalize the installation by clickingthe button Finalize installation . Finalizing takes some 30 seconds. The browser willreload the page and ask you to confirm that your (or which) client side certificate shall beused for authentication (see figure 5.31). If you use different Additional Subject DN forthe different installations, the matching certificate should be pre-selected. (Should you everneed to delete certificates from your browser, please keep in mind that you need to restartyour browser for these changes to take full effect).

This is also the moment where you can connect the second network cable to the Appli-cation Interface (the left one, as seen from behind) if you had not done this before.

Figure 5.31: Certificate Selection

Due to the inner workings of the PKI Appliance, configuration changes onlyget persisted after approximately one hour (or when the machine is properly shutdown/rebooted), leading to lost configuration in case of a power outage rightafter installation. This might be relevant if you are running a test installation onyour desk or in a test lab.

41 (101)


6. RESTORE FROM BACKUP Ver: 3.0.0

Chapter 6

Restore from Backup

A backup file can only be restored to a fresh and unprovisioned machine. You will need thebackup file on a Network File System (NFS) share, the Domain Master Secret that you spec-ified when installing the first machine of your environment and the smart cards dependingon your chosen Appliance Security Level (please refer to the chapter 5.10.1 on page 26 andthe following chapter for more information about the Domain Master Secret, the ApplianceSecurity Level and the smart cards).

i Relating to the S-M-L product size variations, please be aware that youcan only restore a backup to a matching or bigger product size version.Example: A backup from a model M product size can only be restored to ahardware of M or L product size.

In a cluster environment, a backup should only be restored in utmost emergency, e.g.if all of the cluster nodes have proven unoperational. If at least one cluster node is stilloperational, a broken cluster should always be reconfigured from the last remaining node.Please see chapter 9 HA Setup (page 78) for general information about Clustering/HighAvailability Setup and for very detailed information on how to proceed with either bringingback a PKI Appliance into your cluster or - as a last resort - restore a cluster node frombackup (9.5.2 on page 83).

i With version 2.4.0 and newer, the PKI Appliance will not be able to restorefrom backup data created on a PKI Appliance with versions older than 2.2.0.

6.1 Restore Stand-Alone System from BackupThese are the things you should make sure to have at hand:

• Domain Master Secret

42 (101)


6. RESTORE FROM BACKUP Ver: 3.0.0

• Unless the PKI Appliance has been configured with a low Appliance Security Level (fordemo and testing), you will need the PIN pad, the persons with the smart cards andthey will need to know their PINs.

• Physical access to the PKI Appliance.

Now follow the following procedure:

1. Switch on the the PKI Appliance and wait for it to finish booting, this will take about5 minutes.

2. Configure the network settings through the front display.

3. Take note of the One Time Password (OTP) and the TLS Fingerprint.

4. Connect the Management inferface of the PKI Appliance to the network.

5. Navigate your firefox browser to the configured IP address and log in using the OneTime Password.

6. In the installation menu chose „restore from backup“ and enter the connections detailsof your NFS server where your backup is stored.

7. The restoration of the backup can take up to several hours depending on the size of yourbackup. The restore procedure might request you to connect a PIN pad and providethe backup protection smart cards in case your initial system had been configured touse those.

8. After finishing the restore procedure you will be asked to reboot the system. This isthe moment where you can safely connect the second network cable to the ApplicationInterface if you have not yet. Keep in mind that after the system has been rebooted itwill have the restored configuration including IP address, SuperAdmin certificates etc.

43 (101)


7. CONNECT TO CLUSTER Ver: 3.0.0

Chapter 7

Connect to cluster

A fresh and unprovisioned PKI Appliance can be added to a cluster or can be connectedto another standalone PKI Appliance to start your cluster. You have to start the procedureeither on any node that is already part of the cluster or on the standalone machine thatis already installed respectively. When starting the procedure on that node, you’ll be giveninstructions to download a so called cluster bundle. This cluster bundle will then be neededwhen going through this part of the wizard. You will also need the Domain Master Secretthat you specified when installing the first machine of your environment and a copy of theBackup key share smart cards that were created when installing the first machine of yourenvironment (please refer to the chapter 5.10.1 on page 26 and the following chapter formore information about the Domain Master Secret, the Appliance Security Level and thesmart cards).

i Relating to the S-M-L product size variations, please be aware that youshould not mix product size variants in a cluster. Since a filled hard diskmakes the database stop working, the smallest node of your setup will stopworking (and thus reduce redundancy) first.

It is recommended to read the chapter 9 (page 78) in this document if you are changinga standalone setup to a multi-node cluster or extending an existing cluster with additionalnodes.

After logging in to the PKI Appliance using the One Time Password from the front paneldisplay and chosing to connect to a cluster, you will be guided through a short wizard.

44 (101)


Ver: 3.0.0

Part III

WebConf

45 (101)


8. WEBCONF Ver: 3.0.0

Chapter 8

WebConf

The WebConf is the web based user interface for managing the base functionality of the PKIAppliance. The functions are sorted under different tabs (described below) and by selectinga tab, contextual help for the selected functionality is shown to the right.

8.1 StatusThis view shows you information about the overall status of your installation (see figure 8.1).

Figure 8.1: WebConf Status Page

From the status page you can expect to get a rough overview of the health status ofyour PKI Appliance.

8.2 NetworkIn this view you can configure networking for the PKI Appliance (see figure 8.2). ThePKI Appliance has two network interfaces. One for administration (where you are currently

46 (101)



connected to) and one for exposing the running applications as a service.

Figure 8.2: WebConf Network Settings

The network address range for each interface is configured using the IP prefix, but isshown as both Netmask and Network for convenience. Gateway is the default gateway fortraffic to hosts that are not included in any of the interfaces’ network address ranges. OnlyIPv4 is currently supported.

After applying the settings there will be a short delay before the UI is reachable again.If you have changed the management IP address, make sure that you reconnect to thespecified address after the change.

8.2.1 NTP

Network Time Protocol (NTP) can be configured to always keep the clock of the PKI Ap-pliance in sync with a well known time source. It is recommended to use multiple trustedtime sources whenever possible. NTP servers are accessed through the Management Inter-face. An example could be the NIST NTP server: 129.6.15.29 NTP is required for clusteroperation. Please note: Enabling NTP by adding NTP servers will not change/correct thetime instantly. The PKI Appliance clock will be migrated to the time of the NTP sourcevery gently to not disturb operations. Depending on how far off the clock is, a reboot of thePKI Appliance might or might not speed up the clock migration.

8.2.2 DNS

Domain Name System (DNS) servers can be configured to enable host lookup by hostnameinstead of IP address. This should only point to a trusted name servers to avoid that thePKI Appliance communicates with malicious hosts. DNS servers are accessed through theApplication Interface. An example of an untrusted DNS server (OpenDNS) you can use fortesting is: 208.67.222.222

47 (101)



8.2.2.1 Fully Qualified Domain Name (FQDN)

The Fully Qualified Domain Name is used by the SMTP email gateway as origin and shouldmatch the DNS record for the Application Interface IP address.

8.3 AccessIn this view you can manage how the PKI Appliance can be accessed (see figure 8.3).

Figure 8.3: WebConf Access Settings

8.3.1 TLS certificates

8.3.1.1 Server side TLS certificates

Server 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 connectand the client must trust the issuer of the certificate.

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

Subject Distinguisher Name:CN=hostname.example.com...

Subject Alternative Names:DNSName=hostname.example.comIPAddress=10.10.10.10...

Key Usage: Digital Signature, Key EnciphermentExtended Key Usage: TLS server authentication (OID 1.3.6.1.5.5.7.3.1)

48 (101)



Setting the hostname to an IP address will also work.The initial certificates issued for the network interfaces are self-signed. During the in-

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

1. Generate a new key pair .

2. Create a Certificate Signing Request (CSR).

3. Send the CSR to your CA together with the information you would like to have in thecertificate. Note that some implementations (e.g. Java) require a matching IP addressor DNS entry in the certificate.

4. 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 nor-mal EJBCA way of doing things, where the information inside the CSR is not trusted andoverridden by whatever values the RA officer finds acceptable.

8.3.1.2 Client side TLS certificates

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

i Note that no revocation checking has been implemented yet.

8.3.1.3 Trust CA certificates for client authentication

You can configure different trusted certificates (trust anchors) for each network interface. Ifyou want to use client TLS certificates from an external CA, you need to replace the trustedcertificate. To avoid locking yourself out of the PKI Appliance, first add the appropriatematching rules under PKI Appliance Management Accounts, so that you can reconnectand 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 clientTLS certificate issued by this trusted CA.

8.3.2 PKI Appliance Management Accounts

PKI Appliance management accounts are matching rules that will be processed when a usertries to log in. Two types of rules are currently implemented:

49 (101)



• Client TLS certificates authentication.

• Shared secret (password) authentication.

The match value in case of client TLS certificates is the entire Subject DistinguisherName (e.g. "CN=SuperAdmin,O=PrimeKey Labs C,C=DE") of the certificate.

For shared secret authentication, the value is the shared secret. We would stronglydiscourage the use of shared secret authentication and this option might disappear in futurereleases of the PKI Appliance.

Use-Case: Create a new TLS server side certificate for Application Interface

In this exercise we will create a new server TLS certificate for the Application Interface usingWebConf.First we will check which is the present TLS certificate that is used.

1. Open in the browser the Application Interface.

2. Click on the icon where is located before the URL (see figure 8.4) and press More information.

50 (101)



Figure 8.4: EJBCA TLS check

3. Press View Certificate shown in fig. 8.5.

Figure 8.5: EJBCA TLS check certificate

4. Various information about the certificate are displayed. Among them is also CN withthe value node1-tls-app (see figure 8.6).

Now we will create a new TLS server certificate for the Application Interface.

1. Navigate to the tab ACCESS in WebConf

51 (101)



Figure 8.6: EJBCA CN value for TLS

2. In Server side SSL/TLS configuration and under Application Interface pressGenerate new key pair (see figure 8.7)

Figure 8.7: WebConf Access tab

3. New options will appear (see figure 8.8) and we will create a CSR with Create CSR

52 (101)



Figure 8.8: WebConf Create CSR

4. At that point we can download CSR with Download CSR (see figure 8.9).

Figure 8.9: WebConf Download CSR

5. Now we’ll use EJBCA Admin pages. In RA Functions press Search End Entities. .In Search end entity with username write tls_app. The result shows in figure 8.10

6. Click Edit End Entity. A popup window will appear.

7. Set Status to New ,

53 (101)



Figure 8.10: EJBCA Search End Entities

8. for Password set foo123,

9. in CN, Common Name set node1-tls-app-new (see figure 8.11),

Figure 8.11: EJBCA Edit End Entity

10. and at last set Token to User Generated (see figure 8.12).

54 (101)



Figure 8.12: EJBCA Edit End Entity, cont.

11. Navigate to Public Web

12. Under Enroll open Create Certificate from CSR (see figure 8.13).

Figure 8.13: EJBCA Create Certificate from CSR

13. For Username use tls_app,

14. as Enrollment code provide the password we used earlier foo123,

15. Browse... to the file appliance-app.csr.pem,

16. and as Result type choose PEM - full certificate chain (see figure 8.14)

17. Press OK .

55 (101)



Figure 8.14: EJBCA Enroll

18. At that point we’ll save the pem file with name node1tlsappnew.pem (see figure 8.15)

Figure 8.15: EJBCA Save certificate chain

19. Navigate to WebConf to Access tab. As you see in fig. 8.9, we can Browse... forNext chain: and upload node1tlsappnew.pem.

20. It is the time to activate the certificate chain to the server with Activate new cert(see figure 8.16). The procedure will take a while until the new TLS certificate will beactive (see figure 8.17).

56 (101)



Figure 8.16: WebConf: Activate certificate chain

Figure 8.17: WebConf: Upload certificate chain

21. We can verify that the server is using the new certificate by refreshing applicationpages. We will be asked to confirm the new connection (see figure 8.18). Once this isdone, we can see the new certificate as shown on fig. 8.4.

Figure 8.18: EJBCA login

57 (101)



22. When we verify the certificate that is used for the TLS connection, we can see that itis the one we created, with the new CN node1-tls-app-new as in fig 8.19.

Figure 8.19: EJBCA TLS cert CN

From now on each time we login to the Application Interface the new TLS certificatewill be used.

Use-Case: Upload a new trusted CA for TLS authentication and new super-admin certificate for Management Interface

In this exercise we will change the client certificate and update the trusted CA for Manage-ment Interface using WebConf.The new superuser certificate has to be issued from the same CA (MyCustomCA) that we willinstall for TLS authentication. First we have to provide the information about the certificate(MyUsername.pem) that will be used as superuser.

1. Open the WebConf and navigate to Access tab (see fig. 8.20)

58 (101)



Figure 8.20: WebConf Access

2. Check the Subject DN of the certificate using openssl

Run as <user>

\$ openssl x509 -in MyUsername.pem -subjectsubject= /C=MyCountry/O=MyCompany/SN=MyLastName/GN=MyFirstName \

/serialNumber=G824734/CN=MyFirstName MyLastName/UID=R4501ZHE-----BEGIN CERTIFICATE-----MIID3zCCAsegAwIBAgIIdzHlq8R4dnAwDQYJKoZIhvcNAQELBQAwPTETMBEGA1UEAwwKTXlDdXN0b21DQTESMBAGA1UECgwJTXlDb21wYW55MRIwEAYDVQQGEwlNeUNvdW50cnkwHhcNMTUwMTEzMDkxOTIzWhcNMTYwMTEzMDkyNjAzWjCBoDESMBAGA1UEBhMJTXlDb3VudHJ5MRIwEAYDVQQKDAlNeUNvbXBhbnkxEzARBgNVBAQMCk15TGFzdE5hbWUxFDASBgNVBCoMC015Rmlyc3ROYW1lMRAwDgYDVQQFEwdHODI0NzM0MR8wHQYDVQQDDBZNeUZpcnN0TmFtZSBNeUxhc3ROYW1lMRgwFgYKCZImiZPyLGQBAQwIUjQ1MDFaSEUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5Dr5dRsioTvihzdeQQ1cCbDDM/KqN729+wuNcfO3btlMhXMRMrSdBz2gZgfIDfbNjWnmOmkF5...qqh6BtM4h2SpLlzcpELvOA6ySUEsfvaVpK4I7ebLFDFhtTM=-----END CERTIFICATE-----

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

3. Under PKI Appliance Management Accounts and MatchType choose clientcert(see figure 8.21), provide the Subject DN:(C=MyCountry, O=MyCompany, SURNAME=MyLastName, GN=MyFirstName, se-rialNumber=G824734, CN=MyFirstName MyLastName, UID=R4501ZHE ) of the cer-

59 (101)



tificate and press Add .

! EJBCA is using org.bouncycastle.asn1.x500.style.BCStyle which interpretsSN as serialNumber. We inherit this in org.cesecore.util.CeSecoreNameStyle(Legacy reasons). That means that the user has to make sure that he willreplace SN with SURNAME otherwise there is the danger of getting lockedout!

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

4. Under Trusted CAs for TLS client authentication section we will Browse.. forthe MyCustomCA-chain.pem file (see fig. 8.22).

! It has to be the whole chain from the issuer CA of the client certificate upto the trusted RootCA.

60 (101)



Figure 8.22: WebConf Upload the new trusted CA chain

5. Press Activate new CA certifcate

6. TLS will update the new trust of CA as shown in fig. 8.23

Figure 8.23: WebConf TLS is updated

7. When update is done, the new trusted configuration is used for authentication in theManagement Interface (see fig. 8.24).

61 (101)



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

Use-Case: Configure a new trusted CA for TLS authentication and newsuperadmin certificate for Application Interface

In this exercise we will change the client certificate and update the trusted CA for ApplicationInterface using WebConf. First we will configure EJBCA and then WebConf .The new superuser certificate has to be issued from the same CA (MyTrustedSubCA signedby MyTrustedRootCA) that we will install for TLS authentication. First we have to providethe information about the certificate (MyClientAuthenticationCertificate.pem) that will beused as superuser.

1. Open the EJBCA admin web and navigate to Certification Authorities tab and useImport CA certificate... (see fig. 8.25) to upload all CA certificates that belong tothe new trust chain. In our paradigm it is MyTrustedRootCA and MyTrustedSubCA.

62 (101)



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

2. Open Administrator Roles link and click Administrators next to Super Adminis-trator Role as shown in fig. 8.26

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

63 (101)



3. Check the Subject DN of the client certificate which will be used to authenticate usingopenssl

Run as <user>

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

serial=2b4306acbf69224

4. Use the following values (see fig. 8.27) and press Add :

• CA: MyTrustedSubCA

• Match with: X.509: Certificate serial number (Recommended)

• Match type: Equal, case sens.• Match value: 2b4306acbf69224

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

Now EJBCA is configured to use this certificate. But the last step is to configure We-bConf so the Application Interface will also authenticate MyTrustedSubCA-chain.pem

5. Follow the same process but for the Application Interface in analogous ways as de-scribed in Use-Case: Upload a new trusted CA for TLS authentication and new super-admin certificate for Management Interface.

8.4 HSMThe Hardware Security Module (HSM) configuration allows you to change the authenticationcodes of the PKCS#11 slots, change the PIN of Backup Key Share Smart Cards, make one-to-one copies of backup protection cards, change the PIN of user credentials on smart cards

64 (101)



(for slot activation), download a full (protected) backup of the HSM’s key material or handleHSM key synchronization across a cluster.

Figure 8.28: WebConf HSM Settings and Actions

Please note that the figure 8.28 shows some functionality that might not be available,according to your setup.

8.4.1 Changing HSM PKCS#11 slot authentication codes

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

8.4.1.1 Switching from generated to manually entered authentication code

Manually entered authentication codes are not stored on the system, but known by theadministrator, administrators or m out of n administrators in conjunction.

Pros: Key material is not necessarily compromised in the case of lost physical access of thebox.

Cons: After a reboot, the PKCS#11 slot must be manually activated using the authenti-cation code.

8.4.1.2 Changing a manually entered authentication code

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

8.4.1.3 Switching to auto-generated authentication code

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

65 (101)



Figure 8.29: Slot authentication code change from generated to manual

Figure 8.30: Changing the authentication code of a slot

Figure 8.31: Manual slot authentication code change

Pros: Highly available. Authentication code is very hard to brute force. Authentication codecannot be disclosed by administrators.

Cons: Possible to extract given physical access to the machine (theft of the PKI Appliancecould not rule out that the key material of the slot could not be freely accessed).

Figure 8.32: Slot authentication code change from manual to generated

66 (101)



8.4.2 Backup Key Share Smart Card Handling

These options are only available if you initialized the PKI Appliance using smart cards forbackup protection (see ’Appliance Security Level’ on page 26). Before using any of thesefunctions, you need to have the PIN pad connected 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 accessiblefrom the back) will not work. The USB ports on the front of the PKI Appliance are fine.

8.4.2.1 Make a one-to-one copy of a smart card

This allows you to make an identical copy of a smart card. This way, it will allow you tocreate a second set of 2 out of 3 cards for your disaster recovery site, for example. Youshould create a backup set of the Backup Key share smart cards. Please keep in mind thatthe Backup Key share smart cards should never be kept close to the backup of the PKIAppliance

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 tocopy the data form the second smart card to the third smart card, effectively overwriting theBackup Key share on the third smart card.

8.4.2.2 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 shouldabsolutely be done with each of the Backup Key Share smart cards. This is the easiestpossibility to prevent a mixup or accidental overwriting of the contents of a smart card. Thisfunction 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 PKIAppliance.

There is also a similar functionality offered to change the PIN of a PKCS#11 Slot Useron a smart card, given that you have choosen to additionally secure your PKCS#11 slotswith smart card authentication.

8.4.3 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 isprotected using the Backup Key for the higher Appliance Security Levels.

8.4.4 Cluster Key Synchronization Packages

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

If you create a new key in the HSM through EJBCA (e.g. creating a new CA), theknowledge about its existence will synchronize through the database, but the key itself will

67 (101)



not synchronize automatically. Hence, you will have to manually distribute this new key databy downloading a Key Synchronization Package on the Node where you created the newCA and uploading it to each of the other nodes. The applications (EJBCA, SignServer) willautomatically be restarted, so that the key material can be used. See also Chapter 9 on page79 for a more detailed description of the workflow.

8.5 BackupBackups are entire snapshots of the system at a specific point in time. This will guaranteethat you can go back to a stable state in case of disaster.

Figure 8.33: WebConf Backup Settings and Actions

! To restore the system to the state of a backup, you need to perform afactory reset and use the initial wizard. During the restore procedure youwill be prompted for the Domain Master Secret that was set during theinstallation of the system (see chapter 5.10.1).

Configuring backup location

Select a protocol and relevant parameters for this protocol. Only Network File System (NFS)is currently supported. Save the location and try to reload the (empty) list of backups toverify that the location is readable. If this works, continue with taking a manual backup toensure that the location is writable as well.

Taking a manual backup

Click Backup now to start a background backup process. Revisit the Backup tab laterto see that the backup has finished. A backup on an "empty" or freshly installed system isusually done within minutes.

68 (101)



Deleting backup

! Reload the list of backups and press the Delete button for the backupyou want to remove.

Automated backup schedule

i Backups can be automated to run once per day, once per week or onceper month. Taking a backup will put some load on the system, so it isrecommended to pick a time where you expect little usage. Be sure to saveyour settings.

69 (101)



8.6 ClusterThis view gives you an overview of the cluster or rather this nodes’ view of it. You can alsoconfigure cluster settings. (see figure 8.34).

Figure 8.34: WebConf Cluster

Please refer to the chapter 9 HA Setup (see page 78) for further information on how toextend your system to a cluster with multiple nodes.

8.7 MonitoringIn this view you can configure monitoring (SNMP and remote syslog) for the PKI Appliance(see figure 8.35).

Figure 8.35: WebConf Monitoring

8.7.1 Syslog shipping

You can specify an IP address of a syslog server where the syslog of this PKI Applianceshould be shipped to. The syslog contains the syslog of all internal systems as well as theEJBCA audit log. The syslog will be shipped by UDP in unencrypted, unsigned traffic.

70 (101)



8.7.2 SNMP

You can activate snmp access to the PKI Appliance by checking this button. All snmprequests are combined in the "public" community. Now the PKI Appliance will answer to thetwo standard MIBS SNMPv2-MIB and HOST-RESOURCES-MIB. Additionaly the followingparameters 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.108.111.97.100.51.1Load average of the system. Intervals is 5 min 0.10.1.3.6.1.4.1.22408.1.1.2.1.5.108.111.97.100.52.1Load average of the system. Intervals is 15 min 0.06.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

71 (101)



.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

72 (101)



.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.1.3.6.1.4.1.22408.1.1.2.1.6.109.97.105.110.116.49.1Maintenance State as int, 0 if operational, 1 if offline or 2 ifmaintenance

0

.1.3.6.1.4.1.22408.1.1.2.1.6.109.97.105.110.116.50.1Maintenance State as string Operational

Alternatively all OIDs can be reached by the following three snmpwalk commands (replacethe ip address with the one of your system):

# for the standard groupsnmpwalk -v2c -On -c public 192.168.5.162# for the system groupsnmpwalk -v2c -On -c public 192.168.5.162 .1.3.6.1.4.1.22408.1.1.2.1# for the HSM groupsnmpwalk -v2c -On -c public 192.168.5.162 .1.3.6.1.4.1.22408.1.1.2.2

8.8 PlatformIn this view you can see the applications running on the PKI Appliance, update the firmwareand perform basic troubleshooting.

8.8.1 Applications

This gives you an overview of the applications that are installed on your platform, along withtheir access URLs.

8.8.2 Updates

The WebConf allows to update the software of the PKI Appliance over network.Special care needs to be applied if a cluster or one of its nodes is supposed to be upgraded

to a newer version. Please refer to chapter 9 HA Setup (page 78) for general information

73 (101)



Figure 8.36: WebConf Platform page

about Clustering/High Availability Setup and 9.5.3 (page 84) for very detailed informationon how to update a cluster.

Starting with version 2.2.0, the PKI Appliance firmware is to be updated separately fromthe applications installed on the platform of the PKI Appliance. You are supposed to upgradeboth the firmware and the application, starting with the firmware.

Versions older than 2.2.0 cannot be updated to anything newer through this WebConffunction. Please contact PrimeKey Support or your local PrimeKey Partner to obtain helpwith upgrading your PKI Appliance to 2.2.0 and beyond.

Update Stand-Alone System

You need to update both the PKI Appliance firmware and the COS applications (COS,Customer Operating System, EJBCA or SignServer), you will have to manually start bothoperations. It is recommended that you first update the PKI Appliance firmware, then updatethe COS applications.

To update, select the protocol and the parameters related to the selected protocol. Pleasenotice that currently only NFS is supported. Enter the IP-address of the NFS server in theSource Host field. If you have DNS configured and activated (see chapter 8.2.2, page 47for details) the hostname can be used. Enter the export path of the NFS server in theSource Path field. It is possible to apply a filter to either only show the firmware updatefield or the application update files. Click the Search now button if any update is foundit will be displayed in a list. If you are not in the directory of the update files use theChange directory button to traverse to the correct directory.

Update Firmware

Select the desired firmware update file by pressing the Install Firmware button next tothe file name. This will trigger a background job of the update process. It will take a while,so return to this view later to check if the update has finished. During the update the PKI

74 (101)



Appliance will stay fully operational. The updated firmware will not be used until the systemis rebooted.

Update Application

To update a COS application select the desired update file by pressing the Install Applicationbutton next to the file name. This will trigger a background job of the update process. Itwill take a while, so return to this view later to check if the update has finished. Duringthe update the PKI Appliance will be set into maintenance and the application will be notavailable. The update will be used when the update process is finished.

8.8.3 Troubleshooting

The Troubleshooting section provides basic power-cycle functionality and shows the PKIAppliance state including a list of reasons for maintenance and the functionality to set thePKI Appliance Offline.

8.8.4 Platform Access

The platform access page allows you to:

• Enable/disable SSH access

• Upload an SSH public key

• Define a password for cleartext SSH authentication

• Define a password for local console root access

Starting with version 2.4.0, the PKI Appliance will have no default password configuredfor access anymore. This implies that you will have to set up your way of authentication ifyou need access the platform. Please be aware that your SSH client will still ask you for apassword (and thus make it look like there is *some* password set up) if there is no cleartextpassword defined. Defining either SSH public key or root password for SSH access will onlybe possible after you enabled SSH.

8.8.4.1 SSH public key

You will be able to either upload or paste a typical one-line openssh public key. Unfortunately,as a currently known bug, the software will also accept a multiline public key as known fromssh.com/putty but fail at a later point in authentication.

8.8.4.2 Password authentication

You are able to set one (same) password for cleartext authentication for either SSH or localconsole access.

75 (101)



8.8.5 Support

The Support section provides access to already created ’Support Packages’ and the abilityto create new ’Support Packages’ manually. In addition an e-mail address is provided if youneed to get in contact with professional support for the PKI Appliance.

76 (101)


Ver: 3.0.0

Part IV

Advanced

77 (101)


9. HA SETUP Ver: 3.0.0

Chapter 9

HA Setup

9.1 Scope of availabilityFor the PKI Appliance the availability is defined as being able to keep the service running withfull data integrity for the applications running on the PKI Appliance that uses the internalSQL database.

9.1.1 How it works

The cluster implementation used on the PKI Appliance uses regular network connectivityover the Application Interface for all cluster communication. This means that cluster nodesdon’t have to be placed physically close to each other as long as they have good networkconnectivity.

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

9.1.2 Synchronization of key material

Key material stored in the HSM is not automatically synchronized after the cluster has beenset up. Manual synchronization is however possible.

9.1.2.1 Pre-cluster setup generation of keys

If suitable for your use-case, you could generate all keys that will be used during the instal-lations life-time after installing the first node, but before starting the cluster configurationfor the additional nodes. This way, all additional cluster nodes will be provisioned with the

78 (101)



complete key material on installation and no additional manual key synchronization will benecessary.

9.1.2.2 Post-cluster setup generation of keys

When generating new keys (or in any other way modifying the key material) after the clusterhas been setup, you need to manually synchronize the key material.

Note that applications that are connected to the shared database may malfunction ifthey try to use references to keys that are not yet synchronized. For example, if a CertificateAuthority in EJBCA is renewed with new key generation, other cluster nodes shortly afterthe renewal will try to use the new key. This will fail since the key generation was local tothe node where it was performed.

Use-Case: Synchronize key material

1. On Node 1: Generate the key pair(s) on the first node.

2. On Node 1: Go to the HSM tab of the PKI Appliance WebConf and download a "Clus-ter Key Synchronization Package" by clicking Download protected HSM backup.

3. On Node n: Go to the HSM tab of the PKI Appliance WebConf and upload thepackage.

4. Repeat step 3 for each node (n>1).

5. 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 generatethe keys there to avoid a reboot and potential downtime in a two node setup.

9.1.3 Network topology

All 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 leastone other node.

The network connection is done via the GRE protocol (IP protocol number 47, seehttps://en.wikipedia.org/wiki/List_of_IP_protocol_numbers). Since GRE is anIP protocol, it is not based on either TCP or UDP and has no concept of ports. It is anIP protocol by itself. That means that it can not simply be made available with a portforwarding behind a NAT (Network Address Translation). A fully transparent VPN solutionwill 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 mightstill run into the issue of network address complications. This is easiest worked aroundby setting up the systems in a simpler network configuration (e.g. same site) and latershipment/reconfiguration.

79 (101)

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



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

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

9.1.4 Cluster traffic security considerations

The current version of the PKI Appliance uses no protection for the cluster traffic. IPSecwill be used in a later release, but for now you need to ensure that this sensitive traffic isprotected by other means.

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

In the case a custom application is being developed for consumption of the servicesprovided by the PKI Appliances’ external interfaces, this could also be handled by makingthe 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, thiscould also be solved by redirecting a DNS name to the service.

9.3 Levels of availability

9.3.1 Stand alone instance

This is a basic single node installation of the PKI Appliance. In case of a node failure anew PKI Appliance needs to be reinstalled from a backup. All data between the time of thelatest backup and the failure will be lost. If a cold stand-by (spare) PKI Appliance is notavailable, the time of delivery of a new box needs to be taken into account when calculatingthe acceptable downtime.

9.3.2 Hot stand-by with manual fail-over

In this setup, two nodes are connected as a cluster where the first installed node has a higherquorum vote than the second node.

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

80 (101)



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

9.3.3 High availability with automatic fail-over

This is a setup with three or more nodes. In case of a node failure, the remaining nodes willstill be able to form a cluster through a majority quorum vote and continue to operate. Ifthe 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 quorumvote 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, thesite that is intended to remain Active if connectivity between the sites fails should have alarger sum of quorum vote weights than that of the other site. Since cluster nodes with lowernode numberes have higher weights you should deploy nodes 1 to N/2 on the primary site.

9.4 High Availability

Use-Case: Setting up a 2 node cluster from scratch

1. Make a fresh install according to the normal installation procedure or restore a nodefrom backup.

2. If possible, generate all keys in the HSM that will be used during the installationslife-time to avoid manual key synchronization later.

3. Go to the Cluster subtab Configuration on the initial node in the PKI ApplianceWebConf and add a connection to where the next node’s Application Interface will be.

4. From the same subtab, download the setup bundle for the second node.

5. Factory reset the second node and connect to the web based installer

6. Select Connect to cluster and upload the setup bundle.

7. At this point, both network cables need to be connected to the second node. Startthe installation procedure.

8. After installation completes, you should be able to manage the new node using thesame credentials as the first one.

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

81 (101)



Use-Case: Setting up a 3 node cluster from scratch

1. Make a fresh install according to the normal installation procedure or restore a nodefrom backup.

2. If possible, generate all keys in the HSM that will be used during the installationslife-time to avoid manual key synchronization later.

3. Go to the Cluster subtab Configuration on the initial node in the PKI ApplianceWebConf and add the two connections to where the next nodes’ Application Interfacewill be.

4. From the same subtab, download the setup bundle for the two new nodes.

5. Factory reset the second node and connect to the web based installer

6. Select Connect to cluster and upload the setup bundle for node 2.

7. At this point, both network cables need to be connected to node 2. Start the instal-lation procedure.


9. Even if a full synchronization between the first and second node is still running at thispoint, you can proceed with the cluster connection of the third node.

10. Factory reset the third node and connect to the web based installer

11. Select Connect to cluster and upload the setup bundle for node 3.


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

Use-Case: Extending a cluster from n to n+1 nodes

1. Go to the Cluster subtab Configuration on all of the existing (n) nodes in the PKI Ap-pliance WebConf and add a connection to where the next node’s Application Interfacewill be.

2. From the same subtab on one of the nodes, download the setup bundle for the newnode (n+1).

3. Factory reset the new node (n+1) and connect to the web based installer

82 (101)



4. Select Connect to cluster and upload the setup bundle.

5. At this point, both network cables need to be connected to the new node. Start theinstallation procedure.

6. After installation completes, you should be able to manage the new node (n+1) usingthe same credentials as the previous node(s).

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

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

9.5.1 Backing up a cluster

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

If you can afford, we recommend to set up a automated backup schedule on all of yournodes to make sure to be able to recover everything, out of every situation, even if perhapsa failure takes a long time to be discovered.

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

9.5.2 Restoring a cluster from backup

A backup file of a cluster node should only be used in the highest emergency of a full-outscenario. If at least one node remains operational, the cluster should always be reestablishedfrom the last good node.

To recover as much of you data as possible, start by identifying the last good backup youhave available from an Active node by analysing the outage. For example, if the connectionto a disaster recovery site went down long before a backup was made there, you might bebetter 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 theother nodes to this node.

Please refer to chapter 6 (on page 42) for a description on how to restore a backup to aPKI Appliance.

83 (101)



After reboot, the WebConf will be reachable and operational, but the database will refuseto start up in this situation, hence the applications will not yet be operational. The buttonForce into Active that the WebConf offers should be used in this scenario to force thecluster to continue operations from the restored data set.

9.5.3 Updating the software (firmware/applications) on a cluster

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

Starting with version 2.2.0, the PKI Appliance firmware is to be updated separately fromthe applications installed on the platform of the PKI Appliance. You are supposed to upgradeboth the firmware and the application, starting with the firmware.

A PKI Appliance on a version older than 2.2.0 can not simply be customer-upgraded dueto major architectural changes. Please contact PrimeKey Support or your local PrimeKeypartner for support.

For procedures on how to update a cluster on PKI Appliance version 2.3.0 to an evennewer version, please refer to the even newer documentation delivered with the new softwareversion.

Use-Case: Software update on a three node cluster from 2.2.0 to 2.3.0

To update a three node cluster from PKI Appliance version 2.2.0 to 2.3.0, please proceedwith the following steps:

1. Before starting any configuration changes on a cluster node, you should assert that thenode has been running fine up to now. This is the only way to know for sure whetheryou actually broke anything if the procedure does not succeed as expected.

2. You might also want to make a last manual backup of the PKI Appliance

3. Make sure this cluster node is declared as not operational, (e.g. disabling in loadbalancing frontend), so that:

• no other operator does any maintenance on any other node while we deliberatelyreduce redundancy on the cluster,

• nobody relies on the availability of this node during maintenance downtime,• and no alarm is raised if this node gets unavailable.

4. Start the software update procedure on this node by updating the PKI Appliancefirmware first, then updating the COS applications. This should generally be the sameprocedure as described in 8.8.2: Install firmware, reboot, install application.

84 (101)



5. After the cluster node has been rebooted, check that the node is operating correctly.

6. After you asserted that this node is up and running, verify that the entire cluster is ingood shape, i.e. that all of the cluster nodes of your cluster confirm that your clusteris back up and running with redundancy.

7. Announce this cluster node to be operational back again or whatever you need to undofrom step 3.

8. Continue with updating your cluster by applying the same steps on the next clusternode, restarting at step 1.

9.6 Controlled full cluster shutdown and startupThis section describes how to do a controlled shutdown of the whole cluster and get backto a fully running state.

9.6.1 Shutting down the cluster in controlled manner

When shutting down an N node cluster, start with a graceful shutdown of the node with thehighest node number and wait until the node is fully shutdown before proceeding with thenext one. This ensures that the quorum is kept as long as possible and in the end node 1 isthe most up to date node.

9.6.2 Starting a fully shutdown cluster

After a controlled shutdown as described in 9.6.1, the cluster nodes should automaticallybecome Active starting with the most up to date node after startup.

If the cluster is unable to automatically become Active, the administrator needs to manu-ally bootrap the cluster from the node with the most up to date data set. The administratorcan identify the node that had an Active database status last before the shutdown by com-paring 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 nodesshould be compared before selecting a node to Force into Active.

1. Power up all nodes.

2. Wait a minute after all nodes have started to see if the cluster automatically becomesActive.

3. If manual intervention is needed, select the node with the highest Last Transaction IDand use Force into Active on this node (and only this node).

4. Wait until all N nodes are fully started and database status is Active on each node.

85 (101)



9.7 Operational CautionThe cluster will now continuously respond to requests, synchronize the data, and evaluatethe health of the cluster to ensure availability on one hand, but also data integrity on theother hand. As described earlier, a node will rather stop working than to risk a split brainsituation. A split brain situation develops when two nodes believe they are lone survivors,continue to serve requests, causing two different data sets.

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

Maintenance operations on the cluster such as rebooting, updating, network reconfigu-ration, ... should be restricted to only one node at a time, with ample time for the node toreconnect 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 threenode cluster

In a PKI Appliance cluster, the internal communication is being transferred over the Appli-cation 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 configurationsteps to bring back the node into play:

1. Before starting any configuration changes on a cluster node, it is good practice toassert that the node has been running fine up to now. This is the only way to knowfor sure whether you actually broke anything if the procedure does not succeed asexpected.

2. You might also want to make a last manual backup of the PKI Appliance.

3. We’ll assume here that you have announced this cluster node as being not operational(e.g. disabled in a frontend load balancer) for the time of the change.

4. Now start the actual change by changing the Application Interface IP address on thecluster node in WebConf, see chapter 8.2 Network on page 46.

5. Navigate your browser to the Cluster Configuration subtab of the WebConf on all ofthe other cluster nodes.

6. Wait for the cluster node to appear offline/not connected in the cluster connectionstable, the IP address should now be in an editable input field.

7. On every of the other cluster nodes, correct the application IP address of the clusternode in the cluster table.

8. Confirm the operation by hitting Apply . It could be that you have to wait a coupleof seconds before you are allowed to click that button.

86 (101)



9. After the cluster reconfiguration has finished, all cluster nodes should be connected toall of the other cluster nodes.

10. When everything works as expected, you should not forget to bring back the node intothe load balancer.

Replacing a failed cluster node

To replace a failed cluster node, follow the same procedure as you would for adding thecluster node for the first time. See chapter 9.4 Use-Case: Extending a cluster from n to n+1nodes on page 82 for more detailed information. Restoring the node from a backup will notwork because the database content in the backup file will be outdated.

87 (101)


10. SMART CARD HANDLING Ver: 3.0.0

Chapter 10

Smart Card Handling

10.1 IntroductionSmart 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 smartcards. The smart cards that come with the PKI Appliance are preprogrammed cards with theTCOS operating system (TeleSec Chipcard Operating System) and are, as can easily be seen,branded by the manufacturer of the HSM that we incorporate in the PKI Appliance. Smartcards can store some amount of information, organized in sets of so called ’slots’. The datasets 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 slotsis the 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 10.1: Smart card with branding

10.2 Smart Card Reader or PIN PadA smart card is of no good use if you cannot use it, if you can not read it. This is whythere is another thing delivered with each PKI Appliance: A smart card reader or also oftencalled PIN Pad (As a matter of fact, a simple smart card reader would be of no big help in

88 (101)



this case, since all of the functions that we want to use of these smart cards always requirea 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 theUSB ports of the PKI Appliance. The PKI Appliance itself has two USB ports to the frontand two to the back that can be used. Additionally, the HSM that we integrate into the PKIAppliance has a USB port on the back on its own. This USB port cannot be used for ourand your PIN Pad purposes. There is currently no possibility to use this PIN Pad for PKIAppliance purposes connected to your workstation/web browser.

Figure 10.2: PIN Pad with inserted smart card

10.3 Usage of Smart CardsWith the PrimeKey EJBCA PKI Appliance, the smart cards are used to protect the cryp-tographic secrets of the HSM, these functionalities are offered by the vendor of the HSM.Precisely, two different functions are implemented with the smart cards. These two differentfunctions operate on different slots. These different slots have separate PINs. They are allpreset to the default PIN of ’123456’ when delivered. In theory, one smart card can be usedfor 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 leadto confusion.

10.3.1 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 "MasterBackup Key" (MBK) and we make use of that, entirely transparent. When you install the PKIAppliance 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 readback in, from the smart cards into the HSM. From this point on, every bit of informationthat is downloaded from the HSM with administrative functions (such as "create backup")

89 (101)



is encrypted with this Backup Key. This is why you need to have these smart cards at handif you want to restore a backup: The Backup Key that encrypts the backup files needs tobe uploaded to the HSM first. If you configure an 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 BackupKey is spread across these smart cards using a quorum, see next section.

Please be aware that a Backup Key share cannot be restored if it has beenoverwritten by mistake. This is a good reason to change the PIN of a smart cardright after a successful installation to prevent any mixup or mistake. Anothergood practice might be to create copies of backup key share smart cards to bestored in a safe place. Also it might be worth noting that the Backup Key cannotbe changed after installation; this would invalidate all existing backup files.

10.3.2 PKCS#11 slot activation user smart card

Since version 2.2, the smart cards may also be used to store user credentials needed to activatePKCS#11 slots. There is no quorum for user credentials on smart cards. Please refer tochapter 11 on page 96 for more information about PKCS#11 slot smart card activation.

It shall be stated that the user credentials on a user smart card used forPKCS#11 slot activation can not be copied one-to-one, unlike the backup keyshare on a smart card.

10.4 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 can not even read a backup file if he is able to take possession of onesmart card with the according PIN. But splitting a Backup Key across multiple smart cardswould also have disadvantages: It would decrease usability or ease of handling since youwould always need the presence of every single card owner in case of a disaster recovery(and you know how these kind of things always happen in the worst of moments, think ofsummertime, holidays and thunderstorms). And it would effectively decrease reliability sincea single lost, broken or otherwise deactivated smart card would immediately ruin all youremergency precautions. To get the best of both worlds, the Backup Key is distributed acrossthe 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 hisname can be found in the letters of the RSA algorithm). This system is also sometimescalled 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 numberof shares so that every combination of k number of shares is sufficient to reconstruct thecomplete key.

90 (101)



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

10.5 Procedure (Installation, Example for ’2 out of 3’)These things are rather complex and can be confusing. Also, it is a lot of work to "justtry this out" since you cannot do this from your workstation or desk. Remember: The PINPad needs to be connected to one of the four USB ports of the PKI Appliance itself. Thisis 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 thedocumentation in the middle of the process. Any timeout will not be indicated as such onthe PIN Pad display, the display will just turn blank and the information about the timeoutwill be shown on the WebConf

For a ’2 out of 3’ scenario, this is exactly what the procedure will look like:

• Preamble

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

REINER SCTcyberJack e-com

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

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

2. Shortly after starting the installation (as in 5.12 on page 29), the PIN Pad willread:

Write New Keypress OK/Cancel

This is only the notification that we are now going to write a new key / keyshares to the smart cards. Any former Backup Key Share on these smart cardswill 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 twodifferent PKI Appliance environment. Every node in a cluster uses the same

91 (101)



Backup Key, thus any set of Backup Key Share smart cards will work with everynode in a cluster.

3. As soon as you acknowledge this by hitting the green OK button, procedure willcontinue with:

Insert 1. cardpress OK/Cancel

This is the instruction that the first of the smart cards should be inserted.4. 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 freshan unused smart card delivered with the PKI Appliance is ’123456’ until it hasbeen manually changed (see chapter 8.4.2.2 on page 67). The fact that you haveto 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 arethe legitimate owner of the smart card). You can restart the entry of the PINby pressing the yellow Clear button or you can abort the entire operation withthe red Cancel button. If you confirm with the green OK button, there will be ashort screen indicating some ongoing operation. Do not remove the smart cardwhile this operation is lasting.

5. After the short screen indicating the ongoing operation, you’ll see this:


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 clearlyshows that it is asking for the next smart card.

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

Enter PIN******

This is where you enter the PIN of the second smart card.7. After the short screen indicating the ongoing operation, you’ll see this:

92 (101)




This is the instruction that the third smart card of the set should be inserted.8. 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

• Key Reading:

9. After the Backup Key has been generated and the shares have been written ontothe smart cards, the Backup Key needs to be loaded into the HSM, therefore theBackup Key needs to be reconstructed by reading it from the smart cards. Sincethe Backup Key is based on the quorum of ’3 out of 5’ or in this example ’2 outof 3’ (see 10.4), the complete Backup Key can be reconstructed by reading only2 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 sharesfrom the smart cards.

10. If you acknowledge this by hitting the green OK button, procedure will continuewith:


This is the instruction that the first of the smart cards should be inserted. Whenreading back in the key in the ’2 out of 3’ scenario, any two Backup Key Sharesmart cards will do (as long as you insert two different smart cards rather thaninserting 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 smartcard the was written to. So, for convenience, you can leave the smart card in thedevice and enter its appropriate PIN.

11. You should proceed by pressing the green OK button again. The next messageof the display will be:

Enter PIN******

93 (101)



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

12. After the short screen indicating the ongoing operation, you’ll see this:Insert 2. cardpress 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.

13. Insert the next smart card and continue by pressing the green OK buttonEnter PIN******

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

Here is a list of things that can go wrong during this sequence:

• running into a timeout (a timeout message will not be visible on the PIN Paddisplay, only in WebConf)

• entering a wrong PIN for one smart card three times in a row (the smart card willbe 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 Pad

• inserting 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 tobe in an inconsistent state. You will have to do a full Factory Reset as describedin chapter 5.1 on page 15 and restart the installation process.

10.6 WebConf Smart Card Handling ToolsAs you can see in chapter 8.4.2 on page 67, the WebConf offers a couple of tools to helphandling smart cards properly.

10.6.1 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

94 (101)



recovery site, for example. You should create a backup set of the Backup Key share smartcards. Please keep in mind that the Backup Key share smart cards should never be keptclose to the backup of the PKI Appliance. Since each card is unique, this function cannotbe used to recover lost cards in card set. However, if for whatever reason you need a ’2 outof 2’ scenario, this function allows you to copy the data form the second smart card to thethird smart card, effectively overwriting the Backup Key share on the third smart card.

10.6.2 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 shouldabsolutely be done with each of the Backup Key Share smart cards. This is the easiestpossibility to prevent a mixup or accidental overwriting of the contents of a smart card. Thisfunction 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 PKIAppliance.

10.6.3 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 shouldabsolutely be done with each of the PKCS#11 slot activation user smart cards. This is theeasiest possibility to prevent a mixup or accidental overwriting of the contents of a smartcard. This function can also be used if the card is being assigned to another person of thecompany. This function can also be used on a smart card that comes originally from anotherPKI Appliance. See chapter 11 on page 96 for more information about PKCS#11 slot smartcard activation.

95 (101)


11. PKCS#11 SLOT SMART CARD ACTIVATION Ver: 3.0.0

Chapter 11

PKCS#11 Slot Smart CardActivation

11.1 IntroductionAll sensitive cryptographic material of the PKI Appliance is stored on a Hardware Secu-rity Module (HSM). This HSM protects your key material against physical attacks. Thekeys 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, theseslots must be activated with some authentication code. Depending on your requirementsfor availability, usability and security, you can select whether those authentication codesshould be stored on the PKI Appliance or not. This can be chosen per slot. Slots withstored authentication codes can be auto-activated for immediate availability. The generatedand automatically stored authentication codes are of very high quality. This choice can bechanged even later during the operation of the PKI Appliance.If even manually entered authentication codes do not meet the security requirements, thereis an option for a two-factor authorization: It is possible to additionally require an activationwith smart cards for one or more slots. This choice has to be done during installation.

11.2 Installation/ConfigurationPKCS#11 slot smart card activation can be enabled per slot but only during the installationof the PKI Appliance. To do so, untick (Automatically generated) AuthenticationCode for the slot you want to give more security. You will then be given the possibility to tickSmart card activated for that slot. Then you will see some more options available for thegeneral slot smart card activation settings. You still have to define an authentication codeper slot. You can either chose something trivial like 1234 since you are relying to externalsecrets anyways, or you can make it even more secure by defining a real secret authenticationcode which will be required additionally upon activation.

96 (101)



11.2.1 "Number of users required"

It can be chosen how many smart cards should be required to activate a slot. This way avery important application can be secured even further. However, there is no quorum (like"3 out of 5") available. If Number of users required: 5 has been chosen, then 5 differentuser credentials will be generated and written to 5 different smart cards, all of which needto be present when activating a slot. The default setting of the PKI Appliance is to createonly one user credential to be required.

11.2.2 "Number/copies of user smart cards"

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

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

11.2.3 "Require smart cards to activate system after boot"

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

11.2.4 Procedure

For every slot activation user that has been chosen, the following procedure will first runduring the installation:

• The user credentials are generated in memory.

• For every copy that has been chosen, the user credentials will be written to a smartcard. It is required to enter the PIN (default PIN on delivery: 123456) and acknowledgewith "OK".

• The user credentials (only public key) are read into the HSM, it will only be requiredto press the OK button.

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

97 (101)



11.2.4.1 Example with default values

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

• Backup key shares handling

– One 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 user

– Generation of user credentials– One audible alert (bee-beep)– User credential being written to one card (with PIN and OK)– 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)

11.2.4.2 Slots 0 and 1

If the installation is configured to have smart card activation on slot 0 and slot 1 (ManagementCA) Require smart cards to activate system after boot the installation procedure will beextended by more PIN pad operations since the installer needs access to these slots to createthe keys needed for operation, audit log signature and Management CA respectively.These extensions will be activation procedures as described in the next section.

11.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 smartcard(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 beingactivated and user card is required to be inserted.

! The user cards will always be required in ascending order, always startingwith User 1.

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

98 (101)



11.3.1 Activation on boot/slot 0

If Require smart cards to activate system after boot has been chosen during installation, onevery system start/boot, the PKI Appliance will first require the successful activation of slot0 before it can continue with start up. Smart card and PIN have to be entered within onehour after system start.

99 (101)


12. AUDIBLE FEEDBACK Ver: 3.0.0

Chapter 12

Audible Feedback

For an improved feedback, the PrimeKey PKI Appliance has the functionality of issuing somestatus sound tunes in situations where we found it helpful in our own testing.

Following a list of the sounds that the machine might do:

• BIOS startup sound: The BIOS (Basic Input Output System, an archaic bootloader tothe x86-architecture) of the PKI Appliance does also try to give some status informationthrough a series of short high and low-pitched beeps very soon after switching on themachine.

• Booting Done: The PKI Appliance has an overall boot time of about 5 minutes beforeany configuration can take place, during which a boot progress is shown to the frontpanel display as well as the WebConf. The PKI Appliance announces the end of thisboot 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 chapter 5.1on page 15), the machine will acknowledge this with a 4-tone sound similar to an alarmsound; low-high-low-high. Usually, you should be able to hear this quittance whithin5 to 15 seconds after hitting the concealed button. Under certain circumstances, suchas if you press that button twice in a very short timespan of only a few seconds, it maytake up to several minutes for the system to detect this condition. You should not tryto reboot the system before having gotten any acknowledgement about the pressedFactory Reset button.

• PIN Pad Interaction: Ever since version 2.2.0 of the PKI Appliance, there is a smallsound to raise your attention to the PIN pad. For some operations, you have onlyabout 15 seconds to insert the correct smart card and enter the right PIN to it. ThePKI Appliance will also try to give you a hint on which smart card operation is requiredby a short message on the PKI Appliance physical front display. The message will bevisible only shortly though. During Wizard operations like installation, restoring of abackup or adding this PKI Appliance to an existing cluster, there will be more ampleexplanations in your browser. This sound is a short double; bee-beep.

100 (101)


12. AUDIBLE FEEDBACK Ver: 3.0.0

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

101 (101)

pki appliance online help€¦ · 1.releasenotes ver: 3.0.0 chapter1 releasenotes pki appliance...

Documents