PrimeKey PKI Appliance Online Help

PKI Appliance
Online Help
Public Key Infrastructure by PrimeKey
Ver: 3.4.0
2019-08-13
Copyright ©2019 PrimeKey Solutions
Published by PrimeKey Solutions AB
Lundagatan 16
171 63 Solna
Sweden
To report errors, please send a note to support@primekey.com
Notice of Rights
All rights reserved. No part of this book may be reproduced or transmitted in any form by any means,
electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of the
publisher. For more information on getting permission for reprints and excerpts, contact sales@primekey.com
Notice of Liability
The information in this book is distributed on an “As Is” basis without warranty. While every precaution has
been taken in the preparation of the book, neither the authors nor PrimeKey shall have any liability to any
person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by
the instructions contained in the book or by computer software and hardware products described in it.
Trademarks
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and PrimeKey was aware of a trademark claim,
the designations appear as requested by the owner of the trademark. All other product names and services
identified throughout this book are used in editorial fashion only and for the benefit of such companies with
no intention of infringement of the trademark. No such use, or the use of any trade name, is intended to
convey endorsement or other affiliation with this book.
Contents
I Preamble 1
1 Release Notes 2
2 Introduction 4
2.1 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1 Styling Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.2 Daily operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 PKI Appliance Overview 6

3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
II Appliance Installation 7
4 PKI Appliance Unboxing 8

4.1 Included in delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2 Opening the box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3.1 Front View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3.2 Back View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.4 Taking into Operation / Powering Up . . . . . . . . . . . . . . . . . . . . . 13
5 Initial Set-up 14
5.1 External Erase and Factory Reset . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 One Time Password and SSL Fingerprint . . . . . . . . . . . . . . . . . . . . 16
5.3 Changing the IP Address of the PKI Appliance . . . . . . . . . . . . . . . . . 17
5.4 Connecting to the PKI Appliance . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5 Logging in for the first time . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.6 Fresh Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.7 Network Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.8 Date and Time Settings (NTP) . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.9 Management CA Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.10 Security Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.10.1 Domain Master Secret . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.10.2 Appliance Security Level . . . . . . . . . . . . . . . . . . . . . . . . 26
5.10.3 PKCS#11 Slot Configuration . . . . . . . . . . . . . . . . . . . . . . 27
5.10.4 Audit Log Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.10.5 HSM FIPS Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.11 Confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.12 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.12.1 Get PKCS#12 key store . . . . . . . . . . . . . . . . . . . . . . . . 32
5.12.2 Using legacy browser enrollment . . . . . . . . . . . . . . . . . . . . 35
5.12.3 Get certificate from CSR . . . . . . . . . . . . . . . . . . . . . . . . 37
5.13 Finalize Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6 Restore from Backup 42

6.1 Restore Stand-Alone System from Backup . . . . . . . . . . . . . . . . . . . 42
7 Connect to cluster 44
III WebConf 45
8 WebConf 46
8.1 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
8.2 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
8.2.1 NTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.2.2 DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.2.2.1 Fully Qualified Domain Name (FQDN) . . . . . . . . . . . 48
8.3 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
8.3.1 TLS certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
8.3.1.1 Server side TLS certificates . . . . . . . . . . . . . . . . . . 48
8.3.1.2 Client side TLS certificates . . . . . . . . . . . . . . . . . . 49
8.3.1.3 Trust CA certificates for client authentication . . . . . . . . 49
8.3.2 PKI Appliance Management Accounts . . . . . . . . . . . . . . . . . 49
Use-Case: Create a new TLS server side certificate for Application Interface . 50
Use-Case: Upload a new trusted CA for TLS authentication and new super-
admin certificate for Management Interface . . . . . . . . . . . . . . 58
Use-Case: Configure a new trusted CA for TLS authentication and new su-
peradmin certificate for Application Interface . . . . . . . . . . . . . 62
8.4 HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.4.1 Changing HSM PKCS#11 slot authentication codes . . . . . . . . . 65
8.4.1.1 Switching from generated to manually entered authentica-
tion code . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
8.4.1.2 Changing a manually entered authentication code . . . . . . 65
8.4.1.3 Switching to auto-generated authentication code . . . . . . 65
8.4.2 Backup Key Share Smart Card Handling . . . . . . . . . . . . . . . . 67
8.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 . . 67
8.4.3 Download protected HSM export . . . . . . . . . . . . . . . . . . . . 67
8.4.4 Cluster Key Synchronization Packages . . . . . . . . . . . . . . . . . 67
8.5 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
8.6 Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
8.7 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
8.7.1 Syslog shipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
8.7.2 SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
8.8 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.8.1 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.8.2 Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.8.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
8.8.4 Platform Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
8.8.4.1 SSH public key . . . . . . . . . . . . . . . . . . . . . . . . 75
8.8.4.2 Password authentication . . . . . . . . . . . . . . . . . . . 75
8.8.5 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
IV Advanced 77
9 HA Setup 78
9.1 Scope of availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.1.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.1.2 Synchronization of key material . . . . . . . . . . . . . . . . . . . . . 78
9.1.2.1 Pre-cluster setup generation of keys . . . . . . . . . . . . . 78
9.1.2.2 Post-cluster setup generation of keys . . . . . . . . . . . . . 79
Use-Case: Synchronize key material . . . . . . . . . . . . . . . . . . . . . . 79
9.1.3 Network topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.1.4 Cluster traffic security considerations . . . . . . . . . . . . . . . . . . 80
9.2 Continuous service availability . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.3 Levels of availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.3.1 Stand alone instance . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.3.2 Hot stand-by with manual fail-over . . . . . . . . . . . . . . . . . . . 80
9.3.3 High availability with automatic fail-over . . . . . . . . . . . . . . . . 81
9.4 High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Use-Case: Setting up a 2 node cluster from scratch . . . . . . . . . . . . . . 81
Use-Case: Setting up a 3 node cluster from scratch . . . . . . . . . . . . . . 82
Use-Case: Extending a cluster from n to n+1 nodes . . . . . . . . . . . . . . 82
9.5 Backup, Restore and Update . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.5.1 Backing up a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.5.2 Restoring a cluster from backup . . . . . . . . . . . . . . . . . . . . 83
9.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 84
9.6 Controlled full cluster shutdown and startup . . . . . . . . . . . . . . . . . . 85
9.6.1 Shutting down the cluster in controlled manner . . . . . . . . . . . . 85
9.6.2 Starting a fully shutdown cluster . . . . . . . . . . . . . . . . . . . . 85
9.7 Operational Caution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Use-Case: Changing the IP Address of the Application Interface of a
node in a three node cluster . . . . . . . . . . . . . . . . . 86
Replacing a failed cluster node . . . . . . . . . . . . . . . . . . . . . . . . . 87
10 Smart Card Handling 88

10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
10.2 Smart Card Reader or PIN Pad . . . . . . . . . . . . . . . . . . . . . . . . . 88
10.3 Usage of Smart Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
10.3.1 Backup Key Share smart cards . . . . . . . . . . . . . . . . . . . . . 89
10.3.2 PKCS#11 slot activation user smart card . . . . . . . . . . . . . . . 90
10.4 Quorum (’2 out of 3’ or ’3 out of 5’) . . . . . . . . . . . . . . . . . . . . . . 90
10.5 Procedure (Installation, Example for ’2 out of 3’) . . . . . . . . . . . . . . . 91
10.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 . . . . 94
10.6.2 Change the PIN of the backup key share on a smart card . . . . . . . 95
10.6.3 Change the PIN of a PKCS#11 Slot User on a smart card . . . . . . 95
11 PKCS#11 Slot Smart Card Activation 96

11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
11.2 Installation/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
11.2.1 "Number of users required" . . . . . . . . . . . . . . . . . . . . . . . 97
11.2.2 "Number/copies of user smart cards" . . . . . . . . . . . . . . . . . . 97
11.2.3 "Require smart cards to activate system after boot" . . . . . . . . . . 97
11.2.4 Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
11.2.4.1 Example with default values . . . . . . . . . . . . . . . . . 98
11.2.4.2 Slots 0 and 1 . . . . . . . . . . . . . . . . . . . . . . . . . 98
11.3 Application/Activation of a slot . . . . . . . . . . . . . . . . . . . . . . . . . 98
11.3.1 Activation on boot/slot 0 . . . . . . . . . . . . . . . . . . . . . . . . 99
12 Audible Feedback 100
13 Appendix Documents 102

13.1 Technical Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
PKI Appliance
Online Help – Public Key Infrastructure by PrimeKey
Ver: 3.4.0
Part I
Preamble
1 (105)
PKI Appliance
1. RELEASE NOTES Ver: 3.4.0
Chapter 1
Release Notes
PKI Appliance 3.4.0 Release Notes
The PrimeKey Appliance team is proud to announce the 3.4.0 release. This
release brings major updates for EJBCA and SignServer. Besides of that, another
round of improvements under the hood of the PKI Appliance have been introduced.
Furthermore with this release we are introducing basic IPv6 connectivity,
services running on the Appliance can now be reached over IPv6.
New features:
* EJBCA Enterprise 7.2.1: Please check out the EJBCA release notes:
https://download.primekey.se/docs/EJBCA-Enterprise/7_2_1/
EJBCA_7.2.1_Release_Notes.html
* SignServer 5.1.0.Final: Find more information at
https://download.primekey.com/docs/SignServer-Enterprise/5.1.0.Final/
SignServer_5.1_Release_Notes.html
* IPv6 can be configured on the management and application interfaces through
WebConf. After that the WebConf, EJBCA and SignServer will available via
IPv6.
Please note that the following constraints apply to IPv6 connectivity:
* IPv6 connectivity is optional and disabled by default.
* Outgoing PeerConnectors cannot use IPv6.
* Cluster connections over IPv6 are not implemented at the moment.
* The initial installation of the Appliance has to be performed using IPv4,
IPv6 addresses cannot be configured using the front display.
* If SSH access is enabled and IPv6 is configured on the management
interface, SSH access via IPv6 is possible (even using link local
addressing).
* HTTP connections through link local addresses are blocked by the firewall.
2 (105)
PKI Appliance
1. RELEASE NOTES Ver: 3.4.0
Changes:
* After upgrading to 3.4.0 (or higher) it is not possible to downgrade to
versions lower than 3.4.0. If a downgrade is required, please contact
support.
* WebConf sessions are now tracked using a cookie, not using a URL parameter.
* Feedback for smart card operations (e.g. change PIN) have been improved.
Known Issues and Limitations:

