MyID

Version 11.4

PrimeKey EJBCA
Integration Guide

Lutterworth Hall, St Mary's Road, Lutterworth, Leicestershire, LE17 4PS, UK

www.intercede.com | [email protected] | @intercedemyid | +44 (0)1455 558111

Document reference: INT1975-05 December 2019

Copyright
© 2001-2019 Intercede Limited. All rights reserved.
Information in this document is subject to change without notice. The software
described in this document is furnished exclusively under a restricted license or
non-disclosure agreement. Copies of software supplied by Intercede Limited may not be
used resold or disclosed to third parties or used for any commercial purpose without
written authorization from Intercede Limited and will perpetually remain the property of
Intercede Limited. They may not be transferred to any computer without both a service
contract for the use of the software on that computer being in existence and written
authorization from Intercede Limited.
The software or web site referred to in this manual may utilize or contain material that is
© 1994-2000 DUNDAS SOFTWARE LTD., all rights reserved.
No part of this publication may be reproduced, stored in a retrieval system or
transmitted in any form or any means electronic or mechanical, including photocopying
and recording for any purpose other than the purchaser's personal use without the
written permission of Intercede Limited.
Whilst Intercede Limited has made every effort in the preparation of this manual to
ensure the accuracy of the information, the information contained in this manual is
delivered without warranty, either express or implied. Intercede Limited will not be held
liable for any damages caused, or alleged to be caused, either directly or indirectly by
this manual.
Licenses and Trademarks
The Intercede® and MyID® word marks and the MyID® logo are registered trademarks of
Intercede in the UK, US and other countries.
Microsoft and Windows are registered trademarks of Microsoft Corporation. Other
brands and their products are trademarks or registered trademarks of their respective
holders and should be noted as such. All other trademarks acknowledged.

PrimeKey EJBCA Integration Guide Page 2 of 34

Conventions Used in this Document

• Lists:
 Numbered lists are used to show the steps involved in completing a task when
the order is important
 Bulleted lists are used when the order is unimportant or to show alternatives

• Bold is used for menu items and for labels.

For example:
 "Record a valid email address in 'From' email address"
 Select Save from the File menu

• Italic is used for emphasis and to indicate references to other sections within the
current document:
For example:
 "Copy the file before starting the installation"
 "See Issuing a Card for further information"

• Bold and italic are used to identify the titles of other documents.
For example: "See the Release Notes for further information."
Unless otherwise explicitly stated, all referenced documentation is available on the
product media.

• A fixed width font is used where the identification of spaces is important,

including filenames, example SQL queries and any entries made directly into
configuration files or the database.

• Notes are used to provide further information, including any prerequisites or

configuration additional to the standard specifications.
For example:
Note: This issue only occurs if updating from a previous version.

• Warnings are used to indicate where failure to follow a particular instruction may
result in either loss of data or the need to manually configure elements of the
system.
For example:
Warning: You must take a backup of your database before making any changes to it.

PrimeKey EJBCA Integration Guide Page 3 of 34

Contents
1 Introduction ............................................................................................................................... 5
1.1 ECC support ................................................................................................................................ 5
1.2 Hardware and software requirements .......................................................................................... 5
1.3 Prerequisites ................................................................................................................................ 5
1.4 Change history............................................................................................................................. 6
2 Configuring MyID ...................................................................................................................... 7
2.1 Administering EJBCA CA............................................................................................................. 7
2.2 Establishing a secure connection with the CA ............................................................................. 7
2.3 Configuring the MyID RA user ..................................................................................................... 7
2.3.1 Configuring end entity and certificate profiles for an RA User certificate ..................................... 8
2.3.2 Creating a MyID RA User ............................................................................................................ 9
2.3.3 Configuring MyID RA user access ............................................................................................. 10
2.3.4 Adding the MyID RA user to the RA Administrator role ............................................................. 12
2.4 Configuring certification authorities ............................................................................................ 12
2.5 Configuring certificate profiles.................................................................................................... 15
2.6 Configuring end entity profiles ................................................................................................... 19
2.7 Key escrow policy configuration overview.................................................................................. 21
2.8 Configuring MyID ....................................................................................................................... 22
2.8.1 Enabling certificates on a CA ..................................................................................................... 24
2.8.2 Mapping the additional attributes ............................................................................................... 27
2.8.3 Configuring attributes ................................................................................................................. 27
2.8.4 Deleting a CA............................................................................................................................. 28
2.9 Configuring custom certificate extensions ................................................................................. 28
2.9.1 Setting up the custom extensions in MyID ................................................................................. 28
2.9.2 Additional attribute settings ........................................................................................................ 29
3 Attribute Mapping for PIV Systems ...................................................................................... 31
3.1 Common Name.......................................................................................................................... 31
3.2 Publishing policies ..................................................................................................................... 31
3.3 Attribute tables ........................................................................................................................... 31
3.4 PIV-I Systems ............................................................................................................................ 32
4 Troubleshooting and Known Issues .................................................................................... 33
4.1 EJBCA audit logging .................................................................................................................. 33
4.2 Displaying certificates in RA Web .............................................................................................. 34
4.3 EJBCA connector logging .......................................................................................................... 34

PrimeKey EJBCA Integration Guide Page 4 of 34

1 Introduction
This document is a step-by-step guide to integrating the PrimeKey EJBCA Enterprise
PKI® certification authority with MyID®.

1.1 ECC support

MyID has been tested with the following ECC capabilities of the PrimeKey EJBCA
Enterprise PKI certificate authority:
▪ Smart card key generation using ECC using P256, P384, and P521 curves.
Note: Support for this feature is limited by smart card type – see the Smart Card
Integration guide for details.
The following features are not currently supported with the PrimeKey EJBCA Enterprise
PKI certificate authority:
▪ Issuing certificates with ECC keys to a software local store (CSP).
▪ Issuing certificates with ECC keys as a .pfx file.
▪ Issuing certificates with ECC keys to a mobile device.
▪ Issuing certificates with ECC keys using the MyID SCEP interface.
▪ Issuing certificates with ECC keys to a Microsoft Virtual Smart Card.
▪ Issuing certificates with ECC keys to an Intel Virtual Smart Card.
▪ Issuing or recovering certificates with archived keys that use ECC.

