PKI Appliance User Guide - PrimeKey...- MariaDB to 10.2.13 and Galera provider 25.3.23 - OpenSSL...

PKI Appliance

User Guide

Public Key Infrastructure by PrimeKey

Ver: 3.0.0

2018-04-30

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

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

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

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

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

Contents

I Preamble 1

1 Release Notes 2

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

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

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

II Appliance Administration 7

4 WebConf 84.1 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.2 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.2.1 NTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2.2 DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.2.2.1 Fully Qualified Domain Name (FQDN) . . . . . . . . . . . 104.3 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.3.1 TLS certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.3.1.1 Server side TLS certificates . . . . . . . . . . . . . . . . . . 104.3.1.2 Client side TLS certificates . . . . . . . . . . . . . . . . . . 114.3.1.3 Trust CA certificates for client authentication . . . . . . . . 11

4.3.2 PKI Appliance Management Accounts . . . . . . . . . . . . . . . . . 114.4 HSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

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

tion code . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.4.1.2 Changing a manually entered authentication code . . . . . . 134.4.1.3 Switching to auto-generated authentication code . . . . . . 13

4.4.2 Backup Key Share Smart Card Handling . . . . . . . . . . . . . . . . 144.4.2.1 Make a one-to-one copy of a smart card . . . . . . . . . . . 14

4.4.2.2 Change the PIN of the backup key share on a smart card . . 144.4.3 Download protected HSM export . . . . . . . . . . . . . . . . . . . . 154.4.4 Cluster Key Synchronization Packages . . . . . . . . . . . . . . . . . 15

4.5 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.6 Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.7 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.7.1 Syslog shipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.8 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4.8.1 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.8.2 Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.8.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.8.4 Platform Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.8.4.1 SSH public key . . . . . . . . . . . . . . . . . . . . . . . . 204.8.4.2 Password authentication . . . . . . . . . . . . . . . . . . . 20

4.8.5 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

III Appliance in High Availability Setup 21

5 HA Setup 225.1 Scope of availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.1.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225.1.2 Synchronization of key material . . . . . . . . . . . . . . . . . . . . . 22

5.1.2.1 Pre-cluster setup generation of keys . . . . . . . . . . . . . 225.1.2.2 Post-cluster setup generation of keys . . . . . . . . . . . . . 23

Use-Case: Synchronize key material . . . . . . . . . . . . . . . . . . . . . . 235.1.3 Network topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.1.4 Cluster traffic security considerations . . . . . . . . . . . . . . . . . . 24

5.2 Continuous service availability . . . . . . . . . . . . . . . . . . . . . . . . . . 245.3 Levels of availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.3.1 Stand alone instance . . . . . . . . . . . . . . . . . . . . . . . . . . 245.3.2 Hot stand-by with manual fail-over . . . . . . . . . . . . . . . . . . . 245.3.3 High availability with automatic fail-over . . . . . . . . . . . . . . . . 25

5.4 High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Use-Case: Setting up a 2 node cluster from scratch . . . . . . . . . . . . . . 25Use-Case: Setting up a 3 node cluster from scratch . . . . . . . . . . . . . . 26Use-Case: Extending a cluster from n to n+1 nodes . . . . . . . . . . . . . . 26

5.5 Backup, Restore and Update . . . . . . . . . . . . . . . . . . . . . . . . . . 275.5.1 Backing up a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.5.2 Restoring a cluster from backup . . . . . . . . . . . . . . . . . . . . 275.5.3 Updating the software (firmware/applications) on a cluster . . . . . . 28

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

5.6.1 Shutting down the cluster in controlled manner . . . . . . . . . . . . 29

5.6.2 Starting a fully shutdown cluster . . . . . . . . . . . . . . . . . . . . 295.7 Operational Caution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Use-Case: Changing the IP Address of the Application Interface of anode in a three node cluster . . . . . . . . . . . . . . . . . 30

Replacing a failed cluster node . . . . . . . . . . . . . . . . . . . . . . . . . 31

IV Enterprise Java Beans Certification Authority (EJBCA) 32

6 Introduction to EJBCA 336.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.2 Complementary Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.2.1 SignServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.2.2 Single Point of Contact (SPOC) . . . . . . . . . . . . . . . . . . . . 356.2.3 Hardware Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.2.4 Card Management System . . . . . . . . . . . . . . . . . . . . . . . 35

V EJBCA Administration and Public Web 37

7 EJBCA Interface 387.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

8 Public Web Interface 398.1 Enroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398.2 Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408.3 Retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408.4 Inspect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408.5 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9 Administration Web Interface 429.0.1 Publish queue status . . . . . . . . . . . . . . . . . . . . . . . . . . 429.0.2 CA Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.1 Managing Crypto Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439.1.1 New Crypto Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . 439.1.2 View or Edit a Crypto Token . . . . . . . . . . . . . . . . . . . . . . 439.1.3 Activation and deactivation . . . . . . . . . . . . . . . . . . . . . . . 439.1.4 Key management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

9.2 CA Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449.2.1 Creating CAs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459.2.2 CA fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Type of CA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Signing Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Crypto Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Extended Services Key Specification . . . . . . . . . . . . . . . . . . 45Key sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Key sequence format . . . . . . . . . . . . . . . . . . . . . . . . . . 46Enforce unique public keys . . . . . . . . . . . . . . . . . . . . . . . 47Enforce unique DN . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Enforce unique Subject DN serialNumber . . . . . . . . . . . . . . . 47Use Certificate Request History . . . . . . . . . . . . . . . . . . . . . 47Use User Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Use Certificate Storage . . . . . . . . . . . . . . . . . . . . . . . . . 48Certificate Policy Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Name Constrains . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49CRL Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Finish User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

9.2.3 Creating a SubCA signed by an external CA . . . . . . . . . . . . . . 519.2.4 Signing an External CA . . . . . . . . . . . . . . . . . . . . . . . . . 529.2.5 Renewing a SubCA signed by an external CA . . . . . . . . . . . . . 529.2.6 Requesting a cross or bridge certificate . . . . . . . . . . . . . . . . . 539.2.7 Signing a roll-over certificate (NewWithOld) . . . . . . . . . . . . . . 53

9.3 Certificate Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539.3.1 Create a Certificate Profile for SSL servers . . . . . . . . . . . . . . . 539.3.2 Import/Export Certificate Profiles . . . . . . . . . . . . . . . . . . . 54

Export Certificate Profiles . . . . . . . . . . . . . . . . . . . . . . . . 54Import Certificate Profiles . . . . . . . . . . . . . . . . . . . . . . . . 54

9.3.3 Certificate Profile fields . . . . . . . . . . . . . . . . . . . . . . . . . 55Validity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Allow extension override . . . . . . . . . . . . . . . . . . . . . . . . . 56Allow subject DN override . . . . . . . . . . . . . . . . . . . . . . . 56Allow certificate serial number override . . . . . . . . . . . . . . . . . 56Allow back dated revocation . . . . . . . . . . . . . . . . . . . . . . 56Path Length Constraints . . . . . . . . . . . . . . . . . . . . . . . . 57Issuer Alternative Name . . . . . . . . . . . . . . . . . . . . . . . . . 57CRL Distribution Points . . . . . . . . . . . . . . . . . . . . . . . . . 57CRL Issuer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Freshest CRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59OCSP Service Locator . . . . . . . . . . . . . . . . . . . . . . . . . . 59CA Issuer URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Use LDAP DN order . . . . . . . . . . . . . . . . . . . . . . . . . . 59Extended Key Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 60Document Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Private Key Usage Period . . . . . . . . . . . . . . . . . . . . . . . . 60Certificate Transparency . . . . . . . . . . . . . . . . . . . . . . . . . 60Cardnumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Subset of Subject DN . . . . . . . . . . . . . . . . . . . . . . . . . . 61

9.4 RA Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629.5 End Entity profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

9.5.1 Create an End Entity Profile for SSL servers . . . . . . . . . . . . . . 629.5.2 Import/Export End Entity Profiles . . . . . . . . . . . . . . . . . . . 63

Export End Entity Profiles . . . . . . . . . . . . . . . . . . . . . . . 63Import End Entity Profiles . . . . . . . . . . . . . . . . . . . . . . . 63

9.5.3 Import/End Entity Profile fields . . . . . . . . . . . . . . . . . . . . . 64Password Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Subject DN Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Subject Alternative Names . . . . . . . . . . . . . . . . . . . . . . . 65Certificate Validity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Revocation reason to set after certificate issuance . . . . . . . . . . . 67Reverse Subject DN Alt Name Checks . . . . . . . . . . . . . . . . . 67Maximum number of failed login attempts . . . . . . . . . . . . . . . 67Custom certificate extension data . . . . . . . . . . . . . . . . . . . . 68Number of allowed requests . . . . . . . . . . . . . . . . . . . . . . . 68

9.6 End Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699.6.1 Creating Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699.6.2 Create server certificates . . . . . . . . . . . . . . . . . . . . . . . . 699.6.3 Issue a new PKCS#12 keystore for an SSL server . . . . . . . . . . . 709.6.4 Issue a new server certificate from a CSR . . . . . . . . . . . . . . . 719.6.5 Create User certificates . . . . . . . . . . . . . . . . . . . . . . . . . 729.6.6 Certificate Renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

9.7 Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739.7.1 Renewing Superadmin . . . . . . . . . . . . . . . . . . . . . . . . . . 73

9.8 Administrator Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749.8.1 Roles created during install . . . . . . . . . . . . . . . . . . . . . . . 749.8.2 Pre-defined Role Templates . . . . . . . . . . . . . . . . . . . . . . . 749.8.3 Advanced access rules . . . . . . . . . . . . . . . . . . . . . . . . . . 759.8.4 Creating a new administrator . . . . . . . . . . . . . . . . . . . . . . 75

Creating a Certificate Profile For the Administrator . . . . . . . . . . 75Creating an End Entity Profile for the Administrator . . . . . . . . . 76Creating a new RA Role . . . . . . . . . . . . . . . . . . . . . . . . . 77Adding new Administrators to the RA Role . . . . . . . . . . . . . . 77Test the new administrator . . . . . . . . . . . . . . . . . . . . . . . 77

9.8.5 About Roles and Rules . . . . . . . . . . . . . . . . . . . . . . . . . 78Roles and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78The Access Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

9.9 View Log options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799.10 Managing Internal Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . 809.11 Managing Remote Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Adding a Peer Connector . . . . . . . . . . . . . . . . . . . . . . . . 84Edit, Clone or Delete a Peer Connector . . . . . . . . . . . . . . . . . 84

Authorization of incoming connections . . . . . . . . . . . . . . . . . 84Publishing using Peer Connectors . . . . . . . . . . . . . . . . . . . . 85Certificate data synchronization . . . . . . . . . . . . . . . . . . . . . 85Renewal of remote Internal Key Bindings . . . . . . . . . . . . . . . . 85

9.12 Supervision Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869.13 System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869.14 System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

9.14.1 My Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879.15 Other Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

10 PKCS#11 Slot Smart Card Activation 8810.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8810.2 Installation/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.2.1 "Number of users required" . . . . . . . . . . . . . . . . . . . . . . . 8910.2.2 "Number/copies of user smart cards" . . . . . . . . . . . . . . . . . . 8910.2.3 "Require smart cards to activate system after boot" . . . . . . . . . . 8910.2.4 Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

10.2.4.1 Example with default values . . . . . . . . . . . . . . . . . 9010.2.4.2 Slots 0 and 1 . . . . . . . . . . . . . . . . . . . . . . . . . 90

10.3 Application/Activation of a slot . . . . . . . . . . . . . . . . . . . . . . . . . 9010.3.1 Activation on boot/slot 0 . . . . . . . . . . . . . . . . . . . . . . . . 91

VI SignServer 92

11 Introduction to SignServer 93

12 SignServer Web Pages 9412.1 Accessing the web pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9412.2 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

13 SignServer Administration Web 9713.1 Accessing the Administration Web . . . . . . . . . . . . . . . . . . . . . . . 9713.2 Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

13.2.1 Workers Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9813.2.1.1 Status Summary Page . . . . . . . . . . . . . . . . . . . . 9813.2.1.2 Configuration Page . . . . . . . . . . . . . . . . . . . . . . 9813.2.1.3 Crypto Token Page . . . . . . . . . . . . . . . . . . . . . . 9913.2.1.4 Audit log Page . . . . . . . . . . . . . . . . . . . . . . . . 99

13.2.2 Archive page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

14 SignServer Administration GUI 10014.1 Accessing the Administration GUI . . . . . . . . . . . . . . . . . . . . . . . . 10014.2 Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

14.2.1 Connect to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10714.2.2 Web Service URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10714.2.3 Truststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10714.2.4 Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10714.2.5 Load defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10714.2.6 Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10714.2.7 Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

14.3 Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10814.3.1 Workers tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

14.3.1.1 Status Summary tab . . . . . . . . . . . . . . . . . . . . . 10814.3.1.2 Configuration tab . . . . . . . . . . . . . . . . . . . . . . . 10814.3.1.3 CryptoToken tab . . . . . . . . . . . . . . . . . . . . . . . 10814.3.1.4 Audit log tab . . . . . . . . . . . . . . . . . . . . . . . . . 108

14.3.2 Archive tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

PKI ApplianceUser Guide – Public Key Infrastructure by PrimeKey

Ver: 3.0.0

Part I

Preamble

1 (109)


1. RELEASE NOTES Ver: 3.0.0

Chapter 1

Release Notes

PKI Appliance 3.0.0 Release Notes

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

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

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

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

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

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

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

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

2 (109)


1. RELEASE NOTES Ver: 3.0.0

Known Issues and Limitations:

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

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

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

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

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

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

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

3 (109)


2. INTRODUCTION Ver: 3.0.0

Chapter 2

Introduction

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

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

2.1.1 Styling Conventions

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

• Buttons on the GUI are represented like Create .

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

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

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

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

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

4 (109)


2. INTRODUCTION Ver: 3.0.0

i This is an informative message containing extra information.

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

! This is a warning message.

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

Run as user

df -h

2.1.2 Daily operations

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

Use-Case: Install PKI Appliance

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

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

5 (109)


3. PKI APPLIANCE OVERVIEW Ver: 3.0.0

Chapter 3

PKI Appliance Overview

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

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

6 (109)


Ver: 3.0.0

Part II

Appliance Administration

7 (109)


4. WEBCONF Ver: 3.0.0

Chapter 4

WebConf

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

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

Figure 4.1: WebConf Status Page

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

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

8 (109)



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

Figure 4.2: WebConf Network Settings

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

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

4.2.1 NTP

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

4.2.2 DNS

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

9 (109)



4.2.2.1 Fully Qualified Domain Name (FQDN)

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

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

Figure 4.3: WebConf Access Settings

4.3.1 TLS certificates

4.3.1.1 Server side TLS certificates

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

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

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

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

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

10 (109)



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

stallation they are replaced with certificates issued by the initial Management CA.If you already have an existing TLS CA that is trusted by browsers in your organization,

you can replace the certificates in this view.