* While smart card activated slots are supported with PKCS#11 R2, "FIPS
restrictions applied" mode is not.
* When using smart card activated slots with PKCS#11 R2, the maximum amount of
users is one. This is due to a bug which we plan to fix. If you need more
users, you can opt to install your Appliance with PKCS#11 R1 instead of R2.
* When installing updates on a PKI Appliance running 3.2.0, make sure to
unplug any USB sticks before performing the update.
* When a single node is disconnected from the cluster, the local EJBCA instance
will be temporarily unusable (EJBCA admin interface shows an error message).
The problem remediates itself within 1 hour. A restart of EJBCA fixes it
immediately, however if your installation uses smart card authentication,
PIN pad interactions will be required to activate slots again.
* When restoring large backups coming from EJBCA versions smaller than 6.6.0,
after the restore and reboot EJBCA will not be available for some time due
to the database schema change and the need to re-index. For a full database
of a Model M it takes about an hour to re-index the database. After this an
additional reboot is required.
* For cluster backups taken on versions 2.4 up to 2.8 - when restoring the
first backup onto 3.4.0 version the cluster configuration will be deleted and
it is needed to add the IP addresses of all the other nodes manually before
proceeding with the cluster setup.
* Version 3.4.0 does not support restoring backups of versions older than 2.4.0.
* The 2nd generation hardware version offers four ethernet ports, but only two
of them are usable at the moment.
Support for the disabled ethernet ports will be added in future versions.
* Due to a firmware limitation the PKI Appliance only becomes reachable when
both management and application ethernet ports are successfully connected to
a network.
* Ethernet ports might not establish a link if the network cables have been
connected after powering on the device.
* "FIPS restrictions applied" mode is currently not available on appliances of
the 2nd generation hardware version because it is not available on that HSM
generation. Operation in FIPS mode will be added in future releases.
3 (105)
PKI Appliance
2. INTRODUCTION Ver: 3.4.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 understanding
and implementing PKI as a product and service within the PKI Appliance.
2.1 Audience
This guide is intended for use by Information Technology (IT) professionals with an interest
in implementing the PKI products provided by PrimeKey in their environment using the
PKI Appliance. The guide is presented in a structured manner so that it begins with an
introduction to the subject and progressively moves into more deeper technical topics. This
allows 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 shared
interest 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, or
the configuration being applied. For example:
4 (105)
PKI Appliance
2. INTRODUCTION Ver: 3.4.0
i This is an informative message containing extra information.
• Warning messages are used to draw the attention to a critical or sensitive step that
has to be performed, or to critical piece of information that has to be provided. For
example:
! 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 step
by 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 are
outlined in. Do not jump back and forth between different exercises, unless
the instructions explicitly state so.
5 (105)
PKI Appliance
3. PKI APPLIANCE OVERVIEW Ver: 3.4.0
Chapter 3
PKI Appliance Overview
3.1 Description
EJBCA Enterprise Appliance is a PKI-in-a-box and combines the flexibility, reliability and
feature 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 of
built in CA, RA and VA functionality and a variety of interfaces like OCSP, CMP, SCEP and
WebServices, EJBCA Enterprise Appliance provides a unique turn-key PKI solution.
EJBCA Enterprise Appliance is based on an unified and controlled technology stack which
reduces technical risks for the entire PKI project and reduces patch management efforts
during operation. Simplified management and maintenance workflows lower the setup time
and operational costs and reduce the TCO.
High flexibility, performance, support for high-availability and load-balancing make the EJBCA
Enterprise 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 three
different product sizes, designated as S, M or L. Previous unlabeled versions are equivalent
to the M size. While the L version takes advantage of recently available bigger hard disks
to provide for more database space, the S version is a highly reduced version with smaller
database size and also a reduced speed HSM.
6 (105)
PKI Appliance
Ver: 3.4.0
Part II
Appliance Installation
7 (105)
PKI Appliance
4. PKI APPLIANCE UNBOXING Ver: 3.4.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 (105)
PKI Appliance
4.2 Opening the box

By opening the box you should find a PKI Appliance Test Report signed by PrimeKey
authorized 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 (105)
PKI Appliance
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 (105)
PKI Appliance
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 (105)
PKI Appliance
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 (105)
PKI Appliance
4.4 Taking into Operation / Powering Up

1. 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 (105)
PKI Appliance
5. INITIAL SET-UP Ver: 3.4.0
Chapter 5
Initial Set-up
The initial setup of the PKI Appliance transfers the device from the delivery state to a
production setup by configuring all components of the system. The initial setup routine
requires 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 to
your network. Any previously configured IP address or the default IP addresses could already
be 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 network
socket 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 the
Application Interface. It’s default IP address is 192.168.5.161.
• The right one of the two network ports is the Management Interface, which defaults
to 192.168.5.160.
14 (105)
PKI Appliance
5.1 External Erase and Factory Reset