1.2 Hardware and software requirements

The current version of MyID has been tested with:
▪ PrimeKey EJBCA Enterprise PKI version 6.14.
See your PrimeKey EJBCA Enterprise PKI documentation for recommendations of the
hardware and software needed for PrimeKey EJBCA Enterprise PKI.

1.3 Prerequisites
The MyID application server must be able to communicate using secure HTTP/TLS with
the web service that is hosting the CA.
You must obtain an appropriate RA certificate for a configured PrimeKey jurisdiction.
PrimeKey EJBCA Enterprise PKI is a public-key PKI certification platform for registration
agents and remote users.
• Create and configure the following entities:
 CA functions:
 Certification Authority (CA).
 Crypto tokens (for storing CA keys).
 Publishers (if required).
EJBCA provides support for publishing certificates to LDAP and Active
Directory. Custom publishers require customized plugins.
See section 2.4, Configuring certification authorities when configuring a CA for
use within MyID.

PrimeKey EJBCA Integration Guide Page 5 of 34

  System functions:
 Administration Roles.
These roles are used to control access to CAs and administrator
functions.
 Services.
Various timed services are available to carry out periodic system
functions and checks. Services for publishing CRLs and publishing
certificates must be enabled. The HSM service is required if using HSM
for storing cryptographic tokens.
The supported services you may need to configure are:
 CRLUpdater to periodically update the CRL from the required CAs.

 PublisherQueueChecker to periodically check the publication

queue.
• Configure the certificate profiles.
These determine the non-user specific content and behavior of certificates. The
largest part of the settings controls the information that is included in a certificate
that is issued using the certificate profile, and the source of the information. See
section 2.5, Configuring certificate profiles for constraints when configuring a
certificate profile for use within MyID.
• Configure end entity profiles.
These are used to control the information that is present when configuring an end
entity. An end entity profile specifies one or more certificate profiles that is used
when generating certificates. The combination of an end entity profile and a
certificate profile is used to control the information that is present in an issued
certificate.
Although an end entity profile may reference multiple certificate profiles, MyID
treats the combination of an end entity profile and a certificate profile as a
certificate policy, and therefore end entity profiles used within MyID must reference
only a single certificate profile.
See section 2.6, Configuring end entity profiles for constraints when configuring
end entity profiles for use within MyID.
See the PrimeKey EJBCA documentation for details on how to configure the above
entities.

1.4 Change history

Version Description
INT1975-01 Released with MyID 11.0.
INT1975-02 Released with MyID 11.1.
INT1975-03 Released with MyID 11.2.
INT1975-04 Released with MyID 11.3.
INT1975-05 Released with MyID 11.4.

PrimeKey EJBCA Integration Guide Page 6 of 34

2 Configuring MyID
This section describes how to configure the PrimeKey EJBCA Enterprise PKI to provide
RA function for the management of user entities and certificate issuance through MyID.
Several constraints on the configuration of PrimeKey EJBCA Enterprise PKI entities are
imposed to ensure that the configuration is compatible for RA management through
MyID. These constraints are described in this section.

2.1 Administering EJBCA CA

Before you configure the CA through the web browser UI, you must request a certificate
for a CA administrator. The CA administrator certificate is used to provide a secure
connection with the EJBCA,
An administrator certificate is created as part of the EJBCA PKI installation process.
You can administer the CA through the installation server command line interface or
through the web browser UI. The UI provides two main pages for administrating the CA:
• An Admin Web interface for various CA, RA and system level configuration
functions.
The admin web is typically located at:
https://my.primekey.com:8443/ejbca/adminweb

• An RA Web for managing users and user certificate requests.

The RA web is typically located at:
https://my.primekey.com:8443/ejbca/ra

2.2 Establishing a secure connection with the CA

The certificate path, for the RA and CA administrator certificates, must be trusted to
establish a secure connection with the CA. Where the certificate issuing CA is a
PrimeKey EJBCA CA, you can retrieve the certificate for the issuing CA from the public
part of the PrimeKey EJBCA web site; for example:
http://my.primekey.com:8080/ejbca/retrieve/ca_certs.jsp

You must then add the certificate to the Trusted Root Certification Authorities store.

2.3 Configuring the MyID RA user

Before MyID can access your PrimeKey PKI, you must have an RA user, with
appropriate access, to enable MyID to manage certificates on the CA. A Registration
Authority (RA) certificate is required for this RA user to provide a secure communication
between MyID and the web service hosting the CA. When requesting the certificate,
make sure that the request has the Export Private Key option set.
You must copy the RA certificate to the MyID application server. You use the location of
the certificate to set the key store location when configuring the CA; see section 2.8,
Configuring MyID.
Although you can specify the location and password of a PFX key store when
configuring the CA, you are recommended to enroll the PFX into a CSP or KSP for the
MyID COM+ user. Then, export the imported certificate to a certificate file. Use the
location of this file when configuring the CA.

PrimeKey EJBCA Integration Guide Page 7 of 34

2.3.1 Configuring end entity and certificate profiles for an RA User certificate
You must configure a suitable end entity and certificate profile to use when issuing an
RA user certificate.
The end entity profile must have the following configuration:
• Subject DN Attributes
 Common Name
The certificate profile must have the following configuration:
• Key Algorithm – RSA 2048 bits.
• Allow subject DN override by End Entity Information – Enable.
• Key Usage – Digital Signature, Non-Repudiation, Key Encipherment.
• Extended Key Usage – Client Authentication.
Both the end entity and certificate profile must reference the CA that is going to be used
to issue the certificate in section 2.3.2, Creating a MyID RA User.
See the PrimeKey EJBCA documentation for details on how to configure the above
entities.