1. Generate a new key pair .

2. Create a Certificate Signing Request (CSR).

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

4. Upload the issued certificate in PEM format with full certificate chain.

Note that the information in the CSR isn’t set to anything useful. This is the nor-mal EJBCA way of doing things, where the information inside the CSR is not trusted andoverridden by whatever values the RA officer finds acceptable.

4.3.1.2 Client side TLS certificates

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

i Note that no revocation checking has been implemented yet.

4.3.1.3 Trust CA certificates for client authentication

You can configure different trusted certificates (trust anchors) for each network interface. Ifyou want to use client TLS certificates from an external CA, you need to replace the trustedcertificate. To avoid locking yourself out of the PKI Appliance, first add the appropriatematching rules under PKI Appliance Management Accounts, so that you can reconnectand continue to administer the PKI Appliance after the trusted certificate is replaced.

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

4.3.2 PKI Appliance Management Accounts

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

11 (109)



• Client TLS certificates authentication.

• Shared secret (password) authentication.

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

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

4.4 HSMThe Hardware Security Module (HSM) configuration allows you to change the authenticationcodes of the PKCS#11 slots, change the PIN of Backup Key Share Smart Cards, make one-to-one copies of backup protection cards, change the PIN of user credentials on smart cards(for slot activation), download a full (protected) backup of the HSM’s key material or handleHSM key synchronization across a cluster.

Figure 4.4: WebConf HSM Settings and Actions

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

4.4.1 Changing HSM PKCS#11 slot authentication codes

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

4.4.1.1 Switching from generated to manually entered authentication code

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

12 (109)



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

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

Figure 4.5: Slot authentication code change from generated to manual

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

Figure 4.6: Changing the authentication code of a slot

Figure 4.7: Manual slot authentication code change

4.4.1.3 Switching to auto-generated authentication code

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

13 (109)



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

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

Figure 4.8: Slot authentication code change from manual to generated

4.4.2 Backup Key Share Smart Card Handling

These options are only available if you initialized the PKI Appliance using smart cards forbackup protection (see ’Appliance Security Level’ on page ??). Before using any of thesefunctions, you need to have the PIN pad connected to a USB port of the PKI Appliance.Please note that the USB port of the HSM (the USB port on the PCI card, only accessiblefrom the back) will not work. The USB ports on the front of the PKI Appliance are fine.

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

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

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

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

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

14 (109)



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

4.4.3 Download protected HSM export

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

4.4.4 Cluster Key Synchronization Packages

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

If you create a new key in the HSM through EJBCA (e.g. creating a new CA), theknowledge about its existence will synchronize through the database, but the key itself willnot synchronize automatically. Hence, you will have to manually distribute this new key databy downloading a Key Synchronization Package on the Node where you created the newCA and uploading it to each of the other nodes. The applications (EJBCA, SignServer) willautomatically be restarted, so that the key material can be used. See also Chapter 5 on page23 for a more detailed description of the workflow.

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

Figure 4.9: WebConf Backup Settings and Actions

15 (109)



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

Configuring backup location

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

Taking a manual backup

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

Deleting backup

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

Automated backup schedule

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

16 (109)



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

Figure 4.10: WebConf Cluster

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

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

Figure 4.11: WebConf Monitoring

4.7.1 Syslog shipping

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

17 (109)



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

Figure 4.12: WebConf Platform page

4.8.1 Applications

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

4.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 5 HA Setup (page 22) for general informationabout Clustering/High Availability Setup and 5.5.3 (page 28) for very detailed informationon how to update a cluster.

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

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

Update Stand-Alone System

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

18 (109)



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

Update Firmware

Select the desired firmware update file by pressing the Install Firmware button next tothe file name. This will trigger a background job of the update process. It will take a while,so return to this view later to check if the update has finished. During the update the PKIAppliance will stay fully operational. The updated firmware will not be used until the systemis rebooted.

Update Application

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

4.8.3 Troubleshooting

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

4.8.4 Platform Access

The platform access page allows you to:

• Enable/disable SSH access

• Upload an SSH public key

• Define a password for cleartext SSH authentication

• Define a password for local console root access

Starting with version 2.4.0, the PKI Appliance will have no default password configuredfor access anymore. This implies that you will have to set up your way of authentication ifyou need access the platform. Please be aware that your SSH client will still ask you for a

19 (109)



password (and thus make it look like there is *some* password set up) if there is no cleartextpassword defined. Defining either SSH public key or root password for SSH access will onlybe possible after you enabled SSH.

4.8.4.1 SSH public key

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

4.8.4.2 Password authentication

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

4.8.5 Support

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

20 (109)


Ver: 3.0.0

Part III

Appliance in High Availability Setup

21 (109)


5. HA SETUP Ver: 3.0.0

Chapter 5

HA Setup

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

5.1.1 How it works

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

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

5.1.2 Synchronization of key material

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

5.1.2.1 Pre-cluster setup generation of keys

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

22 (109)



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

5.1.2.2 Post-cluster setup generation of keys

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

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

Use-Case: Synchronize key material

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

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

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

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

5. Configure the application to start using the new key pair(s).

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

5.1.3 Network topology

All cluster nodes should have a dedicated connection to all other nodes in the cluster.However the cluster can propagate the data as long as all nodes are connected to at leastone other node.