A 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 Security
Module (HSM) or certificates in the CA database. Performing a Factory Reset is necessary
in 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 PKI
Appliance:
! The next step is a definite action. All sensitive data will immediately be
erased from the HSM. The only possibility to restore the data is from a
backup (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 Hardware
Security Module (HSM) with a hidden button (see figure 5.1). This is the button
for External Erase. Press that button for one second using a pen while the machine
is powered, switched on, finished booting and make sure you hear a confirmation
sound that should be played within 15 seconds (but might take up to ten minutes
under certain circumstances, e.g. if you slipped off the button and pressed it a second
time).
15 (105)
PKI Appliance
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 (audible
and PKI Appliance front display) might take longer.
2. If the machine acknowledged that you pressed the button either by the audible feedback
or by the message on the front panel display, you will have to reboot the PKI Appliance
to actually execute the Factory Reset by briefly pressing the power button on the front
panel and then confirming the reboot via the display buttons. The machine will reboot
and clear all configuration files. It should be clearly stated that a clean shutdown and
boot 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 information
like software version and the One Time Password. Seeing the One Time Password is
proof 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 Fingerprint

After powering up the system, the display will give you the information you need to access
the system through your web browser (see figure 5.2). The One Time Password (OTP) is
required to initially access the WebConf and will become invalid after the installation has
been successfully accomplished. Please take note of this OTP as it will be required for the
web 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 the
fingerprint of the TLS certificate used to secure the connection from your web browser to
the PKI Appliance WebConf (see figure 5.3). The WebConf will ask you to compare this
fingerprint with the fingerprint of the TLS certificate presented to you by the browser to
make sure that you are accessing the right machine.
16 (105)
PKI Appliance
Figure 5.3: Front Display showing the TLS Fingerprint
5.3 Changing the IP Address of the PKI Appliance

After a factory reset and also later during normal operation the display will show you the
IP address of the Management Interface of the PKI Appliance. After a factory reset, this
will 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 not
match 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 application
network address.
Pressing the "OK" button when the IP address is shown will allow you to change the IP
address (see figure 5.5). The IP address will be presented with leading zeroes. The cursor
will start at the first digit of the first byte of the IP address. You can abort this operation
at any time by pressing the x button.
17 (105)
PKI Appliance
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 confirm
the 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 to
10 seconds. After that time, it is safe to connect the first network cable to the Management
Interface (the right one, as seen from behind).
5.4 Connecting to the PKI Appliance

The next and last step of the initial configuration of the PKI Appliance is to run the web
based configurator. During this procedure all components of the system will be configured
according to the parameters you provide.
i The WebConf is designed and tested to work with Firefox 26.0+. Other
browsers like Chrome or Safari are working but are not officially supported
and you may observe minor incompatibilities. Internet Explorer is currently
not officially supported and depending on the version you might not be able
to finish the configuration process successfully.
1. Navigate your browser to the IP address of the Management Interface of the PKI
Appliance. A simple web page will instruct you to connect through TLS (see figure
5.6).
2. Follow that link and your browser will respond with a TLS warning because the servers
18 (105)
PKI Appliance
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. The
certificate will be regenerated during installation and the permanently stored certificate
would 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 (105)
PKI Appliance
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 the
fingerprint 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 (105)
PKI Appliance
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. The
fingerprint should correspond as much as was visible on the display (see figures
5.12 and 5.3).
21 (105)
PKI Appliance
Figure 5.12: Certificate Information
8. If the two fingerprints match, then you can be sure to be connected to the correct
machine. Click The fingerprints are the same as in 5.9.
22 (105)
PKI Appliance
5.5 Logging in for the first time

Now you will need the One Time Password (OTP) that is displayed on the front of the PKI
Appliance. This password changes every time the machine is started, until the system has
been installed. Click Login when you have entered the authentication code (see figure
5.13).
Figure 5.13: Entering the OTP
5.6 Fresh Installation

Anytime you use the OTP to log in to an un-provisioned PKI Appliance, you will be given
the 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 (see
figure 5.14)
5.7 Network Settings

You will be asked to configure the network settings of the PKI Appliance. All of this can be
corrected at a later point in time, if needed.
You might want to make up your mind about the network configuration beforehand: Of
the two physical interfaces, one is designed to be a Management Interface, through which
you can access the WebConf and the AdminGUI of EJBCA. The other interface is designed
23 (105)
PKI Appliance
Figure 5.14: Installation Choices
Figure 5.15: Network Settings
to be the Application Interface, through which the operational payload will be routed. It’s
perfectly fine to set up two separate networks if you want to separate those tasks. For the
time being, the Management Interface IP address has been configured at the front panel
display and is preset to have a network prefix of /24 (subnet mask 255.255.255.0). On the
application network however, you are free to chose the IP address, network prefix and
default gateway. You will also be asked to enter the designated hostnames, if you plan to
make the PKI Appliance available through DNS name resolution.
After the installation, you will be given the possibility to change the IP address of the
Management Interface.
To confirm the configuration and proceed to the next step, click on Next: Time (see
figure 5.15).
5.8 Date and Time Settings (NTP)

For many of the applications of a Public Key Infrastructure (PKI), it is very important to
have a correct date and time. You might consider using a Network Time Protocol (NTP)
24 (105)
PKI Appliance
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 CA

button.
! In case that you will use NTP this is the right time to do it! If you configure
it later and there is a difference between the NTP server and current system
time, the synchronization will not happen directly. It can take up to several
hours.
5.9 Management CA Settings

These are settings that should be carefully considered, because they cannot be altered after
the installation. You should take the time to think of some meaningful identifier to be added
to the Additional Subject Fields, as shown in the picture. The Additional Subject DN
will be reflected in the TLS certificates that are stored in your browser and in the name of
the backup files. If you plan on doing several test/demo installations, this is where you can
brand 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 the
PEM-encoded CA certificate. In case you need the Management CA to be created now, you
will be asked to configure it:
25 (105)
PKI Appliance
• 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 Settings

This is another page of immutable settings. The security section helps you to configure all
security 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 used
to derive a symmetric key which is used to encrypt backup archives created by the PKI
Appliance. It is your choice whether you specify it manually or whether you prefer to have
it generated by the system. If generated, you will be given the possibility to print the highly
secure Domain Master Secret. In both cases it is very important to write down the secret
and 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 (105)
PKI Appliance
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 key
material. As an example, if 2 out of 3 Backup key share cards is chosen, you will be
asked 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 the
smart cards for every backup operation. Should it be necessary to restore the PKI Appliance
from a backup you will need to provide 2 of the initially created 3 smart cards to import
the Backup Key into the HSM to decrypt and import the backup data. Likewise for the
3 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, that
encrypts 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#11
slots of the HSM. Automatically generated authentication codes are stored on the system
so that applications can run unattended while still offering a decent security. Manually
generated authentication codes allow for applications that should only be available after
manual activation. Even higher security can be achieved by enabling smart card activation
on slots. (Minimum PKI Appliance Version 2.2.0, please refer to chapter 11 on page 96
for more information about smart card activated slots. Please notice that the smart card
27 (105)
PKI Appliance
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 security
operations to the clustered storage. Default is enabled. Audit log records consume database
disk space. For a typical installation, the creation of a single certificate issues approximately
10 audit log records. For all typical installations, the audit log database table will be at least
double the size of the other database tables. If you disable the storage of the signed audit
log, you will still be able to receive and store the audit log records externally, over syslog
shipping (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 some
known unsecure mechanisms and algorithms will be disallowed, but also new or modern
mechanisms 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 cards
when FIPS restrictions have been requested.
To continue, click on Next: Summary to see an overview of all configuration options

done so far.
5.11 Confirm
It is highly recommended that you double check everything on this summary page. You
might even want to print this page. If you spot an error, you can easily navigate backwards
with 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 sure
that the PIN pad included in the delivery is connected to one of the USB
ports in the front of the PKI Appliance and you have a sufficient amount
of 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 smart
card 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 . The
installation will take a few minutes (see figure 5.19).
28 (105)
PKI Appliance
Figure 5.19: Confirm installation choices
5.12 Installation
The 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 configuration
of the HSM, the database and the applications, like EJBCA.
i In the case you have decided to use smart cards, please mind the output
from the PIN pad during the installation process which will request you to
insert the smart cards and enter the PIN. You will be asked to enter the
smart cards in two steps using the k out of n schema:
1. Key generation: Insert all (n) smart cards you have chosen to use,
always providing the PIN.
2. Key import (to HSM): Insert again the amount of smart cards that
is needed to restore the Backup Key (k)
29 (105)
PKI Appliance
At the end of the installation, you will find the following screen (see figure 5.20).
Figure 5.20: End of Installation
30 (105)
PKI Appliance
To manage the PKI Appliance you need to get a client side SuperAdmin TLS certificate
issued by the Management CA that can be used from your browser. This certificate will be
your 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 the
WebConf 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 is
generated on the PKI Appliance and manually imported into the browser.
2. Using legacy browser enrollment: The SuperAdmin key pair is generated in the
browser and the SuperAdmin certificate is automatically imported into the browser.
3. Get certificate from CSR: The SuperAdmin key pair is generated outside the browser
context and the SuperAdmin certificate will be created from a Certificate Signing
Request.
The certificate and corresponding key pair is a vital component of your system. You
need to protect and backup it with the same care that you apply to the backups and data
of the PKI Appliance itself: Anyone in possession of this certificate can manipulate your
installation. Without this certificate, you have no access whatsoever to the PKI Appliance.
31 (105)
PKI Appliance
5.12.1 Get PKCS#12 key store

A PKCS#12 key store is a format for storing both private keys and certificates protected
by a password. By selecting this option you will be able to download such key store that
contains both a SuperAdmin certificate and the corresponding key pair. The .p12-file then
needs to be manually imported into the browser using the PKCS#12 protection password
shown to you.
Start by pressing Confirm enrollment option when "Get PKCS#12 key store" is
selected (see figure 5.21).
Figure 5.21: Get PKCS#12 key store - step 1
32 (105)
PKI Appliance
Next, press Get SuperAdmin PKCS#12 key store (see figure 5.22). A new tab
will open.
33 (105)
PKI Appliance
In the newly opened tab, select a Key Specification matching your organization’s security
requirements 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), make
a note of the PKCS#12 protection password. Use your browser’s proprietary mechanism for
importing the .p12-file using the PKCS#12 protection password before proceeding.
Once the P12 has been successfully imported, click Finalize installation .
34 (105)
PKI Appliance
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 will
open.
35 (105)
PKI Appliance
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 in
your 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 (105)
PKI Appliance
5.12.3 Get certificate from CSR

Enrolling the initial SuperAdmin certificate using a Certificate Signing Request/PKCS#10
should only be used when you can’t use any of the other methods. Creation of the CSR and
installing the resulting certificate in such a way that it is usable for client TLS authentication
is outside the scope of this document.
Start by pressing Confirm enrollment option when "Get certificate from CSR" is
selected (see figure 5.27).
Figure 5.27: Get certificate from CSR - step 1
37 (105)
PKI Appliance
Make a note of Enrollment username and Enrollment code. Click that link labeled
Go to SuperAdmin enrollment page (see figure 5.28). A new tab will open.
38 (105)
PKI Appliance
In the newly opened tab, enter Enrollment username and Enrollment code from the
previous page. Select or paste the certificate signing request you want to use to issue the
initial SuperAdmin certificate. Click OK . (See figure 5.29.)
39 (105)
PKI Appliance
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 (105)
PKI Appliance
5.13 Finalize Installation

As the very latest step of our installation, you have to finalize the installation by clicking
the button Finalize installation . Finalizing takes some 30 seconds. The browser will
reload the page and ask you to confirm that your (or which) client side certificate shall be
used for authentication (see figure 5.31). If you use different Additional Subject DN for
the different installations, the matching certificate should be pre-selected. (Should you ever
need to delete certificates from your browser, please keep in mind that you need to restart
your 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 only
get persisted after approximately one hour (or when the machine is properly shut
down/rebooted), leading to lost configuration in case of a power outage right
after installation. This might be relevant if you are running a test installation on
your desk or in a test lab.
41 (105)
PKI Appliance
6. RESTORE FROM BACKUP Ver: 3.4.0
Chapter 6
Restore from Backup
A backup file can only be restored to a fresh and unprovisioned machine. You will need the
backup 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 depending
on your chosen Appliance Security Level (please refer to the chapter 5.10.1 on page 26 and
the following chapter for more information about the Domain Master Secret, the Appliance
Security Level and the smart cards).
i Relating to the S-M-L product size variations, please be aware that you
can 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 a
hardware 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 still
operational, 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/High
Availability Setup and for very detailed information on how to proceed with either bringing
back a PKI Appliance into your cluster or - as a last resort - restore a cluster node from
backup (9.5.2 on page 83).
i With version 2.4.0 and newer, the PKI Appliance will not be able to restore
from backup data created on a PKI Appliance with versions older than 2.2.0.
6.1 Restore Stand-Alone System from Backup

These are the things you should make sure to have at hand:
• Domain Master Secret
42 (105)
PKI Appliance
6. RESTORE FROM BACKUP Ver: 3.4.0
• Unless the PKI Appliance has been configured with a low Appliance Security Level (for
demo and testing), you will need the PIN pad, the persons with the smart cards and
they 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 about
5 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 One
Time Password.
6. In the installation menu chose „restore from backup“ and enter the connections details
of 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 your
backup. The restore procedure might request you to connect a PIN pad and provide
the backup protection smart cards in case your initial system had been configured to
use those.
8. After finishing the restore procedure you will be asked to reboot the system. This is
the moment where you can safely connect the second network cable to the Application
Interface if you have not yet. Keep in mind that after the system has been rebooted it
will have the restored configuration including IP address, SuperAdmin certificates etc.
43 (105)
PKI Appliance
7. CONNECT TO CLUSTER Ver: 3.4.0
Chapter 7
Connect to cluster
A fresh and unprovisioned PKI Appliance can be added to a cluster or can be connected
to another standalone PKI Appliance to start your cluster. You have to start the procedure
either on any node that is already part of the cluster or on the standalone machine that
is already installed respectively. When starting the procedure on that node, you’ll be given
instructions to download a so called cluster bundle. This cluster bundle will then be needed
when going through this part of the wizard. You will also need the Domain Master Secret
that you specified when installing the first machine of your environment and a copy of the
Backup key share smart cards that were created when installing the first machine of your
environment (please refer to the chapter 5.10.1 on page 26 and the following chapter for
more information about the Domain Master Secret, the Appliance Security Level and the
smart cards).
i Relating to the S-M-L product size variations, please be aware that you
should not mix product size variants in a cluster. Since a filled hard disk
makes the database stop working, the smallest node of your setup will stop
working (and thus reduce redundancy) first.
It is recommended to read the chapter 9 (page 78) in this document if you are changing
a standalone setup to a multi-node cluster or extending an existing cluster with additional
nodes.
After logging in to the PKI Appliance using the One Time Password from the front panel
display and chosing to connect to a cluster, you will be guided through a short wizard.
44 (105)
PKI Appliance
Ver: 3.4.0
Part III
WebConf
45 (105)
PKI Appliance
8. WEBCONF Ver: 3.4.0
Chapter 8
WebConf
The WebConf is the web based user interface for managing the base functionality of the PKI
Appliance. The functions are sorted under different tabs (described below) and by selecting
a tab, contextual help for the selected functionality is shown to the right.
8.1 Status
This 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 of
your PKI Appliance.
8.2 Network
In this view you can configure networking for the PKI Appliance (see figure 8.2). The
PKI Appliance has two network interfaces. One for administration (where you are currently
46 (105)
PKI Appliance
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 is
shown as both Netmask and Network for convenience. Gateway is the default gateway for
traffic to hosts that are not included in any of the interfaces’ network address ranges. Only
IPv4 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 the
specified 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 trusted
time 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 cluster
operation. Please note: Enabling NTP by adding NTP servers will not change/correct the
time instantly. The PKI Appliance clock will be migrated to the time of the NTP source
very gently to not disturb operations. Depending on how far off the clock is, a reboot of the
PKI 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 hostname
instead of IP address. This should only point to a trusted name servers to avoid that the
PKI Appliance communicates with malicious hosts. DNS servers are accessed through the
Application Interface. An example of an untrusted DNS server (OpenDNS) you can use for
testing is: 208.67.222.222
47 (105)
PKI Appliance
8.2.2.1 Fully Qualified Domain Name (FQDN)

The Fully Qualified Domain Name is used by the SMTP email gateway as origin and should
match the DNS record for the Application Interface IP address.
8.3 Access
In 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 connect
and the client must trust the issuer of the certificate.
The following values are normally set in an TLS certificate (assuming that the host is
hostname.example.com and the IP is always 10.10.10.10):
Subject Distinguisher Name:

CN=hostname.example.com
...
Subject Alternative Names:
DNSName=hostname.example.com
IPAddress=10.10.10.10
...
Key Usage: Digital Signature, Key Encipherment
Extended Key Usage: TLS server authentication (OID 1.3.6.1.5.5.7.3.1)
48 (105)
PKI Appliance
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 the
certificate. Note that some implementations (e.g. Java) require a matching IP address
or 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 and
overridden 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 PKI
Appliance. 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 certificate
is trusted, the PKI Appliance or application firmware will try to match the information in
the 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. If
you want to use client TLS certificates from an external CA, you need to replace the trusted
certificate. To avoid locking yourself out of the PKI Appliance, first add the appropriate
matching rules under PKI Appliance Management Accounts, so that you can reconnect
and continue to administer the PKI Appliance after the trusted certificate is replaced.
To configure a new trusted certificate, simply upload the CA certificate (in PEM format)
and confirm the change. After a short delay, you will be able to reconnect using the client
TLS certificate issued by this trusted CA.
8.3.2 PKI Appliance Management Accounts

PKI Appliance management accounts are matching rules that will be processed when a user
tries to log in. Two types of rules are currently implemented:
49 (105)
PKI Appliance
• Client TLS certificates authentication.
• Shared secret (password) authentication.
The match value in case of client TLS certificates is the entire Subject Distinguisher
Name (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 strongly
discourage the use of shared secret authentication and this option might disappear in future
releases 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 using
WebConf.
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 (105)
PKI Appliance
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 with
the 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 (105)
PKI Appliance
Figure 8.6: EJBCA CN value for TLS
2. In Server side SSL/TLS configuration and under Application Interface press

Generate 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 (105)
PKI Appliance
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 (105)
PKI Appliance
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 (105)
PKI Appliance
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 (105)
PKI Appliance
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... for
Next 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 be
active (see figure 8.17).
56 (105)
PKI Appliance
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 application
pages. We will be asked to confirm the new connection (see figure 8.18). Once this is
done, we can see the new certificate as shown on fig. 8.4.
Figure 8.18: EJBCA login
57 (105)
PKI Appliance
22. When we verify the certificate that is used for the TLS connection, we can see that it
is 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 certificate
will 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 will
install 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 (105)
PKI Appliance
Figure 8.20: WebConf Access
2. Check the Subject DN of the certificate using openssl
Run as <user>
\$ openssl x509 -in MyUsername.pem -subject

subject= /C=MyCountry/O=MyCompany/SN=MyLastName/GN=MyFirstName \
/serialNumber=G824734/CN=MyFirstName MyLastName/UID=R4501ZHE
-----BEGIN CERTIFICATE-----
MIID3zCCAsegAwIBAgIIdzHlq8R4dnAwDQYJKoZIhvcNAQELBQAwPTETMBEGA1UE
AwwKTXlDdXN0b21DQTESMBAGA1UECgwJTXlDb21wYW55MRIwEAYDVQQGEwlNeUNv
dW50cnkwHhcNMTUwMTEzMDkxOTIzWhcNMTYwMTEzMDkyNjAzWjCBoDESMBAGA1UE
BhMJTXlDb3VudHJ5MRIwEAYDVQQKDAlNeUNvbXBhbnkxEzARBgNVBAQMCk15TGFz
dE5hbWUxFDASBgNVBCoMC015Rmlyc3ROYW1lMRAwDgYDVQQFEwdHODI0NzM0MR8w
HQYDVQQDDBZNeUZpcnN0TmFtZSBNeUxhc3ROYW1lMRgwFgYKCZImiZPyLGQBAQwI
UjQ1MDFaSEUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5Dr5dRsio
TvihzdeQQ1cCbDDM/KqN729+wuNcfO3btlMhXMRMrSdBz2gZgfIDfbNjWnmOmkF5
...
qqh6BtM4h2SpLlzcpELvOA6ySUEsfvaVpK4I7ebLFDFhtTM=
-----END CERTIFICATE-----
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 (105)
PKI Appliance
tificate and press Add .
! EJBCA is using org.bouncycastle.asn1.x500.style.BCStyle which interprets

SN as serialNumber. We inherit this in org.cesecore.util.CeSecoreNameStyle
(Legacy reasons). That means that the user has to make sure that he will
replace SN with SURNAME otherwise there is the danger of getting locked
out!
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.. for
the MyCustomCA-chain.pem file (see fig. 8.22).
! It has to be the whole chain from the issuer CA of the client certificate up
to the trusted RootCA.
60 (105)
PKI Appliance
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 the
Management Interface (see fig. 8.24).
61 (105)
PKI Appliance
Figure 8.24: WebConf New configuration for Management Interface is in use
Use-Case: Configure a new trusted CA for TLS authentication and new

superadmin certificate for Application Interface
In this exercise we will change the client certificate and update the trusted CA for Application
Interface using WebConf. First we will configure EJBCA and then WebConf .
The new superuser certificate has to be issued from the same CA (MyTrustedSubCA signed
by MyTrustedRootCA) that we will install for TLS authentication. First we have to provide
the information about the certificate (MyClientAuthenticationCertificate.pem) that will be
used as superuser.
1. Open the EJBCA admin web and navigate to Certification Authorities tab and use
Import CA certificate... (see fig. 8.25) to upload all CA certificates that belong to
the new trust chain. In our paradigm it is MyTrustedRootCA and MyTrustedSubCA.
62 (105)
PKI Appliance
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 (105)
PKI Appliance
3. Check the Subject DN of the client certificate which will be used to authenticate using
openssl
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 HSM
The Hardware Security Module (HSM) configuration allows you to change the authentication
codes 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 (105)
PKI Appliance
(for slot activation), download a full (protected) backup of the HSM’s key material or handle
HSM 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 authentication
codes. 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 the
administrator, administrators or m out of n administrators in conjunction.
Pros: Key material is not necessarily compromised in the case of lost physical access of the
box.
Cons: After a reboot, the PKCS#11 slot must be manually activated using the 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 the
user/administrator. When switching to a generated authentication code, EJBCA is re-
configured to automatically activate the slot on startup.
65 (105)
PKI Appliance
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 code
cannot be disclosed by administrators.
Cons: Possible to extract given physical access to the machine (theft of the PKI Appliance
could not rule out that the key material of the slot could not be freely accessed).
Figure 8.32: Slot authentication code change from manual to generated
66 (105)
PKI Appliance
8.4.2 Backup Key Share Smart Card Handling

These options are only available if you initialized the PKI Appliance using smart cards for
backup protection (see ’Appliance Security Level’ on page 26). Before using any of these
functions, 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 accessible
from 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 to
create a second set of 2 out of 3 cards for your disaster recovery site, for example. You
should create a backup set of the Backup Key share smart cards. Please keep in mind that
the Backup Key share smart cards should never be kept close to the backup of the PKI
Appliance
Since each card is unique, this function cannot be used to recover lost cards in card set.
However, if for whatever reason you need a 2 out of 2 scenario, this function allows you to
copy the data form the second smart card to the third smart card, effectively overwriting the
Backup 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 should
absolutely be done with each of the Backup Key Share smart cards. This is the easiest
possibility to prevent a mixup or accidental overwriting of the contents of a smart card. This
function can also be used if the card is being assigned to another person of the company.
This function can also be used on a smart card that comes originally from another PKI
Appliance.
There is also a similar functionality offered to change the PIN of a PKCS#11 Slot User
on a smart card, given that you have choosen to additionally secure your PKCS#11 slots
with 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 is
protected 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 changes
to the other nodes of your cluster environment.
If you create a new key in the HSM through EJBCA (e.g. creating a new CA), the
knowledge about its existence will synchronize through the database, but the key itself will
67 (105)
PKI Appliance
not synchronize automatically. Hence, you will have to manually distribute this new key data
by downloading a Key Synchronization Package on the Node where you created the new
CA and uploading it to each of the other nodes. The applications (EJBCA, SignServer) will
automatically be restarted, so that the key material can be used. See also Chapter 9 on page
79 for a more detailed description of the workflow.
8.5 Backup
Backups are entire snapshots of the system at a specific point in time. This will guarantee
that 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 a

factory reset and use the initial wizard. During the restore procedure you
will be prompted for the Domain Master Secret that was set during the
installation of the system (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 to
verify that the location is readable. If this works, continue with taking a manual backup to
ensure that the location is writable as well.
Taking a manual backup

Click Backup now to start a background backup process. Revisit the Backup tab later
to see that the backup has finished. A backup on an "empty" or freshly installed system is
usually done within minutes.
68 (105)
PKI Appliance
Deleting backup
! Reload the list of backups and press the Delete button for the backup
you want to remove.
Automated backup schedule
i Backups can be automated to run once per day, once per week or once
per month. Taking a backup will put some load on the system, so it is
recommended to pick a time where you expect little usage. Be sure to save
your settings.
69 (105)
PKI Appliance
8.6 Cluster
This view gives you an overview of the cluster or rather this nodes’ view of it. You can also
configure 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 to
extend your system to a cluster with multiple nodes.
8.7 Monitoring
In 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 Appliance
should be shipped to. The syslog contains the syslog of all internal systems as well as the
EJBCA audit log. The syslog will be shipped by UDP in unencrypted, unsigned traffic.
70 (105)
PKI Appliance
8.7.2 SNMP
You can activate snmp access to the PKI Appliance by checking this button. All snmp
requests are combined in the "public" community. Now the PKI Appliance will answer to the
two standard MIBS SNMPv2-MIB and HOST-RESOURCES-MIB. Additionaly the following
parameters can be accessed with the following OIDs:
OID
Example Value Value
.1.3.6.1.4.1.22408.1.1.2.1.2.118.109.1
Status 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.1
Temperature of the CPU 27
.1.3.6.1.4.1.22408.1.1.2.1.4.118.100.98.49.1
Database usage in % 2
.1.3.6.1.4.1.22408.1.1.2.1.4.118.100.98.50.1
1 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.1
rpm of cpu fan 1025
.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.50.1
rpm of system fan 1 1126
.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.51.1
.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.52.1
.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.53.1
0 if cpu fan ok, 1 otherwise 0
.1.3.6.1.4.1.22408.1.1.2.1.4.102.97.110.54.1
0 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.1
Load 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.1
Load 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.1
.1.3.6.1.4.1.22408.1.1.2.1.5.108.111.97.100.52.1
.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.49.1
Status of RAID, 0 if clean or active, 1 otherwise 0
71 (105)
PKI Appliance
.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.50.1
Status of RAID as string clean
.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.51.1
Devices in RAID Total Devices : 2
.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.52.1
Devices in RAID as int 2
.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.53.1
Devices active in RAID Raid Devices : 2
.1.3.6.1.4.1.22408.1.1.2.1.5.114.97.105.100.54.1
Devices 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.1
Version 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.1
Local node ID 1
.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.50.1
Db cluster size 3
.1.3.6.1.4.1.22408.1.1.2.1.8.99.108.117.115.116.101.114.51.1
Currently 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.1
Local 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.1
Local 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.1
Last transaction ID 208
.1.3.6.1.4.1.22408.1.1.2.1.8.104.101.97.108.116.104.101.49.1
EJBCA 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.1
EJBCA 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.1
Signserver 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.1
Signserver healthcheck returns 0 for "ALLOK", 1 otherwise 0
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.49.1
Status of HSM as string STATUS_is_OPER
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.50.1
Enum of Status of HSM 0
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.51.1
Status of HSM, 0 if operational, 1 otherwise 0
72 (105)
PKI Appliance
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.52.1
Battery voltage of HSM 3.100 V
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.53.1
Battery state, 0 if ok, 1 otherwise (eg. low voltage) 0
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.55.1
Battery voltage of external HSM battery 3.272 V
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.56.1
Battery state, 0 if ok or absent, 1 otherwise (eg. low voltage) 0
.1.3.6.1.4.1.22408.1.1.2.2.4.104.115.109.54.1
Serial Number of HSM CS445661
.1.3.6.1.4.1.22408.1.1.2.1.6.109.97.105.110.116.49.1
Maintenance State as int, 0 if operational, 1 if offline or 2 if 0
maintenance
.1.3.6.1.4.1.22408.1.1.2.1.6.109.97.105.110.116.50.1
Maintenance State as string Operational
Alternatively all OIDs can be reached by the following three snmpwalk commands (replace
the ip address with the one of your system):
# for the standard group

snmpwalk -v2c -On -c public 192.168.5.162
# for the system group
snmpwalk -v2c -On -c public 192.168.5.162 .1.3.6.1.4.1.22408.1.1.2.1
# for the HSM group
snmpwalk -v2c -On -c public 192.168.5.162 .1.3.6.1.4.1.22408.1.1.2.2
8.8 Platform
In this view you can see the applications running on the PKI Appliance, update the firmware
and perform basic troubleshooting.
8.8.1 Applications
This gives you an overview of the applications that are installed on your platform, along with
their 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 (105)
PKI Appliance
Figure 8.36: WebConf Platform page
about Clustering/High Availability Setup and 9.5.3 (page 84) for very detailed information
on how to update a cluster.
Starting with version 2.2.0, the PKI Appliance firmware is to be updated separately from
the applications installed on the platform of the PKI Appliance. You are supposed to upgrade
both the firmware and the application, starting with the firmware.
Versions older than 2.2.0 cannot be updated to anything newer through this WebConf
function. Please contact PrimeKey Support or your local PrimeKey Partner to obtain help
with 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 both
operations. It is recommended that you first update the PKI Appliance firmware, then update
the COS applications.
To update, select the protocol and the parameters related to the selected protocol. Please
notice that currently only NFS is supported. Enter the IP-address of the NFS server in the
Source Host field. If you have DNS configured and activated (see chapter 8.2.2, page 47
for details) the hostname can be used. Enter the export path of the NFS server in the
Source Path field. It is possible to apply a filter to either only show the firmware update
field or the application update files. Click the Search now button if any update is found
it will be displayed in a list. If you are not in the directory of the update files use the
Change directory button to traverse to the correct directory.
Update Firmware
Select the desired firmware update file by pressing the Install Firmware button next to
the 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 (105)
PKI Appliance
Appliance will stay fully operational. The updated firmware will not be used until the system
is rebooted.
Update Application
To update a COS application select the desired update file by pressing the Install Application
button next to the 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 Appliance will be set into maintenance and the application will be not
available. 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 PKI
Appliance state including a list of reasons for maintenance and the functionality to set the
PKI 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 configured
for access anymore. This implies that you will have to set up your way of authentication if
you need access the platform. Please be aware that your SSH client will still ask you for a
password (and thus make it look like there is *some* password set up) if there is no cleartext
password defined. Defining either SSH public key or root password for SSH access will only
be 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 from
ssh.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 local
console access.
75 (105)
PKI Appliance
8.8.5 Support
The Support section provides access to already created ’Support Packages’ and the ability
to create new ’Support Packages’ manually. In addition an e-mail address is provided if you
need to get in contact with professional support for the PKI Appliance.
76 (105)
PKI Appliance
Ver: 3.4.0
Part IV
Advanced
77 (105)
PKI Appliance
9. HA SETUP Ver: 3.4.0
Chapter 9
HA Setup
9.1 Scope of availability

For the PKI Appliance the availability is defined as being able to keep the service running with
full data integrity for the applications running on the PKI Appliance that uses the internal
SQL database.
9.1.1 How it works

The cluster implementation used on the PKI Appliance uses regular network connectivity
over the Application Interface for all cluster communication. This means that cluster nodes
don’t have to be placed physically close to each other as long as they have good network
connectivity.
However, this also means that a node cannot distinguish between the failure of another
node and broken network connectivity to the other node. To avoid the situation where
the cluster nodes operate independently and get diverging data sets (a so called split brain
situation), the cluster nodes take a vote and will cease to operate unless they are part of the
majority of connected nodes. This ensures that there is only one data set that is allowed to
be updated at the time. In the case of a temporary network failure, disconnected nodes can
easily synchronize their data to the majority’s data set and continue to operate.
9.1.2 Synchronization of key material

Key material stored in the HSM is not automatically synchronized after the cluster has been
set 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 configuration
for the additional nodes. This way, all additional cluster nodes will be provisioned with the
78 (105)
PKI Appliance
complete key material on installation and no additional manual key synchronization will be
necessary.
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 cluster
has been setup, you need to manually synchronize the key material.
Note that applications that are connected to the shared database may malfunction if
they try to use references to keys that are not yet synchronized. For example, if a Certificate
Authority in EJBCA is renewed with new key generation, other cluster nodes shortly after
the renewal will try to use the new key. This will fail since the key generation was local to
the node where it was performed.
Use-Case: Synchronize key material

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 the
package.
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 generate
the 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 least
one other node.
The network connection is done via the GRE protocol (IP protocol number 47, see
https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers). Since GRE is an
IP protocol, it is not based on either TCP or UDP and has no concept of ports. It is an
IP protocol by itself. That means that it can not simply be made available with a port
forwarding behind a NAT (Network Address Translation). A fully transparent VPN solution
will be required if the cluster is supposed to be installed over different locations.
If you do have network equipment that is able to encapsulate the protocol, you might
still run into the issue of network address complications. This is easiest worked around
by setting up the systems in a simpler network configuration (e.g. same site) and later
shipment/reconfiguration.
79 (105)
PKI Appliance
A cluster node will never forward traffic between two other nodes to avoid networking
loops. Compared to using the spanning tree protocol (STP), this means that a broken
network connection between two nodes will not trigger any downtime of other connections.
If you prefer the dynamic loop prevention behaviour, you could add managed switches in
front of the Application Interfaces of the PKI Appliances. Please note that if the network
topology change prevents network traffic between the nodes for too long, your cluster nodes
might stop operation and require manual interaction. Rapid Spanning Tree Protocol (RSTP)
might be an interesting alternative to STP in this case.
9.1.4 Cluster traffic security considerations

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

To ensure that service clients always connect to an operational node in the cluster, an external
load-balancer should be used for automatic fail-over and/or load distribution.
In the case a custom application is being developed for consumption of the services
provided by the PKI Appliances’ external interfaces, this could also be handled by making
the custom application connect to any of the nodes that is found to be operational.
If lower availability and manual interaction is acceptable in case of a node failure, this
could also be solved by redirecting a DNS name to the service.
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 a
new PKI Appliance needs to be reinstalled from a backup. All data between the time of the
latest backup and the failure will be lost. If a cold stand-by (spare) PKI Appliance is not
available, the time of delivery of a new box needs to be taken into account when calculating
the acceptable downtime.
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 higher
quorum vote than the second node.
In the case the second node fails, the first node will continue operating but the second
node will be set into maintenance. In the case the first node fails, the second node will cease
to operate and will be set into maintenance. To bring back the second node into service it
requires manual interaction via the PKI Appliance administrative interface (WebConf).
80 (105)
PKI Appliance
To avoid data loss, the manual interaction is required and the second node should only
be Forced into Active if the first node really is dead and will be replaced.
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 will
still be able to form a cluster through a majority quorum vote and continue to operate. If
the PKI Appliance that has failed is still switched on it will be set into maintenance.
To ensure that quorum votes never result in a tie, all nodes are assigned unique quorum
vote weights according to their assigned node number (W eight = 128 − N odeN umber).
In a setup where an even number of nodes N are distributed equally over two sites, the
site that is intended to remain Active if connectivity between the sites fails should have a
larger sum of quorum vote weights than that of the other site. Since cluster nodes with lower
node 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 node
from backup.
2. If possible, generate all keys in the HSM that will be used during the installations
life-time to avoid manual key synchronization later.
3. Go to the Cluster subtab Configuration on the initial node in the PKI Appliance
WebConf and add a connection to where the next node’s Application Interface will be.
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. Start
the installation procedure.
8. After installation completes, you should be able to manage the new node using the
same credentials as the first one.
If the first node has been used for a while before the second node was connected, you
might need to wait until the data is fully synchronized, even after the cluster connection has
completed. When the Local node state in the WebConf’s Status tab shows Active, the
node is ready for use.
81 (105)
PKI Appliance
Use-Case: Setting up a 3 node cluster from scratch

1. Make a fresh install according to the normal installation procedure or restore a node
from backup.
2. If possible, generate all keys in the HSM that will be used during the installations
life-time to avoid manual key synchronization later.
3. Go to the Cluster subtab Configuration on the initial node in the PKI Appliance
WebConf and add the two connections to where the next nodes’ Application Interface
will be.
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 this
point, 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, you
might need to wait until the data is fully synchronized, even after the cluster connection has
completed. When the Local node state in the WebConf’s Status tab shows Active, a node
is ready for use.
Use-Case: Extending a cluster from n to n+1 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 Interface
will be.
2. From the same subtab on one of the nodes, download the setup bundle for the new
node (n+1).
3. Factory reset the new node (n+1) and connect to the web based installer
82 (105)
PKI Appliance
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 the
installation procedure.
6. After installation completes, you should be able to manage the new node (n+1) using
the same credentials as the previous node(s).
When the Local node state in the WebConf’s Status tab shows Active, the new node is
ready for use.
9.5 Backup, Restore and Update

In the domain of High Availability/Clustering, the topics of backup, restore and update have
to be handled differently as compared to stand alone instances of the PKI Appliance to not
disrupt operation.
9.5.1 Backing up a cluster

Although that you have set up a High Availability Setup to prevent any outages, you should
always take full-out scenario into consideration. In this case, and only in this case, you will
have to recover your cluster from a backup. From operational perspective, it might make
sense to decide to take backups only from node 3 (which is designed to be at a disaster
recovery site off-location) to reduce load and network traffic on the nodes at the main site.
If you can afford, we recommend to set up a automated backup schedule on all of your
nodes to make sure to be able to recover everything, out of every situation, even if perhaps
a failure takes a long time to be discovered.
Generally 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 from
node 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-out
scenario. If at least one node remains operational, the cluster should always be reestablished
from the last good node.
To recover as much of you data as possible, start by identifying the last good backup you
have available from an Active node by analysing the outage. For example, if the connection
to a disaster recovery site went down long before a backup was made there, you might be
better off with an older backup from the primary site after such outage.
Once you have identified the best possible backup from a previously Active node N,
restore the backup to the PKI Appliance designated to be node N and then reconnect the
other nodes to this node.
Please refer to chapter 6 (on page 42) for a description on how to restore a backup to a
PKI Appliance.
83 (105)
PKI Appliance
After reboot, the WebConf will be reachable and operational, but the database will refuse
to start up in this situation, hence the applications will not yet be operational. The button
Force into Active that the WebConf offers should be used in this scenario to force the
cluster 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 PKI
Appliance in a cluster should always be scheduled with care as to not accidentally degrade
cluster performance. It is a common mistake to ease up on the operational caution when it
is known that some technical measures are in place to take care of outages and thus give
away any safety margins. In a cluster, software update should be applied on a single node at
a time. Only if the node you are currently working on is completely done with the update
and confirmed to be back up and running should you proceed to updating the next node.
Starting with version 2.2.0, the PKI Appliance firmware is to be updated separately from
the applications installed on the platform of the PKI Appliance. You are supposed to upgrade
both 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 due
to major architectural changes. Please contact PrimeKey Support or your local PrimeKey
partner for support.
For procedures on how to update a cluster on PKI Appliance version 2.3.0 to an even
newer version, please refer to the even newer documentation delivered with the new software
version.
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 proceed
with the following steps:
1. Before starting any configuration changes on a cluster node, you should assert that the
node has been running fine up to now. This is the only way to know for sure whether
you actually broke anything if the procedure does not succeed as expected.
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 load
balancing frontend), so that:
• no other operator does any maintenance on any other node while we deliberately
reduce redundancy on the cluster,
• nobody relies on the availability of this node during maintenance downtime,
• and no alarm is raised if this node gets unavailable.
4. Start the software update procedure on this node by updating the PKI Appliance
firmware first, then updating the COS applications. This should generally be the same
procedure as described in 8.8.2: Install firmware, reboot, install application.
84 (105)
PKI Appliance
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 in
good shape, i.e. that all of the cluster nodes of your cluster confirm that your cluster
is back up and running with redundancy.
7. Announce this cluster node to be operational back again or whatever you need to undo
from step 3.
8. Continue with updating your cluster by applying the same steps on the next cluster
node, restarting at step 1.
9.6 Controlled full cluster shutdown and startup

This section describes how to do a controlled shutdown of the whole cluster and get back
to 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 the
highest node number and wait until the node is fully shutdown before proceeding with the
next one. This ensures that the quorum is kept as long as possible and in the end node 1 is
the most up to date node.
9.6.2 Starting a fully shutdown cluster

After a controlled shutdown as described in 9.6.1, the cluster nodes should automatically
become Active starting with the most up to date node after startup.
If the cluster is unable to automatically become Active, the administrator needs to manu-
ally bootrap the cluster from the node with the most up to date data set. The administrator
can identify the node that had an Active database status last before the shutdown by 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 nodes
should 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 becomes
Active.
3. If manual intervention is needed, select the node with the highest Last Transaction ID
and use Force into Active on this node (and only this node).
4. Wait until all N nodes are fully started and database status is Active on each node.
85 (105)
PKI Appliance
9.7 Operational Caution

The cluster will now continuously respond to requests, synchronize the data, and evaluate
the health of the cluster to ensure availability on one hand, but also data integrity on the
other hand. As described earlier, a node will rather stop working than to risk a split brain
situation. 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 be
taken. A planned network reconfiguration could be mistaken to be an emergency by the
cluster, for example.
Maintenance operations on the cluster such as rebooting, updating, network reconfigu-
ration, ... should be restricted to only one node at a time, with ample time for the node to
reconnect and synchronize after the task is completed. Before you proceed to the next node,
make sure that your cluster is back to full health.
Use-Case: Changing the IP Address of the Application Interface of a node in a three

node 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 configuration
steps to bring back the node into play:
1. Before starting any configuration changes on a cluster node, it is good practice to

assert that the node has been running fine up to now. This is the only way to know
for sure whether you actually broke anything if the procedure does not succeed as
expected.
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 the
cluster 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 of
the other cluster nodes.
6. Wait for the cluster node to appear offline/not connected in the cluster connections
table, the IP address should now be in an editable input field.
7. On every of the other cluster nodes, correct the application IP address of the cluster
node in the cluster table.
8. Confirm the operation by hitting Apply . It could be that you have to wait a couple
of seconds before you are allowed to click that button.
86 (105)
PKI Appliance
9. After the cluster reconfiguration has finished, all cluster nodes should be connected to
all of the other cluster nodes.
10. When everything works as expected, you should not forget to bring back the node into
the load balancer.
Replacing a failed cluster node

To replace a failed cluster node, follow the same procedure as you would for adding the
cluster node for the first time. See chapter 9.4 Use-Case: Extending a cluster from n to n+1
nodes on page 82 for more detailed information. Restoring the node from a backup will not
work because the database content in the backup file will be outdated.
87 (105)
PKI Appliance
10. SMART CARD HANDLING Ver: 3.4.0
Chapter 10
Smart Card Handling
10.1 Introduction
Smart cards are, essentially, Hardware Security Modules (HSM). They might also be called
’chip cards’ or ’integrated circuit cards’. SIM cards in cellular mobile phones are also smart
cards. The smart cards that come with the PKI Appliance are preprogrammed cards with the
TCOS operating system (TeleSec Chipcard Operating System) and are, as can easily be seen,
branded by the manufacturer of the HSM that we incorporate in the PKI Appliance. Smart
cards can store some amount of information, organized in sets of so called ’slots’. The data
sets can be configured to be protected with a Personal Identification Number (PIN) or not.
Also, the slots can have different PINs. This principle of different data across different slots
is the 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 Pad

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

With 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 different
functions operate on different slots. These different slots have separate PINs. They are all
preset to the default PIN of ’123456’ when delivered. In theory, one smart card can be used
for both functions, but the PINs for both functions/slots need to be changed independently.
We generally discourage to use one smart card for both functions since this is bound to lead
to confusion.
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 "Master
Backup Key" (MBK) and we make use of that, entirely transparent. When you install the PKI
Appliance and opt for any of the available smart card options in the Appliance Security Level,
such a Backup Key is first generated (in memory), then written to the smart cards, then read
back in, from the smart cards into the HSM. From this point on, every bit of information
that is downloaded from the HSM with administrative functions (such as "create backup")
89 (105)
PKI Appliance
is encrypted with this Backup Key. This is why you need to have these smart cards at hand
if you want to restore a backup: The Backup Key that encrypts the backup files needs to
be uploaded to the HSM first. If you configure 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 Backup
Key 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 been
overwritten by mistake. This is a good reason to change the PIN of a smart card
right after a successful installation to prevent any mixup or mistake. Another
good practice might be to create copies of backup key share smart cards to be
stored in a safe place. Also it might be worth noting that the Backup Key cannot
be changed after installation; this would invalidate all existing backup files.
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 activate
PKCS#11 slots. There is no quorum for user credentials on smart cards. Please refer to
chapter 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 for
PKCS#11 slot activation can not be copied one-to-one, unlike the backup key
share 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 one
smart card with the according PIN. But splitting a Backup Key across multiple smart cards
would also have disadvantages: It would decrease usability or ease of handling since you
would always need the presence of every single card owner in case of a disaster recovery
(and you know how these kind of things always happen in the worst of moments, think of
summertime, holidays and thunderstorms). And it would effectively decrease reliability since
a single lost, broken or otherwise deactivated smart card would immediately ruin all your
emergency precautions. To get the best of both worlds, the Backup Key is distributed across
the smart cards using a method called "Shamir’s Secret Sharing" in reference to its inventor,
Adi Shamir, a worldwide well known and accepted cryptographer (another reference to his
name can be found in the letters of the RSA algorithm). This system is also sometimes
called a Quorum or a "k out of n" or "m out of n".
In the application of this method, a cryptographic symmetric key is split into n number
of shares so that every combination of k number of shares is sufficient to reconstruct the
complete key.
90 (105)
PKI Appliance
In the case of the PrimeKey PKI Appliance, the software generates a 32 bytes long AES
key (symmetric cryptography) and offers the choices of ’2 out of 3’ and ’3 out of 5’. While
the latter obviously represents a higher applied security, please bear in mind that it implies
that you strictly need to have three of those 5 smart card owners available for a disaster
recovery, even if service availability agreements force you to bring the system back to life at
5 ’o clock on a sunday morning. This is often called the "Person Is There Always" scenario.
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 "just
try this out" since you cannot do this from your workstation or desk. Remember: The PIN
Pad needs to be connected to one of the four USB ports of the PKI Appliance itself. This
is why we would like to walk you through this step in every detail possible. Furthermore,
the timeout on the smart card operations does not really allow for careful reading of the
documentation in the middle of the process. Any timeout will not be indicated as such on
the PIN Pad display, the display will just turn blank and the information about the timeout
will be shown on the WebConf
For a ’2 out of 3’ scenario, 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 SCT
cyberJack e-com
This text will vanish with any PIN Pad operation, therefore, if you have multiple
PIN Pad operations in one session, the display screen might be entirely blank if
you start this operation.
• Key generation: At first, a new Backup Key needs to be generated and the Backup
Key Shares need to be written to the smart cards.
2. Shortly after starting the installation (as in 5.12 on page 29), the PIN Pad will
read:
Write New Key
press OK/Cancel
This is only the notification that we are now going to write a new key / key
shares to the smart cards. Any former Backup Key Share on these smart cards
will be overwritten. A smart card cannot store more than one Backup Key Share.
A smart card cannot be used to save two different Backup Key Shares for two
different PKI Appliance environment. Every node in a cluster uses the same
91 (105)
PKI Appliance
Backup Key, thus any set of Backup Key Share smart cards will work with every
node in a cluster.
3. As soon as you acknowledge this by hitting the green OK button, procedure will
continue with:
Insert 1. card
press 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 fresh
an unused smart card delivered with the PKI Appliance is ’123456’ until it has
been manually changed (see chapter 8.4.2.2 on page 67). The fact that you have
to enter the PIN only once is an indication that you are not defining the PIN
(setting the PIN or changing the PIN), but only authenticating (proving you are
the legitimate owner of the smart card). You can restart the entry of the PIN
by pressing the yellow Clear button or you can abort the entire operation with
the red Cancel button. If you confirm with the green OK button, there will be a
short screen indicating some ongoing operation. Do not remove the smart card
while this operation is lasting.
5. After the short screen indicating the ongoing operation, you’ll see this:
Insert 2. card
press OK/Cancel
This is the instruction that the second smart card of the set should be inserted.
A smart card should not be removed from the PIN Pad before the display clearly
shows that it is asking for the next smart card.
6. First, remove the smart card that is in the PIN Pad rand insert the second of the
smart cards and continue by pressing the green OK button
Enter PIN
******
This is where you enter the PIN of the second smart card.
92 (105)
PKI Appliance
Insert 3. card
press OK/Cancel
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 onto
the smart cards, the Backup Key needs to be loaded into the HSM, therefore the
Backup Key needs to be reconstructed by reading it from the smart cards. Since
the Backup Key is based on the quorum of ’3 out of 5’ or in this example ’2 out
of 3’ (see 10.4), the complete Backup Key can be reconstructed by reading only
2 smart cards (or 3 smart cards in the scenario of ’3 out of 5’). In consequence,
it does not matter in which order the cards are read.
Read New Key
press OK/Cancel
This is the notification that we are now going to read the new key / key shares
from the smart cards.
10. If you acknowledge this by hitting the green OK button, procedure will continue
with:
Insert 1. card
press OK/Cancel
This is the instruction that the first of the smart cards should be inserted. When
reading back in the key in the ’2 out of 3’ scenario, any two Backup Key Share
smart cards will do (as long as you insert two different smart cards rather than
inserting the same smart card twice), although the display will ask for the ’1.’ and
’2.’. In consequence, the first smart card to read the key can be the third smart
card the was written to. So, for convenience, you can leave the smart card in the
device and enter its appropriate PIN.
11. You should proceed by pressing the green OK button again. The next message
of the display will be:
Enter PIN
******
93 (105)
PKI Appliance
This is where you enter the PIN. If you confirm with the green OK button, there
will be a short screen indicating some ongoing operation.
Insert 2. card
press OK/Cancel
This is the instruction that the second smart card of the set should be inserted,
which again can be any other of the smart cards.
13. Insert the next smart card and continue by pressing the green OK button
Enter PIN
******
This is where you enter the PIN. After confirming this with the green OK button,
this operation is completed.
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 Pad
display, only in WebConf)
• entering a wrong PIN for one smart card three times in a row (the smart card will
be blocked)
• failing to enter two different smart cards for the "Key Reading" part of the sequence
(3 cards in case of the ’3 out of 5’ scenario)
• accidental unplugging of the PIN 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 to
be in an inconsistent state. You will have to do a full Factory Reset as described
in chapter 5.1 on page 15 and restart the installation process.
10.6 WebConf Smart Card Handling Tools

As you can see in chapter 8.4.2 on page 67, the WebConf offers a couple of tools to help
handling 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 (105)
PKI Appliance
recovery site, for example. You should create a backup set of the Backup Key share smart
cards. Please keep in mind that the Backup Key share smart cards should never be kept
close to the backup of the PKI Appliance. Since each card is unique, this function cannot
be used to recover lost cards in card set. However, if for whatever reason you need a ’2 out
of 2’ scenario, this function allows you to copy the data form the second smart card to the
third 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 should
absolutely be done with each of the Backup Key Share smart cards. This is the easiest
possibility to prevent a mixup or accidental overwriting of the contents of a smart card. This
function can also be used if the card is being assigned to another person of the company.
This function can also be used on a smart card that comes originally from another PKI
Appliance.
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 should
absolutely be done with each of the PKCS#11 slot activation user smart cards. This is the
easiest possibility to prevent a mixup or accidental overwriting of the contents of a smart
card. This function can also be used if the card is being assigned to another person of the
company. This function can also be used on a smart card that comes originally from another
PKI Appliance. See chapter 11 on page 96 for more information about PKCS#11 slot smart
card activation.
95 (105)
PKI Appliance
11. PKCS#11 SLOT SMART CARD ACTIVATION Ver: 3.4.0
Chapter 11
PKCS#11 Slot Smart Card

Activation
11.1 Introduction
All 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. The
keys required by the PKI Appliance and your infrastructure are organized in so-called slots,
commonly used with the cryptographic API PKCS#11. To operate on these keys, these
slots must be activated with some authentication code. Depending on your requirements
for availability, usability and security, you can select whether those authentication codes
should be stored on the PKI Appliance or not. This can be chosen per slot. Slots with
stored authentication codes can be auto-activated for immediate availability. The generated
and automatically stored authentication codes are of very high quality. This choice can be
changed even later during the operation of the PKI Appliance.
If even manually entered authentication codes do not meet the security requirements, there
is an option for a two-factor authorization: It is possible to additionally require an activation
with smart cards for one or more slots. This choice has to be done during installation.
11.2 Installation/Configuration
PKCS#11 slot smart card activation can be enabled per slot but only during the installation
of the PKI Appliance. To do so, untick (Automatically generated) Authentication
Code for the slot you want to give more security. You will then be given the possibility to tick
Smart card activated for that slot. Then you will see some more options available for the
general slot smart card activation settings. You still have to define an authentication code
per slot. You can either chose something trivial like 1234 since you are relying to external
secrets anyways, or you can make it even more secure by defining a real secret authentication
code which will be required additionally upon activation.
96 (105)
PKI Appliance
11.2.1 "Number of users required"

It can be chosen how many smart cards should be required to activate a slot. This way a
very 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 different
user credentials will be generated and written to 5 different smart cards, all of which need
to be present when activating a slot. The default setting of the PKI Appliance is to create
only one user 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 not
be copied from card to card. A lost, broken or blocked smart card can not
be 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 user
credential.
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 slot
0, which contains the key that is used to sign the audit log. Since EJBCA produces an audit
log entry for every single action, it needs access to slot 0 for every single action, including
start-up. This effectively means that EJBCA will not be reachable after a system startup
unless slot 0 has been successfully activated by smart card.
11.2.4 Procedure
For every slot activation user that has been chosen, the following procedure will first run
during the installation:
• The user credentials are generated in memory.
• For every copy that has been chosen, the user credentials will be written to a smart
card. It is required to enter the PIN (default PIN on delivery: 123456 ) and acknowledge
with "OK".
• The user credentials (only public key) are read into the HSM, it will only be required
to press the OK button.
After the installation, it is strongly advised to change the PINs of the smart cards through
the WebConf.
97 (105)
PKI Appliance
11.2.4.1 Example with default values

The procedure with an PKI Appliance Security Level of "2 out of 3" and slot smart card
activation on slot 7 with default values 1 user and 2 copies will look like this:
• Backup key shares 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

– User credential being written to one card (with PIN and OK)
– User credential being written to one card (with PIN and OK)
– 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 (Management
CA) Require smart cards to activate system after boot the installation procedure will be
extended by more PIN pad operations since the installer needs access to these slots to create
the keys needed for operation, audit log signature and Management CA respectively.
These extensions will be activation procedures as described in the next section.
11.3 Application/Activation of a slot

Whenever the application will attempt a "Login" to the slot (as when activating a Crypto-
Token in EJBCA), the PKI Appliance will automatically and immediately request the smart
card(s) to be inserted to the PIN pad. This can be noticed by a small audible alert (bee-
beep). The PKI Appliance physical front display will give a short hint at which slot is being
activated and user card is required to be inserted.
! The user cards will always be required in ascending order, always starting
with User 1.
Whenever some PKCS#11 slot activation with smart card goes wrong, the internal PKI
Appliance mechanism will restart all applications, which in turn requires that all slots need
to be activated again.
98 (105)
PKI Appliance
11.3.1 Activation on boot/slot 0

If Require smart cards to activate system after boot has been chosen during installation, on
every system start/boot, the PKI Appliance will first require the successful activation of slot
0 before it can continue with start up. Smart card and PIN have to be entered within one
hour after system start.
99 (105)
PKI Appliance
12. AUDIBLE FEEDBACK Ver: 3.4.0
Chapter 12
Audible Feedback
For an improved feedback, the PrimeKey PKI Appliance has the functionality of issuing some
status sound tunes in situations where we found it helpful in our own testing.
Following a list of the sounds that the machine might do:
• BIOS startup sound: The BIOS (Basic Input Output System, an archaic bootloader to
the x86-architecture) of the PKI Appliance does also try to give some status information
through a series of short high and low-pitched beeps very soon after switching on the
machine.
• Booting Done: The PKI Appliance has an overall boot time of about 5 minutes before
any configuration can take place, during which a boot progress is shown to the front
panel display as well as the WebConf. The PKI Appliance announces the end of this
boot period with a 3-tone sound similar to a short fanfare; ta-ta-taaa.
• Factory Reset: If the concealed Factory Reset button has been pressed (see chapter 5.1
on page 15), the machine will acknowledge this with a 4-tone sound similar to an alarm
sound; low-high-low-high. Usually, you should be able to hear this quittance whithin
5 to 15 seconds after hitting the concealed button. Under certain circumstances, such
as if you press that button twice in a very short timespan of only a few seconds, it may
take up to several minutes for the system to detect this condition. You should not try
to reboot the system before having gotten any acknowledgement about the pressed
Factory Reset button.
• PIN Pad Interaction: Ever since version 2.2.0 of the PKI Appliance, there is a small
sound to raise your attention to the PIN pad. For some operations, you have only
about 15 seconds to insert the correct smart card and enter the right PIN to it. The
PKI Appliance will also try to give you a hint on which smart card operation is required
by a short message on the PKI Appliance physical front display. The message will be
visible only shortly though. During Wizard operations like installation, restoring of a
backup or adding this PKI Appliance to an existing cluster, there will be more ample
explanations in your browser. This sound is a short double; bee-beep.
100 (105)
PKI Appliance
12. AUDIBLE FEEDBACK Ver: 3.4.0
• The machine has more audible feedback for internal uses of manufacturing and testing.
101 (105)
PKI Appliance
13. APPENDIX DOCUMENTS Ver: 3.4.0
Chapter 13
Appendix Documents
102 (105)
PKI Appliance
by PrimeKey
PKI Appliance
Model specification
With PrimeKey PKI Appliance you will get your PKI

projects done in time and on budget. PrimeKey’s
purpose-built PKI Appliance is the all- in-one solution for
a Public Key Infrastructure with built-in high availability
and reliability functionality. It provides a ready to use
EJBCA Enterprise with an integrated Hardware Security
Module (HSM) and a comprehensive management
interface.
PKI Appliance PKI Appliance
Software stack
Small
PrimeKey EJBCA
Medium
PrimeKey EJBCA
Large
PrimeKey EJBCA
Validation
Authority
PrimeKey EJBCA
Model Specification
Enterprise & Prime Enterprise & Prime Enterprise & Prime Enterprise & Prime
LFS* LFS* LFS* LFS*
Protocols & API’s
OCSP - - - 
SCEP -   -
CMP -   -
PrimeKey PKI Appliance is the easiest and most efficient way to EST -   -
WebServices API -
deploy and manage an enterprise PKI system. With a pre-packaged
  
REST API -   -
solution you are quickly up and running without the hassles of CLI    
Key Features
complex installation and integration procedures. Certificate Capacity <100 8M 20 M N/A
Secure & Automated Backup    
Mechanism
PrimeKey PKI Appliance offers a complete feature set and support for CMP v2 RFC 4210, SCEP, EST. Certificate 2 Factor Authentication    
needed to operate a full blown, highly available PKI. It is data is synchronized in real-time between CA and VA, FIPS 140/2 Level 3 validated HSM    
based on PrimeKey EJBCA Enterprise, with easy to use and between CA and RA instances via dedicated secure inside
management functions, high-performance hardware and channels called Peer Systems. Dedicated Mng & App Interfaces    
a built-in FIPS 140-2 Level 3 certified Hardware Security Clustering -   
Module (HSM). Large
Dual power supply    
The largest model of PKI Appliance includes all
SNMP, Syslog, Audit Log    
Depending on the requirements PrimeKey offers four functionality you find it the two previous models and an
Accessories
different PKI appliance models to address different extended capacity when it comes to certificate storage.
SmartCards 10 10 10 -
needs. PKI Appliance Large supports 20 million certificates.
PinPad Reader - 1 1 -
External Battery adapter  Optional Optional Optional
Small Validation Authority (VA)
Performance (opp/sec) Cert. issuance Responses
PKI Appliance Small includes EJBCA Enterprise with a The PKI Appliance VA model includes support for
Audit log on/off Audit log off
core library for Certificate Authority (CA) functionality CRL distribution and OCSP. Revocation information
RSA 1024 SHA 1 with RSA 5/30 28/101 28/101 450
for an unlimited number of CAs. EJBCA Enterprise is synchronized in real-time between CA and VA via
RSA 2048 SHA 256 with RSA 1/10 26/79 26/79 80
is certified with Common Criteria EAL 4+. The Small dedicated secure channels called Peer Connectors.
RSA 4096 SHA 512 with RSA 0,5/0,5 9/11 9/11 11
model supports operating multiple, independent PKI Utilizing dedicated VA Appliances can massively
EC secp256r1 SHA256withECDSA 5/43 25/98 25/98 490
hierarchies within one installation and a Registration increases security of an infrastructure as it is best
Authority (RA) with role based access control and placed in the DMZ and isolated from the CA Appliances
approval mechanisms. PKI Appliance Small is ideal for allowing only one way secure connections from CA to VA
Technical specifications
an offline Root CA in a PKI deployment. instances.
Form Factor 2U
Dimensions 88,4 x 430 x 633mm (3 1/2 x 17 x 25 inch)
Medium
Weight 12,5kg (27.5lb)
In addition to the functionality of PKI Appliance
Operational Environment +10°C - +50°C (+50°F - 122°F)
Small, the Medium model also includes highly flexible
Storage Environment -10°C +55°C (+14°F - 131°F)
integration interfaces based on web services, REST API
Safety Agency Approval CE, RoHS, FCC
Power Supply Dual 500W
AC Power 110/240V, 50/60Hz
Power Cosumption typ. 80W, max 135W
For testing purposes, it is possible to run CA, VA and RA on one singe instance of the appliance
* = PrimeKey Linux From Scratch
PKI APPLIANCE — PKI BY PRIMEK E Y PKI APPLIANCE — PKI BY PRIMEK E Y

About PrimeKey
PrimeKey Solutions AB is one of the world’s
leading companies for PKI solutions. PrimeKey
has developed successful solutions, such as
EJBCA Enterprise, SignServer Enterprise and
PrimeKey PKI Appliance. PrimeKey is a pioneer
in open source security software that provides
businesses and organisations around the world
with the ability to implement security solutions
such as e-ID, e-Passports, authentication,
digital signatures, unified digital identities and
validation. PrimeKey has its head office in
Stockholm, Sweden.
© PrimeKey Solutions AB
All rights reserved
sales@primekey.com
+46 873 561 01
www.primekey.com

PrimeKey PKI Appliance Online Help

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PrimeKey PKI Appliance Online Help

Uploaded by

Copyright:

Available Formats

PKI Appliance

Public Key Infrastructure by PrimeKey

To report errors, please send a note to support@primekey.com

3 PKI Appliance Overview 6

4 PKI Appliance Unboxing 8

6 Restore from Backup 42

10 Smart Card Handling 88

11 PKCS#11 Slot Smart Card Activation 96

12 Audible Feedback 100

13 Appendix Documents 102

PKI Appliance 3.4.0 Release Notes

Known Issues and Limitations:

2.1.1 Styling Conventions

i This is an informative message containing extra information.

! This is a warning message.

2.1.2 Daily operations

Use-Case: Install PKI Appliance

PKI Appliance Overview

PKI Appliance Unboxing

4.1 Included in delivery

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

• Optionally: One PIN pad and ten smart cards.

• A Quality Assurance Test Report

4.2 Opening the box

Figure 4.1: Opening the box.

Figure 4.2: Components inside the box.

Figure 4.3: PIN pad with smart cards.

Figure 4.4: PKI Appliance packed in the cardboard box.

Figure 4.5: Front View of the PKI Appliance

4. SSD Slot 2, empty

5. SSD Slot 3, empty

6. Cooling vents. Do not obstruct!

9. Front USB ports, suitable for PIN pad connection

10. Safeguarded reset button

11. Power button (ATX)

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

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

4.4 Taking into Operation / Powering Up

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

• Performing a Factory Reset

• Running the WebConf and completing the setup

5.1 External Erase and Factory Reset

• you lose access to the PKI Appliance,

• you need to reinstall the PKI Appliance,

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

Figure 5.1: Placement of the External Erase button.

i As soon as OTP is displayed, the PKI Appliance is in Factory Reset state,

5.2 One Time Password and SSL Fingerprint

Figure 5.2: Front Display showing the One Time Password