PrimeKey EJBCA Integration Guide Page 8 of 34

2.3.2 Creating a MyID RA User
Create a MyID RA user through the EJBCA RA Web using the Enroll > Make New
Request option. The MyID RA user certificate must be signed by an appropriate CA in
the EJBCA; for example:

PrimeKey EJBCA Integration Guide Page 9 of 34

 Enroll the user certificate by clicking the Download PKCS#12 button. You can then use
the downloaded certificate with MyID; the password is provided in the Enrollment code
field.
Note: To allow the establishment of a secure connection, you must configure the
EJBCA server to trust the CA that is used to issue the certificate.

2.3.3 Configuring MyID RA user access

The roles assigned to the RA user used by MyID define the MyID administrative
capabilities. You can assign access rules for a role when creating the role, as described
below, or after creating the role using EJBCA GUI Roles > Access Rules option.
Although MyID acts as an RA administrator, the default RA Administrator template
access rules do no provide sufficient access to enable MyID to validate and synchronize
the policies of the EJBCA. As such, you need the Advanced Mode to configure the
access rules.
At minimum the user must have the following access rules assigned:
Configuration Option Setting
Role MyID RA Administrator
Authorized CAs Access to all Certificate Authorities.
Regular access rules ▪ Default RA Administrator access rules
▪ View certificate profile
▪ View end entity profiles
End Entity Rules ▪ Create, Delete, Edit, Revoke, and View End
Entities.
▪ Key Recover End Entities.
End Entity Profiles Provide access to all the end entity profiles, or at
least those end entity profiles associated with
MyID. Even if access is provided to all end entity
profiles, only those profiles that reference one or
more of the CAs used by MyID will be visible
within MyID as certificate policies.
Validators None.
Internal key binding None.
Other rules None.

PrimeKey EJBCA Integration Guide Page 10 of 34

 The following shows the minimum configuration options in the Regular Access Rules
settings when configuring the access rules in advanced mode:

You can configure an RA administrator role, if not already provided by default, using the
administrator RA Web Role Management > Roles option.

PrimeKey EJBCA Integration Guide Page 11 of 34

2.3.4 Adding the MyID RA user to the RA Administrator role
Add the MyID RA user to the MyID RA Administrator role using the Add Role Member
option in the RA Web Role Management > Role Members option; for example:

In the above example, the subject common name is used to determine the user role,
and hence their capabilities.
You can also add a user to a role through the EJBCA Adminweb using the
Administrator Roles > Members option.

2.4 Configuring certification authorities

Before you add a PrimeKey EJBCA CA into MyID, you must configure the CA on the
PrimeKey EJBCA.
See your PrimeKey EJBCA documentation for details.
The following restrictions are imposed on configuring a CA to ensure that MyID can
manage certificates using the CA, and to prevent performance degradation due to
unnecessary database queries.
Configuration Field Purpose Enforcement
Type of CA Controls the type of X.509
certificates that can be
issued by the CA, X509
or CVC.
Crypto Token Token where the CA's PKCS#11 HSM slot
key mappings are mapping, or a Soft
expected to exist. PKCS#12 keystore in the
database.
A PKCS#11 crypto token
requires additional
common fields to be set to
identify the location of the
crypto token. See the
PrimeKey EJBCA
documentation for details.

PrimeKey EJBCA Integration Guide Page 12 of 34

 Configuration Field Purpose Enforcement
Enforce unique public When enabled, checks Disable
keys are performed that the When enabled may affect
same public key is not performance if the
used to issue certificates database is not configured
using different certificate with
policies (users are (subjectKeyId,issuerDN)
associated with database index.
certificate policy when
used by MyID).
Enforce unique DN Enforces that the same Disable
DN cannot be used when Enabling this option would
issuing policies using prevent a user being
different certificate issued certificates using
policies. different policies but the
same DN.
Enforce unique Subject Ensures that only one Disable (default)
DN Serial Number end entity, with a specific Enabling this option can
Subject DN Serial affect certificate issuance
Number, can be issued performance and prevent
from this CA. the same user being
issued certificates using
different certificate policies
if Subject DN serial
number is used.
Use Certificate Request Maintain a history of Disable (default)
History Certificate Requests. Enabling this option will
lead to reduced certificate
issuance performance.
Use User Storage Allows users (end Enable
entities) to be searched. You can disable the option
When enabled, a to improve performance
certificate can only be when the CA is not being
requested for stored used for escrow.
users (end entity).
You must enable this
option when using the
PrimeKey PKI CA for key
escrow.
Use Certificate Storage Stores issued certificates Enable (default)
to enable certificates to Required to provide CRLs
be retrieved and provide although it does have the
revocation information. effect of reducing
performance.
You must enable this
option when using the
PrimeKey PKI CA for key
escrow.

PrimeKey EJBCA Integration Guide Page 13 of 34

 Configuration Field Purpose Enforcement
Default CA defined Configure a CRL If you need to validate
validation data distribution point OCSP certificates against a CRL,
default service URI. the CRL publishing service
A CRL publishing service must be enabled to publish
is required to periodically the updated CRL
publish the CRL. periodically; the MyID
application server must be
able to access the
Certificate Revocation List
(CRL) location, and if
configured, the OCSP
default service URI.
Certificate profiles used to
issue certificates that are
published with the CA
must have the Access
Information Access, as
well as the Use CA
defined CA issuer and/or
the Use CA defined
OCSP locator options
enabled; see section 2.5,
Configuring certificate
profiles.
Approval Settings Provides default approval None
settings for the relevant Enabling these prevents
options. operations being
completed until the
operation has been
approved.
Finish User Checks if an end entity Enable
should transit from New Disabling this setting
to Generated after prevents the end entity
issuing a certificate. from being created in a
specific table within
PrimeKey database. This
will prevent the EJBCA
"republish all" CLI
command from failing
when attempting to publish
an issued certificate to an
external database.