The network connection is done via the GRE protocol (IP protocol number 47, seehttps://en.wikipedia.org/wiki/List_of_IP_protocol_numbers). Since GRE is anIP protocol, it is not based on either TCP or UDP and has no concept of ports. It is anIP protocol by itself. That means that it can not simply be made available with a portforwarding behind a NAT (Network Address Translation). A fully transparent VPN solutionwill be required if the cluster is supposed to be installed over different locations.

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

23 (109)

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



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

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

5.1.4 Cluster traffic security considerations

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

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

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

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

5.3 Levels of availability

5.3.1 Stand alone instance

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

5.3.2 Hot stand-by with manual fail-over

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

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

24 (109)



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

5.3.3 High availability with automatic fail-over

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

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

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

5.4 High Availability

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

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

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

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

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

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

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

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

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

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

25 (109)



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

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

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

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

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

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

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

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


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

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

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


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

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

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

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

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

26 (109)



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

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

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

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

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

5.5.1 Backing up a cluster

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

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

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

5.5.2 Restoring a cluster from backup

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

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

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

Please refer to chapter ?? (on page ??) for a description on how to restore a backup toa PKI Appliance.

27 (109)



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

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

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

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

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

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

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

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

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

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

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

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

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

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

28 (109)



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

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

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

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

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

5.6.1 Shutting down the cluster in controlled manner

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

5.6.2 Starting a fully shutdown cluster

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

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

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

1. Power up all nodes.

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

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

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

29 (109)



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

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

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

Use-Case: Changing the IP Address of the Application Interface of a node in a threenode cluster

In a PKI Appliance cluster, the internal communication is being transferred over the Appli-cation Interface. Hence, if you need to change the IP address of the Application Interface,cluster communication will fail at first and you will have to take some manual configurationsteps to bring back the node into play:

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

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

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

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

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

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

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

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

30 (109)



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

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

Replacing a failed cluster node

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

31 (109)


Ver: 3.0.0

Part IV

Enterprise Java Beans CertificationAuthority (EJBCA)

32 (109)


6. INTRODUCTION TO EJBCA Ver: 3.0.0

Chapter 6

Introduction to EJBCA

EJBCA is an enterprise class PKI Certificate Authority software, built using Java (JEE)technology. It is a robust, high performance, platform independent, flexible, and componentbased CA to be used stand-alone or integrated in other JEE applications. As an enterpriseclass PKI CA, EJBCA can be used to build a complete PKI infrastructure for an enterprise.If only want to issue a few single certificates for testing, there are probably options that canbe implemented easily and quicker, but for a more serious PKI, EJBCA is recommended. Asa product, EJBCA is capable of being deployed on one of the following roles:

• A Certification Authority

• A Validation Authority

• An OCSP Responder

This part of the guide describes the deployment of EJBCA as a certification authority.

6.1 FeaturesThe following are some of the features that make EJBCA useful as a certification authority

• Multiple CAs and levels of CAs, build a complete infrastructure (or several) within oneinstance of EJBCA.

• Unlimited number of Root CAs and SubCAs. Request cross certificates and bridgecertificates from other CAs and Bridge CAs. Issue cross certificates to other CAs.

• Get your own CA signed by public recognized CAs such as Comodo or T-Systems.

• Follows X.509 and PKIX (RFC5280) standards where applicable.

• Supports RSA key algorithm up to 8192 bits.

• Supports DSA key algorithm with 1024 bits.

33 (109)



• Supports ECDSA key algorithm with named curves or implicitlyCA.

• Supports multiple hash algorithms for signatures, SHA-1, SHA-2.

• Compliant with NSA SUITE B algorithms and certificates.

• Support for X.509 certificates and Card Verifiable certificates (CVC BSI TR-03110used by EU EAC ePassports).

• Individual enrolment or batch production of certificates.

• Issues SSL/TLS certificates that work with all common servers.

• Admin registration and self-registration work-flows out of the box. Supports virtuallyany work-flow with plug-ins and integration.

• Server and client certificates can be exported as PKCS12, JKS or PEM.

• Browser enrolment with Firefox, IE, etc.

• Enrolment for other applications through open APIs and tools.

• Enrolment generating complete OpenVPN installers for VPN users.

• Mobile enrolment, i.e. iOS using SCEP.

• Revocation and Certificate Revocation Lists (CRLs).

• CRL creation and URL-based CRLDistribution Points according to RFC5280.

• Smart card logon certificates for Windows, Linux and Mac OS X.

• Configurable certificate profiles for different types and contents of certificates.

• Standard and custom certificate extensions supported.

• Supports the Simple Certificate Enrolment Protocol (SCEP).

• Qualified Certificate Statement (RFC3739) for issuing EU/ETSI qualified certificates.

• Supports the Online Certificate Status Protocol (OCSP - RFC2560, RFC6960 andRFC5019), including AIA-extension.

• Supports RFC4387 for distribution of CA certificates and CRLs over HTTP.

• Validation Authority service serving OCSP responses (RFC2560/5019), CA certificatesand CRLS (RFC4387).

• Supports the German Common PKI SigG CertHash OCSP extension.

• Supports CMP (RFC4210 and RFC4211).

• Supports synchronous XKMS version 2 requests.

• Key recovery to store private keys for recovery for selected users and certificates.

34 (109)



6.2 Complementary ProductsAs a certification authority, EJBCA can be integrated with several other products to enhancethe PKI experience and thus serve a wider variety of business needs.

6.2.1 SignServer

The SignServer is an application for server side signature generation. It is a framework thatcan be customized to specific needs using simple plug-in modules. The SignServer has aready to use TimeStamp Authority (RFC 3161 compliant) and a MRTD Signer. Anotherusage is to provide a simplified method to provide signatures in different application managedfrom one location in the company. The SignServer has been designed for high-availabilityand can be clustered for maximum reliability.

6.2.2 Single Point of Contact (SPOC)

The SPOC is used to enable cross certification of document verifiable (DV) certificates.The SPOC can be integrated with EJBCA to enable automatic issuance and and renewal ofcertificates.

6.2.3 Hardware Tokens

EJBCA supports the issuance of certificates on tokens. While in theory any token can besupported, the following tokens have been tested with EJBCA:

• Aventra,

• AET SafeSign

• SecureMetric

• Feitian

• Gemalto

• SecMaker

• OpenSC

• SafeNet iKey

6.2.4 Card Management System

EJBCA supports the integration of several card management systems of the purpose ofissuing smart cards containing certificates and their associated private keys. The followingcard management systems have been implemented in various other projects as part of EJBCA.

• GemSAFE Toolbox

35 (109)



• AET SafeSign IC bundle

• SecMaker NetID

• Aventra Card Management System

• SecureMetric SecureTMS

36 (109)


Ver: 3.0.0

Part V

EJBCA Administration and PublicWeb

37 (109)


7. EJBCA INTERFACE Ver: 3.0.0

Chapter 7

EJBCA Interface

EJBCA provides a large array of interfaces for performing life cycle events. This chapterdescribes the available interfaces and describes the various operations that can be performedusing these interfaces.

7.1 OverviewAn administrator’s main interaction with EJBCA is conducted via graphical web pages. Theseweb pages are divided into two independent sites: the Public Web and the Admin Web.The Public Web Interface - as its name suggests - is initially configured to be accessibleby anyone. The Administration Web Interface - a separate site - requires an admin clientcertificate to be installed in the browser that will attempt to connect to the site. This chapterintroduces the public and administrative GUI and describes the terminology and functionsaround these items. Also introduced are other interfaces used for interfacing and integratingwith EJBCA using various protocols

38 (109)


8. PUBLIC WEB INTERFACE Ver: 3.0.0

Chapter 8

Public Web Interface

The public web interface is used to issue certificates for end entities that have been previouslyadded from the administration interface or via a process provided by a registration authorityand approved, by process or an administrator, in the administration interface. Additionally,the public web interface provides a location for the public to download CRLs, OCSP certifi-cates and CA certificates. The public web interface consists of three main sections: Enrol,Retrieve, and Miscellaneous. Enroll enables end entities to request or create various types ofcertificate keystores. The second section, Retrieve provides end entities with the ability toretrieve the CA root certificate, OCSP and user certificates. The final section, Miscellaneous,allows entities to list certificates, check status or launch the administrative interface. Thefollowing paragraphs provide more details about the functionality of each section.

8.1 EnrollThis section of the interface provides functions for certificate enrollment.

Create Browser CertificateInstall a certificate in your web browser. This certificate may be exportable dependingon browser and browser settings.

Create Certificate from CSRSend a PKCS#10 certificate request generated by your server, and receive a certificatethat can be installed on the server. Consult your server documentation.

Create KeystoreThis option allows an operator to create a server generated keystore in PEM, PKCS#12or JKS format and save to a file. This keystore can be installed in a server, browser orin other applications.

Create CV CertificateThis option is used for generating card verifiable certificates based on the EAC standard.Certificate requests may be in base 64 format

39 (109)



8.2 RegisterThis section describes the operations for the submission of registration of certificate requestsand primarily serves the self registration feature provided by EJBCA.

Request RegistrationThis option allows a user to request a certificate using the self registration businessprocess.

i Self registration must be enabled and configured to allow this option towork.

8.3 RetrieveThese operations allow the retrieval of certificates, CRLs and other available data via adownload process.

Fetch CA and CertificatesBrowse and download CA certificates.

Fetch CA CRLsDownload Certificate Revocation Lists.

List User’s CertificatesList certificates for a user for a certificate Distinguished Name is known.

Fetch User’s Latest CertificateDownload the last issued certificate for a user for whom you know the certificateDistinguished Name.

8.4 InspectThe inspection option facilitates the user friendly view of certificates and other binary datahandled by EJBCA.

Inspect certificate/CSRView the contents of a certificate in X.509 or CVC format or a signed request inPKCS#10 format

Check Certificate StatusThis option allows the performance of a revocation status for a certificate where theIssuer Distinguished Name and the serial number are known.

40 (109)



8.5 MiscellaneousThe miscallaneous options cover other operations of use to operators.

AdministrationThis is a short cut to the EJBCA Admin Web. Access to the EJBCA admin webrequires client certificate authentication.

DocumentationThis section provides a link to the built in documentation provided with the product

41 (109)


9. ADMINISTRATION WEB INTERFACE Ver: 3.0.0

Chapter 9

Administration Web Interface

You can administer EJBCA using a web browser and the Admin GUI, this is the easiestway. The Admin GUI requires SSL with authentication using client certificate, i.e. strongauthentication.The administration web interface is used to configure and administer EJBCA. The adminis-tration web interface is divided into four sections based on the operation an administrator islooking to perform:

• CA Functions

• RA Functions

• Supervision Functions

• System Functions

9.0.1 Publish queue status

The publish queue status shows the current number of publish events that is stored in thepublisher queue. Events can be stored in the publisher queue either because publishing failed,or because publishing goes to the queue directly.

9.0.2 CA Status

The CA status overview shows ok or error if CAs are off line and if CRLs are not valid.

CA Status shows a red error if the CA is not on-line or the CA token is not on-line.External CAs are always show as ok. If the CA or CA token is not on-line, you should checkthe CA activation page, to see if the CA can be activated.

CRL status show a red error is a CRL or delta CRL has expired without a new one beingcreated. Delta CRLs are only monitored if used. If CRLs have expired you can generate newCRLs.

42 (109)



9.1 Managing Crypto TokensA Crypto(graphic) Token in EJBCA is where keys are stored. A Crypto Token is backed anHSM PKCS#11 slot.In the EJBCA Admin GUI the menu item "Crypto Tokens" will show you all the Crypto Tokenrelated management. Activation of Crypto Tokens can also be done from the CA Activationpage.

9.1.1 New Crypto Tokens

• Name: A user-friendly name for the Crypto Token.

• Type: PKCS#11 HSM slot mapping.

• Authentication Code: The PKCS#11 slot PIN that will protect the soft keystore.

• Repeat Authentication Code: Should be the same as the previous field.

• Auto-activation: If the authentication code should be stored (obfuscated) in thedatabase and used to always keep the Crypto Token active.

For PKCS#11 Crypto Token additional fields are displayed:

• PKCS#11 Library: PKCS#11 shared library.

• PKCS#11 Reference Type: What kind of a slot reference that is described by thenext parameter (Id, Index or Label).

• PKCS#11 Reference: PKCS#11 slot number, index or label.

9.1.2 View or Edit a Crypto Token

The view is very similar to the creation of a token except for showing the ID and acti-vation status. It is not possible to change the Crypto Token ID, type or the change theauthentication code of soft Crypto Tokens.

9.1.3 Activation and deactivation

In the list of Crypto Token there are 3 possible actions available:

• Activate: Enter a authentication code and clicking "Activate" will activate an inactiveCrypto Token.

• Deactivate: Clicking "Deactivate" will deactivate an active Crypto Token.

• Reactivate: Clicking "Reactivate" will reactivate an active Crypto Token with auto-activation enabled.

43 (109)



9.1.4 Key management

While viewing an active Crypto Token it is possible to also view and interact with the CryptoToken’s keys. The shown SubjectKeyID column is a SHA1 over the public key.

• A new key pair can be created by giving it an alias, a key specification and clickinggenerate.

• Key pairs can be removed by clicking "Remove" for the specific key pair or selectingmultiple keys and clicking "Remove selected".

• A key pair can be tested by clicking "Test" for the specific key pair.

• A key pair’s public key can be downloaded in PEM format by clicking "DownloadPublic Key".

9.2 CA FunctionsThe CA Functions section provides an operator with several useful options relating to CAmanipulation. The CA Functions provides the following task-based optionsCA Activation

This menu option allows an operator to activate or deactivate an existing CA.

CA Structure & CRLsThis menu option allows an operator to have a general overview of the CAs that residein the instance of EJBCA as well as view the information relating to the CRLs. Thissection was perviously called Basic Information.

Certificate ProfilesThis menu option allows an operator to create or edit certificate profiles. Certificateprofiles are templates from which certificates can be issued to created end entities.

Certificate AuthoritiesThis menu option allows an operator to create modify and delete certificate authorities.Certificate authorities are a central component of the system and will be coveredextensively.

Crypto TokensThis menu option allows an operator to configure crypto tokens for use in the system.There are two types of supported crypto tokens. Soft tokens and PKCS#11 tokens.Crypto Tokens is a new feature introduced in EJBCA 6.

PublishersConfigure a publisher for an End Entity Profile. This enables an administrator totrigger actions via the publisher every time a profile is utilized. There are five potentialpublisher types that can be used. They will be discussed in more detail in a latersection.

44 (109)



9.2.1 Creating CAs

Your CAs can be either root CAs, subordinate CAs to another CA in EJBCA or subordinateCAs to an external CA. The initial admin CA is a RootCA.Creating CAs in the Admin GUI is done by selecting ’Edit Certificate Authorities’ in themenu, entering a new CA name in the text field and clicking Create .

9.2.2 CA fields

Type of CA

Type of CA can be either X.509 or CVC.An X.509 CA is a normal CA for secure email, login, web authentication, VPN etc etc. ACVC CA is a CA issuing CV certificates, which are special certificates for EU EAC ePassports.

Signing Algorithm

The signing algorithm to use for issuing certificates, signing CRLs etc.

Crypto Token

The Crypto Token where the CA’s key mappings are expected to exist.The list of available Crypto Tokens are those that the administrator is authorized to viewand use. The Crypto Token must also be active and contain a key that can be used withthe CA signing algorithm in order to be shown.The purpose mappings are the key alias in the Crypto Token to use for what:

• defaultKey: The key to use no specific alias is selected (Required).

• certSignKey: The key to use for certificate issuance. Must comply with the SigningAlgorithm and only valid choices are shown.

• crlSignKey: The key to use for CRL signing. Even though it could theoretically beseparate from the certSignKey according to the RFCs, client support is rare and thecertSignKey will always be used.

• keyEncryptKey: Key to use for key recovery when enabled. Decrypts escrowed keysand must be RSA. hardTokenEncrypt: Deprecated functionality, do not use.

• testKey: Key used by health-check to verify that the Crypto Token is usable. Usuallya short key for speedy connection checks.

Extended Services Key Specification

Each CA has a set of Extended Services than can be enabled and sign requests in variousformats. For some of the services, the CA will delegate signing to soft keys stored in thedatabase as part of the CA object. These keys will have signing certificates issued by the

45 (109)



CA’s signature keys and similar SubjectDN to the CA. This field allows selection of the keyspecifications to use for these soft keys.

• Cryptographic Message Syntax (CMS, superseded PKCS#7): A soft key pair in thedatabase will be used.

If you don’t plan on using CMS or XKMS with any special requirements, you can safelyuse the default value here.

Key sequence

CVC SequenceThe key sequence is used in the certificate holder reference of an EAC CVC certificate /certificate request. According to the BSI specifications the sequence must be 5 bytes long.The initial value must be specified in the sequence field. The sequence MAY start with aniso 3166-2 countrycode.When renewing keys for HSMs using the Admin GUI, the new signing key label will be theold label with the new key sequence in the end. When renewing keys for HSMs using theAdmin GUI the key sequence is automatically increased.For X.509 CAs the key sequence should not be important, except for key labels when renewingkeys.If you are unsure of the key sequence you can safely leave it to be handled automatically.

Key sequence format

Within EAC, there are several options regarding the sequence format. The format can bechoosen in the field "Key sequence format". The following options are available:

• 5 byte numericThe sequence MUST contain numeric characters [0-9]. The sequence shall be increasedfrom 00000 to 99999

• 5 byte alphanumericThe sequence MUST contain alphanumeric characters [0-9][A-Z]. The sequence shallbe increased from 00000 to ZZZZZ

• 2 byte country code, 3 byte numericThe sequence must start with a 2 byte country code (e.g. SE). The other bytes shallbe increased from 000 to 999

• 2 byte country code, 3 byte alphanumericThe sequence must start with a 2 byte country code(e.g. SE). The other bytes shallbe increased from 000 to ZZZ

For X.509 the 5 byte numeric is recommended

46 (109)



Enforce unique public keys

Enforce unique public keys guarantees that certificates with the same public key can only beissued to the same user from this CA. This means that a user is allowed to have multiplecertificates (e.g. due to renewal) with the same key as long as the same ’username’ is used,but two users can not share the same public key. The check is only performed when newcertificates are issued.To use this feature efficiently you should have a database index over (subjectKeyId,issuerDN)on the table CertificateData.

Enforce unique DN

’Enforce unique DN’ guarantees that users with the same Subject DN can not be issuedcertificates from this CA. This means that a user is allowed to have multiple certificates(e.g. for different uses) with the same Subject DN as long as the same ’username’ is used,but two users can not share the same Subject DN. The check is only performed when newcertificates are issued.The check only affects new users, i.e. if you have two users with the same DN before enablingthe limitation, these old users can still share the same DN and get new certificates.To use this feature efficiently you should have a database index over (subjectDN,issuerDN)on the table CertificateData.

Enforce unique Subject DN serialNumber

’Enforce unique Subject DN SerialNumber’ guarantees that only one end entity with a spe-cific Subject DN SerialNumber can be issued from this CA. When adding a new end entity,a check is done to ensure that there are no other end entities, issued by this CA before, havethe same Subject DN SerialNumber. Note that end entities issued from other CAs can havethe same Subject DN SerialNumber as end entities issued from this CA.

i Note that this option is currently extremely inefficient and will only workwith a low number of users, in the hundreds or a few thousand. This is dueto the face that it select all users from the database registered for a specificCA. Future versions of EJBCA can optimize this query.

Use Certificate Request History

The Certificate Request History stores the values used when generating a certificate for anend entity. Since the values of the end entity, such as the DN, can be edited between re-quests, this function ensures that there is a possibility to trace the values used for issuing acertain certificate. Information stored is:

• fingerprint

47 (109)



• serialNumber

• issuerDN

• username

• timestamp

• UserDataVO

Turning on certificate request history will reduce performance and use more database space,and is disabled by default since EJBCA version 6.0. If request history is needed pleaseconsider using the audit log functionality instead.

Use User Storage

Certificates are normally issued in a two step process where a User is first added to thedatabase with a username, password (or enrollment code) and additional information thatshould go into the certificate. Later EJBCA processes a request that this user should beissued a certificate and the provided credentials (username and password) is verified with thestored User data. In the EJBCA Admin GUI it is currently only possible to search for Usersand not certificates, so without this enabled, the Admin GUI will not be very useful.The user data storage is enabled by default.If EJBCA is used as a factory and where the functionality of the Admin GUI is not required,this could be disabled to improve performance.

Use Certificate Storage

Issued certificates are stored in the database to be able to provide them upon request orprovide revocation information.The certificate data storage is enabled by default.If EJBCA is used as a factory and where the functionality of the Admin GUI is not required,this could be disabled to improve performance.

Certificate Policy Id

Setting the Certificate Policy Id when creating a CA affects the certificate policy extensionin the CA certificate. You can define Certificate Policy Id in:

• CA settings

• Certificate Profile

• Both

When a CA is created or renewed, the Certificate Policy Id fields of the CA settings and theCertificate Profile are merged when the CA certificate is created. This means that if youhave a value defined in both places, both Certificate Policy Ids will be included in the CA

48 (109)



certificate.For consistency reasons it might be a good idea to only use the Certificate Policy Id in theCertificate Profiles, as it is the same for all type of certificates, and merge effects can beconfusing.

Name Constraints

You may restrict the domain names and IP addresses under which a CA is allowed to issuecertificates. Root CA operators might require that this certificate extension is used in subCAs that are operated by customers. The intended work-flow is to specify the name con-straints on the end-entity for a sub CA, which will cause the name constraints extension tobe included in the sub CA certificate once it’s generated. It’s also possible to add nameconstraints directly on a CA.

i Name constraints must first be enabled in the Certificate Profile and theEnd-Entity Profile (the latter is for end-entities only). At the time of writing(May 2014) they are not supported in Apple Safari or on iOS devices, sothis extension can not yet be marked as critical if there are such clients.The default mode is non-critical for this reason.

EJBCA supports domain name, directory name, e-mail (RFC 822 name) and IP address(both IPv4 and IPv6) constraints. These syntaxes are accepted:

• example.comMatches example.com and subdomains.

• @example.comMatches all mailboxes at example.com.

• [email protected] a specific e-mail address.

• C=SE,O=CompanyMatches against the beginning of the Subject DN. The certificates must not use LDAPDN order, which is enabled by default!Also note that the RDN encoding must match. If the Name Contraint is encodedas PrintableString, the certificate must also be issued with PrintableString in thesubjectDN, otherwise Name Contraint matching will fail. If you get an name constrainterror about "XKMSCertificate" or "CMSCertificate" when creating a CA, then you havesome problem with the Subject DN matching.

• 198.51.100.0/24Matches an IPv4 subnet. The IP address checked is the one in the certificate, whichin turn is checked if the host is accessed by IP address.

49 (109)



• 2001:db8::/32Similarly, matches an IPv6 subnet.

Name constraints are only checked for the types of constraints that are specified. So, ife.g. no IP addresses are addresses then the IP address will not be constrained. Conversely, ife.g. a domain name is listed as permitted then no other domain names will be permitted. Ifneither any permitted or excluded names are entered, then the Name Constraints extensionwill be omitted from the certificate.

CRL Period

There are four settings in CA configuration dictating the times when CRL generation is done:

• CRL Expire Period: Mandatory. The validity period for generated CRLs. If set to forexample 24h, the nextUpdate for a generated CRL will be the issue time + 24 hours.

• CRL Issue Interval: Optional. A fixed interval when CRLs will be issued. If set tofor example 1h a new CRL will be issued every hour, even though the old one is stillvalid for another 23 hours. The default value here is 0, which means that a new CRLwill be issued when the old one is about to expire (see also overlap time). Keeping thedefault value 0 has the same as effect as setting this value to the same value as CRLExpire Period.

• CRL Overlap Time: Optional. When checking if a CRL should be generated (if theold one is about to expire), the new CRL is generated this amount of time before theold CRL expires. The default value is 10 minutes, meaning that if CRL Expire periodis 24 hours, a new CRL will be issued after 23h50m. This ensures that there is no timeperiod (even a few seconds) when there is no valid CRL issued. It also gives clients atime-slot to download a new CRL before the old one expires.

• Delta CRL Period: Optional. The amount of time your delta CRLs will be valid ifdelta CRLs are issued. If this period is larger than 0, Delta CRLs will be issued.

Finish User

The Finish User configuration defines if the CA calls a process called "finishUser" after acertificate has been issued for an end entity. This process is what makes the user’s passworda one-time password, i.e. it removes the password and/or decreases the password use count.With this setting enabled (default) an end entity password can only be used once (or asmany times as defined in ’Number of allowed requests’ when adding the end entity) to enrollfor a certificate. After the certificate has been issued the user status is set to ’Generated’and the password blanked. When status is ’Generated’ a new certificate can not be issueduntil status is reset to ’New’, usually by editing the end entity. With this setting disabledthe password can be used unlimited number of times to enroll for certificates, and the statusstays as ’New’ after each time.

50 (109)



9.2.3 Creating a SubCA signed by an external CA

Some CA hierarchies have the requirement of being signed by an external Certificate Author-ities and sometimes other external CA:s need to be signed by your CA.When creating a CA that is signed by an external CA, you create a PKCS10 certificaterequest that is sent to the external CA. When the external CA returns your CAs certificate,this is processed and the CA becomes activated.In order to have your CA signed by an external CA you have to go through the followingsteps.

1. Go the the Edit Certificate Authorities page in the Administration GUI.

(a) Create a new CA in the same way as internal CAs, but when selecting signing CA,select External CA instead. The fields Certificate Profile, Validity, SubjectAlternative Name and Policy Id will become gray and are no longer editable.

(b) Fill in the Description and CRL Specific data.(c) Make sure that the certificate chain is available, this can be done in one of three

ways:i. Select a file containing the CA certificate chain of the signing CA. This file

should be in PEM encoding. If there is more than one top CA certificatethen all their certificates should be appended into one single file. It shouldbe in plain PEM format without blank lines before or after. An example isbelow.

ii. Append the chain to the signed certificate file in the same way when receivingthe request (see below).

iii. Import the complete certificate chain beforehand as External CAs (Certificate

Authorities -> Import CA Certificate ).

(d) Click on the Make Certificate Request button in the bottom of the page.

2. After successfully clicking Make Certificate Request the generated PKCS10 cer-tificate request will be displayed. You can copy and paste it to the signing CA ordownload the PEM file if that approach is preferred.

3. The external CA should sign the certificate request and return a certificate. Meanwhile,the newly created CA will have the status ’Waiting for Certificate Response’ and willnot appear anywhere in the system except in the ’Edit CA’ page.

4. When the Certificate Response has arrived, it is time to activate the new CA. Youmark the waiting CA and click on Edit button in the ’Edit CA’ page. Go to thebottom of the page and click on Receive Certificate Response (you can leavethe password field blank). Then upload the received certificate and click again onReceive Certificate Response .

51 (109)



5. If the received certificate forms a valid certificate chain with the previously uploadedchain or contained a full chain, the status of the CA will be set to ’Active’.

6. If you want to activate OCSP functionality for this new CA you have to edit it onceagain and mark the OCSP functionality as active.

7. The new externally signed CA is ready to use.You can treat an internal CA (a CA residing on the same EJBCA instance as another

CA) as an external CA. From the SubCA this works just like the normal case, but on theRootCA you will issue the SubCA as an end entity.This can be useful if you have an HSM setup where only one set of keys can be active atone time, for example using nCipher with two different, non-persistence, operator cards setsfor the RootCA and the SubCA. Using the SubCA as an external CA you can still create thePKI but with only one CA active at a time.

9.2.4 Signing an External CA

In some cases you might want to have one of your CA:s signing another external CA. Thiscan be done in two ways:

1. Create a certificate profile and an end entity profile for Sub CAs. The certificate profilemust be of type SubCA .

2. Create an End Entity where you select a SubCA certificate profile when adding theend entity.

3. Issue the CA certificate as you would normally issue any end entity certificate.

4. The SubCA can be managed and revoked conveniently just as other end entities.Using an end entity is the recommended way to sign Sub CAs, because of the better man-agement features.

9.2.5 Renewing a SubCA signed by an external CA

When you renew a SubCA signed by an external CA you create a new request that is sent tothe external CA. The External CA issues a new certificate that you import in your SubCA.You can renew the SubCA in two ways:

1. Using the same CA signing keys.

2. Generating new CA signing keys.To renew a CA go to Edit Certificate Authorities select the SubCA and use the buttonRenew CA in the bottom of the page. The CA’s Crypto Token must be active to makea certificate signing request (and optionally for key generation).When you generate new keys for the SubCA, the new keys will not be used until you uploada new CA certificate for this key pair. Until then, the CA will continue to work as if nothinghas happened (and issue certificates with the current CA signing key pair).

52 (109)



9.2.6 Requesting a cross or bridge certificate

If you have set up your own CA you can request another CA to cross certify your CA, or youcan get certified by Bridge CA such as the Federal Bridge. This is done in the following way:

1. In the ’Edit CA’ page, choose a CA that you intend to get cross certified by anotherCA by and click on Edit .

2. In the lower part of the screen, click on Make Certificate Request and skip uploadof the signing certificate chain.

3. Save the created PKCS#10 certificate request to disc and send to the other CA.

Now you have a certificate request to send to the other CA or Bridge CA. When the otherCA have issued a certificate for you, everything is completed. You don’t need to (and usuallyshould not) import the cross-certificate or bridge-certificate in EJBCA. What you need to dois make sure the clients using the certificates issued by your CA have access to the correctcertificate chain. If you are cross-certified with several other CA, multiple possible certificatechains exist.Handling the certificate chains on clients is out of the scope for EJBCA.If you choose to upload the resulting certificate chain, this will convert your CA from aninternal CA to an externally signed CA.

9.2.7 Signing a roll-over certificate (NewWithOld)

One way to handle update of trust points when renewing a Root CA is to generate a certificatethat contains the new key signed with the old key. For X.509 CAs you can create such acertificate by checking Create link certificate before renewing the CA. The latest linkcertificate can then be downloaded from the edit CA view.For CVC CAs a link certificate is always generated during the renewal.

9.3 Certificate ProfilesCertificateProfiles define different types of certificates, with regards to DN-contents, exten-sions etc.

9.3.1 Create a Certificate Profile for SSL servers

This section will show you how to create a certificate profile suitable for SSL/TLS servers,such as web servers.

1. Under CA Functions, press Certificate Profiles.

2. Enter a name for your end entity certificate profile e.g. SSLServerCertificateProfile,and press Add .

53 (109)



3. Select SSLServerCertificateProfile and press Edit .

4. Under Validity enter 365d (1 year validity).

5. Under Key usage, choose Digital Signature and Key encipherment (ctrl-click toselect multiple).

6. Un-check Allow Key Usage Override.

7. Check Use Extended Key Usage.

8. Under Extended Key Usage, choose Server Authentication .

9. Under Available bit lengths, 1024 bit , 2048 bit and 4096 bit .

10. Under Available CAs, choose your CA ManagementCA (the CA you use to issueserver certificates).

11. Under Type, select End Entity .

12. Press Save

Another way of creating a new Certificate Profile is to use an existing profile as template:In the list of certificate profiles, clone profile SERVER.

9.3.2 Import/Export Certificate Profiles

It is possible to import and export certificate profiles in the AdminGUI under CA Functionsand Certificate Profiles.

Export Certificate Profiles

Every non-fixed certificate profile is exported to the specified local directory as an xmlfile inside a zip file named "certprofiles.zip". The name of the xml file has the formatcertprofile_PROFILENAME-PROFILEID.xml.

Import Certificate Profiles

All profiles to be imported should be included in a zip file. The file containing a singleprofile should be an xml file and its name is in the format certprofile_PROFILENAME-PROFILEID.xml. Any file with a name that is not in this format will be ignored.

54 (109)



9.3.3 Certificate Profile fields

Validity

The validity determines the validity in days of certificates from the time the certificate isissued. The field notAfter in the issued certificate will have the value now + validity days.It can also, if noted in the field, be entered in terms of years, months and days. For instance10y 9mo 8d is translated to 10 years, 9 months and 8 days from now. Instead of the validityperiod an absolute end date could specify the end of the validity period. This date shouldbe given in the format yyyy-MM-dd HH:mm:ssZZ, for example, the date June 3rd, 2011 at6:15 PM in UTC should be given as 2011-06-03 18:15:00+00:00.The check box Allow Validity Override will make it possible to request a specific notAfterdate. This is currently possible when using CMP (the CRMF request format), or when usingthe API to issue certificates.The validity of a certificate is determined as follows:

• The Validity field in the profile specifies the maximum allowed validity, which will bethe validity if nothing else is specified.

• If Allow validity override is enabled in the profile the profile value can be overriddenwith:

– Start and end time specified when adding the end entity, of allowed in the EndEntity Profile.

– Requested validity from the certificate request (CMP for example).

There are some constraints for the validity of a certificate issued by the CA:

• The notAfter time of issued certificates can never be longer than the validity timespecified in the certificate profile used.

• The notAfter time of issued certificate can never be longer than the CAs own validity.

• notAfter can never be before nofBefore and vice versa.

• notBefore is normally 10 minutes before the current time, to avoid problems with clocksthat are a few minutes out of sync.

• notBefore can be set to any desired value if allow validity override is enabled, exceptfor the limitation with regard to notAfter.

• notAfter can be set to any desired value if allow validity override is enabled, except forthe limitation of max and min value specified above.

If the validity is for a CA the certificate profile specifies the maximum validity, but it can beshorter if specified when adding the CA. The validity of the CA can never be longer than thevalue specified in the profile.The last option you have is to set a global maximum validity date for certificates issued

55 (109)



from the EJBCA instance. You can do this by setting the option ’ca.toolateexpiredate’ inejbca.properties. See the documentation in conf/ejbca.properties.sample for more details. Ifa validity period would exceed this value, if it is configured, an error occurs and no certificateis issued.

Allow extension override

If extension override is allowed, X.509 certificate extensions featured in certificate requests arehonored, otherwise they are ignored. Externally supplied extensions are added to certificates"as-is". In the case such an extension is already defined in the certificate profile (i.e. havingthe same OID), the definition in the profile will be overridden including the criticality flag.This option should only be used when you know that the request comes from a very trustedsource. Such a trusted source is normally an RA through CMP or WebService.Currently this only works for extensions in CRMF (CMP) requests.

Allow subject DN override

If subject DN override is allowed, the X.509 subject DN extension created in a certificate cancome directly from the request sent by the user. This is instead of the normal way wherethe user’s registered DN is used.Using this option certificates with very strange DNs, or with DNs in very specific orders canbe created.This option should only be used when you know that the request comes from a very trustedsource. Such a trusted source is normally an RA through CMP or webservice.

Allow certificate serial number override

The generated certificate serial number could be overridden if Allow certificate serialnumber override is enabled in the used certificate profile.If the Admin GUI should be used for creating entities you must also add Custom certificateserial number to the used end entity profile.With web services you use the ’setCertificateSerialNumber’ for your ’UserDataVOWS’ user.With External RA (ExtRA) the CertificateRequestRequest takes a certificate serial numberas a parameter.Please note that the row ’serialNumber’ number in the table ’CertificateData’ of the databasemust have an unique index for this feature to work should work, normally you use an indexfor unique issuerDN, serialNumber. Without index the feature is automatically disabled.

Allow back dated revocation

Revocation information of a revoked certificate contains the date and time from which thecertificate is not valid (the revocation time). Normally the revocation time is set to the timeof the revocation. But with this feature enable it is possible to set an earlier time whenrevoking a certificate from the profile. This is called a back dated revocation.

56 (109)



Currently you can only back date revocations with the use of Web Service, either by usingthe WS API call revokeCertBackdated in your application.

i Do not enable this feature if the profile will be used by a CA that is issuingdelta CRLs.

Path Length Constraints

i This extension is only applicable for immediate CA certificates and it setshow deep the succeeding certificate hierarchy may be. If it is set to 0 thisCA certificate is the last CA in a chain and only end entity certificates mayfollow.

From RFC5280 (4.2.1.9):The pathLenConstraint field is meaningful only if the cA boolean is asserted andthe key usage extension, if present, asserts the keyCertSign bit (Section 4.2.1.3).In this case, it gives the maximum number of non-self-issued intermediate cer-tificates that may follow this certificate in a valid certification path. (Note: Thelast certificate in the certification path is not an intermediate certificate, and isnot included in this limit. Usually, the last certificate is an end entity certificate,but it can be a CA certificate.) A pathLenConstraint of zero indicates that nonon self-issued intermediate CA certificates may follow in a valid certificationpath. Where it appears, the pathLenConstraint field MUST be greater than orequal to zero. Where pathLenConstraint does not appear, no limit is imposed.

Issuer Alternative Name

Using the Issuer Alternative Name extension simply copies the Subject Alternative Namevalue from the issuing CA certificate and places it into the certificate produced.An example of usage is to create a CA with Subject Alternative Name "[email protected]",and including that in the CA certificate. If you include Issuer Alternative Name in thecertificate profile used to issue end entity (or sub CA) certificates, the end entity certificateswill get Issuer Alternative Name "[email protected]". The end entity certificates canhave a totally different Subject Alternative Name, as this is registered for the specific endentity.

CRL Distribution Points

The CRL Distribution Point (CDP) extension is provided as info for clients verifying a certifi-cate. The value is a URI that points to a CRL that can be used to check if the certificate isrevoked. The CRL is issued by the CA. There are different kinds of CRL Distribution Pointsand currently EJBCA supports a URI.

57 (109)



i Note that you are responsible for the order and encoding of your CRLIssuer,if this is important check it!

A CRLDistributionPoint for a CA in EJBCA could look like:

http://host:port/ejbca/publicweb/webdist/certdist?cmd=crl&issuer=url-encoded-issuerDN

(such as the link from the web distribution pages)

• host is the DNS name by which the CA is accessible. Port 8080 is the default portthat JBoss listens to, but if you changed the JBoss port, this value should also change.

• url-encoded-issuerDN is the CAs common name as configured when the CA was cre-ated. This is the same DN as occurs as Issuer in certificates issued by this CA.

When configuring this extension you should take the URI entered and test it in a normalbrowser, from another machine than the CA, to see that it works before issuing any certifi-cates.It should also be possible to use an LDAP distribution point, if you have configued a publisherto publish CRLs to LDAP.

ldap://yourLdapServer:port_number/cn=CA-test,ou=CRLPUB,dc=mycompany,dc=com?certificateRevocationList

When defining CRL distribution point and CRL issuer in a certificate profile, you canchoose to set the values in either the certificate profile, or in the CA configuration (editCAs). By having the setting in the CA configuration it is possible to use the same certificateprofile for several CAs, otherwise you would have to create a new certificate profile for allCRL distribution points.By checking ’Use CA defined CRL Distribution Point’ you can configure the CRL distributionpoint in the edit CA page instead, and use this value in every certificate profile that uses thatCA. It is a convenience function, so you don’t have to enter the same CDP in all certificateprofiles.

It is possible to configure multiple URLs for CDPs if they are separated by ’;’. Forexample:

http://cdpurl-1/mycrl.der;http://cdpurl-2/crl.crl

The same applies to CRLIssuer, for example:

CN=Foo,C=SE;CN=Bar,C=US

Please note that if an URI contains a ’;’ it has to be double-quoted. For example if youhave two URLs:

• http://cdpurl-1/mycrl.der

58 (109)



• http://cdpurl-2/getcrl;binary

You could then put them together as:

http://cdpurl-1/mycrl.der;"http://cdpurl-2/getcrl;binary"

CRL Issuer

According to RFC3280 a CRL issuer is:

An optional system to which a CA delegates the publication of certificaterevocation lists;The contents of the field in the profile is a DN, like "CN=CRLIssuerForManagementCA,O=foo,C=SE".You have to build the actual CRL Issuer software yourself.

Freshest CRL

(a.k.a. Delta CRL Distribution Point)The Freshest CRL extension is used for Delta CRLs. How to issue delta CRLs is explainedin CA configuration. The freshest CRL extension identifies how delta CRL informationis obtained. The same syntax is used for this extension and the cRLDistributionPointsextension.

OCSP Service Locator

This extension is used when revocation information for the certificate containing this ex-tension is available using the Online Certificate Status Protocol (OCSP) [RFC2560]. TheURI field is the location of the OCSP responder, using the conventions defined in RFC2560,usually a plain URL such as http://ocsp.company.com/. The default URL for the internalOCSP responder in EJBCA is http://hostname:8080/ejbca/publicweb/status/ocsp.

CA Issuer URI

This value is used for the Authority Information Access CRL Extension as specified inRFC4325. The URI specified in this field must point to a certificate containing file con-taining either a single certificate (.cer) or a collection of certificates (.p7c).

Use LDAP DN order

In a certificate the order of the CN components can be put in different order depending onwich standard you abide to.

• Ldap DN order (RFC2253): CN=Common Name, O=Organization, C=Country

• X.500 DN order: C=Country, O=Organization, CN=Common name

59 (109)



In theory the order of the DN should not matter, because comparisons between DNsshould be done on the RDN level. In practice DN comparisons is often done using stringcomparisons, where the string value is depending on the order.For historical reasons EJBCA uses Ldap DN order. Some applications do require X.500 DNorder however and therefore EJBCA gives you the choice. There are two places in EJBCAwhere this can be configured:

• In the Certificate profile (Certificate Profiles)

• In the CA configuration (Certification Authorities)

The relationship between the settings is that they are both evaluated in a logical ANDexpression. This means that if both are true the DN will have Ldap DN order, but if anyone of them is false the DN will have X.500 order.

Extended Key Usage

The meaning of Extended key usage is defined in RFC5280. Normally the values specified inthe fixed certificate profiles are good for the usage the fixed profile is for.

Document Type List

The DocumentTypeList extension is used to indicate the document types (as contained inthe MRZ) that the corresponding document signer is allowed to produce. The list should beseparated with a comma ’,’. For example: "P", or "P,ID"See ICAO MRTD Technical Report LDS and PKI Maintenance for reference.

Private Key Usage Period

The Private Key Usage Period certificate extension is specified in RFC 3280.EJBCA calculates the extension’s notBefore and notAfter components based on the issuingtime of the certificate (cert.notBefore) and the values filled into the "Start offset" (startOff-set) and "Period length" (periodLength) fields as follows:

notBefore = cert.notBefore + startOffsetnotAfter = notBefore + periodLength

Certificate Transparency

This is a module in EJBCA Enterprise Edition that implements Certificate Transparency(CT) as specified in RFC 6962. The purpose of CT is to create public audit logs of allcertificates issued by the public SSL/TLS CAs. The presence of audit records is plannedto be required for EV certificates in Google Chrome from February 2015 (and other webbrowsers and non-EV certificates later on as well). Note that CT is only relevant for CAsissuing public SSL/TLS certificates; other types of CAs should not use CT. More informationcan be found on the CT website.The following options are visibile if the CT module is available:

60 (109)



• Enabled CT Logs: Which logs to submit to and obtain Signed Certificate Timestamp(SCTs) from. New logs can be added in the System Configuration.

• Minimum number of SCTs: If fewer servers respond with an SCT than this number,the underlying operation will fail (certificate issuing or OCSP response).

• Maximum number of SCTs: After having received this number of SCTs, EJBCA willstop contacting log servers.

• Number of retries: If a log server times out it will be tried again after all other logshave been tried. This is the maximum number of tries per server.

If part of the DNS in the SubjectAlternativeName extension should be a secret, thatpart can be redacted and replaced by the String "(PRIVATE)" in the precertificate that willbe published to the Certificate Transparency Log. When adding the end entity to EJBCA,the part of the DNSName that should be redacted in the SubjectAlternativeName in theprecertificate should be surrounded by parentheses. For example, when entering DNSName"(top.secret).domain.se", the precertificate in the Certificate Transparency Log will havethe DNSName "(PRIVATE).domain.se" in its SubjectAlternativeName, but the certificateitself will have the DNSName "top.secret.domain.se" in its SubjectAlternativeName. EJBCAimplements this feature according to RFC 6962.

Cardnumber

Select this if you want to use the SEIS Cardnumber Extension. The card number is a uniqueidentifier stored in the certificate and should also be printed on top of the card on which thecertificate is stored. When used, the card number needs to be set for the end entity beforecreating a certificate. The extension is specified in the the Seis document SS 614331 chapter4.3 and has OID 1.2.752.34.2.1.

Subset of Subject DN

By Using a subset of Subject DN in the certificate you can register users with more infor-mation than is present in the issued certificate. Example:

• Use Subset of Subject DN in a certificate profile, with selected values CN,O and C.

• Register an end entity with CN=Tomas Gustavsson,O=PrimeKey,OU=Ignored,C=SE,and the configured certificate profile.

• Issue a certificate using the certificate profile.

• Issue a certificate. The issued certificate will contain subject DN CN=Tomas Gustavs-son,O=PrimeKey,C=SE.

61 (109)



! Do not use a Subset of Subject DN when issuing CA certificates. Thatcan have undesired consequences, such as colliding CAIds and inability tofind CA certificates.

9.4 RA FunctionsThe RA Functions section provides the administrator access to modify parameters used bythe registration authority (RA) functionality of EJBCA. This section is divided into four maintask areas allowing administrators to:

Add End EntityFacilitates the addition and removal of end entities.

End Entity ProfilesEnd Entity Profiles and End Entity Certificate profiles are used here.

Search End EntitiesQuery the CA to return a list of end entities and edit their specific properties. Thissection provides filters on searching.

User Data SourcesRetrieve information from an external source to propagate the information into EJBCAwhen you add new end entities.

9.5 End Entity profilesEndEntityProfiles defines which parts of user DN should be registered for various types ofend entities. It defines which parts that is already pre-set, and which can be altered etc. Italso contains other information, that is specific to each individual end entity, for issuance ofcertificates.An EndEntityProfile can be connected to specific CertificateProfiles so users belonging to aspecific EndEntityProfile can only get certificates from the specified CertificateProfile.

9.5.1 Create an End Entity Profile for SSL servers

This section will show you how to create an end entity profile suitable for SSL/TLS servers,such as web servers. You should previously have created the certificate profile for SSL serversin the section Create a Certificate Profile for SSL servers.

• Under RA Functions, press End Entity Profiles.

• Enter a name for your end entity profile e.g. SSLServerEndEntityProfile, and pressAdd .

• Select SSLServerEndEntityProfile and press Edit End Entity Profile .

62 (109)



• Under the Subject DN Fields select O, Organization and press Add .

• At O, Organization enter "EJBCA Edu" in the textbox, check the required checkboxand uncheck the modifiable checkbox.

• Under the Subject DN Fields select C, Country and press Add .

• At C, Country enter SE in the textbox, check the required checkbox and uncheckthe modifiable checkbox.

• Under the Subject Alternative Fields select DNS Name and press Add .

• Uncheck "Use" at Email Domain.

• Under Default Certificate Profile, choose SSLServerCertificateProfile (createdearlier).

• Under Available Certificate Profiles, choose SSLServerEndEntityCertificateProfile.

• Under Default CA, choose ManagementCA (the CA you use to issue server certifi-cates).

• Under Available CAs, choose ManagementCA (same as above).

• Under Default Token, choose User Generated .

• Under Available Tokens, choose User Generated , P12 , JKS and PEM(ctrl-click to select multiple).

• Press Save .

9.5.2 Import/Export End Entity Profiles

It is possible to import and export end entity profiles in the AdminGUI in End EntityProfiles.

Export End Entity Profiles

Every non-fixed end entity profile is exported to the specified local directory as an xmlfile inside a zip file named "entityprofiles.zip". The name of the xml file has the formatentityprofile_PROFILENAME-PROFILEID.xml.

Import End Entity Profiles

All profiles to be imported should be included in a zip file. The file containing a singleprofile should be an xml file and its name is in the format entityprofile_PROFILENAME-PROFILEID.xml. Any file with a name that is not in this format will be ignored.

63 (109)



9.5.3 Import/End Entity Profile fields

Password Fields

Passwords are used when a user (end entity) is requesting a certificate and/or when generatinga keystore. Usually this is required and no default value is configured. When the passwordis only used during the request procedure this is called an "Enrollment Code" in the publicweb to avoid making users confused or worried, since it is only valid once and is not used toprotect the keys. There is no difference between an "Enrollment Code" and a "Password"other than the name.You can use auto-generation of passwords with email notification to send the user a generatedpassword together with information on how to fetch the certificate.You can also specify the minimum bit-strength a password is allowed to have in order to makepolicy compliance easier. The strength of a password is calculated as floor(log2(number ofallowed password characters)*(the number characters in the password)). For non-generatedpasswords the number of allowed password characters is estimated to 72. Example usage:

Password: foobar123 (9 characters)Allowed characters: a-z, A-Z, 0-9, 22 additional printable characters (72 intotal)Password strength / char: log2(72) = 6.17Password strength: floor(6.17 ∗ 9) = floor(55.53) = 55bits

Setting this value to 55 will require the RA admin to set a 9 character password or longer.

Subject DN Fields

Subject DN fields define which DN components should be present for an end entity. If"Enable End Entity Profile Limitations" in the System Configuration is enabled this restrictsthe values that can be used when adding or editing an end entity using all interfaces, beit web GUI, web service, cmp or something else. If you define values as required and non-modifyable you can specify one or more values. If you specify multiple values separated by’;’, the admin in the web GUI will get a drop-down list to select from.When having several fields of a certain type with mixed required and not required fields somespecial handling might be needed when adding users using web sevrice API. If you have forexample:

• The first OU field is required (Bar1) and not modifiable.

• The next 3 OU fields are modifiable only (not required).

• The last OU is required (Bar1) and not modifiable.

Then when adding an end entity with DN CN=Foo,OU=Bar1,OU=Bar2 will result in anerror:

64 (109)



org.ejbca.core.model.ra.raadmin.UserDoesntFullfillEndEntityProfile: SubjectDN field ’ORGANIZATIONALUNIT’ must exist.

This is because EJBCA can not keep track of which fields you mean to set, if it is one ofthe required or non-required. To help EJBCA determine this you can specify the non-requiredOU fields with empty values, CN=Foo,OU=Bar1,OU=,OU=,OU=,OU=Bar2.There is one particular subject DN field that deserves extra informations, postalAddress.PostalAddress is not encoded simply as a string as one might think, but is an ASN.1 sequence.If you only enter the value as a string it will be encoded as a simple UTF8String, which isinvalid. You need to enter is as a hex encoded ASN.1 DirectoryString. This is done by hexencoding the ASN.1 object and prepending it with #, i.e. #30...

Subject Alternative Names

Subject alternative names (altNames) are extra naming items that are not fit to have inthe Distinguished Name, such as email, dns, ip address etc. There are a number ofstandard ones, and the possibility to define special ones, which many companies have donefor altNames such as MS UPN, GUID, Krb5PrincipalName.Subject alternative names can be:

• rfc822Name =< email >,

• dNSName =< hostname >,

• uri =< http : //host.com/ >,

• ipaddress =< address >,

• upn =< MSUPN >,

• guid =< MSgloballyuniqueid >,

• directoryName =< LDAPescapedDN >,

• krb5principal =< Krb5principalname >,

• permanentIdentifier =< PermanentIdentifiervalues >

RFC 822 Name (e-mail address) Configuration of email fields can be a bit tricky, sincethere are two places in the End Entity profile where email adresses can be configured:

1. Email field - registers a user email in the EJBCA database (used for email notificationsetc).

2. Subject alternative name field - add an email address to the SubjectAlternativeNamefield in an issued certificate.

65 (109)



These two fields can be the same, but does not have to be, which is why configurationcan be a bit tricky if you configure them individually.For the Subject alternative name field there are different options:

• Use entity e-mail field checked: this results in a single entry for ’End Entity E-mail’when adding a new end entity.

– Required: if checked the End Entity E-mail field must be filled and can not beomitted.

• Use entity e-mail field unchecked: this results in a separate input field for RFC 822Name.

– Required: if checked the ’RFC 822 Name’ field must be filled and can not beomitted.

– Modifiable: if checked the RA administrator can fill in an email address.If a domain (foo.com) is set in the profile the RA administrator can fill in thefirst part of the email, i.e. before @ (since the domain is pre-filled), but also thedomain part can be modified.If Modifiable is unchecked a full, fixed, email address must be provided in theprofile, and all end entities will be registered with this email address (the profilecan be configured with only domain part, but filling an email adress by the RAadministrator later will not work).

IP address An IP address can be either an IPv4 address or an IPv6 address.Example IPv4:

192.168.2.54

Example IPv6:

2001:DB8:85A3:0:0:8A2E:370:7334

Krb5 Principal Name The Krb5 principal name is of the form principal1/principal2@realm,and should be entered as such in the field. Example:

[email protected]

for a normal user in the realm PRIMEKEY.COM.Or:

krbtgt/[email protected]

for a kdc.

66 (109)



Permanent Identifier (RFC 4043) The Permanent Identifier is of the form "identifier-Value/assigner" where identifierValue is an optional string and assigner is an optional OID,and should be entered as such in the field. If the identifierValue string contains a ’/’ (slash)character it should be escaped with an back slash (""). Examples:

abc0123/1.2.3.4abc0123//1.2.3.4/

Certificate Validity

By setting the Certificate Validity Start Time and End Time you can precisely specify, fora specific end entity, when the certificate will start being valid and when the certificate willcease being valid. When selecting to use Certificate Validity Start or End time you will getthe possibility to enter these fields when a new end entity is added. You can also specify adefault value for the end entity profile. Different formats of specifying the validity time isprovided as examples in the end entity profile page.This function requires the Allow validity override function in the Certificate Profile.

Revocation reason to set after certificate issuance

Using this option you can define that when adding a new user, the revocation state ofan issued certificate can be set immediately to something else than ’Active’. Useful if youwant to issue certificate that are ’On hold’ for users. After the user receives the certificatethey might be required to perform some action in order to have their certificate activated.Most useful when used in combination with OCSP since it will require, in practice, instantrevocation checking.When enabling this option in the profile, a corresponding selection will be available whenadding new users. The user data corresponding to this option is an ExtendedInformationattribute, ExtendedInformation.CUSTOM_REVOCATIONREASON.

Reverse Subject DN Alt Name Checks

This checkbox is not recommended to be used in normal operations. When using the ExternalRA and more than one DN field type is set in the profile, for example one optional OU andone required OU, it might be needed to check this checkbox for the profile validation towork.Only use it in such a special case, if nothing else work. This option may be removed in thefuture.

Maximum number of failed login attempts

By choosing a maximum number of failed login attempts the status of a user will change toGENERATED in case a wrong password is entered more than the specified number of times.

67 (109)



Note that what is called a "password" in the admin web is often called an "enrollment code"in the public web. The checkbox "Use" must be checked for the end entities to use thisfeature. If the checkbox "Modifiable" is checked the specified number can be changed for aparticular end entity at the creation time of the end entity or later by editing it.

Custom certificate extension data

By checking ’Use’ for custom certificate extension data in the end entity profile an text areais provided when adding or editting an end entity for supplying custom certificate extensiondata.Extension data are entered in the text area in the same format as for Java properties files.Typically key=value with one entry one each line. What extension data that is acceptedand/or required depends on what custom extensions that has been chosen in the certificateprofile as Used Custom Certificate Extensions and how they are configured.For example custom extensions of type BasicCertificateExtension configured with the prop-erty dynamic=true accepts custom extension data of the form "OID.value=value" where OIDis the OID of the configured extension and value is the value to put in the extension in theconfigured encoding.

1.2.3.4.value = 65486c6c206f6f776c7200641.5.6.value = Helloworld

An example configuration of a certificate extension taking dynamic value in RAW haxencoded format is:

id1.oid = 1.2.3.4id1.classpath=org.cesecore.certificates.certificate.certextensions.BasicCertificateExtensionid1.displayname=SingleExtensionid1.used=trueid1.translatable=falseid1.critical=falseid1.property.dynamic=trueid1.property.encoding=RAW

Number of allowed requests

By checking ’Use’ for number of allowed requests you enable the possibility to request severalcertificates in a row, without the user status being set to generated. Normally after ausername/password pair has been used to generate a certificate, the users status is setfrom ’new’ to ’generated’. This makes the password invalid, thus implementing a one-timepassword scheme. By selecting a number higher than one for ’number of allowed requests’the user can request several certificates before the status is set to ’generated’. This makesit possible to enroll for several certificates directly, for example one authentication and onesignature certificate.

68 (109)



The number of allowed requests in the End Entity Profiles will set the default, andmaximum value available when adding or editing a new end entity. When editing an existingend entity and setting the status to new, from a non-new status, the ’number of allowedrequests’ will automatically be altered to the default value for the profile. If the end entityprofile used no longer uses the ’number of allowed requests’ the request counter for the endentity will be removed when the end entity is edited.

9.6 End Entities

9.6.1 Creating Users

Users are added in the Admin GUI, Add End Entity. If a ’,’ is needed in the DN the commamust be escaped using ’ ’.

9.6.2 Create server certificates

A good way to create server certificates is to generate a PKCS12, JKS or PEM file for theserver, depending on what server it is. This means that the private key is generated by theCA, you do not have to generate a CSR on your server for this. To do this:

1. Create desired profiles (the default entity and certificate profiles work fine, but areperhaps too generic). You certificate profile should have:

• KeyUsage: Digital signature , Key encipherment

• Extended key usage: Server Authentication

2. Create a user with the Admin GUI.The Distinguished name (DN) of the server should have the the servers full host-name (host.domain.com) in the CommonName (CN) field.Example DN for webserver: C=SE,O=AnaTom,CN= www.anatom.se, or for mailserverC=SE,O=AnaTom,OU=Engineering,CN=mail.anatom.se.You can also put the same name (or several names) as a DNSName in SubjectAlter-nativeNames.For so-called wildcard certificates, use *.anatom.se.Set the token type to match the kind of token that should be generated for your server.

3. To be able to batch-generate certificates, the batch generation program must haveaccess to the users (servers) password in order to request a certificate on behalf of theuser. Normally the password is stored in hashed form.

4. To generate keys and certificates use the Public Web.

Many servers (ex Apache, Tomcat) wants keys and certificates in PEM-format (Apache) orSUN JKS (Tomcat). To generate PEM-files use token type PEM. The generated PEM-filescan be used with Apache etc, and are NOT protected by any password.

69 (109)



To generate JKS-files use token type JKS. The generated JKS- files can be used with Tomcatetc, and are protected (both private key password and keystore password) by the userspassword.If the server generates the keys and a certificate request (CSR) for you, select token type "Usergenerated". You can use the public enrollment web pages (http://127.0.0.1:8080/ejbca/) topaste the request and receive the certificate. This function is under Create Certificatefrom CSR in Public Web.It is also possible to use openssl to transform a PKCS12 file to PEM- format.

openssl pkcs12 -in pkcs12-file -nodes

copy and paste the private key to key file, the first certificate to server cert file and lastcertificate to CA cert file (If your CA is a subordinate CA to another Root CA, the CA certfile may need to contain the whole cert chain). Exactly how your server wants the files isserver dependent.

For your convenience, here is the standard text (RFC2818) how browsers validate thename(s) in the certificate.

If a subjectAltName extension of type dNSName is present, that MUST beused as the identity. Otherwise, the (most specific) Common Name field inthe Subject field of the certificate MUST be used. Although the use of theCommon Name is existing practice, it is deprecated and Certification Authoritiesare encouraged to use the dNSName instead.Matching is performed using the matching rules specified by [RFC2459]. If morethan one identity of a given type is present in the certificate (e.g., more thanone dNSName name, a match in any one of the set is considered acceptable.)Names may contain the wildcard character * which is considered to match anysingle domain name component or component fragment. E.g., *.a.com matchesfoo.a.com but not bar.foo.a.com. f*.com matches foo.com but not bar.com.In some cases, the URI is specified as an IP address rather than a hostname. Inthis case, the iPAddress subjectAltName must be present in the certificate andmust exactly match the IP in the URI.

9.6.3 Issue a new PKCS#12 keystore for an SSL server

This section will show you how to issue a PKCS#12 keystore suitable for SSL/TLS servers,such as web servers. You should previously have created the certificate profile and end entityprofile for SSL servers in the sections above.

• Goto RA Functions -> Add End Entity.

• Choose the end entity profile SSLServerEndEntityProfile.

• At Username enter testsrv.domain.com.

• At Password enter a password.

70 (109)



• Under CN, Common Name enter testsrv.domain.com.

• And at DNS Name enter testsrv.domain.com.

• Under Certificate Profile you should not be able to choose anything but the defaultSSLServerCertificateProfile .

• Under CA you should not be able to choose anything but the default ManagementCA.

• Under Token, choose P12 .

• Press Add .

• Goto Public Web and then Create Keystore.

• Enter the username, testsrv.domain.com, and password for the user you created, andpress OK .

• Choose Key length 1024 .

• Under Certificate Profile you should not be able to choose anything but the defaultSSLServerCertificateProfile .

• Press OK .

• A new certificate will be generated and downloaded to your desktop.

• If you like you can import the P12 file (double-click it on windows) to look at thecertificate inside.

9.6.4 Issue a new server certificate from a CSR

This section will show you how to issue a certificate suitable for SSL/TLS servers from aCSR generated by the server. You should previously have created the certificate profile andend entity profile for SSL servers in the sections above.

1. Goto RA Functions -> Add End Entity.

2. Choose the end entity profile SSLServerEndEntityProfile .

3. At Username enter testsrv.domain.com.

4. At Password enter a password. It will be used only during enrollment, as a one-timecode.

5. Under CN, Common Name enter testsrv.domain.com.

6. And at DNS Name enter testsrv.domain.com.

71 (109)



7. Under Certificate Profile you should not be able to choose anything but the defaultSSLServerCertificateProfile .

8. Under CA you should not be able to choose anything but the default ManagementCA.

9. Under Token, choose User Generated .

10. Press Add .

11. Goto Public Web and then Create Certificate from CSR.

12. Enter the username, testsrv.domain.com, and password for the user you created. Notethat the password field is called Enrollment code here. Paste the CSR from the serverand press OK .

13. A new certificate will be generated so you can download it to your desktop.

9.6.5 Create User certificates

To enroll for a certificate using a browser, go to http : // < your_server_name :servlet_container_port > /ejbca/ (e.g. http://127.0.0.1:8080/ejbca/) and select Create

Browser Certificate. Enter username and enrollment code, click the OK button andfollow the instructions.To enroll for certificates manually (e.g. for server certificates), go to http : // < your_server_name :servlet_container_port > /ejbca/, select Create Certificate from CSR and fill out theform.Note that application for certificates only work when the status of a user is NEW, FAILED orINPROCESS (one time password thing). The status is set to GENERATED after a certificatehas been issued. To issue a new certificate, the status must be reset to NEW, which can bedone through the Admin GUI.During batch generation of certificates, users with status NEW or FAILED are generated.This is due to the possibility that a batch generation for some reason failed. If it fails statusis set to FAILED and you can try again after fixing the error.

9.6.6 Certificate Renewal

Certificate renewal is a often missunderstood term. Certificate renewal simply means issuanceof a new certificate containing the same public key as an already issued certificate. It doesnot mean issuing a new certificate with the same certificate serial number, and it does notmean that the CA in some magical way has access to the end entitys private key.To renew a certificate using the admin GUI, simply:

1. Go to Search End Entities and find the end entity in question.

2. Set status to NEW .

72 (109)



3. Have the end entity create a new certificate request (CSR), using the same public keyas the first certificate.

4. Send the new certificate request to the CA (the same way you did when getting thefirst certificate).

5. Get the certificate back.

Since the CA has all public keys of end entities, as they are in the certificates that the CAstores, this process can be automated. How to automate that is more advanced and can bedone in many ways, suitable for different work-flows. How to do that is not described here.

9.7 AdministratorsAn EJBCA Administrator is identified by information in the client TLS certificate. Theinformation is validated in the following steps:

1. During the TLS handshake with the application server, the issuer of the client certificateis verified with a list of trusted CA certificates known as the ’truststore’.

2. EJBCA verfies that the client certificate exists in the database and that it’s not revoked.

3. EJBCA tries to match the information in the certificate with any of the matching crite-rias found in the different roles. Matching rules are evaluated separately so matchingwith both CN and OU would match all CN matched certificates and also all OUmatched certificates.

4. If a match is found, the access rules for this group is given to the administrator.

Administrator privileges is configured through Administrator Roles under System func-tions in the Admin GUI. If you have locked yourself out of the GUI, the CLI can add anotheradmin certificate to allow continued operations.

9.7.1 Renewing Superadmin

Renewing the superadmin certificate is done in the same way as for any client certificate.You can use either the Admin GUI or the CLI to renew the superadmin. The superadmincertificate is normally issued as a PKCS#12 keystore (if not issued as a browser certificatefor smart card enrollment).Using the admin GUI:

1. Go to Search End Entities.

2. Search for user superadmin.

3. Click Edit End Entity.

4. Set a new password and set status to NEW, click Save.

73 (109)



5. Go to Public Web and then Create Keystore.

6. Enter superadmin username, and the password you gave.

7. In the next screen, select key length 2048 and click OK .

8. Your new superadmin keystore is downloaded. You can install it in your browser.

9.8 Administrator RolesThis section is a tutorial that will guide you through creating a new administrative user andnew role with limited privileges. A role is assigned certain access rules, and users are assigneda role. All users assigned to a role will have the access privileges defined by the access rulesin this role.

9.8.1 Roles created during install

During installation EJBCA created a super administrator role, by default called the SuperAdministrator Role. By default this role:

• has overall access to EJBCA

• can edit system configuration

• can manage CAs

• can manage publishers (LDAP, AD, custom)

• can create CA administrators

9.8.2 Pre-defined Role Templates

EJBCA also comes with three default role templates designed to cover most use cases, orto be easily extendable. If none of these are suitable a role can be created with the Customtemplate and be manually configured in Advanced Mode.

• The CA Administrator:

– manages certificate profiles– manages end entity profiles– manages log configuration– can create RA administrators– can renew a CA with new certificate and new keys– can have full read access to the audit log

• The RA Administrator (those options can be enabled):

74 (109)



– can create end entities– can modify end entities– can revoke end entities– can delete end entities– can view existing end entities and their history– can have full read access to the audit log

• The Supervisor:

– can view created end entities– has full read access to the audit log

9.8.3 Advanced access rules

When editing access rules, you can click on Advanced mode to get access to advanced accessrule configuration. In this mode you will see all available access rules, in detail, and canaccept or reject specific rules for the role you are editing. The rules are numberous, andnew rules may be included in new versions of EJBCA. They have somewhat human readablenames and can often be figured out. See ’ About Roles and Rules’ below for a detaileddescription how the principe of access rules work.Using advanced access rules you can define you own roles in detail and construct a role setsuitable for most auditing schemes.

9.8.4 Creating a new administrator

This example will walk you through creating a new administrator certificate, adding thisadministrator to a role and testing the access.

Creating a Certificate Profile For the Administrator

This section will show you how to create a new Certificate Profile for administrators. Theadministrators certificates will be issued by a CA called ManagementCA

• Under CA Functions -> Certificate Profiles

• Clone template ENDUSER

• Enter a name for your end entity certificate profile e.g. AdministratorEndEntityCertifi-cateProfile

• Press Create from template

• Select "AdministratorEndEntityCertificateProfile"

• Press Edit

75 (109)



• Under Validity enter 365d (1 year validity).

• Under Key usage, choose Digital Signature and Key encipherment .

• Un-check Allow Key Usage Override.

• Check Extended Key Usage.

• Under Extended Key Usage, choose Client Authentication .

• Under Available bit lengths, 1024 bit , 2048 bit and 4096 bit .

• Under Available CAs, choose ManagementCA (the CA you use to issue admincertificates).

• Press Save .

Creating an End Entity Profile for the Administrator

This section will show you how to create a new End Entity Profile for administrators. Theprofile will be connected to the Certificate Profile created above.

• Under RA Functions -> End Entity Profiles

• Enter a name for your end entity profile, AdministratorEndEntityProfile

• Press Create

• Select AdministratorEndEntityProfile and press Edit End Entity Profile

• Under the Subject DN Fields add a few DN fields that you want in the admin DN,for example O, UID and C.

• Under Default Certificate Profile, choose AdministratorEndEntityCertificateProfile

• Under Available Certificate Profiles, choose AdministratorEndEntityCertificateProfile

• Under Default CA, choose ManagementCA

• Under Available CAs, choose ManagementCA

• Press Save

Issue the following new end entity based on the new end entity profile.CN: SoftCard RA Admin1

76 (109)



Creating a new RA Role

The RAadmin shall have access to add/list/edit end entites. To create a new role:

• Choose Administrator Roles in the left frame.

• Press Add .

• Choose a name for your new administrator group, RAAdministratorRole.

• When the group is created, press Access Rules.

• Choose the RA Administrator role template.

• Under Authorized CAs, choose which CAs the role should have access to. ChooseManagementCA .

• Under End Entity Profiles Select AdministratorEndEntityProfile .

• Press Save .

Adding new Administrators to the RA Role

• Choose Search End Entities and select your newly created end entity, choose ViewCertificates.

• Copy the value of Certificate Serial Number, e.g. 5F003A0113F507F9.

• Go to Administrator Roles, press Administrators under RAAdministratorRole .

• Choose the CA that the administrator belongs to, ManagementCA .

• Paste the text from Certificate Serial Number in the Match value.

• Press "Add"

Test the new administrator

Try to log in with the new administrators to see the difference between that and the super-admin. You should also try the different roles and privileges to see the differences betweenthem all.

i Note that the authorization privileges are cached and there will be a delaybefore a rule change is used.

77 (109)



9.8.5 About Roles and Rules

Roles and Rules

Permissions in EJBCA are never given out on an individual basis, but to a certain Role whichcontains a list of aspects and access rules. While Roles can be named at the user’s discretion,Rules represent the resource they are named after. Access to this resource is also associatedwith an AccessRuleState, which may be one from the following table.

Rule Type DescriptionUnused This explicitly declares that a Role does not have a rule for this resource.Accept Access is granted for this resource. If set to be recursive, Accept

will also be default for any rules of type Accept deriving this rule.Decline Access is denied for this resource. Will trump any recursive Decline

rules previously encountered.

Table 9.8: Access Rule States

The Access Tree

Resources are created according to a hierarchical structure, much like a file tree. A typicalresource could be /ca_functionality/create_certificate which consists of three subresources:the root , its child ca_functionality and the end node create_certificate. If desired, a Rulecould be applied to any one of these. Access to the end resource (create_certificate) canbe granted by either giving it the value Accept or setting Accept for any of its parentsnodes and setting them as recursive. Access can be denied by setting access to it or any ofits parents as Accept or using Unused the whole way down. This is further illustratedby the following figure (see fig. 9.1):

78 (109)



Figure 9.1: Access Tree.

Requesting access to the above resources will result in the following table:

/ Denied Status is unknown, hence denied./a Denied Explicitly denied./a/a Denied Even though /a/a is granted, /a explicitly denies access to its children./b Granted Explicitly granted./b/a Granted Granted thanks to the recursive accept in /b./b/a/a Denied Explicitly denied, which trumps the recursive grant in /b/a./b/a/a/a Denied Denied as a result of /b/a/a.

/c Granted Explicitly granted./c/a Denied Unknown in spite of the fact that /c was granted, hence defaults to denied./d Denied Unknown, hence denied./d/a Granted Explicitly granted.

Table 9.9: Access Rules

9.9 View Log optionsWhen viewing the log, you can chose what logs to see by chosing an option from a list:

EventYou can chose what kind of event to see. For example, Administrators logged in, CArelated activities, certificate related activities, End Entity related activities, activitiesthat caused error... etc.

79 (109)



CAYou can chose to see all the logs related to a specific CA.

ModuleYou can chose to see all the logs related to a specific module, tex. CA, RA, PublicWeb, Hard Token, Approval, Service... etc.

UsernameYou can chose to see all the logs related to a specific username.

CertificateYou can chose to see all the logs related to a specific certificate. The certificate isspecified by its serialnumber written in hexadecimal format.

Administrator CertificateYou can chose to see all the logs created by a specific administrator. The administratoris specified by his certificate serialnumber written in hexadecimal format.

CommentYou can chose to see all the logs created with a specific comment.

Administrator detailsYou can chose to see all the logs created by a specific type of administrator, his orher IP address or the hexadecimal serialnumber of the administrator certificate used.There are six types of administrators:

• An administrator who logs in with a certificate. Typically an administrator whologs into the Admin GUI to perfom tacks that need administrator privileges. Anadministrator who logs in with a certificate is loged with his certificate serialnum-ber and SubjectDN.

• An administrator who logs into the public web using only username and password.An administrator who logs into the public web is loges with his IP address.

• An RA user. The RA user is loged with his IP address.• An administrator performing administrative tasks through commandline.• An administrator performing administrative tasks through batch commandline.• An internal user performing tasks within Ejbca.

The log can be displayed on the screen or exported as a XML file.

9.10 Managing Internal Key BindingsAll Internal Key Bindings share the following properties:

• Type: OcspKeyBinding or AuthenticationKeyBinding.

80 (109)



• Id: Unique identifying number.

• Name: A unique and human readable name.

• Crypto Token: The Crypto Token where we reference a key pair.

• Key Pair Alias: A reference to the currently used key pair in the specified CryptoToken.

• Signature Algorithm: The signature algorithm user during signing, for example thesigning of an OCSP response.

• Next Key Pair Alias: A reference to the next key pair to use in the specified CryptoToken when renewing.

• Bound Certificate: A certificate issued for the current key pair’s public key.

ActionsFrom the overview page the following actions are available:

• Enable/Disable: Marks the Internal Key Binding as Active/Disabled. OnlyActive ones will be used and processed by health-check.

• Delete: Removes the Internal Key Binding, but will not remove the referencedkey pair or certificates.

• New keys: Generates a new key pair in the referenced Crypto Token using thesame key specification as the current key has and an alias derived from the currentalias.

• CSR: Creates a Certificate Signing Request using the next key pair (or currentkey pair when no next key pair exists).

• Update: Searches the database for the latest issued matching certificate forthe next key pair (or current key pair when no next key pair exists) by usingSubjectKeyId.

• Renew: When the CA that issued the current certificate is active and resides inthe same instance, this will create a new certificate using the same End Entity asthe last one was issued with. If a next key pair exists, that key pair will be used.

OcspKeyBindingA CA can delegate the signing of OCSP responses to a separate key pair. This isconfigured as an Internal Key Binding.

• The certificate must have Key Usage: Digital Signature .

• The certificate must have Extended Key Usage: OCSPSigner .• The certificate normally has the "OCSP No Check" extension enabled.• The list of trusted certificates will be used to validate the OCSP request signature

(if a signature is required).

81 (109)



Implementation specific properties:

• Non existing is good: If true a certificate that does not exist in the database, butis issued by a CA the responder handles will be treated as not revoked. Default(when both this value and value of "Non existing is revoked" are false) is totreat it as "unknown". Since the OCSP responders database normally containsall issued certificate this gives sensible values (in line with RFC6960) to "ok","revoked" and "unknown" certificates. Setting this value to true is useful if youwant an External OCSP responder database to only contain revoked certificates,and not all certificates. In this case the responder will answer "ok" to requestsfor certificates that do not exist in the database. If both "Non existing is good"and "Non existing is revoked", the responder will answer "ok"

• Non existing is revoked: If true a certificate that does not exist in the database,but is issued by a CA the responder handles will be treated as revoked; therevocation reason will be "Certificate Hold" and the revocation time is January1st, 1970. Default (when this value and value of "Non exsiting is good" are false)is to treat it as "unknown". If both "Non existing is good" and "Non existing isrevoked", the responder will answer "ok".

• Max-Age HTTP header (seconds): A hint to caching proxies when usingHTTP GET for how long to retain a response.

• Request must be signed with a trusted certificate: When true, request sig-natures will be checked against the list of trusted certificates or trust anchors.

• Response validity (seconds): How long the OCSP response is valid and maybe used.

• ResponderID: Defines the ResponderID type included in the response. TheResponderID is either a Name (SubjectDN of the signing certificate used forresponse) or Keyhash (SHA-1 digest of the public key of the signing certificateused for response).

• Include signing certificate in response: When true, the signing certificate willbe included in the response.

• Include certificate chain in response: When true, the entire certificate chain,except for the root CA certificate, will be included in the response (note that thisis only applicable if ’Include signing certificate in response’ is true).

AuthenticationKeyBindingThe identity in outgoing SSL connections is configured as an Internal Key Binding.

• The certificate must have Key Usage: Digital Signature and Key Encipher-ment.

• The certificate must have Extended Key Usage: Client Authentication.• The list of trusted certificates will be used to validate the server side SSL certifi-

cate.

No implementation specific properties exist for this Internal Key Binding.

82 (109)



9.11 Managing Remote SystemsAn EJBCA instance can be both target and initiator of remote operations from anotherEJBCA instance. Connections are made using dual authenticated HTTPS. This is similarto how you use a client certificate to authenticate to the AdminGUI and then manage anEJBCA instance, but in this case the configured administrator is another EJBCA instace.Normally the instance with higher security requirements (e.g. an EJBCA acting as CA)initates connections to a system with lower security requirements (e.g. an EJBCA acting asVA).In the Remote Systems overview you can:

• Modify global settings like enabling or disabling incoming connections.

• See a list of configured known remote systems that this instance can connect to (PeerConnectors) and their current connection status.

• See a list of systems that have connected to this instance recently (Incoming Connec-tions).

Additionally there are links to the relevant authentication settings for outgoing connections(AuthenticationKeyBinding) and incoming connections (Administrator Role).

Setting up Peer Connectors for outgoing connectionsOutgoing connections are allowed by default and can be disabled by administratorsauthorized to /peer/modify recursive.A Peer Connector is a representation of a remote EJBCA instance and can be refer-enced by other components like Publishers and Services. Each Peer Connector main-tains a pool of outgoing re-usable (HTTP Keep-Alive) connections and new connec-tions are only created when needed.To authenticate to the remote system, you need to configure an AuthenticationKeyBinding.The AuthenticationKeyBinding is the EJBCA instance identity and consists of a clientTLS X.509 certificate and a key pair in one of the instance’s Crypto Tokens. Ensurethat the AuthenticationKeyBinding is configured to trust the remote system’s serverTLS certificate or the connection will fail. AuthenticationKeyBinding settings are onlyread when a Peer Connector’s connection pool is stared and if the client certificate isupdated this will not take affect until a connection pool is Reset.For each configured Peer Connector, you can see the human readable name, connec-tion end point and current connection status. You can Ping any of the remote systemsto check connectivity and the result is the round-trip time from and to the applicationover the secure connection (giving a more accurate view of the actual round trip timethan a network ping using the ICMP protocol).Only the first connection to a remote system using the same client certificate will besubject to a full authentication check and subsequent requests will share the same cre-dential. This means that an initial Ping request to a peer system will be significantlyslower than the next one.

83 (109)



Adding a Peer Connector

Outgoing connections must be allowed to be able to add a new Peer Connector. Fromthe Remote Systems overview, click the Add button. Configure the following fieldsand click Create .

• Name: Your name for the remote system.• URL: The target end point where the remote system is listening. Normally you

only need to change the hostname of the URL.• Enabled: If a Peer Connector is enabled connections to the remote system are

allowed to be created when needed.

Edit, Clone or Delete a Peer Connector

From the Remote Systems overview, click the Edit button for an existing Peer Con-nector. In the view of the Peer Connector you can modify and save the existing name,URL or state. In the Edit view, you additionally have buttons for cloning (Clone) ordeleteing (Delete) the current object.

Incoming connectionsIncoming connections are not allowed by default and can be enabled by administratorsauthorized to /peer/modify recursive.In the list of incoming connections, you can see systems that have successfully con-nected to the EJBCA instance with a client certificate trusted by the application server’sTLS configuration. If the client certificate presented by the connecting system is al-ready part of an Administrator Role, the name of this role will be shown.

Authorization of incoming connections

If no Administrator Role exists for the connecting system’s client certificate, you arepresented with a Create Authorization button. Clicking this button will allowyou to quickly setup a new Administrator Role with for the incoming client certificateand a relevant set of access rules or add the incoming client certificate to an existingAdministrator Role.If an Administrator Role already exists for the connecting system’s client certificate,you are presented with a Modify Authorization button where you can change therelevant set of access rules for the Administrator Role.Note that this is just a simplified view of EJBCA’s normal authentication and autho-rization management and the created Administrator Role can be edited just like anyother Administrator Role.

Management operations for a remote systemOnce an EJBCA instance has been authorized to connect and manage another EJBCA

84 (109)



instance, operations on the remote system can be performed through the Admin GUIof the authorized instance.The administrator initating these operations needs to be authorized to the /peer/view/peer/manage access rules and additionally any relevant CA.

Publishing using Peer Connectors

Publishers are used to propagate certificate or CRL information to a remote system.The PeerPublisher implementation allows this information to be pushed to a configuredPeer Connector.The connecting system needs to be authorized to the /peerincoming /peerpublish/write-cert /peerpublish/writecrl /ca/[CAName] access rules to be able to push both certifi-cate and CRL data.

Certificate data synchronization

In a setup where an EJBCA CA instance (or a cluster) uses external EJBCA VA/OCSPresponders, revocation information needs to be propagated from CA to VA. Informa-tion about newly issued certificates and revocation updates are normally sent usinga (Peer)Publisher, but the first time a new VA is connected the current state of allpreviously issued certificates needs to be pushed to the VA.In the overview of peer connectors, click Manage for the peer connector represent-ing the VA and select the Certificate Data Synchronization tab. Configure the relevantsubset of information to synchronize and click Start to initate the synchronzationas a background task. The progress can be followed either in this view or in the remotesystem overview.Note that the subset of revocation information to send affects how database queriesare performed. Depending on your database it might be faster to only synchronizeeverything or only one subset of data at the time.The connecting system needs to be authorized to the /peerincoming /peerpublish/read-cert /peerpublish/writecert /ca/[CAName] access rules to be able to check synchron-zation data and push missing or outdated certificate entries.

Renewal of remote Internal Key Bindings

In a setup where an EJBCA CA instance (or a cluster) uses external EJBCA VA/OCSPresponders, a CA delegates signing of OCSP responses to an OCSP singing certificate(configured as a OcspKeyBinding) at the VA. The OCSP singing certificate shouldbe short lived and to make renewal easier, this is available as a remote managementoperation on the CA.In the overview of peer connectors, click Manage for the peer connector representingthe VA and select the Remote Key Bindings tab. Click Renew to generate a new

85 (109)



certificate. Optionally you can also select to generate a new key pair for the nextOCSP signing certificate.Renewal of remote Internal Key Bindings can be automated using a Remote Internal Key Binding Updaterservice.The connecting system needs to be authorized to the /peerincoming /internalkeybind-ing/view/[IKB] /internalkeybinding/modify/[IKBName] /cryptotoken/view/[CTName]access rules to be able to renew an Internal Key Binding certificate. Additionally /cryp-totoken/keys/generate/[CTName] is required if key renewal should be allowed.

9.12 Supervision FunctionsThe supervision section provides several main task areas for performing supervisory tasks onEJBCA, The tasks are described below. This section is relevant for dual role managementas it provides tasks that would normally be performed by a second user or an auditor.

Approve ActionsUsed when approvals queues are configured for use on your CA(s). In this queue youwill see pending approvals.

i More information about approvals will be covered in later lessons.

View LogThis section allows an operator to perform advanced searches and view the EJBCA logstored in the database.

9.13 System FunctionsThe System Functions section provides the necessary menu options for the overall adminis-tration of the CA system.

Administrator RolesThe Administrator roles function allows users to be assigned to roles. This section alsoallows the creation of additional roles for fine grained access controls.

Internal Key BindingsAn Internal Key Binding can be used to make keys in a Crypto Token available forother uses than in a CA. Internal Key Bindings is a new feature introduced in EJBCA6.

ServicesEJBCA has the provision to be able to manage and run timed services. This menuoption allows the creation and management of timed services.

86 (109)



9.14 System ConfigurationThe System Configuration option allows for the management of certain global settings re-lating to the system.

CMP ConfigurationThe CMP configuration allows the configuration of EJBCA as a CMP server for re-ceiving and processing CMP requests and sending responses.

SCEP ConfigurationFrom this menu we can manage SCEP aliases and configure them as CA or RA mode.

System ConfigurationSystem can be configured from this menu. Some optrion that are configurable areEnable Key Recovery, Clear All Caches, Enable CLI, etc.

9.14.1 My Preferences

This menu option allows a user to customise settings specific to the user like the languageand any styling options pertinent to the interface.

9.15 Other InterfacesEJBCA provides additional methods of communicating with the available functions and tasksother than the two aforementioned web interfaces. Interfaces can be accessed via a commandline or connected to or from your own applications using web services. A list of some of themost commonly used interfaces are:

• Online Certificate Status Protocol (OCSP)

• Simple Certificate Enrolment Parotocol (SCEP)

• Certificate Management Protocol (CMP)

• Light Weight Directory Access Protocol (LDAP)

• External RA API

• Web Services

87 (109)


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

Chapter 10

PKCS#11 Slot Smart CardActivation

10.1 IntroductionAll sensitive cryptographic material of the PKI Appliance is stored on a Hardware Secu-rity Module (HSM). This HSM protects your key material against physical attacks. Thekeys required by the PKI Appliance and your infrastructure are organized in so-called slots,commonly used with the cryptographic API PKCS#11. To operate on these keys, theseslots must be activated with some authentication code. Depending on your requirementsfor availability, usability and security, you can select whether those authentication codesshould be stored on the PKI Appliance or not. This can be chosen per slot. Slots withstored authentication codes can be auto-activated for immediate availability. The generatedand automatically stored authentication codes are of very high quality. This choice can bechanged even later during the operation of the PKI Appliance.If even manually entered authentication codes do not meet the security requirements, thereis an option for a two-factor authorization: It is possible to additionally require an activationwith smart cards for one or more slots. This choice has to be done during installation.

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

88 (109)



10.2.1 "Number of users required"

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

10.2.2 "Number/copies of user smart cards"

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

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

10.2.3 "Require smart cards to activate system after boot"

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

10.2.4 Procedure

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

• The user credentials are generated in memory.

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

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

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

89 (109)



10.2.4.1 Example with default values

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

• Backup key shares handling

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

• Handling of one slot activation user

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

10.2.4.2 Slots 0 and 1

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

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

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

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

90 (109)



10.3.1 Activation on boot/slot 0

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

91 (109)


Ver: 3.0.0

Part VI

SignServer

92 (109)


11. INTRODUCTION TO SIGNSERVER Ver: 3.0.0

Chapter 11

Introduction to SignServer

SignServer is a server-side application that implements cryptographic document operations.There are many situations where client applications can not or may not perform crypto-

graphic operations themselves, but have to refer those operations to a specialized instance.SignServer can be used to provide signatures in different applications managed from one

location in the company or in a data-/trust-center environment.SignServer can be deployed as:

• Time-Stamp Authority (TSA), RFC#3161 and MS Authenticode

• Machine Readable Travel Documents (MRTD) signer and CSCA Master List signer,for ePassports

• PDF signer, including support for visible signatures, embedded CRLs and OCSP re-sponses

• Cryptographic Message Syntax signer (CMS, PKCS#7)

• MS Authenticode (Windows) code signer

i SignServer is an optional feature on the PKI Appliance. The following chap-ters are only relevant for PKI Appliances with the SignServer applicationenabled.

93 (109)


12. SIGNSERVER WEB PAGES Ver: 3.0.0

Chapter 12

SignServer Web Pages

SignServer provides multiple interfaces for administration as well as for submitting documentsfor signing. This chapter covers the web interface which among other things can be used forsubmitting files/documents to be signed as well as for downloading the Administration GUIapplication or to access the Administration Web interface.

12.1 Accessing the web pagesThere is a link to the SignServer application in the WebConf Platform tab and underServices access (see fig. 12.1).

Figure 12.1: Accessing SignServer from the WebConf

The web interface can also be accessed directly by using the IP address of the applicationor Management Interface of the PKI Appliance and with /signserver/ on the end of theaddress.

94 (109)



Figure 12.2: SignServer public web interface

12.2 IndexThe root page of the SignServer web interface lists available the available pages:

Signing and Validation DemoWeb pages with various upload forms for requesting signing (or validation) of docu-ments or files of different types.

Health CheckWeb page giving a status for all the configured workers. Either "ALLOK" or a failuremessage.

DocumentationThe SignServer documentation for the version of SignServer running on the PKI Ap-pliance. Contains the complete SignServer manual with the information needed toadministrate SignServer.

Client CLI DownloadWeb page offering the Client CLI bundle for download. The bundle is a ZIP archivecontaining the SignClient tool that can be used to send signing requests to SignServer.

Administration GUI DownloadWeb page offering the SignServer AdminGUI bundle for download. The bundle is a ZIParchive containing the SignServer Administration GUI Java application pre-configuredwith the Management CA certificate and the hostname or IP address of the ApplicationInterface of the PKI Appliance installation.

95 (109)



Administration WebThe Administration Web is the new way of administrating SignServer instead of usingthe old Administration GUI.

SignServer Web SiteLink to the signserver.org web site.

96 (109)


13. SIGNSERVER ADMINISTRATION WEB Ver: 3.0.0

Chapter 13

SignServer Administration Web

The SignServer Administration Web is the main way of configuring, administrating andmanaging SignServer on the PKI Appliance. As an alternative the old Administration GUI isalso available. See chapter 14.

13.1 Accessing the Administration WebOn the SignServer web pages (see chapter 12), click on Administration Web link.

Figure 13.1: SignServer Web Pages

The interface requires HTTPS with mutually authenticated TLS. This means that theweb browser must have access to your client certificate that you got when the PKI Appliance

97 (109)



was installed.

Figure 13.2: Initial Administration Web.

13.2 Main PageThe main page consists of multiple parts such as the top menu with links like Workers, GlobalConfiguration, Administrators etc. At the right-most side is the Documentation link whichlinks to the SignServer Manual documentation for the currently visible page.

This section only describes some of the components in the Administration Web. For acomplete description see the SignServer manual available from the Documentation link inthe Administration Web or the public web pages.

13.2.1 Workers Page

The Workers page consists of a list of all the currently configured workers.

13.2.1.1 Status Summary Page

Clicking on one of the workers shows its Staths Summary Page with information about itsWorker status, Token status as well as Errors (if any).

13.2.1.2 Configuration Page

The Configuration page contains the worker’s properties. Worker properties can be added,removed or edited and will directly be applied to the worker. See the Status Summary pagefor any errors after making a change to see if the state change to OFFLINE and if there areany errors.

98 (109)



13.2.1.3 Crypto Token Page

The Crypto Token page is only available for crypto workers such as the HSMCryptoToken10and lists the key aliases (names) of the keys in the HSM slot. Buttons exists for operationslike key generation and removal etc.

13.2.1.4 Audit log Page

The Audit log page contains one table of audit log search conditions and one where the logsearch results are displayed. To search the log press the Reload button.

The logged in administrator needs to have the Auditor role to be allowed to query the log.To edit the authorized administrators click the Administrators link. Click Add... link and forinstance use Load current to have the fields populated with the certificate information forthe currently logged in administrator. Make sure to check the Auditor role. After reloadingthe search results the log should be displayed.

13.2.2 Archive page

The Archive page contains on table archive search conditions and one where the archivesearch results are displayed. To search the archive press the Reload button.

The logged in administrator needs to have the Archive Auditor role to be allowed to querythe log. See the previous section for how to edit the list of authorized administrators.

99 (109)


14. SIGNSERVER ADMINISTRATION GUI Ver: 3.0.0

Chapter 14

SignServer Administration GUI

The SignServer Administration GUI previously was the main way of configuring, administrat-ing and managing SignServer on the PKI Appliance. Nowdays, the Administration Web ispreferred interface. See chapter 13.

The Administration GUI is implemented as a standalone Java application intended to berun on the administrator’s computer or a dedicated workstation. The Administration GUIconnects to the PKI Appliance over mutually authenticated TLS.

14.1 Accessing the Administration GUIFor convenience the Administration GUI is available for download from a running PKI Ap-pliance as a pre-configured bundle that only needs to be configured with the keystore (orsmart card) that should be used for authenticating the administrator.

100 (109)



Steps to install the application initially:

1. On the SignServer web pages (see chapter 12), click on AdminGUI Download link tonavigate to the download area (see fig. 14.1).

Figure 14.1: SignServer Web Pages

2. Download the zip file via signserver-admingui.zip (see fig. 14.2) and save it (seefig. ??)

Figure 14.2: SignServer download area.

3. The PKCS#12 file has to be extracted from Firefox (if it is installed there). Open Pref-erences -> Advanced -> View Certificates -> Your Certificates and use the Backupbutton (see fig. 14.3) to save it to signserver/p12/superadmin.p12 (see fig. 14.4).

101 (109)



Figure 14.3: Backup superadmin.p12 from Firefox.

Figure 14.4: Save the file under signserver/p12/.

102 (109)



4. Provide a backup password as shown in fig. 14.5.

Figure 14.5: Provide a password to protect the keystore.

5. The Administration GUI can be opened from signserver/bin/signserver-gui (see fig.14.6)

Figure 14.6: Open the SignServer Administration GUI.

103 (109)



6. Use the ... button in Keystore file path: to point to the superadmin.p12 file whichwas saved in signserver/p12/superadmin.p12 in previous steps (see fig. 14.7).

! If no DNS is configured, use the IP address of the Application Interface inthe Web Service URL:

Figure 14.7: Configure keystore file path.

7. Press the Connect button to connect to the server (see fig. 14.8) and provide thepassword for the keystore (see fig. 14.9).

Figure 14.8: Connect to server.

8. The user has to use his superadmin certificate to authenticate to server (see fig. 14.10).

104 (109)



Figure 14.9: Provide keystore password.

Figure 14.10: Choose superadmin.

105 (109)



9. The initial Administration GUI and its current workers are displayed (see fig. 14.11).

Figure 14.11: Initial Administration GUI.

106 (109)



14.2 Connection DialogThe ’Connect to SignServer’ dialog is the first that is displayed when the Administration GUIis started (see fig. 14.8). How to use it for accessing the Administration GUI the first timewas briefly described in the previous chapter.

14.2.1 Connect to

You can choose to either connect to a Local SignServer or a Remote SignServer. ThePKI Appliance is a "Remote SignServer" instance.

14.2.2 Web Service URL

This field should contain the address used to access the PKI Appliance. When usingthe AdminGUI bundle this is already filled in but normally is https://<IP-ADDRESS-OR-HOSTNAME>/signserver.

14.2.3 Truststore

This fields defines which CA certificates are trusted and can be used to validate the PKIAppliance server’s TLS certificate. When using the AdminGUI bundle this is already filled inwith the Management CA certificate as created during the PKI Appliance installation.

14.2.4 Keystore

These fields define the key-pair and certificate to use when authenticating the administratorwith the PKI Appliance.

If the key-pair and the certificate have been installed as a soft token in the web browserwhen installing the PKI Appliance use Type PKCS12 and browse ... for the exportedkeystore file.

Instead if the administrator key-pair and certificate is on a smart card or USB token, useType PKCS11 and browse ... for the smart card middleware PKCS#11 shared library file(.dll, .so or .dylib).

14.2.5 Load defaults

The Load defaults button will undo all changes made in the fields and restore the initialconfiguration.

14.2.6 Cancel

The Cancel button will close the application.

107 (109)



14.2.7 Connect

The Connect button will start connecting to SignServer using the specified information.Depending on the choices there might be additional windows popping up asking for a pass-word or PIN code for the keystore/smartcard and to select which certificate to authenticatewith. After connecting to SignServer the main window of the Administration GUI is displayed(see fig. 14.11).

14.3 Main WindowThe main window consists of multiple parts such as the application menu with items likeFile, Edit, View etc, the toolbar with buttons such as Refresh, Activate and Deactivate etcand the tabs like Workers, Audit log and Archive.

This section only describes some of the components in the Administration GUI. For acomplete description see the SignServer manual available on the PKI Appliance on http://example.com/signserver/doc/Administration_GUI.html by replacing example.comwith the hostname or IP address of the PKI Appliance Application Interface.

14.3.1 Workers tab

The Workers tab consists of a list of available workers to the left and to the right detailsfor the selected worker(s).

14.3.1.1 Status Summary tab

The Status Summary tab contains status information for the selected workers. Importantinformation is the Worker status, Token status as well as Errors (if any).

14.3.1.2 Configuration tab

The Configuration tab contains the worker properties for the selected workers. Workerproperties can be added, removed or edited and will directly be applied to the worker andthe Administration GUI will be refreshed. See the Status Summary tab for any errors aftermaking a change if the worker changed its state to OFFLINE.

14.3.1.3 CryptoToken tab

The CryptoToken tab is only available for crypto workers such as the HSMCryptoToken10and lists the key aliases (names) of the keys in the HSM slot. Buttons exists for operationslike key generation and removal etc.

14.3.1.4 Audit log tab

The Audit log tab contains one table of audit log search conditions and one where the logsearch results are displayed. To search the log press the Reload button.

108 (109)

http://example.com/signserver/doc/Administration_GUI.html

http://example.com/signserver/doc/Administration_GUI.html



The logged in administrator needs to have the Auditor role to be allowed to query thelog. To edit the authorized administrators click the menu Edit -> Administrators.... ClickAdd and for instance use Load current to have the fields populated with the certificateinformation for the currently logged in administrator. Make sure to check the Auditor role.After reloading the search results the log should be displayed.

14.3.2 Archive tab

The Archive tab contains on table archive search conditions and one where the archivesearch results are displayed. To search the archive press the Reload button.

The logged in administrator needs to have the Archive Auditor role to be allowed toquery the log. See the previous section for how to edit the list of authorized administrators.

Archived artifacts can be downloaded by selecting them in the list, clicking the Download...button afterwards and selecting a folder to store them in.

109 (109)

PKI Appliance User Guide - PrimeKey...- MariaDB to 10.2.13 and Galera provider 25.3.23 - OpenSSL...

Documents

Transcript of PKI Appliance User Guide - PrimeKey...- MariaDB to 10.2.13 and Galera provider 25.3.23 - OpenSSL...