PrimeKey EJBCA Integration Guide Page 14 of 34

2.5 Configuring certificate profiles
The following restrictions are imposed on configuring certificate profiles that are used for
issuing certificates to users to ensure that MyID can manage certificates using the CA.
Configuration Field Purpose Enforcement
Type Type of entity using the End Entity
certificate profile.
Available key algorithm List of allowed key Select RSA if the profile is
algorithms that public key to be used for issuing
used in the certificate RSA certificates.
request. Select ECDSA if the
profile is to be used for
issuing ECC certificates.
You can use a profile for
both RSA and ECDSA
keys.
Available bit lengths List of allowed key sizes Ensure that the required
that the public key used in bit lengths are selected.
the certificate requests Bit lengths supported by
must comply with. MyID are:
RSA: 1024, 1536, 2048
and 4096
ECDSA: 256, 384 and
521
Validity Offset A validity offset can be To prevent a certificate
configured to handle to lifetime exceeding the
handle clock skew. required certificate
The offset adjusts the lifetime, MyID specifies
certificate validity the certificate start time
start/end times when the only in terms of relative
corresponding validity time. The certificate end
time is specified as a time is specified as a fixed
relative time. time. Hence the validity
offset is applied only to
The default validity offset the certificate start time.
is used if an offset is not
specified.
Allow validity override Enables the default Enable
certificate validity period, MyID allows the required
specified in the certificate validity period to be
profile, to be overridden overridden by the setting
by the validity period in the credential profile used
the certificate request. to issue the certificate.
The policy validity period
should not be modified
through the Certificate
Authorities workflow, as
the change would get
overwritten on the next
policy synchronization.

PrimeKey EJBCA Integration Guide Page 15 of 34

 Configuration Field Purpose Enforcement
Allow extension override When enabled, allows Enable
X.509 certificate MyID provides dynamic
extensions featured in a extension data that is
certificate request to be written to the certificate.
honored. Externally
supplied extensions are
added "as-is". Matching
extensions already
supplied in the certificate
profile are overridden.
Further override control
can be provided by
providing a comma
separated list of OIDs
specifying the extensions
that may (or may not) be
overridden.
When this option is
disabled, the default
certificate profile
extensions are used and
the end entity subject DN
is taken from the
registered entity LDAP
setting.
Allow subject DN override Allows the X.509 subject You must disable this
by CSR DN in a certificate to option for certificate
come directly from the profiles that are used for
PKCS#10 included in the key escrow policies, as
certificate request rather PKCS#10 is not provided
than from the registered in the certificate request
end entity LDAP DN for these policies.
entry. Normally this option is
enabled for non-key
escrow policies, although
you can disable the option
if the subject DN is being
generated using the policy
attributes.
You must enable either
this option or the Allow
subject DN override by
End Entity Information
option, as end entities
may not be registered in
LDAP depending on the
CA configuration.
See section 2.8.3,
Configuring attributes for
information on configuring
policy attributes.

PrimeKey EJBCA Integration Guide Page 16 of 34

 Configuration Field Purpose Enforcement
Allow subject DN override Allows the X.509 subject When enabled, the
by End Entity Information DN in a certificate to subject DN is dynamically
come from the end entity generated using the
information supplied in the certificate authority policy
certificate request rather attribute configuration.
than from the registered The Allow subject DN
end entity LDAP DN override by CSR option
entry. takes precedence, when
enabled, over this option.
See section 2.8.3,
Configuring attributes for
information on configuring
policy attributes.
Allow Key Usage Override When enabled, allows the Disabled (default)
key usage to be The option is not currently
overridden by the used by MyID.
certificate request.
Use certificate storage Issued certificates are Enabled
stored in the database to Note: This may impact on
provide certificate certificate issuance
management and CRLs. performance.
CRL Distribution point The CRL Distribution Enable
point information enables
a client to verify a
certificate using the
provided URI.
Certificate Policies Policy OIDs may be set to Enable the Use option
indicate that certificates and specify the required
issued using this profile policy OIDs to ensure that
are for a specific purpose. certificates issued using
the profile assert the
required policy OID as
specified by the
appropriate common
policy requirement; for
example, PIV model
policies may be required
to assert policy OIDs to
satisfy the X.509
Certificate Policy for the
U.S. Federal PKI
Common Policy
Framework.

PrimeKey EJBCA Integration Guide Page 17 of 34

 Configuration Field Purpose Enforcement
X.509v3 extensions This group of Enable the Use option for
configuration options is the extensions according
used to control which to the common policy
X.509v3 validation data requirements; for
extensions URIs are example, PIV model
asserted by certificates policies may be required
issued with this profile. to assert the CRL
Distribution Points and the
OCSP Service Locator
URIs.
It is recommended that
the URI values are
inherited from the CA
configuration rather than
being specified within the
profile.
Used Custom Certificate Selects custom Select the required
Extensions extensions, configured configured custom
through the custom data extensions.
in System Custom extensions, as
Configuration, as described in section 2.9.1,
described in section 2.9, Setting up the custom
Configuring custom extensions in MyID, are
certificate extensions. added to a policy only if at
Selected custom least one custom
extensions are, by default, extension has been
treated as mandatory, and selected in the
the extension default corresponding certificate
value is used if an profile.
override value is not
provided in the certificate
request.
Approval settings Provides default approval None (default)
settings for the relevant Enabling these prevents
options. operations being
completed until the
operation has been
approved.
Available CAs Determines which CAs You must at least select
can use this certificate the CA that was specified
profile for certificate in the CA Path field when
issuance. configuring the CA
through the Certificate
Authorities workflow.
Publishers Controls where the Select if certificates
certificate is published. issued using the
certificate profile are
required to be published.
Single Active Certificate Controls if multiple active Disable (default)
Constraint certificates can be issued Enabling this option
to an end entity. prevents MyID from
issuing multiple
certificates using the
same certificate policy.

PrimeKey EJBCA Integration Guide Page 18 of 34

2.6 Configuring end entity profiles
The following restrictions are imposed on configuring end entity profiles that are used
for issuing certificates to users to ensure that MyID can manage certificates using the
CA.
Configuration Field Purpose Enforcement
Username Controls if the username Disable auto-generated
for the end entity is MyID provides the
automatically generated. username based on the
end entity profile name.
Password (Enrolment Password is used for key Disable auto-generated
Code) and certificate recovery. Enable the Required
option for profiles being
used for key escrow
certificates, as a
password is required to
recover the server-
generated keypair.
Passwords are not
required for non-key
escrow certificates, as
certificates issued using
the profile do not need to
be recovered.
Maximum number of Used when the EJBCA is Disable
failed login attempts also validating login
attempts using the
configured password.
Batch generation (clear Password is used to Required to be enabled
text pwd storage) authenticate PKI for key escrow certificate
requests. profiles only.
End Entity E-mail Email is used for Disable
notifications. The EJBCA is not used
for sending notifications.

PrimeKey EJBCA Integration Guide Page 19 of 34

 Configuration Field Purpose Enforcement
Subject DN Attributes Controls which DN Do not set if using the
attributes can be subject DN attribute from
configured in the Subject the PKCS10 in the
DN. certificate request, see
This configuration is used section 2.9.2, Additional
to populate the certificate attribute settings.
policy extensions in MyID. Check the Required
option if the attribute is
mandatory. A certificate
request will fail if a
mandatory attribute is not
supplied in the certificate
request even if the subject
DN attributes are being
taken from the supplied
PKCS10 data.
See section 2.8.1,
Enabling certificates on a
CA for details of mapping
policy attributes in MyID.
Check the Modifiable
field if the value can be
modified. This option is
normally enabled unless
there is a specific reason
for wanting a static
attribute value in the
issued certificates.
You must specify a static
value for any non-
modifiable attribute. This
value must not be
changed when configuring
the policy attributes in
MyID.
Other Subject Attributes Controls which SAN and As for Subject DN
Subject Directory Attributes.
attributes are required to When adding RFC 822
be configured in this Name attribute, the Use
certificate policy. entity e-mail field option
This configuration is used is automatically enabled
to populate the certificate and the Modifiable option
policy extensions in MyID. is disabled. An email
address is not set for an
end entity and therefore
you must disable the Use
entity e-mail option.
The Modifiable option
must also be enabled but
initially this may remain
disabled; in this case, you
must save the profile
setting and then re-edit
the profile to set the
Modifiable option.

PrimeKey EJBCA Integration Guide Page 20 of 34

 Configuration Field Purpose Enforcement
Default Certificate Profile The certificate profile MyID does not specify the
used if a certificate profile certificate profile in the
is not specified in the received certificate
certificate request. request, therefore the
default certificate profile is
used.
Available Certificate Controls which certificate You can leave this list
Profiles profiles can be used in a unselected, as the default
certificate request using certificate will be added
this profile. even if it has not been
selected.
Available CAs Determines which CAs Must at least select the
can use this certificate CA selected in the
profile for certificate certificate profile
issuance. referenced by this profile.
Ensure that the profile
does not reference a CA,
including the default CA,
that is not referenced by
the referenced certificate
profile.
Default Token Controls the types of Must select User
certificates that may be Generated.
issued using this profile. Must also select P12
token for key escrow
certificate policies.
Key recoverable Identifies that the profile Check Use if the profile is
can be used to recover to be used for issuing key
the server-generated escrow certificates;
encryption keys. otherwise, leave this
option unchecked.
Send Notifications Notification is sent when a Leave unset
certificate is available for PrimeKey EJBCA CA
collection. must not be used for
sending notifications.

2.7 Key escrow policy configuration overview

This section provides an overview of the configurations required to support key escrow
policies:
1. Enable the Enable Key Recovery option in the Basic Configuration tab under
System Configuration.
You must set this first, as the key recoverable option is available in the end entity
profile only when key recovery is enabled.
2. Set the following configuration options in the end entity profile being used for
issuing key escrow certificates:
 Password – check Required.
 Batch generation (clear text pwd storage) – check Use and Required.
 Key recoverable – check Use.
 Subject DN Attributes – configure according to the required subject DN
attributes.

PrimeKey EJBCA Integration Guide Page 21 of 34

 3. Check the following configuration options in the certificate profile being used for
issuing key escrow certificates:
 Available key algorithm – select RSA.
 Signature algorithm – select the required RSA hashing algorithm.
 Allow subject DN override by CSR – Uncheck Allow.
 Allow subject DN override by End Entity Information – Check Allow.

2.8 Configuring MyID

Configure the PrimeKey PKI CA using the Certificate Authorities workflow.
1. Put the RA certificate file on the MyID application server.
Note: The MyID named COM+ user must have access to this file.
2. From the Configuration category, select Certificate Authorities.
3. Click New.
4. From the CA Type drop-down list, select EJBCA.

5. Type a CA Name.
This is a friendly name that is used to identify the CA.
6. Type a CA Description.
This is a description for the CA.
7. Set the Retry Delays.
This is a semi-colon separated list of elapsed times, in seconds.
For example, 5;10;20 means:
 If the first attempt to retrieve details from the CA fails, a second attempt will be
made after a 5 second delay.
 If this second attempt fails, the CA will be contacted again after 10 seconds.
 Subsequent attempts will be made to retrieve information every 20 seconds,
until a response is received.

PrimeKey EJBCA Integration Guide Page 22 of 34

 If you want to limit the number of retry attempts, enter 0 as the last number in the
sequence.
The default is:
15;60;60;60;60;120;180;360;3600;86400;0

This retries after 15 seconds, then after a minute four times, then two minutes,
three minutes, six minutes, an hour, 24 hours, then stops.
8. Type the CA Path.
The CA name as configured on the EJBCA. The name is not case-sensitive.
9. Make sure that the Enable CA checkbox is selected.
10. Type the Service Point.
This is the full URL for the PrimeKey-hosted certification authority web service; for
example:
https://myserver.com:8443/ejbca/ejbcaws/ejbcaws

Note: The EJBCA web service API is called ejbcaws, and is located in the
directory named ejbca/ejbcaws – therefore, the web service full URL ends with
the following:
/ejbca/ejbcaws/ejbcaws

11. If your RA private key is enrolled in a CSP or KSP, as described in section 2.3,
Configuring the MyID RA user:
a) For the Connection Type, select the Certificate option.
b) Type the location of the certificate file in the Certificate Store box.
For example:
C:\PrimeKey\RACert.cer

12. If your RA certificate is held in a PFX file:

a) For the Connection Type, select the PFX option.
b) Type the location of the certificate file in the PFX Certificate Store box.
For example:
C:\PrimeKey\RACert.p12

c) Type and confirm the password for the certificate (only required for a pfx or
p12 certificate store).
Note: You are recommended to enroll the private key into a CSP or KSP for
establishing the secure connection to avoid the additional overhead related to
using a p12 or pfx files.
13. Click Save.
You can now go back into the Certificate Authorities workflow and set up your
certificate templates.

PrimeKey EJBCA Integration Guide Page 23 of 34

2.8.1 Enabling certificates on a CA
Note: Because of the way MyID manages PrimeKey PKI certificate template names, the
displayed Friendly name is the name of the end entity profile on the PrimeKey EJBCA
that references the CA as identified in the CA Name field.
Although all certificate templates are detected when you add the CA to MyID, they are
all initially disabled. To enable them:
1. From the Configuration category, select Certificate Authorities.
2. From the CA Name drop-down list, select the certificate authority you want to work
with.

3. Click Edit.

PrimeKey EJBCA Integration Guide Page 24 of 34

 4. Make sure Enable CA is selected.
5. Select a certificate template you want to enable for issuance within MyID in the
Available Certificates list.
6. Click the Enabled (Allow Issuance) checkbox.
7. Set the options for the policy:
 Display Name – the name used to refer to the policy.
 Description – a description of the policy.
 Allow Identity Mapping – used for additional identities. See the
Administration Guide for details.
 Reverse DN – select this option if the certificate requires the Distinguished
Name to be reversed.
 Archive Keys – select whether the keys should be archived. For policies
configured for key archive, set this option to EJBCA Client.
 Certificate Lifetime – the life in days of the certificate. This is defaulted to the
maximum allowed life imposed by the certificate policy on CA.
 Automatic Renewal – select this option if the certificate is automatically
renewed when it expires.
 Certificate Storage – select one of the following:
 Hardware – the certificate can be issued to cards.
 Software – the certificate can be issued as a soft certificate.
 Both – the certificate can be issued either to a card to as a soft
certificate.
 Recovery Storage – select one of the following:
 Hardware – the certificate can be recovered to cards.
 Software – the certificate can be recovered as a soft certificate.
 Both – the certificate can be recovered either to cards or to a soft
certificate.
 None – allows you to prevent a certificate from being issued as a historic
certificate, even if the Archive Keys option is set. If the Certificate
Storage option is set to Both, the certificate can be issued to multiple
credentials as a shared live certificate, but cannot be recovered as a
historic certificate.
 Additional options for storage:
If you select Software or Both for the Certificate Storage, or Software,
Both, or None for the Recovery Storage, set the following options:
 CSP Name – select the name of the cryptographic service provider for
the certificate. This option affects software certificates issued or
recovered to local store for Windows PCs.
The CSP you select determines what type of certificate templates you
can use. For example, if you want to use a 2048-bit key algorithm, you
cannot select the Microsoft Base Cryptographic Provider; you must select
the Microsoft Enhanced Cryptographic Provider. See your Microsoft
documentation for details.
 Requires Validation – select this option if the certificate requires
validation.
Note: This option is available only if you select Software or Both for the
Certificate Storage option.

PrimeKey EJBCA Integration Guide Page 25 of 34

  Private Key Exportable – when a software certificate is issued to local
store, create the private key as exportable. This allows the user to export
the private key as a PFX at any point after issuance.
It is recommended that private keys are set as non-exportable for
maximum security.
Note: This setting affects only private keys for software certificates –
private keys for smart cards are never exportable.
 User Protected – allows a user to set a password to protect the
certificate when they issue or recover it to their local store.
This means that whenever they want to make use of the soft certificate,
they will be prompted for a password before they can use it. This is a
CSP feature that is enabled when you set this option, and affects only
software certificates that are issued or recovered to local store for
Windows PCs.
 Key Algorithm – select the type and length of the key-pairs used for
certificate generation. A longer key length is more secure but certain
manufacturers' CSPs do not support longer lengths. Select the appropriate
key length from the list. This must match the key type and length set up in
your CA.
 Key Purpose – select one of the following:
 Signature – the key can be used for signing only.
 Signature and Encryption – the key can be used for either signing or
encryption.
Note: The Key Purpose option has an effect only where the device being
issued supports the feature. PIV cards do not support this feature, while smart
cards issued with minidrivers and software certificates issued to local store for
Windows PCs do support this feature.
8. If you need to edit the policy attributes, click Edit Attributes.

a) For each attribute, select one of the following options from the Type list:
 Not Required – the attribute is not needed.
 Dynamic – select a mapping from the Value list to match to this attribute.
 Static – type a value in the Value box.
b) Click Hide Attributes.
Note: MyID may not override the settings of the CA. You need to obtain the correct
settings from the administrator of your CA.
9. Click Save.
Note: Changes made to certificate profiles do not take effect immediately, as the normal
interval for MyID to poll for updates is 50 minutes. To force MyID to poll for changes
immediately, you must manually restart the eKeyServer service, then restart the
eCertificate service.

PrimeKey EJBCA Integration Guide Page 26 of 34

2.8.2 Mapping the additional attributes
You must use the Edit Attributes option for each certificate policy in the Certificate
Authorities workflow to set up a mapping or a static value for each of the additional
attributes that you want to pass in the certificate request. See section 2.8.1, Enabling
certificates on a CA for details

2.8.3 Configuring attributes

The end entity profile configuration is used to determine which attributes are available
for the corresponding certificate policy within MyID.
The following shows an example of configuring Subject DN Attributes:

The following subject attributes are defined in the above example: Common Name
(CN), Organizational Unit (OU), Organization (O), and Country (C). Of these, the CN
and OU attributes are mandatory, and C has a non-modifiable static value.
Note: The default value for an attribute is used only if the attribute is not modifiable.
The available Subject DN and Subject Alternative Name attributes are limited to the
attributes that are supported by the EJBCA, not all of which are supported by MyID. The
attributes for which MyID provides a dynamic mapping, for the inserted attribute value,
are listed below:
Ejbca End Entity Attribute Group MyID Attribute Mapping
Profile Attribute
Common Name Subject DN Common Name
Domain Component Subject DN Domain
First Name Subject DN First Name
Full Name Subject DN Full Name (name)
Organizational Unit Subject DN Group Name or
Application Group
DN Serial Number Subject DN Serial Number
Surname Subject DN Surname
Title Subject DN Title
RFC 822 Name Subject Alt-Name Email
(e-mail address)
FASC-N Subject Alt-Name FASC-N (Hex)
User Principle Name Subject Alt-Name User Principle Name
Uniform Resource ID Subject Alt-Name UUID (ASCII)
You can use attributes for which MyID does not have default dynamic mapping, but
these would require static value or custom implementation.

PrimeKey EJBCA Integration Guide Page 27 of 34

 Note: You must not set dynamic mappings of attributes to Organizational Unit or
Distinguished Name, as these may be made of multiple attribute components and
therefore will result in the certificate request being rejected by the EJBCA.
Note: You must supply a mapped value if the attribute is configured as being mandatory
in the end entity profile in the EJBCA.

2.8.4 Deleting a CA
You can delete a CA from the list of available CAs if you no longer need to be able to
work with it, or if you created it in error.
See the Administration Guide for details.

2.9 Configuring custom certificate extensions

Note: Only non-PIV custom extensions are currently supported.
PrimeKey EJBCA Enterprise PKI provides support for custom extensions to be added to
a certificate.
The required extensions are first configured in the PrimeKey EJBCA through the
Custom Certificate Extensions settings in the System Configuration as shown:

The OID is the extension that is added to the certificate.

Inclusion of a custom extension in a certificate requires that:
• The associated certificate profile references the required custom extension through
its Used Custom Certificate Extensions setting.
• The use Custom certificate extension data option is enabled in the
corresponding end entity profile.
Further information about managing these custom extensions is described in the
PrimeKey EJBCA administration guide.

2.9.1 Setting up the custom extensions in MyID

MyID is unable to interrogate the PrimeKey EJBCA system configuration through the
web service interface and, although it can identify that a certificate profile is referencing
custom extensions, it cannot extract the extension details. Therefore, custom
extensions cannot be automatically added to certificate policies within MyID.
Therefore, these custom extensions are identified through a custom extensions
configuration file: EjbcaPKIConnector.xml. All custom extensions are defined in this
file within an XML <Extensions> node. Each custom extension is defined in an
<Extension> node.

PrimeKey EJBCA Integration Guide Page 28 of 34

 For example, a configuration with two custom extensions would look like:
<Extensions>
<Extension displayType="optional">
<Name>MyExtnsion</Name>
<DisplayName>My Extension</DisplayName>
<OID>0.1.0.01</OID>
</Extension>
<Extension displayType="mandatory">
<Name>MyExtnsion2</Name>
<DisplayName>My Extension 2</DisplayName>
<OID>0.1.0.02</OID>
</Extension>
</Extensions>

The EJBCA connector attempts to load the custom extensions file from the MyID
Components folder on the MyID application server; by default, this is:
C:\Program Files (x86)\Intercede\MyID\Components\

A default EjbcaPKIConnector.xml file, containing only the PIV NACI extension, is

installed in the EJBCA installation folder on the MyID application server; by default, this
is:
C:\Program Files (x86)\Intercede\MyID\Components\PKI\EJBCA\

You must add any additional custom extension to this file, then copy the file to the MyID
Components folder.

As MyID cannot determine which custom extensions are being referenced by the
individual policies, all custom extensions identified in the configuration file are added as
policy attributes to any policy that references a custom extension on the PrimeKey
EJBCA. It is up to the administrator to configure the required attributes through the
Certificate Authorities workflow, as described in section 2.8.1, Enabling certificates on
a CA.
Although an extension can be set to mandatory or optional within MyID, any referenced
custom extensions are treated as mandatory by the EJBCA with the default value,
configured in the system configuration, being used if a value is not supplied.
Note: The OID value of these custom extensions must match the extensions configured
in the System Configuration in the PrimeKey EJBCA.
Note: After you have made any changes to this file, you must restart the eCertificate
service to update the certificate policies within MyID.
1. From the Windows Administrative Tools, double-click Services.
2. Right-click the eCertificate Services Server service, then from the popup menu
click Restart.

2.9.2 Additional attribute settings

The following table shows the configuration required to support the additional attributes
and custom extensions
Certificate Profile End Entity Profile MyID certificate policy
attributes
Allow Extension override: Enabled Configure attributes in Configure certificate policy
and Subject DN Attributes. attributes as described in
section 2.8.1, Enabling
Allow subject DN override by End certificates on a CA.
Entity Information: Enabled
and
Allow subject DN override by CSR:
Disabled

PrimeKey EJBCA Integration Guide Page 29 of 34

 Certificate Profile End Entity Profile MyID certificate policy
attributes
Allow Extension override: Disabled Subject DN Attributes Attributes not present.
or are not used and therefore
not required to be
Allow subject DN override by CSR: configured.
Enabled
Allow Extension override: Enabled The required attributes are Configure certificate policy
and required to be configured attributes as described in
in Subject Alternative section 2.8.1, Enabling
Subject Alternative Name: Enabled Name. certificates on a CA.

Allow Extension override: Enabled The required attributes are Configure certificate policy
and required to be configured attributes as described in
in Subject Directory section 2.8.1, Enabling
Subject Directory Attributes: Enabled Attributes. certificates on a CA.

Allow Extension override: Enabled Enable Custom Configure the required

and certificate extension extensions in
data. EjbcaPKIConnector.xml
The required custom extensions are as described in section
selected in Used Custom Certificate Note: MyID cannot
2.9.1, Setting up the
Extensions. validate that this setting
custom extensions in
has been enabled.
MyID.
The required custom
Configure certificate policy
extensions are required to
attributes as described in
be configured in System
section 2.8.1, Enabling
Configuration as described
certificates on a CA.
in section 2.9, Configuring
custom certificate The custom extensions
extensions. defined in the external file
are added to all PrimeKey
PKI certificate policies.
Only those extensions
required by the policy
should be configured
within MyID. Configuring
more custom attributes
than required may result in
a certificate request being
rejected due to
configuration mismatch.

PrimeKey EJBCA Integration Guide Page 30 of 34

3 Attribute Mapping for PIV Systems
For PIV systems, you must set up the attributes of the PIV certificate policies to have
specific Dynamic mappings; see section 2.8.3, Configuring attributes for details.
EJBCA allows the certificate’s subject DN attributes to be extracted from the PKCS10 or
passed into the certificate request as end entity data. When using the subject DN from
the end entity data, the subject DN in the end entity configuration must be configured to
include all the required subject attributes, and the certificate profile must be configured
to take the subject DN extensions from the end entity information, as described in
section 2.9.2, Additional attribute settings.
The following tables provide an example configuration for PIV cards.
Note: The PIV Card Authentication certificate policy must not contain a mapping for
Email.

3.1 Common Name

The common name is either obtained from the PKCS#10 passed in the certificate
request, or through providing dynamic mapping in the subject DN attributes setting in
the end entity profile; see sections 2.8.3, Configuring attributes and 2.9.2, Additional
attribute settings.

3.2 Publishing policies

Policy publishing is controlled through the Certificate Profile configuration for the
certificate policy. See section 2.5, Configuring certificate profiles.

3.3 Attribute tables

The following tables show the recommended options for attribute mapping.
ManagedPKI PIV Account Signer
Attribute Value
Common Name Common Name
Publish policy No

ManagedPKI PIV Authentication

Attribute Value
Common Name Common Name
FASC-N FASC-N (Hex)
User Principle Name User Principle Name
Uniform Resource ID UUID (ASCII)
NACI NACI Status
Publish policy No

ManagedPKI PIV Card

Attribute Value
DN Serial Number FASC-N (ASCII)
FASC-N FASC-N (Hex)
Uniform Resource ID UUID (ASCII)

PrimeKey EJBCA Integration Guide Page 31 of 34

 NACI NACI Status
Publish policy No

ManagedPKI PIV End User Encryption

Attribute Value
Common Name Common Name
RFC 822 Email Email (optional)
Publish policy Yes

ManagedPKI PIV End User Signing

Attribute Value
Common Name Common Name
RFC 822 Email Email (optional)
Publish policy Yes

3.4 PIV-I Systems

The FASC-N mapping is required for standard PIV cards, but is not permitted for PIV-I
cards. The Printable FASC-N mapping is set to FASC-N (ASCII) for PIV cards, and
UUID (ASCII) for PIV-I cards.
For example, for a PIV-I system, the following certificate policies would need to be
different from the example for a PIV system above:
ManagedPKI PIV Authentication
Attribute Value
Common Name Common Name
FASC-N Not required
User Principle Name User Principle Name
Uniform Resource ID UUID (ASCII)
NACI NACI Status
Publish policy1 No

ManagedPKI PIV Card

Attribute Value
DN Serial Number FASC-N (ASCII)
FASC-N Not required
Uniform Resource ID UUID (ASCII)
NACI NACI Status
Publish policy No

1
Certificate publication is controlled through the corresponding certificate profile configuration on the
EJBCA; see section 3.2, Publishing policies. This configuration is not visible in MyID.

PrimeKey EJBCA Integration Guide Page 32 of 34

4 Troubleshooting and Known Issues

4.1 EJBCA audit logging

You can enable EJBCA audit logging when deploying the EJBCA, and can modify it
through the server command line interface.
See your EJBCA installation and administration guides for details.
When logging is enabled, the audit logs can be viewed by an administrator using the
View Log command through a web browser. You can apply a filter to reduce the number
of log entries as shown:

Hover over or click the required Details column entry to view detailed information. To
download results, select the Download shown results option.

PrimeKey EJBCA Integration Guide Page 33 of 34

4.2 Displaying certificates in RA Web
An administrator can view the details of issued certificates using the
Search > Certificates option. You can use filters to view only the required certificates,
as shown:

4.3 EJBCA connector logging

The MyID EJBCA connector supports logging. For information on how to enable this
logging, contact customer support quoting reference SUP-286.

PrimeKey EJBCA Integration Guide Page 34 of 34