37007259 EJBCA Admin Guide

Search ejbca.org for:

EJBCA support, development and maintenance by

IntroductionConceptsExport and import profilesManaging CAs

Export and import CAsRemove and restore CA soft keystoreRenew CAsRevoke CAs

Import usersCRL generation

CRL Update service workerCron jobDelta CRLs

ScepLevel of SCEP supportTested devices

CMP (EJBCA >=3.4)ConfigurationCMP over httpCMP over TCPUser authenticationProof of possessionNormal or RA mode for CMPCertificate validityCertificate Key UsageInteroperabilityCMP Proxy

OcspStand-alone OCSP responderSimple OCSP clientAdobe Acrobat Reader

EJBCA Web Service InterfaceWeb Services authenticationConfiguring Web Services CLIConfiguring Web Services behaviorUsing the Web Services CLIUsing the Web Service API for IntegrationSample codeAccessrules required when using the Web Service APIError codes on web servicesWS transaction logging

XKMS ServiceIntroductionHow to configure the XKMS ServiceImplementation Specific NotesUsing the XKMS clientRunning the XKMS test script

External RA APIKey recovery

Technical detailsEmail notifications

End entity email notificationsDynamic Substitution VariablesExamples

Printing of User DataApproving ActionsFramework for External User Data SourcesFramework for ReportsServices Framework

ConfigurationCurrently Available ServicesWriting Customized Services

Hardware Security Modules (HSM)Auto-activation of CA tokensHSMs and DSA or ECDSAGeneric PKCS#11 providerUtimaco CryptoServernCipher nShield/netHSMnCipher load balancingAEP KeyperARX CoSignBull TrustwaySafeNet LunaSafeNet ProtectServerWriting support for new HSMs

LDAP and PublishersLDAP NamingLDAP BasicsConfigure LDAP publishersExtra device schemaCustom publishersPublisher Queue and failures

ECDSA keys and signaturesGenerated keys and certificateUsing ECDSA with an HSMECC named curves vs explicit parametersNamed curvesImplicitlyCA curvesCreating client certificatesLimitations

InternationalizationAdding a new language to the admin GUI

EJBCA - Open Source PKI Certificate Authority - Admin Guide

1 of 38

Internal InternationalizationCustom DN and altName oids

altNamesCustom Certificate Extensions

Configuring Custom Certificate ExtensionsBasic Certificate ExtensionImplementing an Advanced Certificate Extension

LoggingLog4JLogDeviceOldLogDeviceProtectedLogDevice

Reference manualCommand line interfaceOther ConfigurationAsn1DumpBatch creation of certificatesFetching certificates and CRLsOther deployment scenarios

Customizing EJBCAHandling changes in a separate tree (EJBCA >= 3.5)Adding your own public web-pagesAdding your own rules to regulate the values of End Entity Fields

Using the demo servletSamplesTroubleshootingExtra info about the admin-GUI

Character limitationsCode signing

Introduction

Information how to install EJBCA can be found in the Installation guide.

This Administrator Guide is a reference guide to the concepts, configurations and options available in EJBCA. The guide is targeted foradministrators who are responsible for installing, configuring and maintaining EJBCA installations. More detailed hands on instructionsfor various day to day administrative tasks can be found in the User Guide.

This guide covers detailed information about using various protocols, hardware security modules etc of EJBCA. These details coversboth configuration and usage.

Concepts

Before using this guide you should be familiar with the various concepts, such as certificate and end entity profiles, used in EJBCA.There is a separate document explaining the different concepts.

Export and import profiles

Certificate and End Entity profiles can be exported as XML files and imported in another instance of EJBCA, or in the same instanceafter removal of the old ones.

When exporting profiles (bin/ejbca.sh ca exportprofiles), all profiles will be exported to the specified directory. The exported files willbe given unique names containing profile name and profile id. When importing profiles the profile name and id will be read from thefilename. All profiles present in the specified directory will be imported.

Fixed profiles will not be exported or imported. If a profiles with the same name as the one being imported already exist, the profileswill not be imported. References to publishers with unknown id will be dropped.

Import of profiles try to keep the same profile id. If it already exist a profile with the same id in the database, it will try to chooseanother and change any (end entity profile to certificate profile) reference during later imports. The reason the id is kept is that thereare references to the profile id from users belonging to the profile.

During import on a new EJBCA instance where CAs that are referenced from the profiles don't exist, a default CA has to be specifiedon command line. Two CAs are concidered identical in this context if they have the same subject DN.

Managing CAs

Export and import CAs

Under certain circumstances, it can be wise to backup the CA's signature and encryption keys. Remember to protect the backup inthe same way as the CA itself.

Soft token CAs can be exported and backed up. CAs with the keys on a HSM can naturally not be exported through EJBCA. Use theHSMs methods to back up such keys.

Soft token CAs can be imported using both the CLI and admin-GUI, while HSM CAs can only be imported using the CLI.

*** Using command line interface ***

To export a CA named "TestCA" to the PKCS#12-file "/path/TestCA.p12" with password "foo123" enter the following from the$EJBCA_HOME directory:

[ user @host ej bca] $ bin/ ej bca. sh ca expor tca TestCA ./ Test CA. p12Usi ng J Boss JNDI provi der. . .Ent er keyst ore password: f oo123[ user@host ej bca]$

To import the backup keys for "TestCA" later, enter the following from the $EJBCA_HOME directory:

[ user @host ej bca] $ bin/ ej bca. sh ca i mpor tca TestCA /path/ TestCA. p12 Si gnatureKeyAl i as Encrypti onKeyAl i asUsi ng J Boss JNDI provi der. . .Ent er keyst ore password: f oo123[ user@host ej bca]$

Enter the command:

[ user @host ej bca] $ bi n/ej bca. sh ca i mpor tca

to get usage instructions how to import HSM CAs.

*** Using admin-GUI ***

To be able to export and import the CA's keys using the admin-GUI, you have to have superadministrator access. Make surethat .p12 files are not automatically saved to an unsuitable place by your browser. before you do an export.

To export a the CA's keys, do the following:


2 of 38

Select "Edit Certificate Authorities" from the administrator menu.Select the CA you want to export and press the "Edit"-button.Go to the line where the help-text say "CA export requires the keystore password".Enter the keystore password in the box to the right of the help-text.Press the "Export CA keystore.."-button.The PKCS#12-file will be downloaded by your browser to the location you select.

To import a CA's keys, do the following:

Select "Edit Certificate Authorities" from the administrator menu.Press the "Import CA keystore.."-button.Fill out the form with the CA's name, full pathname to the PKCS#12-file and keystore password.Keep the two "Alias.."-fields to the default value, if you used EJBCA to export the CA's keys.Press the "Import CA keystore"-button.

Remove and restore CA soft keystore

Soft token CAs can have their keystore removed from the database. When the keystore is removed the CA can not issuecertificates and its CA token status is set to 'offline'.

Warning: Before removing the keystore make sure you have exported it if you would like to be able to restore it later. See thesection 'Export and import CAs'

To remove the catoken keys for "TestCA", enter the following from the $EJBCA_HOME directory:

[ user@host ej bca]$ bi n/ ej bca.sh ca removekeyst ore TestCAUsi ng J Boss J NDI provi der. . .[ user@host ej bca]$

To restore the catoken keys again for "TestCA" with the keystore exported as "TestCA-exported.p12", enter the following from the$EJBCA_HOME directory:

[ user@host ej bca] $ bi n/ej bca. sh ca restorekeystore TestCA / pat h/TestCA- export ed. p12 Si gnatureKeyAl i as Encrypti onKeyAl i asUsi ng J Boss J NDI provi der. . .Ent er keyst ore password: f oo123[ user@host ej bca]$

Renew CAs

You can renew CAs in different ways:

Renew only CA certificate, using the same keys.Renew CA keys and certificate.

To renew only the CA certificate using the same keys you simply press the button "Renew CA". Your CA have to be on-line for thisto work, so it can sign the new certificate if it's a self signed CA or the certificate request if it is a sub CA. Also if it is a subCA withthe rootCA in the same EJBCA instance the root CA must also be on-line.

To renew the CA keys you check the box "Renew keys" and give the CA token authentication code. After this you simply press"Renew CA".Renewing the keys will not always work if you are using an HSM. It may work with some HSMs and not work with others.You can report success and failures to us.

When using an HSM you can also make the renewal of keys manually. Simply generate new keys on the HSM with whatever toolsyou used the first time (preferably the EJBCA cli tools), and then edit the CA token properties to use the new key. After the newkey has been configured you can simply press "Renew CA" (without the renew keys checkbox), to generate your new CAcertificate.

Revoke CAs

If you want to revoke a CA you can do so by going to "Edit Certificate Authorities" in the admin GUI. There is a button "RevokeCA".

If you revoke a Root CA it will revoke all certificates in the database issued by the root CA, and create a CRL.If you revoke a Sub CA it will revoke all certificates in the database issued by the sub CA, and to the sub CA, and create aCRL. This works automatically if the sub CA and root CA is handled by the same EJBCA instance. If the Sub CA is signed byan external CA, the sub CA's certificate must be revoked by the external CA.If you revoke an external CA /sub CA to a CA in EJBCA) the external CAs certificate will be revoked and put on the CRL of the issuing CA in EJBCA.

Import users

Users from another CA can be imported with the CLI command:

bi n/ej bca. sh ca i mport cert

You have to give several parameters to the command. Running the command without parameters will print instructions.

CRL generation

A new CA should always issue an (empty) CRL. This is done when the ca is created and can also be done by running 'ca.sh/cmdcreatecrl caname'.

See also the User Guide for details how to configure CRL periods, CRL Distribution Points and CRL Issuers.

There are at least two ways to have EJBCA to periodically create updated CRLs.

CRL Update service worker

From EJBCA 3.4 there is a timed service framework in EJBCA. In the Admin-GUI you can go to 'Edit Services' and add a newservice. Edit the service and select the 'CRL Updater' worker and the interval you want to use. Don't forget to set the service to'Active'.Now this service will run with the interval you have configured and generate CRLs according to the settings for each CA.

Cron job

Yet another way to generate CRLs way is to have a cron job or equivalent call 'bin/ejbca.sh ca createcrl'. The 'createcrl' commandwill then check all active CAs if it is a need to update their CRLs, otherwise nothing is done.

If you want to force CRL generation for a CA, use 'bin/ejbca.sh ca createcrl caname'

Example crontab entry:

PATH=$PATH: / usr/ j ava/ j dk1.6. 0_01/bi n@dai l y cd / home/ ej bca; / home/ej bca/ bi n/ej bca. sh ca createcrl ;

where '/usr/java/jdk1.4.2_01/bin' is the path to where 'java' can be found. '/home/ejbca' is where ejbca is installed and 'ca.sh'


3 of 38

located.

Sample crontab to be installed with 'crontab -e':

SHELL=/ bi n/ shPATH=/ usr / l oca l / sbi n: / usr / l oca l / bi n: / sbi n: /b i n: / usr / sbi n: / usr / bi nCLASSPATH=$CLASSPATH: / r oot / ej bcaAPPSRV_HOME=/ usr/ l ocal / j boss# m h dom mon dow command00 0 * * * cd / root/ ejbca; . / bin/ ejbca.sh ca createcrl

Delta CRLs

EJBCA can issue delta CRLs. In the CA configuration, set 'Delta CRL Period' to the amount of time your delta CRLs will be valid if delta CRLs are issued. Command line interface and CRL Update service will generate delta CRLs if 'Delta CRL Period' is larger than0.

Scep

Since SCEP uses encryption, you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK. The policy files can be found atthe same place as the JDK download. Further information on this can be found in the Sun documentation on the JCE.

There are some compatibility issues with SCEP, one being if the CA certificate should be returned in a SCEP enrollment response ornot. The CA certificate is optional but some, Cisco VPN client, seems to require it while others, Juniper, seems to dislike it. ThereforeEJBCA has two SCEP URLs.

The default including the CA certificate (use if nothing else specified):

htt p:/ / l ocalhost: 8080/ ejbca/publi cweb/ apply/ scep/pki cl i ent. exe

Not including the CA certificate (try if the default doesn't work):

htt p:/ / l ocalhost: 8080/ ejbca/publi cweb/ apply/ scep/noca/pki cl i ent. exe

Level of SCEP support

EJBCA implements features from (at least) draft 11 of the SCEP spec. This means that we implement the following SCEPmessages:

PKCSReqGetCRLGetCACertGetCACertChainGetCACaps

Using the External RA API the following SCEP message is also supported for polling mode:

GetCertInitial

The following CA capabilities are supported:

POSTPKIOperationSHA-1

*** CA mode ***

EJBCA does successfully receive SCEP 'PKCSReq' requests and send back the certifificate/CRL immediately in a proper SCEPreply message. EJBCA (standard) does not support the 'polling' model, EJBCA uses the direct CA method, where a request isgranted or denied immediately. The SCEP client will send messages directly to the CA, encrypted with the CAs certificate.

The CN part of the DN in the PKCS#10 request, which is part of the Scep request, will be used as the 'username' whenauthenticating the request in EJBCA. Create the Scep request with a CN mathing the username registered in EJBCA. ThechallengePassword in the PKCS#10 request, which is part of the Scep request, will be used as the 'password' whenauthenticating the request in EJBCA. Create the Scep request with a challengePassword mathing the password registered inEJBCA.

The most common errors should be wrong username/password or wrong status (not NEW) on the user in EJBCA.

*** RA mode (ExtRA API 3.4.2) ***

EJBCA supports the SCEP 'polling' RA model using the External RA API. Using this a SCEP client can send a request to theExternal RA, and then wait, polling the RA for updates. When the request is processed by the CA, which fetches the pkcs10request from the External RA, the certificate is sent back to the External RA. When the certificate is complete on the ExternalRA, the RA sends back the SCEP certificate response the next time the SCEP client polls the RA. This feature is very useful tosecurely insulate the CA from the SCEP clients throughout the network.

EJBCA will not send back proper SCEP error messages in all cases of failure. The error messages are not completely implemented,although most of them are implemented.

Tested devices

*** OpenScep ***

OpenScep has does not work with modern OpenSSL implementation (only works with OpenSSL 0.9.6) and also has a bug thatcauses it to crash when receiving SCEP responses. There are patches that address these issues though so it can be used.

To use the OpenScep client to request a certificate from this servlet, use the command:

. / scep -k test . key -r t est. pemreq -c ej bca-ca.pem- q foo123 -u htt p:/ / l ocalhost: 8080/ ej bca/publi cweb/ appl y/scep

Where test.key is generated with:

openssl genrsa -out t est. key

test.req is generated with:

openssl req -key test. key - new - days 30 -out t est. req -outf ormDER -conf i g .. / openssl / openscep.cnf

and test.pemreq is generated with:

openssl req -key test. key - new - days 30 -out test . pemreq - outf ormPEM - confi g . . / openssl / openscep.cnf

*** Simple Scep Client (sscep) ***

Simple Scep Client. You should only use CN in the users DN (same as for PIX below).

*** jSCEP ***


4 of 38

jSCEP. jSCEP uses EJBCA as one of the servers it is tested against.

*** Juniper Networks NetScreen-25/NetScreen-50 ***

Works nice using the URL not including the CA certificate.

To enroll using the Juniper box go to the Web GUI at https://<juniper-ip>/, then click your way to Objects->Certificates. Tocreate a new certificate request:

New - enter the DN that your box will receive:Name=netscreen.foo.seOrganization=PrimeKeyCountry=SEIP Address=192.168.1.1FQSN=netscreen.foo.se

Click generate.

1.

Automatically enroll to -> New CA Server settings. The CGI URL differs if you are using the direct CA mode or the RA

polling mode:RA CGI: http://<ra-ip>:8080/scepraserver/scep/noca/pkiclient.exe or ht tp://<ca-ip>:8080/ejbca/publicweb/apply /scep/noca/pkiclient.exe.CA CGI: http://<ra-ip>:8080/scepraserver/scep/noca/pkiclient.exe or http://<ca-ip>:8080/ejbca/publicweb/apply /scep/noca/pkiclient.exe.CA IDENT: The CA Name in EJBCA, for example ScepCA.Challenge: A password for a pre-registered user in CA mode, or a random password used for polling RA mode.

Click OK.

2.

You can now see the request in Objects->Certificates. If you are using polling RA mode, you can click 'Retrieve' after therequest has been approved in the CA and the certificate has been generated.

3.

*** Cryptlib ***

Cryptlib is working as of EJBCA 3.1.3.

When using Cryptlib, the CA certificate must have KeyUsage 'Key Encipherment' in addition to the usual key usage flags. Thisis reasonable, since SCEP requires the CA to actually encrypt data (which generally is a bad thing, since a special encryptioncertificate should be used for that).Key usage for a ScepCA should be: Certificate Sign, CRL Sign, Digital Signature, Key Encipherment

Use the complete path as for the Cisco VPN client below as server name.

*** Cisco VPN client ***

Tested with version 4.0.2 and 5.0.

To enroll using the Cisco VPN client use:

CA URL='http://127.0.0.1:8080/ejbca/publicweb/apply/scep/pkiclient.exe'CA Domain=you CAs name in EJBCAIn the DN screen simply enter the username (as added in EJBCA) as 'Name [CN]'

When using an External RA to enroll with the Cisco VPN client, the RA certificate must have KeyUsage SigitalSignature andKeyEncipherment for the client to accept the CA certificates. However, to locate the RA encryption certificate, onlyKeyEncipherment can be set, which makes things quite complicated.

The conclusion is that RA enrollment does not work with Cisco VPN client.

*** AutoSscep ***

EJBCA has been tested successfully with AutoSscep for enrollment against the CA and the External RA SCEP service.

Instructions:

Download and build AutoSscep (make).1.

Create a configuration file, ejbca.conf, as the example below.2.

Create a user in EJBCA with username (common name) and DN exactly as entered in the configuration file.3.

run 'autosscep ejbca.conf'.4.

Sample configuration file, ejbca.conf:

Verbose = "yes"Debug = "no"

CADi r ="/ home/ autosscep/ "Cert Di r ="/ home/ autosscep/ "KeyDi r="/ home/ autosscep/ "

[ CA]DN="C=SE, O=EJ BCA Sampl e, CN=Admi nCA1"URL="htt p:/ / l ocal host: 8080/ ejbca/ publi cweb/ apply/ scep/pki cl i ent. exe"Cert Fi l e="Admi nCA1. cacert . pem"EncCert Fi l e="Admi nCA1. cacert . pem"[ / CA]

[Cer t i f i cate ]Cert Fi l e="mycert "KeyFi l e="mykey"CADN="C=SE, O=EJ BCA Sampl e, CN=Admi nCA1"

# Cr eate a user wi t h user name "r outer 4711" and password "f oo123" i n EJ BCA# to automati call y enrol l# Note you need to add a user wi t h exactl y t hese f i el ds i n the DN i n EJBCAEmai l = "mymai l @mydomai n"Countr y="SE"St at e=" BS"Locati on="St ockhol m"Or gani zat i on="Pr i meKey"CommonName="r out er 4711"

Chal l engePasswor d="f oo123"[ / Cer t i f i cate ]

AutoSscep also handles enrolling against an RA, where the RA first sends a PENDING response which the request i s beeingprocessed. After processing (by the CA) you simply run the AutoSscep client again to pick up the generated certificate.In order to enroll against the External RA SCEP Server in EJBCA i only had to change the CA part of the configuration file touse the SCEP RA servers certificate for signing and encrypting the messages instead of the CAs, and to use the URL to the RA.The SCEP RA certificate is the end entity certificate issued to the External RA SCEP server (the keystore is usually calledscepraserver.p12).

[ CA]DN="C=SE, O=EJ BCA Sampl e, CN=Admi nCA1"URL="htt p:/ / l ocal host: 8080/ scepraserver/ scep/pki cl i ent. exe"Cert Fi l e="sc epra. pem"


5 of 38

EncCert Fi l e="scepr a. pem"[ / CA]

*** Cisco PIX/3000 ***

Cisco PIX is working as of EJBCA 3.1.3.Also Cisco 3000 is reported working well. The description below is for PIX, 3000 probably have less constraints than the PIX.

You must configure JBoss to use port 80 to enroll with PIX, this is done in APPSRV_HOME/server/default/deploy /jbossweb-tomcat50.sar/service.xml (or similar depending on version). You must run as root to use port 80.EJBCA supports the 'ca' mode of enrollment for pix, not 'ra'. For 'ra' and polling enrollment you can use the External RAmodule (extra).The certificate profile used by the SCEP CA must include the key usages KeyEncipherment and DataEncipherment,otherwise PIX will not be able to verify/decrypt encrypted SCEP messages. This is not in the default certificate profile forCAs. Create a new certificate profile before creating the Scep CA, you can use ROOTCA as template for the newcertificate profile.When enrolling for certificate using SCEP with for example a Cisco PIX it is a 'ca_nickname'. This nickname should be theCA-name as defined when creating the CA in EJBCA. For example 'vpnca'.Only use lower-case names when creating the CA in EJBCA, since PIX will change the CA name VpnCA to vpnca whenenrolling.The username in EJBCA must be the name the PIX identifies itself with name.domain, example pix.primekey.se.The end-entity DN must include the DN components CN and unstructuredName, ex "CN=pix.primekey.se,unstructuredName=pix.primekey.se". You can also include O, C etc in the certificate. A normal DN for a PIX is"CN=pix.primekey.se,unstructuredName=pix.primekey.se,O=PrimeKey,C=SE".Certificates used for PIX MUST include the DN component unstructuredName (fqdn) and could also includeunstructuredAddress (ip) being the IP-address of the PIX.The certificate used on the Cisco PIX MUST have a SubjectAltName field dNSName, matching the DN componentunstructuredName. This is needed in order for Cisco VPN clients to connect to the PIX. The DNS Name field is notnecessary for the PIX to enroll perfectly with EJBCA, only for the client to be able to connect.Certificates used for PIX may also use the SubjectAltName iPAddress matching the DN component unstructuredAddress,but it's not necessary.Cisco does not support use of the 'Domain Component', DC, attribute in DNs, don't use it .KeyUsage should include Digital Signature and Key Encipherment , the EJBCA defaults work fine.When the Cisco VPN-client (above) connects to the PIX, the 'ou' part of the clients DN must match a Vpngroup you havespecified, otherwise the connection will fail.Cisco PIX needs the SCEP response messages to use MD5 as hash algorithm, not SHA1, this is handled by EJBCAautomatically.

Please notice this Cisco note:

Be sure that the PIX Firewall clock is set to GMT, month, day, and year before configuring CA. Otherwise, the CA may reject orallow certificates based on an incorrect timestamp. Cisco's PKI protocol uses the clock to make sure that a CRL is not expired.Set timezone first, then set time, then check time with 'show clock'.

The enrollment steps should be something like:

- - Connect wi t h pi x and ent er admi n modetel net 10. 1.1.1 ( def aul t pwd cisco)enabl e (defaul t bl ank pwd)conf i gure t ermi nal- - Enabl e CA l oggi ngdebug crypt o ca- - Cl ear curr ent PKI conf i gc lear ca i dent i ty- - Enter PKI conf i g, i . e l ocati on of CA etc. Don' t r equir e CRLs, i t ' s easierca i denti ty pi xca ca- i p:/ ejbca/ publi cweb/ apply/ scep/pkicl i ent. execa confi gure pi xca ca 1 0 crl opt i onalca authenti cate pi xca- - wa i t - -- - Look at t he fetched cert i f i cateshow ca cer t i f i cateca save al lwr mem- - Get a CRL i f you real l y want t o (i f you di d not confi gure CRL as opt i onal you must)ca crl request pi xca- - wa i t - -show ca crl- - Generat e keys and enrol l f or t he cert i f i cate (user i n ej bca has password foo123)ca generat e r sa key 1024ca enrol l pi xca f oo123-- wai t , wai t , th i s wi l l take a long t i me - -- - Look at t he fetched cert i f i cat e, t his shoul d now show both t he pix cert and the ca certshow ca cer t i f i cate

pi x(conf i g)# show ca certCer t i f i cate Status: Avai l abl e Cert i f i cat e Seri al Number: 594f 643a6916d78d Key Usage: Gener al Purpose Subj ect Name: C = SE O = Pri meKey CN = pi x. pri mekey. se UNSTRUCTURED NAME = pi x. pr i mekey. se UNSTRUCTURED I P = 10. 1. 1. 1 Val i dit y Date: st ar t dat e: 14: 42: 29 GMT Sep 17 2005 end dat e: 14: 52: 29 GMT Sep 17 2007

CA Cert i f i cate Status: Avai l abl e Cert i f i cat e Seri al Number: 7c7cf 75236955a51 Key Usage: Gener al Purpose C = SE O = Pri meKey CN = pi xca Val i dit y Date: st ar t dat e: 15: 59: 20 GMT Sep 16 2005 end dat e: 16: 09: 20 GMT Sep 14 2015

CMP (EJBCA >=3.4)

CMP (RFC4210) is a very complex protocol, which EJBCA does implement some parts of.The following CMP messages are supported:

Initialization request (ir)Certification request (cr)Certification Confirm (certConf)

Certificate requests use the CRMF (RFC4211).


6 of 38

From EJBCA 3.5, CMP support in RA mode (see below) can support several CAs and profiles based on the keyId of the password usedto protect the CMP messages (PBE protection).In EJBCA 3.4 CMP support in RA mode is currently limited to one keyId, making RA requests for one CA.

Configuration

Copy conf/cmp.properties.sample to conf/cmp.properties and configure. The options in the configuration file should be documentedthere.

CMP over http

By default EJBCA support CMP over the http transport protocol. The URL for the CMP servlet is:http://127.0.0.1:8080/ejbca/publicweb/cmp

CMP over TCP

You can enable a CMP TCP service by changing the option 'cmp.tcp.enabled' in conf/cmp.properties. The service MBean is so farJBoss specific (at least the deployment of it).When re-deploying EJBCA this will start a TCP listener on the default port for CMP over TCP. You must run JBoss as root to use thedefault port, since it is a low port (<1024). See the documentation in conf/cmp.properties for information about configurationoptions for TCP. We recommend using a non standard port > 1024.

User authentication

Initialization and certification requests uses the CRMF request message (RFC4211). There messages are interesting as there are azillion options how to authenticate them. EJBCA currently does authentication through the means of a regToken control(id-regCtrl-regToken) in the CRMF message. The regToken is a UTF8String which is the users password as registered in EJBCA.

Users can be looked up from the request in different ways, as configured in conf/cmp.properties. By default the subject DN fromthe certTemplate in the request is used to look up the used in EJBCA. You can also configure EJBCA to use the CN or the UID fromthe subject DN as the username in EJBCA.

Proof of possession

Proof of Possession (POP) is another part where CMP has gazillions of different options.The following POPs in the CRMF are supported by EJBCA:

raVerify - if configured so in conf/ejbca.properties EJBCA will support the raVerify POP and in that case not do anyverification of POP. By default this is false, because the standard does not recommend this option.signature - where the PublicKey is in the CertTemplate and the signature is calculated over the CertReqMsg.certReq (thestandard procedure when the CertTemplate contains the subject and publicKey values).

Currently these are the only POPs supported by EJBCA, so if you don't use raVerify or signature your request will fail because POP

is not verified.

Normal or RA mode for CMP

CMP in EJBCA can work in two modes:

*** Normal ***

Normal mode works like any other enrollment in EJBCA. When a request comes in EJBCA verifies the request (see Userauthentication above) and issues a certificate to a user that has been previously registered in EJBCA.This is the default mode of operation.

*** RA ***

RA mode is used when the CMP client will act as an RA to EJBCA. When the RA sends a certificate request to EJBCA, no user ispre-registered in EJBCA. When EJBCA receives the request, the message will be authenticated using PasswordBasedMAc, asdefined in the CMP spec, using a pre-shared password. When the message has been authenticated, a user is created in EJBCAand a certificate is issued.

The users DN is taken from the CertTemplate in the request message send from the RA (i.e. the DN requested by theRA).The username in EJBCA is generated according to the options set in conf/cmp.properties.The password for the user in EJBCA is random.If the Certificate Profile allows it, keyUsage and validity is also taken from the CertTemplate in the request message.

After the user has been created in EJBCA, a certificate is generated as usual and sent back to the RA, who will distribute it to

the end-user.

If the same username is constructed (for example UID) as an already existing user, the existing user will be modified with newvalues for profile etc, and a new certificate will be issued for that user.

To allow requests with different KeyId to be mapped to different CAs and profiles in EJBCA, so the documentation for theoptions in conf/cmp.properties.sample.

*** Sample config ***

A sample config of EJBCA to allow an RA to request certificates for users. The RA uses password based mac (pbe) protection of CMP messages with password 'password'. Users will be created using UID from the request DN and with a prefix, so theresulting username will be: cmp<UsersUID>. End entity profiles names CMP_ENTITY and CMP_CERT is created in EJBCAallowing the request DN.

cmp. operat i onmode=r acmp.al l owraveri f ypopo=t ruecmp. r esponsepr otect i on=pbecmp.r a.authent i cati onsecret=passwordcmp. r a. namegener at i onscheme=DNcmp. r a. namegener at i onparamet er s=UI Dcmp. r a. namegener at i onpref i x=cmp#cmp. ra. namegenerat i onpost f i x=cmp. r a. endenti t yprof i l e=CMP_ENTI TYcmp.r a.cer t i f i cateprofi l e=CMP_CERTcmp. r a. caname=Admi nCA1

Certificate validity

Normally the validity period of issued certificates are controlled by the certificate profile. If you enable 'Allow validity override' inthe certificate profile, and the CMP initialization- or certification request contains a validity time in the CRMF request template,this validity period will be used.

Certificate Key Usage

Normally the key usage extension of issued certificates are controlled by the certificate profile. If you enable 'Allow Key UsageOverride' in the certificate profile, and the CMP initialization- or certification request contains a key usage in the CRMF requesttemplate, this key usage will be used.

Interoperability


7 of 38

CMP has been tested using RSA jCert toolkit for initialization requests. To run this as an RA you should configure CMP with:

cmp.operationmode=racmp.allowraverifypopo=truecmp.responseprotection=pbecmp.ra.authenticationsecret=your shared passwordand other configurations you want for your RA.

CMP has been tested with BlueX from AET Europe (http://www.aeteurope.nl/). From EJBCA's point of view BlueX functions as anRA with the same configuration options as for jCert.

CMP Proxy

In some installations it may be desirable to terminate the client connection in a DMZ before connecting further to the CA. In thiscase the client never has a direct network connection to the CA machine. In such a scenario you can use the CMP proxy module.Clients use the CMP proxy, as it would otherwise use EJBCA. The proxy in turn connects to EJBCA gets the answer and forwards itback to the client.

The proxy is a stand alone module that runs on another mahing than the CA itself.

See '${EJBCA_HOME}/modules/cmpProxy/resources/README' for information how to build and use the proxy.

Ocsp

Note! Some OCSP clients does not handle external OCSP responders very well unfortunately. You should be aware of this.

OCSP is used by PKI-clients to verify the validity of certificates in real-time. This is done by sending a request for the status of aspecific certificate to an OCSP responder. The responder may or may not be the same as the CA. The OCSP responder sends a signedreply, containing the requested status information back to the client. The client uses this status information to determine whether thecertificate is valid for use or revoked.

It is an OCSP servlet receiving requests on http://localhost:8080/ejbca/publicweb/status/ocsp. The servlet can process requests forcertificates signed by a CA running in EJBCA, as long as the CAs OCSP service has not been deactivated.

The OCSP servlet receives OCSP request by http(s) and send back a status response signed by the CA, or with a dedicated respondercertificate.

For a CA to be valid as an OCSP-responder it must have the KeyUsage 'Digital Signature' in the certificate profile used to create theCA. This KeyUsage must be included if the CA is to sign OCSP-responses. The default certificate profiles for CAs includes the keyusage 'Digital Signature'.

There are a two parameters affecting the OCSP service that can be configured in conf/ejbca.properties:

'useCASigningCert' - If set to true (default) the OCSP responses will be signed directly by the CAs certificate instead of the CAsOCSP responder. If set to false, the CAs special OCSP responder certificate is used to sign the OCSP responses. The OCSPresponder certificate is signed directly by the CA.'defaultResponderID' - Specifies the subject of a CA which will generate responses when no real CA can be found from therequest. This is used to generate 'unknown' responses when a request is received for a certificate that is not signed by any CAon this server. Set this to the same DN as your initial Admin CA for example.

These values should be set during deployment of EJBCA. After the values have been edited, they are installed with the 'ant deploy'command.

Example to generate an OCSP request using OpenSSL (works with both internal and external OCSP responders):

openssl ocsp - i ssuer Test- CA. pem- CAf i l e Test- CA. pem -cert Test. pem- req_text - url http: / / l ocalhost: 8080/ ejbca/publi cweb/ sta

If Firefox is to request and accept OCSP-responses from a CA it must be configured:

'Use OCSP to validate all certificates using this URL and signer' in 'Privacy & Security->Validation'. Choose the CA from EJBCA

(which you should have made Trusted by right clicking in 'Privacy & Security->Certificates->Manage Certificates->Authorities'and checking the appropriate checkboxes).

1.

If using a Certificate Profile that includes a OCSP Service URL for client certificates, the Validation option in Firefox 'Use OCSPto validate only certificates that specify an OCSP service URL' also works fine. When this option is checked you may need torestart Mozilla.

2.

When the validation settings are set, Firefox will query the OCSP server when for example double-clicking on a certificate in thecertificate manager. An appropriate URL for validation is: http://hostname:8080/ejbca/publicweb/status/ocsp

If using a dedicated OCSP responder certificate, this certificate must probably not be imported in Firefox as a Trusted CA certificate.But if you want to, you can do this through 'View Certificates' in EJBCA (http://hostname:8080/ejbca/retrieve/ca_certs.jsp).

In doc/samples it is a sample how to check revocation with OCSP using the new APIs in JDK 1.5.

Stand-alone OCSP responder

You can set up separated OCSP responders in EJBCA. Using this you can isolate the CA from the Internet and still be able toanswer OCSP request. You can set up firewalls so that only outgoing traffic is allowed from the CA, and nothing to the CA.

Separated OCSP responders is also good when you don't require high-performance clustering for the CA, but you do needhigh-performance for the OCSP responders. This should be a usual setup, if the CA only issues certificates once every year for onemillion users, this does not put much pressure on the CA, but the OCSP responders can be put under high load continuously.

See the OCSP Installation document for information how to set up stand-alone, separated OCSP responders.

Simple OCSP client

To try out and test your OCSP installation you can use the EJBCA client toolbox, (see below). The toolbox has replaced the oldocsp client which has been removed. You can also use the API directly from your java program.

Adobe Acrobat Reader

A good example of using OCSP is to check digitally signed PDF documents using Adobe Reader.

To be able to verify certificates in Adobe Reader, you must first add the CA-certificate as trusted in Adobe Reader. You can do thatin the menu Document->Trusted Identities. Choose Certificates in the drop-down list and click 'Add contacts', now you can browseto the CA-certificate that you have downloaded in DER format (for example by choosing download to IE on the public EJBCApages). The CA-certificate must have been saved with a name ending with '.cer'. After adding the new contact, you have to click'Edit trust' and check at least 'Signatures and as trusted root' and 'Certified documents'. This works the same using both internaland external OCSP responders.

Certificates that have an 'OCSP service locator' will be verified against the OCSP responder. You can configure this in thecertificate profile used to issue certificates.

EJBCA Web Service Interface

New to EJBCA 3.4 is a JAX-WS 2.0 Web Service Interface used to access the basic functions remotely over client authentication


8 of 38

HTTPS.

The functionality currently available through the Web Service Interface are documented in theEJBCA Web Service API Reference.

There is also a cli tool that can be used for remote scripting. See following section for more information. Note: All these calls are notavailable through the CLI.

Web Services authentication

the Web Services interface requries client certificate authentication from administrators, in the same way as the admin GUI does.If you have a client certificate the works on the admin GUI you should also be able to use it for the web service interface.

Configuration for the Web Services CLI requires a JKS keystore. You can easily generate a JKS for an administrator using theadmin GUI (you can even create a JKS for superadmin). Below is a short description how to create a JKS for a user on thecommand line, and adding the new user to the superadministrator admin group.

ej bca ra adduser <1> <2> "C=. . , O=. . , CN=<1>" nul l Admi nCA nul l 1 J KSej bca ra set cl earpwd <1> <2>ej bca bat chej bca admi ns addadmi n " Tempor ar y Super Admi ni st r at or Gr oup" Admi nCA WI THCOMMONNAME EQUALCASEI NS <1>

Configuring Web Services CLI

There exists one propertyfile in conf/jaxws.properties.sample that is used to configure the behaviour of the WS service. Toconfigure it copy it and name it jaxws.properties.

See the sample file for details of how to configure the Web Service interface.

Configuring Web Services behavior

If the end entity profile informations must be used to define default values when you create a user, the flag "Allow merge DNWebservices" must be checked in the end entity profile.

If multiple instances of a component exist, the merge is done from end to begin, and the remaining values of this component typewill be placed at the end. For example, if you want to merge :dn=cn=f oo, . . . , dc=dc1, . . . , dc=dc2, . . . with dn=. . . , dc=mdc1,

. . . , dc=mdc2, . . . , dc=mdc3, . . . the result will be : dn=cn=f oo, . . . , dc=mdc1, . . . , dc=mdc2, . . . , dc=mdc3, . . .

Using the Web Services CLI

Included in the EJBCA Client Tool Box is a Web Service CLI tool.

To use the client do the following, copy the directory with all included files to the computer you want to remote administrate from.Then create a JKS or P12 file with the appropriate access rights (See the Using API section for details) and finally configure thefile ejbcawsracli.properties. In this file you should specify the hostname of the CA server, the name of the keystore and thepassword to unlock it. Documentation for each setting is in the file ejbcacsracli.properties.

Use 'ejbcaClientToolBox.sh EjbcaWsRaCli' for a list of each subcommand and 'ejbcaClientToolBox.sh EjbcaWsRaCli "subcommand"'for detailed help how to use the cli.

Example usage: ejbcaClientToolBox.sh EjbcaWsRaCli pkcs12req testuser2 foo123 2048 NONE tmp

ejbcaClientToolBox.sh EjbcaWsRaCli revokeuser testuser2 SUPERSEDED false

Using the Web Service API for Integration

You can use the Web Service interface to integrate EJBCA from other applications.

If you are using another language than Java you should start by downloading the WSDL file at http://hostname:8080/ejbca /ejbcaws/ejbcaws?wsdl

When using java you can find the required libs in 'dist/ejbcawscli' and it's 'lib' subdirectory.

Some programming examples:

To initialize the web service:

CertTools . i nsta l l BCProvider( ) ; Stri ng url str = "htt ps: / / l ocalhost: 8443/ ejbca/ ejbcaws/ ejbcaws?wsdl ";

System. setProperty( "j avax. net. ssl . tr ustStor e"," p12/ wstest. j ks"); System. setProperty( "j avax. net. ssl . tr ustStor ePassword"," f oo123");

System. setProperty( "j avax. net. ssl . keyStore", "p12/wstest. j ks"); System. setProperty( "j avax. net. ssl . keyStorePassword"," f oo123");

QName qname = new QName(" htt p:/ / ws. protocol . core. ej bca. org/ ", "Ej bcaWSServi ce") ; Ej bcaWSServi ce servi ce = new Ej bcaWSServi ce(new URL( url st r ) , qname); ejbcaraws = servi ce. get EjbcaWSPort () ;

Example call to find all users having 'Vendil' in their subject dn:

UserMatch usermatch = new UserMat ch() ; user mat ch. set Mat chwi t h( User Mat ch. MATCH_WI TH_DN) ; user mat ch. set Mat cht ype( User Mat ch. MATCH_TYPE_CONTAI NS) ; usermatch. setMatchval ue( "Vendi l ") ; Li st <UserDataVOWS> resul t = ej bcaraws. f i ndUser( user match);

Example generating a certificate from a PKCS10 request:

User Dat aVOWS user 1 = new User Dat aVOWS( ) ; user 1. set User name( "WSTESTUSER1") ; user 1. set Subj ect DN( "CN=WSTESTUSER1") ; user 1. set CaName( "Admi nCA1") ; user1.setEmail (null ); user1. setSubj ectAl t Name(nul l ) ; user1. setEndEnt i t yProfi l eName(" EMPTY") ; user1. setCert i f i cateProf i l eName(" ENDUSER") ;

KeyPai r keys = KeyTool s. genKeys( "1024", Al gori t hmConstant s. KEYALGORITHM_RSA); PKCS10Cer t i f i cat i onRequest pkcs10 = new PKCS10Cert i f i cati onRequest ( "SHA1Wi t hRSA", Cert Tool s. st ri ngToBcX509Name(" CN=NOUSED") , keys.getPubl i c( ) , null , keys.getPr i vate() );

Certi f i cateResponse cert env = ej bcaraws. certi f i cat eRequest( user1, Cert i f i cateHel per. CERT_REQ_TYPE_PKCS10, new Str i ng( Base64. encode(pkcs10.getEncoded() ) ) , nul l , Cert i f i cateHel per. RESPONSETYPE_CERTI FI CATE);

X509Cert i f i cate cert = cert env.getCert i f i cate ( ) ;

Example checking the revocation status of a certificate:


9 of 38

RevokeSt atus r evokestatus = ej bcaraws. checkRevokati onStatus( cert . get I ssuerDN. t oSt ri ng, cert . getSeri al Number( ) . t oStr i ng( i f ( r evokes tatus != nul l ){ i f ( revokest atus. get Reason() != RevokeStat us.NOT_REVOKED) ) { / / Cert i f i cate i s revoked }el se{

/ / Cert i f i cate i sn' t revoked } }el se{

/ / Cert i f i cate doesn' t exi st }

Sample code

See the file modules/ejbca-ws/src/org/ejbca/core/protocol/ws/common/IEjbcaWS for more detailed instructions of the API. Samplecode can be taken from:

The JUnit tests for the WS-API: modules/systemtests/src/org/ejbca/core/protocol/ws/EjbcaWSTest.javaThe WS-API CLI: modules/ejbca-ws-cli/src/org/ejbca/core/protocol/ws/client/*.java

Accessrules required when using the Web Service API

All the calls requires HTTPS client authentication. The keystore used must be set up as a regular administrator and access rulesaccording to the following:

Common for all calls (except isAuthorized, existsHardToken, isApproved that only needs a valid trusted certificate):

/administrator /ca/'related CA'

editUser:

/ra_functionali ty/create_end_entity and/or edit_end_enti ty /ra_functionali ty/'end entity profile of user'/create_end_entity and/or edit_end_entity

findUser, findCert:

/ra_functionali ty/view_end_entity /ra_functionali ty/'end entity profile of the user'/view_end_enti ty

pkcs10Request, pkcs12req:

/ra_functionali ty/view_end_entity /ra_functionali ty/'end entity profile of the user'/view_end_enti ty /ca_functionality/create_certificate

certificateRequest, softTokenRequest:

/ra_functionali ty/create_end_entity and/or edit_end_enti ty /ra_functionali ty/'end entity profile of user'/create_end_entity and/or edit_end_entity /ca_functionality/create_certificate

revokeCert, revokeToken: These calls support approvals.

/ra_functionali ty/revoke_end_enti ty /ra_functionali ty/'end entity profile of the user owning the cert'/revoke_end_entity

revokeUser: This call support approvals.

/ra_functionali ty/revoke_end_enti ty /ra_functionali ty/'end entity profile of the user'/revoke_end_enti ty /ra_functionali ty/delete_end_enti ty (only if users should be deleted) /ra_functionali ty/'end entity profile of the user'/delete_end_entity (only if users should be deleted)

fetchUserData: It is possible to turn of authorization of this call in the jaxws.properties

/userdatasourcesrules/'user data source'/fetch_userdata

genTokenCertificate: Important this call also supports approvals, and the default behaviour is when someone without the'/administrator' access is creating a call then will a GenerateTokenApprovalRequest be created. This behaviour can be turned off inthe jaxws.properties file.

/ra_functionali ty/create_end_entity and/or edit_end_enti ty /endentityprofilesrules/'end entity profile of user'/create_end_entity and/or edit_end_entity /ra_functionali ty/revoke_end_enti ty (if overwrite f lag is set) /endentityprofilesrules/'end entity profile of user'/revoke_end_entity (i f overwrite flag is set) /ca_functionality/create_certificate /ca/'ca of all requested certificates'hardtoken_functionality/issue_hardtokens

getHardTokenData: Important this call also supports approvals, and the default behaviour is when someone without the'/administrator' access is creating a call then will a ViewHardTokenApprovalRequest be created. This behaviour can be turned off inthe jaxws.properties file.

/ra_functionali ty/view_hardtoken /endentityprofilesrules/'end entity profile of user'/view_hardtoken /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if vi ewPUKData = true)

getHardTokenDatas:

/ra_functionali ty/view_hardtoken /endentityprofilesrules/'end entity profile of user'/view_hardtoken /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if vi ewPUKData = true)

republishCertificate:

/ra_functionali ty/view_end_entity /endentityprofilesrules/'end entity profile of the user'/view_end_entity /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if vi ewPUKData = true)

customLog: No CA access rule is required.

/log_functionality/log_custom_events (must be configured in advanced mode when editing access rules)

deleteUserDataFromSource:

/userdatasourcesrules/'user data source'/remove_userdata (for all the given user data sources)

getCertificate: no requirement of the '/administrator' flag


10 of 38

/ca_functionality/view_certificate

caCertResponse, caRenewCertRequest:

/ca_functionality/renew_ca

Error codes on web services

Business error code have been added in order to discriminate exception of type Ej bcaExcept i on.

The following code sample shows how to use error codes :

t r y { ej bcaraws. edi t User( user1) ;} cat ch(Ej bcaExcept i on_Excepti on e) { i f ( org.ej bca.core.Err orCode.CERT_PROFI LE_NOT_EXI STS.getI nternal ErrorCode() . equal s(e. getFaul tI nfo() . getErr orCode() . get l og. error("No such cert i fcate prof i l e ." ) ; }}

All error codes are described in org.ej bca.core.Err orCode.

You can also take a look at src/ t est/ org/ ej bca/ core/ protocol / ws/ CommonEj bcaWSTest. j ava to see how the error code can be used.

WS transaction logging

The logging is done the same way as the logging for the OCSP responder is done. See OCSP Audit and Account Logging. Butdifferent tags are used:

LOG_TIME : The time the call took placeSESSION_ID : A random 32 Byte long String generated when the OCSP-responder is started.LOG_ID : An integer identifying that starts from 1 and is increased for every received request.REPLY_TIME : The time it took to return from the WS method.METHOD : Name of the called WS method.ERROR_MESSAGE : An error message with information of the error. If the call returned successfully then 'NO_ERROR'.ADMIN_DN : Subject DN for the client certificate in the call.ADMIN_ISSUER_DN : Issuer DN of the client certificate in the call

The configuration is done in ./conf/jaxws.properties.

In jboss-log4j.xml 'org.ejbca.core.protocol.ws.logger.TransactionLogger' should be used as category name for the appender.

XKMS Service

Introduction

From EJBCA 3.4 the XKMS protocol is supported as a service as a complement to the EJBCA Web Service interface.

It's disabled in the standard installation (from EJBCA 3.10) and have the Web Service URL http://"hostname":8080/ejbca /xkms/xkms

NOTE: XKMS only works well with JDK 1.5, it does not work with JDK 6.

How to configure the XKMS Service

The XKMS service is configured in the file conf/xkms.properties, just edit the file before building the application.

The following settings exists:

xkms.enabled: Enables the XKMS Service (default: false)xkms.request.requiresignature: id signed XKMS request should be required (default: false)xkms.request.acceptedcas: List of CA names that are accepted for XKMS signed requests. Use ';' as a separate for multiple.(default 'AdminCA1')xkms.response.acceptsignrequest: Accept signed responses on request (defaul t: true)xkms.response.alwayssign: Always sign responses (default: false)xkms.response.causedforsigning: Specify which CA that should be used with the signed responses. Only one can bespecified. (default 'AdminCA1')xkms.keyusage.signatureisnonrep: Setting specifying the keyusage in a X509 certificate that is mapped to XKMS KeyUsageSignature, Default is non-repudiation but if set to false will XKMS KeyUsage Signature be mapped against digital signatureX509 key usage.xkms.serviceport=This is a development setting that is set in the WSDL to instruct the client use a non default port. This isonly needed if a WS tap listener is used to review the messages. (default: 8080)xkms.krss.poprequired=Defines if proof of possession of the private key is required (default: true)xkms.krss.servergenkeylength=Defines the key length of server generated keys (default: 1024)xkms.krss.allowrevokation=Defines it should be possible for users to revoke their certificate with a revocation code (default:true)xkms.krss.allowautomaticreissue=Setting to allow the user to renew automatically as long as the current key isn't revoked(default: false)

Important, if signing of responses is needed, must the XKMS CA service for the configured CA be activated in the 'Edit CA' page.The XKMS Signer have it's own certificate for each CA just as the OCSP service and is created during the installation or upgrade of a CA.

Implementation Specific Notes

*** What is implemented ***

Currently are the methods locate, validate, register, reissue, revoke and recover). The Compond request isn't implemented.

The XKMS Service only supports synchronized calls, not asynchronized or two-phase requests.

The TimeInstant attribute of QueryKeyBinding is not supported

In the NotBoundAuthentication isn't the 'Protocol' attribute used.

The register listener expects a UseKeyWith=urn:ietf:rfc:2459 (PKIX) with the subjectDN as identifier and is mapped to theuser. The password of the user Must be marked as cleartext in order for KRSS to work. In KeyInfo is one RSAKeyInfo requiredif the user have the type 'USERGENERATED'. All other UseKeyWith or KeyUsage is ignored. since it is the register userdatathat is used when issuing the certificate. If the user have the type "P12" in it's userdata then will a server generated key beinserted in a PrivateKey in the response. It is the same password to encrypt the key as for the enrollment. RespondWithRSAPublicKey, X509Certificate, X509CertificateChain and PrivateKey is supported.

The reissue listener expects one X509Certificate KeyInfo in the request and the subjectDN and public is extracted and used forthe new certificate. Revoked certificates cannot be renewed. The generated key will be inserted in a PrivateKey in theresponse. It is the same password to encrypt the key as for the enrollment. RespondWith RSAPublicKey, X509Certificate andX509CertificateChain.


11 of 38

The recover listener expects one X509Certificate KeyInfo in the request and is used to select the user in the database. Beforea key can be recovered the key have to be marked for recovery and a password set for the user in the usual way.RespondWith RSAPublicKey, X509Certificate, X509CertificateChain and PrivateKey is supported.

The revoke listener expects one X509Certificate KeyInfo in the request and is used to select the certificate that should berevoked. A revokation code is required, authentication tag is not supported. RespondWith RSAPublicKey, X509Certificate andX509CertificateChain is supported.

*** XKMS Mappings ***

The RespondWith tag supports X509Certificate, X509CertificateChain, X509CRL, KeyName, KeyValue (and PrivateKey forregister and recover).

The QueryKeyBinding The query of a QueryKeyBinding is performed in the following way: If KeyInfo is included, the certificateis extracted and the is used for checking the key usage and validity of the certificate If UseKeyWith is included (and noKeyInfo) is the user database queried using the UseKeyWith mappings (if several UseKeyWith are the queried with an 'AND'operator. Then are all certificates that fulfills all the KeyUsage mappings returned.

In KeyInfo is only X509Certificate and X509CertificateChain supported

KeyUsage Mappings, The key usage constants is mapped against the following X509 key usages

SIGNATURE : either non-repudiation or digital signature depending on configurationENCRYPTION: data enciphermentEXHANGE: digital signature and key encipherment

UseKeyWith Mappings, All queries find their data using beginwith (except PKIX) of the identifier.

XKMS: Subject Altname, UNIFORMRESOURCEIDENTIFIERXKMS/profile: Subject Altname, UNIFORMRESOURCEIDENTIFIERS/MIME: Subject Altname, RFC822 addr-specPGP: Subject Altname, RFC822 addr-specTLS: Subject Altname, UNIFORMRESOURCEIDENTIFIERTLS/HTTPS: SubjectDN, Common NameTLS/SMTP:Subject Altname, DNS NameIPSEC:Subject Altname, IP AddressPKIX: Entire SubjectDN

Using the XKMS client

When building EJBCA, a XKMS CLI tool is also generated. The tool is placed in the directory dist/ejbca-xkms-cli and consists of theall the necessary files needed to run the cli.

To use the client do the following, copy the directory with all included files to the computer you want to remote administrate from.(Optionally create a JKS keystore from one XKMS Service trusted CAs) and configure the file xkmscli.properties. In this file youshould specify the hostname of the CA server, the name of the JKS keystore, the alias and the password to unlock it.

Use 'xkmscli.sh/cmd' for a list of each subcommand and 'xkms.sh/cmd "subcommand"' for detailed help how to use the cli.

Running the XKMS test script

To automatic test the XKMS Service do the following:

1. Start with a fresh installation with all the default values. Then activate the XKMS CA service in the Edit CA page for AdminCA1.

2. Run 'ant test:xkms' and a link to the report will be shown.

External RA API

Information on how to use the External RA API is available here.

Key recovery

Key Recovery can be used to re-use or restore a users private key. To enable key recovery use the admin-GUI:

Set 'Enable Key Recovery' in 'System Configuration'.1.

Create a new End Entity Profile and set to use 'Key Recoverable'.2.

Add users with this End Entity Profile.3.

The following is an example of a sequence of commands that can be used to generate a new certificate for a user using the same keypair:

# First revoke username, with revocation reason reason,

bi n/ ej bca.s h ra revokeuser $username $r eason

# then mark the certificate for keyrecovery,

bi n/ ej bca.s h ra keyrecovernewest $username

# then set clear text password for Batch session to use

bi n/ ej bca.s h ra setcl earpwd $username $userpass

# and finally reissue the certificate.

bin/ ejbca.sh batch

The same can be accomplished using a browser:

Admin GUI - List/Edit End Entities - View_Certificates for user - Revoke the certificate with revocation reasonAdmin GUI - List/Edit End Entities - View_Certificates for user - Recover Key, CloseAdmin GUI - List/Edit End Entities - Edit_End_Entity for user - Enter new password for user, SavePublic Web - Create Keystore - Enter username and password - Fetch the keystore

Technical details

What the operation "bin/ejbca.sh ra keyrecovernewest", or "recover key" in the admin GUI, or keyRecoverNewest in the WS APIactually does is that it marks the user/certificate for key recovery. This means that the next time you make a call to generate akeystore (p12/jks/pem) for the user the CA will get the private key, held encrypted in the recovery database, and the existinguser certificate or a new certificate, and create a keystore for the user with this old key pair. The actual recovery would thenhappen when you make a call to i.e. pkcs12Req in the WS API, or if keystore type is P12, JKS or PEM in the admin GUI.

Email notifications

Mail settings in JBoss is created when running the 'ant deploy' using the values specified in conf/mail.properties (or default).


12 of 38

It is (automatically) configured in $APPSRV_HOME/server/default/deploy/ejbca-mail-service.xml for JBoss. For other containers youmust create a mail service with the same JNDI name as specified in conf/mail.properties.

End entity email notifications

Email notification can be sent when status changes for an end entity, for example when a new user is added (status changes tonew).

To configure email notifications in EJBCA:

You must create a new end-entity profile to be able to issue certificates to end users using email notifications. Under the RA

functions, choose "Edit End Entity Profiles" and add a new profile. Select the profile and go into 'Edit End Entity profile'. Inthis page you can Enable Send Notifications and create the notification message. Make sure the checkbox 'Use SendNotification' is checked.

1.

Add a new end entity. You must select the new end entity profile you created above. Make sure the checkbox 'SendNotification' is checked. Enter the from-address and subject. Enter a message using the variables defined for dynamicsubstitution in the next section. Use ${NL} for newline in the mail message.

2.

The Notification Recipient can have a few different values:

USER: send notification to the email registered for the end [email protected]: send notification to the specified email address. Multiple email addresses can be entered comma separated.CUSTOM: plug-in mechanism to retrieve addresses your own way. See interfaceorg.ejbca.core.model.ra.raadmin.ICustomNotificationRecipient for implementation details. Enter a string like"CUSTOM:org.ejbca.MyCustomPluginClass" to use.

You can also use substitution variable in the notification sender and recipient fields. See samples below.

The Notification Events specify which status changes for a user that will trigger a notification. The default values are suitable tosend an email to a user when he/she should go and pick up a certificate. You can also select for example STATUSGENERATED tosend email notifications to an administrator when the user picks up the certificate.

Tip: If you configure autogenerated password in end entity profile you don't need to enter one in the adduser page. A generatedone will automatically be sent with the email.

If you want to re-send a notification for a user, reset the status to NEW.

Dynamic Substitution Variables

Parameters that can be used with different usages of email notification. All parameters isn't always set, it depends on the inputdata.

The following parameters can be set:

${NL} = New Line in message${DATE} or ${current.DATE} = The current date

Variables used with userdata:

${USERNAME} or ${user.USERNAME} = The users username${PASSWORD} or ${user.PASSWORD} = The users password${CN} or ${user.CN} = The common name of the user.${SN} or ${user.SN} = The serial number (in DN) of the user.${O} or ${user.O} = The user's organization${OU} or ${user.OU} = The user's organization unit${C} or ${user.C} = The user's country${user.E} = The user's email address from Subject DN${user.TIMECREATED} = The time the user was created${user.TIMEMODIFIED} = The time the user was modified${approvalAdmin.XX} variables from below can be used to get the administrator who adds an end entity.

Variables used with approvals:

${approvalRequest.DATE} = The time the approval request was created${approvalRequest.ID} = The id of the approval request${approvalRequest.ABS.ID} = The id of the approval request with out any '-' sign, used for presentation purposes.${approvalRequest.TYPE} = The type of approval request${approvalRequest.APROVEURL} = A URL to the review approval page with the current request.${approvalRequest.APPROVALSLEFT} = The number of approvals remaining.${approvalRequest.APPROVALCOMMENT} = The comment made by the approving/rejecting administrator${requestAdmin.USERNAME} = The requesting administrator's username${requestAdmin.CN} = The common name of the requesting administrator.${requestAdmin.SN} = The common name of the requesting administrator.${requestAdmin.O} = The requesting administrator's organization${requestAdmin.OU} = The requesting administrator's organization unit${requestAdmin.C} = The requesting administrator's country${requestAdmin.E} = The requesting administrator's email address from Subject DN${approvalAdmin.USERNAME} = The approving administrator's username${approvalAdmin.CN} = The common name of the approving administrator.${approvalAdmin.SN} = The common name of the approving administrator.${approvalAdmin.O} = The approving administrator's organization${approvalAdmin.OU} = The approving administrator's organization unit${approvalAdmin.C} = The approving administrator's country${approvalAdmin.E} = The approving administrator's email address from Subject DN

Variables used with expiring certificates:

${expiringCert.CERTSERIAL} = The serial number of the certificate about to expire${expiringCert.EXPIREDATE} = The date the certificate will expire${expiringCert.CERTSUBJECTDN} = The certificate subject DN${expiringCert.CERTISSUERDN} = The certificate issuer DN

Examples

In certain circumstances, e.g. when you need to comply with PCI or the lighter levels of FIPS-140/160, it may be required toconfigure a 2 step issuance process. This can by done by using the notifications. Create 3 email notifications:

To: USER

Email notification to -just- the user with the URL to pick up the cert and the username. Make clear in the message that heor she will be contacted by the approving admin with the password.

1.

To: ${approvalAdmin.E}

Email notification to the apporiving admin with the password (but not the username) and a message which makes clear thatthis password is to be passed to the user - by phone or f2f (but not by email).

2.

To: ca-team@foo... **

Email notification of the issuing to the auditor mailing lists - without above username/password.

3.


13 of 38

Printing of User Data

From EJBCA 3.4 it is possible to have userdata printed on a printer whenever an end entity is added or edited. The functionality ispractically the same as for notifications.

This is configured in the end entity profiles by selecting a printer, the number of copies and uploading a SVG formatted template.There exists a template in 'src/cli/svgTemplate/Batch PIN envelope print.svg' that can be used for testing.

For more information how to write EJBCA SVG templates see: http://wiki.ejbca.org/ (Administration->hardtokenprofiles).

One good SVG client can be downloaded from inkscape.org

In order to renew the list of available printers you must restart the http session since the list is cached for performance reasons.

Approving Actions

It is possible to have other administrators (1-5) to approve an action in order to make sure the correct data is entered.

Currently are the following actions are enabled for approvals :

Add End EntityEdit End EntityChange User StatusRevoke End EntityRevoke Token (approval for each certificate)Revoke CertificateReactivate Certificate On Hold

In the main menu there is a new option 'Approve Actions' that lets the administrator to search for waiting requests and review its dataand finally gives his approval or reject the action.

Configuring Approvals

Approvals are configured for each CA, in the 'Edit Certificate Authorities' page and for each certificate profile in the 'Edit CertificateProfiles' page. Just select the actions that needs approval and the number of approvers required and save. The actions 'Add EndEntity', 'Change End Entity' and 'Change User Status' are all covered by the setting 'Add/Edit End Entity'. 'Revoke End Entity', 'RevokeCertificate', 'Revoke Token' and 'Reactivate Certificate' are covered by setting 'Revocation'. Approvals will be required if the CA or thecertificate profile enforces it and in case the number of approvers differs between the CA and the certificate profile the largest numberof approvers will be used.

Authorizing Approving Administrators

In order to authorize an administrator to review approval requests do one of the following.

Using Basic Rule Sets:

Give an admin group the role of SuperAdmin, CAAdmin or RAAdmin with Approve End Entities selected.

The SuperAdmin and CAAdmin gives access to approve rules not associated with any end entity profile (I.e dual authenticated CAconfiguration (Not implemented yet)) while the RAAdmin only can approve actions related to authorized end entity profiles.

Using Advanced Rule Sets:

There are three new access rules:

'/cafunctionality/approve_caaction' , a rule that gives access to non end entity profile related actions like approving CA editingand creation (not implemented yet). An administrator must have either this rule or the '/rafunctionalty/approve_end_entity' inorder to access the 'Approve Actions' web pages.'/rafunctionalty/approve_end_entity' , a rule (along with the corresponding end entity profile rule) that gives access to end entityprofile related access rules, like adding and editing end entities. The administrator must also have the 'approve_end_entity rule'for at least one of the '/endentityprofilerules/' in order to approve any actions.'/endentityprofilerules/<endentityprofilename>/approve_end_entity' see previous rule.

Two Different Approval Requests

In the system there are basically two different classes of requests. One is requests to do some action, like adding an end entity, andthat is executed directly after the last required administrator has approved the action. This type is called 'Executable Action Request'.The other type are requests to get hold of some information, like hard token PUK codes or archived keys. This kind of request isapproved when the last administrator gives his consent and is valid for a defined period of time (in conf/ejbca.properties). In this caseis the requesting administrator supposed to poll the approval request if it has been approved or not. These requests are called'Non-Executable Action Requests'.

Explanation of approval status

Here follows an explanation of what the different approval requests statuses.

Waiting: Means that the action request is waiting to be processed by authorized administrators, request are valid for the timespecified by approval.defaultrequestvalidity in conf/ejbca.properties before it is set to status Expired.

Approved : Means that the action request is approved and is valid for the amount of time specified byapproval.defaultapprovalvalidity in conf/ejbca.properties. After this it is set to Expired. Used by action requests that are notexecutable.Rejected : Means that the action request is rejected and won't be allowed. The rejection lasts the amount of time specified byapproval.defaultapprovalvalidity in conf/ejbca.properties. After this it is set to Expired and a new request can be done. Used byaction requests that are not executable.Expired : Means that the action request isn't valid any more and cannot be processed. The requesting administrator has to makea new request in order to approve it.Expired and Notified : Same as 'Expired' but also indicates that the requesting administrator has been notified about that hisrequest have expired.Executed : Means that the action request have been executed successfully. Used by action requests that are executable.Execution Failed : Means that the action request failed for some reason during execution, see log for more information. Used byaction requests that are executable.Execution Denied : Means that the action request hasn't been approved and will not be executed. The difference with status'Rejected' is that this status is only used with executable requests and don?t have any expire time. This means that therequesting administrator can apply again directly after the rejection.

Approval Notification

EJBCA approval functionality have been enhanced to sent notifications about approval requests.

To enable approval notification go to the system configuration page and check the 'Use Approval Notification' checkbox. You are alsorequired to set the email-address to the approving administrators. This should be a mail-alias to all administrators that should be ableto review approval requests and the from address that should be used when EJBCA sends emails.

Then whenever an approval request is created an e-mail is sent both to the requesting admin (if he has an e-mail configured in hisuser data) and to the approval administrators.


14 of 38

When the approving administrators have recieved the mail, there is a link directly to the approve request page where he can reviewthe requests. When he has approved and rejected the requested all the other administrators in notified about this.

The text of notifications is configured in src/intresources.xx.properties. See the ' Dynamic Substitution Variables' section in thismanual for a list of available variables.

Remember to configure mail-server settings in the ejbca.properties file.

Framework for External User Data Sources

In EJBCA 3.3 there exists a basic framework of custom user data sources for importing user data from existing databases.

These instructions is intended for EJBCA developers.

Currently there exists a standalone framework for implementing custom user data sources in the same way as for custom publishers.Later on will ready made LDAP and AD userdatasources be implemented to be used out of the box.

A custom userdatasource have two extra fields of data

The first one is a set of CA ids that the userdatasource is applicable to. It can have a constant BaseUserDataSource.ANY_CA.

The second is a set of fields instructing the RA interface GUI which fields that should be modifyable by the RA and which that shouldbe fixed. Important, there is not connection between the user data source, isModifyable data and the end entity profile isModifyabledata. The userdata source is only an instruction to the RA gui then when the userdata is added will it be matched against the endentity profile, and it's the data in the end entity profile that really counts.

Tip. The RA gui should read non-modifyable data twice since the RA could change the postdata even if the form have a field asdisabled.

To implement a custom user data source do the following:

Create a class implementing the interface org.ejbca.core.model.ra.userdatasource.ICustomUserDataSource containing the

methods: init(), fetch() and testConnection(), see org.ejbca.core.model.ra.userdatasource.DummyCustomUserDataSource for ansimple example implementation.

1.

Create a jar file containing the class and deploy it to the application server.2.

Make the user data source available to EJBCA by adding a userdata source, choose 'Custom user data source' as type and enterit's classpath and properties (using the same semantics as a regular java property file).

3.

Now it is possible to fetch userdata from the userdata source from custom implemented webpages using the

UserDataSourceSession session bean calling the method java.util.Collection IUserDataSourceSessionLocal.fetch(Admin admin,Collection userdatasourceids, String searchstring) method.

4.

Framework for Reports

Jasper Reports and JFreeChart. The reports function can be accessed from the Admin-GUI under 'Supervisor Functions->Reports'.JasperReports files can be created using the free tool iReport (http://jasperforge.org/sf/projects/ireport). The report definition file isunder src/adminweb/WEB-INF/reports/reports.jrxml. There are a few pre-defined reports, and suggestions for more real-usagereports are welcome.

To create a new report:

Create a report definition file and put in src/adminweb/WEB-INF/reports/*.jrxmlAdd a new method generating the report in src/java/org/ejbca/ui/web/admin/reports/ReportsManagedBean.javaAdd potential new methods to src/java/org/ejbca/ui/web/admin/reports/ReportsDataSource.javaEdit src/adminweb/reports/resportslist.jsp and add a call to the new method in ReportsManagedBean

Services Framework

EJBCA has a framework for timer services, i.e. procedures that should be run on a timely basis. Currently there exists five types of services:

a 'CRL Updater' that automatically updates the CRL.a 'Certificate Expiration Checker' that checks if a CA have certificates about to expire and sends an email notification to the enduser and/or the administrator.a 'User Password Expire Service' that checks if a user have not enrolled for a new certificate within a certain amount of timeafter been registered, and expires the users possibility to enroll.a 'Renew CA Service' that checks if CA certificates are about to expire and renews them.a 'Publisher queue process service' that retries failed publishing.

It is also possible to easily write plug-ins for customized services.

A service consists of the components, a worker doing the actual work, an interval determining the time to the next time the serviceshould run and an action (optional) of what should be done if a certain condition occurs.

Configuration

*** Workers ***

The worker is the class that will be executed when the service runs. Each worker can have different worker specificconfiguration.

*** Intervals ***

Periodical Interval

Defines in days/hours/minutes/seconds of how often the worker will be run.

*** Actions ***

Mail Action

Action that sends an email notification when the service is executed and have the following settings:

Sender Address - The from-address used in the email.Receiver Address - The to-address of the email of it isn't specified by the worker.

Currently Available Services

CRL Update Service

The CRL Updater have the same functionality as the current JBoss Service and will in the future replace the old variant. I checks if any of the CA:s need a new CRL and updates it if necessary. The worker have no settings and only supports the periodical intervaland no action.

The CRL update worker should never run simultaneously on two nodes, or simultaneously on one node. To avoid running morethan one instance on a single node there is a semaphore that inhibits more than one instance of the worker to run in a singleJVM. If a worker starts and another worker is already running the worker is rescheduled to run on the next planned interval, andimmediately terminated.


15 of 38

To avoid running any two services on two nodes simultaneously, the service have a time stamp that is set when it runs, andschedules the next run before the actual work is started. This time stamp makes it possible for another node to determine of theservice is already running on another node and not start running.

In practice what this leads to is that a service will always run on a single node, the same node every time.

Certificate Expiration Check Service

A worker that checks if a CA have certificates about to expire and sends an email notification the the end user and/oradministrator. The worker have the following settings:

CAs to Check - Select here which CAs that should be searched for expiring certificates.Time before notification is sent - The number of Days/Hours/Minutes/Seconds that should remain of the certificates validitybefore the notification is sent.Send notification to end user - Check this if a notification should be sent to the owner of the certificate. Observe that theend user must have an email set in the user database (not necessarily in the certificate) in order for the service to send thenotification.Notification Subject to End User - The e-mail subject.End User Message - Message body of the notification. Here can the substitution variables be used defined in the 'EmailNotifications' section.Send notification to Administrator - Check this if a notification should be sent to some defined administrator-mail address.The address of the administrator is configured in the Mail Action component.Notification Subject to Administrator - The e-mail subject.

Administrator Message - Message body of the notification. Here can the substitution variables be used defined in the 'EmailNotifications' section.

Note: you may configure multiple certificate expiration services set with differentTime before notification is sent values in order tofurther alert the user or administrator that a certificate is about to expire.

User Password Expire Service

A worker that checks if a user has not enrolled for a new certificate within a specified amount of time after the user was lastedited. If the user has not enrolled within this time, the user's status is set to Generated and the user will not be able to enroll.The worker have the same basic setting as the 'Certificate Expiration Check Service', except for 'Time before notification is sent'which is replaced by:

Time until user password expire - The number of Days/Hours/Minutes/Seconds that a user should be able to enroll for acertificate, i.e. the time before the user's password expire.

Renew CA Service

The renew CA service can be used to automatically renew CAs that are about to expire. This might be used for SubCAs that arevalid only short periods of time. The specific settings are:

CAs to Check - which CAs should be checked, and renewed if they are about to expire.Time before CA expires to renew - the amount of time before the CA actually expires that the service should renew the CA.

For CAs using soft keystores and not using the default password, auto-activation is required.

Publisher Queue Process Service

The publisher queue process service processes the publisher queue. In the publisher queue, entries where publishing failed iscollected. This service will try to re-publish entries from this queue. The specific settings are:

Publishers to check - which publishers should this service check and re-publish for. You can run one service for eachpublisher or one service for all publishers.

Note

If you run one service for each publisher you should onle configure one publisher in every service. Do not let twoservices handle the same publisher.

To read on how the algorithm to prevent excessive database load etc is done, the easiest way is to read in the java file for classPublishQueueProcessWorker.

The same algorithm as for the CRL update worker is used to make sure the service only runs in one instance on one node.

Writing Customized Services

It is possible to write customized component plug-ins that can be used with other standard (or customized plug-ins) and thissection explains the steps necessary.

Common for all the components is that it is required to create a class implementing the components interface. Then you have tocreate a jar containing the necessary plug-in classes and deploy it to application server so it is included in the class-path. The nextstep is to create a service using the custom component by specifying the class path and optionally the custom properties used bythe component. The properties field have the same syntax as a regular Java property file.

CustomWorker

A Custom worker must implement the org.ejbca.core.model.services.IWorker interface. But a simpler way is to inherit theBaseWorker class. Then you have to implement one method 'void work()' doing the actual work every time the serviceframework decides it is time. The work method can make a call to the action (optional) component by'getAction().performAction(someActionInfo);' The action info can vary depending on the action component but it mustimplement the ActionInfo interface.

If something goes wrong during the work should a ServiceExecutionFailedException be thrown with a good error message.

See org.ejbca.core.model.services.workers.DummyWorker for an example implementation.

CustomInterval

A Custom Interval must implement the org.ejbca.core.model.services.IInterval interface. But a simpler way is to inherit theBaseInterval class. You then have to implement one method 'public long getTimeToExecution();' which should return the timein seconds until the next time the service is run. Or it should return DONT_EXECUTE it the service should stop running.

See org.ejbca.core.model.services.intervals.DummyInterval for an example implementation.

CustomAction

A Custom Interval must implement the org.ejbca.core.model.services.IAction interface. But a simpler way is to i nherit theBaseAction class. Then should only one method be implemented 'performAction(ActionInfo actionInfo)' that should perform theaction according to the defined properties and the ActionInfo (all optional). If something goes wrong during the processing of the action should a ActionException be thrown.

See org.ejbca.core.model.services.actions.DummyAction for an example implementation.


16 of 38

Hardware Security Modules (HSM)

EJBCA have support for several HSMs. Each HSM has it's own interface for key generation and maintenance, specific to the HSM andindependent of EJBCA. You should make sure you are familiar with how your HSM works.

When configuring a CA to use a HSM in the administration GUI it is a property field where properties unique to this very HSM isspecified. All implemented HSM modules are using the same property keywords to define the identity and the purpose of the keys tobe used. These keywords are:

certSignKey - the key to be used when signing certificates, can be RSA or ECDSA.crlSignKey - the key to be used when signing CLSs, can be RSA or ECDSA.keyEncryptKey - the key to be used for key encryption and decryption, this must be an RSA key.testKey - the key to be used by HSM status checks, can be RSA or ECDSA.hardTokenEncrypt - the key to be used for hardtoken encryption and decryption. PUK will be decrypted by this key.defaultKey - the key to be used when no other key is defined for a purpose. If this is the only definition then this key will beused for all purposes.pin - optional pin code used for auto-activation of CA token, see below. Not recommended for high security set-ups, but veryuseful in some cases.

You may omit defaultKey if you want to be sure that the right key is used, but then all the other keys must be specified. It'srecommended that the certificate and CRL signing keys are linked to the same key since different keys are rarely supported byverifying applications.

When implementing support for a new HSM the 'KeyStrings' class could be used to manage the key properties described above. Whenit is an JCA/JCE API for the HSM it could also be wise to extend the BaseCAToken class.

The same activation code must be used for all keys used by a CA.

There are four additional key properties that can (optionally) be used when renewing CA keys and to produce roll-over certificates..

previousCertSignKey - this is the alias of the previous signature key, as opposed to 'certSignKey' which is the current signaturekey.previousSequence - this is the sequence identifying the previous signature key, as opposed to the current sequence that is heldin the CA token. This sequence will replace the current sequence in the caRef field when signing a request with the CAs previouskey.nextCertSigningKey - this is the alias of a new generated key on the HSM. When updating a CA signed by an external CA this isused to send a request, but the CA is still active using the old key. When the certificate response is received this key is activateand moved to certSignKey/crlSignKey.nextSequence - this is the sequence identifying the next signature key.

Supported and tested HSMs are described below, with sample configurations and HSM specific documentation.

Since EJBCA 3.6 the recommended HSM connector is to use the PKCS#11 interface. Older jce implementations will gradually bedeprecated and removed.

PrimeKey Solutions is selling a module called PrimeCardHSM that implements a flexible HSM using low cost smart cards.

Auto-activation of CA tokens

The 'pin' property is used to be able to automatically activate a CA token. The activation code may be specified in the propertyfield with the keyword 'pin'. If this property is not specified then the CA has to be manually activated after each restart orre-deployment of EJBCA.Manual activation is done in the admin-GUI under 'Basic Functions->View Information', or using the cli 'bin/ejbca.sh caactivateca'.

The 'pin' property can use a clear text password or an encrypted one.(encrypted is only available in EJBCA >= 3.5):

pi n f oo123pi n 6bc841b2745e2c95e042a68b4777b34c

These two properties contains the same password. The encrypted pin value can be obtained with the command 'bin/ejbca.shencryptpwd':

$ bi n/ ej bca.s h encryptpwd foo123Usi ng J Boss J NDI provi der. . .Please note that t his encrypti on does not provide absolute securi ty, . . . .Ent er word t o encrypt :hi ddenEncrypti ng pwd.. .6bc841b2745e2c95e042a68b4777b34c

NOTE: This encryption is not high security encryption, it is only meant to protect the password for accidental viewing. Theencryption uses a build in encryption key in EJBCA. With an encrypted pin you can for example bring up the 'Edit CAs' page in theadmin-GUI without everyone around immediately seeing your password.If an attacker gets hold of the encrypted value it is easy to decrypt using the source code of EJBCA.

HSMs and DSA or ECDSA

Support for DSA or ECDSA in HSMs are dependant on the support for the algorithms in the HSM manufacturers JCE provider. Youhave to check if that support is available.

Generic PKCS#11 provider

A PKCS#11 wrapper has been used to implement support for tokens with PKCS#11 libraries. The PKCS#11 provider have beentested with Utimaco CryptoServer and nCipher nShield/netHSM and SafeNet ProtectServer and SafeNet Luna and AEP Keyper andARX CoSign and Bull TrustWay.

Besides the keys previously described the property field of the administration GUI should contain the following properties:

slot - the slot of the CA.slotListIndex - the index number in the slot list for the slot of the CAsharedLibrary - the shared PKCS#11 library to be used.

But only one of 'slot' or 'slotListIndex' should exist.

Optionally a few extra properties fields can be used:

attributesFile - a file specifying PKCS#11 attributes (used mainly for key generation).keyspec - key specification used when generating new HSM keys from within the admin GUI. Keyspec that is used as firstchoice when generating new keys in the GUI of form "1024" for RSA keys, "DSA1024" for DSA keys and secp256r1 for ECkeys. If keyspec is not given EJBCA tries to generate a key with the same specification as the current cert signing key.

Attributes file is in the format specified in the "JavaTM PKCS#11 Reference Guide". See http://java.sun.com/javase/6/docs /technotes/guides/security/p11guide.html and the examples further down in th is file. An attr ibutes fil e for nCipher typically lookslike this:


17 of 38

att ri butes( gener ate, CKO_PRI VATE_KEY,* ) = { CKA_PRI VATE = t r ue CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_TOKEN = t r ue}

Note

If you are using an attributesFile and have more than one CA using the same slot it is very important that BOTH CA tokenproperties configurations contains the attributesFile. This is because the attributes are applied when the provider is installedduring startup. If one configuration does not have the attributesFile it can not be applied later on by the other configuration.

The tool "$EJBCA/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool" is used administrate and generate keys. Use itwithout parameters to get all valid options. Keys may be generated in two ways. Examples:

. / cl i entTool Box- di st / ej bcaCl i entTool Box. sh PKCS11HSMKeyTool generat e hsmp11. so 2048 defaul t Key 1

. / cl i entTool Box- di st / ej bcaCl i entTool Box. sh PKCS11HSMKeyTool gener ate hsmp11. conf 2048 defaul t Key

The first example uses the default attributes of the HSM and are then using specified slot and PKCS#11 library. The second uses aconfiguration file. The contents of the file is specified in the PKCS#11 wrapper documentation from Sun. Often it is enough to usethe default but with some HSM it necessary to define some PKCS#11 attributes for the generated key.

hsmp11.conf looks for example like this for a SafeNet ProtectServer Gold:

name=Saf eNetl i brary=/ opt / PTK/ l i b/ l i bcryptok i . sosl ot=1at t r i but e s( * , * , * ) = { CKA_TOKEN = t r ue}att ri butes( *, CKO_PRI VATE_KEY,* ) = { CKA_PRI VATE = t r ue CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_EXTRACTABLE = t r ue CKA_SENSI TI VE = t r ue}

All keys to be used has to be generated before the application server is started.

*** Generated HSM objects ***

EJBCA (the java PKCS#11 provider) needs three object on the HSM, which are all generated by the generate commandsabove:

A private keyA public keyA certificate - this is simply a holder of the public key used by java, and not the real certificate of a CA

Note

Normally when generating keys on the PKCS#11 HSM there will be a label on the certificate but not on the private and publickey. You can add a CKA_LABEL attribute to the attributes file to get a label on the private and public keys as well. The va lueof the attribute is a hexadecimal string starting with "0h". These labels are normally seen only when you use the native HSMtools to list and manipulate objects.

The above example would then include:

at t r i but e s( * , * , * ) = { CKA_TOKEN = t r ue CKA_LABEL = 0h6b657931}

The example above gives the label 'key1' to the private key. You can give any label by simply looking up the hex codes of characters in the ascii table.

*** SUN or IAIK PKCS#11 Provider ***

The IAIK PKCS#11 provider have support for more algorithms than the SUN provider, and therefore you can choose whichprovider to use. EJBCA first tries to load the IAIK provider, and if that is not available it uses the SUN provider. The SUNprovider is always available in JDK 5 and later. To enable the IAIK provider you must do the following:

Purchase server licenses for the IAIK PKCS#11 provider and obtain the files. Visit their website for more information.Copy three jar files to the application servers class path, for JBoss this is usually APPSRV_HOME/server/default/lib. The jar files needed are: iaikPkcs11Provider.jar, iaikPkcs11Wrapper.jar and iaik_jce.jar.Copy the PKCS#11 provider shared library to the library search path for your platform. On linux this might be done bycopying libpkcs11wrapper.so to /usr/lib.Start JBoss, EJBCA should now use the IAIK PKCS#11 provider instead of the SUN provider.

Utimaco CryptoServer

The Utimaco PKCS11 module have a configurable timeout (AppTimeout) that clears all session information if you do not use thekeys for some time. The default time-out is 30 minutes, which may be way too short if your CA is not very very active. Werecommend that you set this timeout to a longer value, several days.Put a configuration file in /etc/utimaco/cs2_pkcs11.ini:

[Gl obal ] Ti meout = 5000Loggi ng = 0Logpat h = / t mp

[ CryptoServer]Devi ce = TCP: [email protected]. 175. 128

Ti meout = 600000AppTi meout = 172800Sl otCount = 100

The timeout in this example of 172800 seconds will allow your CA to idle for a long time.

When using a PKCS#11 token you should first create keys with the command: $EJBCA_HOME/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate

Each CA should have its own slot.

Each slot must have been initialized before keys could be generated on the them. This includes setting a user PIN for it. The slotmust also require login. Tools for doing this is not provided from EJBCA. The HSM vendor should provide this tool.

Here follows an example on how to initialize a slot and generate keys to be used by EJBCA. The password is user1:


18 of 38

. / p11tool Slot=1 I nit Token=off i cer1

. / p11tool Sl ot=1 Label =CVCA Logi nSO=off i cer1 I ni t Pi n=user1$EJ BCA/ cl i ent Tool Box-di st / ej bcaCl i ent Tool Box. sh PKCS11HSMKeyTool generat e . / l i bcs2_pkcs11. so 4096 si gnKey 1PKCS11 Token [ SunPKCS11-l i bcs2_pkcs11.sosl ot 1] Password:Creati ng cert i f i cate wi th entr y si gnKey.$EJ BCA/ cl i ent Tool Box-di st / ej bcaCl i ent Tool Box. sh PKCS11HSMKeyTool generat e . / l i bcs2_pkcs11. so 2048 default Key 1PKCS11 Token [ SunPKCS11-l i bcs2_pkcs11.sosl ot 1] Password:Creati ng cert i f i cate wi th entr y defaul tKey.$EJ BCA/ cl i ent Tool Box-di st / ej bcaCl i ent Tool Box. sh PKCS11HSMKeyTool generat e . / l i bcs2_pkcs11. so 512 t estKey 1PKCS11 Token [ SunPKCS11-l i bcs2_pkcs11.sosl ot 1] Password:Creati ng cert i f i cate wi th entr y testKey.

You can view the pkcs11 objects created with the command:

. / p11tool Sl ot=1 Logi n=user1 Li st Obj ects

This is a example of a property field when creating the CA:

s l o t 1def aul t Key def aul t Keycert Si gnKey si gnKeycrl Si gnKey si gnKeyt estKey t estKeypi n user1sharedLi brary / opt / uti maco/ p11/l i bcs2_pkcs11. so

Utimaco have an emulator for their CryptoServer LAN HSM that can be used for test and development. If you have the emulationkit there is a howto in doc/howto/cryptoserver-lan-emulator.txt with steps to follow in order to use it with EJBCA.

You can check the status of a CryptoServer LAN device, for example the emulator with:

. / csadmDevi ce=TCP: 3001@172. 16. 175. 128 Get Stat e

*** Import a PKCS#12 file in Utimaco CryptoServer ***

Although not recommended it is possible to import keys from a p12 file to CryptoServer. These steps were contributed byPhilipp Vogt and Helmut Edlhaimb-Rexeis. The tools used are a combination of p11tool that ships with Utimaco HSMs and"ejbcaClientToolBox.sh PKCS11HSMKeyTool".

Import the .p12 file with p11Tool from Utimaco (into slot 20 in this example).p11tool Slot=22 AuthRSASign=GenPKIAd,:cs2:cyb:/dev/ttyS0 Login=123456 ID=TestCA2XYIDImportP12=mycert.p12,1234It is absolutely necessary to set an unique id (ID=...) at import time.The key alias for the imported key is set to "X509 Certificate" (taken from the imported certificate) and cannot bechange at import time.Rename the key alias to an unique key alias with "PKCS11HSMKeyTool rename" from ejbcaClientToolbox.ejbcaClientToolBox.sh PKCS11HSMKeyTool rename /etc/utimaco/libcs2_pkcs11.so 20 "X509 Certificate" "TestCA2Key"The new key alias is set to the label and the id of the CKO_CERTIFICATE and the id of the CKO_PRIVATE_KEY.Optional: Delete the public key with p11Tool using Label="RSA Public Key".p11tool Slot=20 Login=123456 Label="RSA Public Key" DeleteObjectTest the keys, to make sure they are usable from EJBCA.ejbcaClientToolBox.sh PKCS11HSMKeyTool test ./libcs2_pkcs11.so 20 1

Make sure no other public keys using this label are present in the HSM. Even if more than one .p12 file needs to be importedonly one at a time can be imported and renamed. The import and the rename process are tied together and cannot beseparated.

nCipher nShield/netHSM

This subsection describes how the nShield card from nCipher is used.

First the card has to be installed and admin and operator card sets has to be created. This is described in step 1.

Step 2 describes environments variables that must be set before generating keys and installing a new CA.

Step 3-5 describes PKCS#11 keys are generated and how different CAs within an installation is configured to use these keys. Inearlier versions of this manual it was also described how the nCipher JCA provider could be used by EJBCA. This has beenremoved since PKCS#11 keys are better in every respect.

1. Install the nShield card

Make sure you have all necessary software and drivers installed and created the user and group nfast. In Linux should thesoftware be installed to /opt/nfast or the location environment variable NFAST_HOME is pointing to.

login as the nfast user: 'sudo su nfast'

Set the nCipher box to initialization mode by setting the switch to mode 'I'.

Clear the nCipher box by pressing the reset button on the device

Check that the mode is in 'pre-initialization mode' and not in 'operational':

nfast @donny: / home/l ars/ work$ / opt / nfast / bi n/enqui ryServer: enqui r y repl y f l ags none enqui ry repl y l evel Six ser i al number 41C5- BA04-6D2C mode operat i onal versi on 2.23. 6 speed i ndex 147 r ec. queue 442. . 642 l evel one f l ags Hardware HasTokens versi on st r i ng 2. 23.6cam5, 2. 22. 6cam7 bui l t on Apr 25 2005 18: 15: 46 checked i n 00000000431dca98 Tue Sep 6 18: 58: 00 2005 l evel two f l ags none max. wri t e si ze 8192 l evel three f l ags KeyStorage l evel f our fl ags Order l yCl earUni t HasRTC HasNVRAM HasNSOPermsCmd ServerHasPol l Cmds FastPol l Sl otLi st HasSEE HasKLF H modul e t ype code 0 product name nFast ser ver devi ce name Enqui r ySi x versi on 4 i mpath kx gr oups f eature ctr l f l ags none f eatur es enabl ed none vers i on ser i a l 0 r emote ser ver port 9004

Modul e #1: enqui r y repl y f l ags none enqui ry repl y l evel Six ser i al number 41C5- BA04-6D2C


19 of 38

mode pre- i ni t i a l i sat i on versi on 2.22. 6 speed i ndex 147 rec. queue 9.. 152 l evel one f l ags Hardware HasTokens I ni t i al i sati onMode PreMai ntI ni t Mode versi on st r i ng 2. 22.6cam7 bui l t on Apr 25 2005 18: 15: 46 checked i n 00000000426636cd Wed Apr 20 13: 02: 37 2005 l evel two f l ags none max. wri t e si ze 8192 l evel three f l ags KeyStorage l evel f our fl ags Order l yCl earUni t HasRTC HasNVRAM HasNSOPermsCmd ServerHasPol l Cmds FastPol l Sl otLi st HasSEE HasKLF H modul e t ype code 6 pr oduct name nC1002P/ nC3022P devi ce name #1 nFast PCI devi ce, bus 0, sl ot 13. Enqui r ySi x versi on 5 i mpat h kx gr oups DHPr i me1024 f eature ctr l f l ags LongTerm f eatur es enabl ed StandardKM versi on seri al 24 r ec. LongJ obs queue 8 SEE machi ne t ype gen1AI Fnfast @donny:/ home/ l ars/ work$

Create the security world with the command :

nfast @donny: / home/l ars/ work$ / opt / nfast / bi n/new- worl d - i - Q 1/115: 04: 50 WARNI NG: Modul e #1: preempti vel y erasi ng modul e t o see i t s sl ots !

Create Securi t y Worl d: Modul e 1: 0 cards of 1 wri t t en Modul e 1 sl ot 0: empty Modul e 1 sl ot 0: unknown card Modul e 1 sl ot 0: - passphrase speci f i ed - overwri t i ng cardCard wr i t i ng compl ete.

secur i t y wor l d gener at ed on modul e #0; hknso = 6807e0b031c4f 797b739ec33ca7dba05279cf 54f nfast @donny:/ home/ l ars/ work$

The '-Q K/N' option tells how many administration cards that are created N. K of these cards will be needed to restore a modulewith a backup of the security world. '1/1' is a bad choice in production but will do in this example. Choose K>=3 and N>K inproduction.

Change mode on the switch on the device to mode 'O'.

Press the 'Clear' button again.

Check with 'enquiry' that the mode have changed to 'Operational'

Example on creation of operator cards:

nfast@donny:/ home/l ars/ work$ /opt/ nfast/ bin/ createocs -m 1 - Q 2/3 - N ej bca - M - p -T 0

Creati ng Cardset: Modul e 1: 0 cards of 3 wri t t en Modul e 1 sl ot 0: Admi n Car d #1 Modul e 1 sl ot 0: empty Modul e 1 sl ot 0: bl ank card Modul e 1 sl ot 0: - passphrase speci f i ed - wr i t i ng card (nami ng ÈJ BCA card 1' ) Modul e 1: 1 card of 3 wr i t t en Modul e 1 sl ot 0: r emove al r eady- wr i t t en card #1 Modul e 1 sl ot 0: empty Modul e 1 sl ot 0: bl ank card Modul e 1 sl ot 0: - passphrase speci f i ed - wr i t i ng card (nami ng ÈJ BCA card 2' ) Modul e 1: 2 cards of 3 wri t t en Modul e 1 sl ot 0: r emove al r eady- wr i t t en card #2 Modul e 1 sl ot 0: empty Modul e 1 sl ot 0: bl ank cardNew passphr ases do not mat ch; pl ease tr y agai n. Modul e 1 sl ot 0: - passphrase speci f i ed - wr i t i ng card (nami ng ÈJ BCA card 3' )Card wr i t i ng compl ete.

cardset cr eated; hkl t u = 8d30f 2ab5bdccacd8a4333aefed2c0ea1f f 0e6dbnfast @donny:/ home/ l ars/ work$

This will generate 3 cards of the card set named 'ejbca'. Any 2 of these cards will be needed when generating keys and startingejbca. Different card sets could be used for different CAs.

Note

The preload command (see below) must always be called as the same user unless the directory /opt/nfast/kmdata/preload isremoved.If you get a "HostDataAccessDenied" error when running preload or starting JBoss, it is because the file permissions on thedirectory /opt/nfast/kmdata/preload is wrong. It's probably because you (sometime) ran preload as another user, such as root ornfast.

Load the card set so that keys protected by the card set could be generated:

j boss@donny: ~$ / opt / nf ast / bi n/ pr el oad - c ej bca pauseLoadi ng cardset s:ej bca on modul es 1

Loadi ng èj bca' : Modul e 1 sl ot 0: èj bca' #3 (ÈJ BCA card 3' ) Modul e 1 sl ot 0: - passphrase suppl i ed - r eadi ng card Modul e 1 sl ot 0: èj bca' #3 (ÈJ BCA card 3' ) : al ready read Modul e 1 sl ot 0: empty Modul e 1 sl ot 0: èj bca' #2 (ÈJ BCA card 2' ) Modul e 1 sl ot 0: - passphrase suppl i ed - r eadi ng cardCard r eadi ng compl ete.

Loadi ng compl ete; now pausi ng

Step 2. Setup the environment.

Login as the user that is running the application server. This user must be a member of the nfast group.The following environment variables should be set for this user:

JAVA_HOME (/usr/local/jdk1.6.0_16 or similar)APPSRV_HOME (/home/jboss/jboss-4.2.3.GA or similar)EJBCA_HOME (/home/jboss/ejbca or similar)NFAST_HOME (/opt/nfast)

Step 3. Create PKCS#11 keys that should be used on the nShield card

Start a new window and login as the same user (jboss user). Create a file (ocs-sunpkcs11.cfg) with the following contents:


20 of 38

name=NFast J aval i brary=/ opt / nfast / tool k i t s /pkcs11/ l i bcknf ast . sosl otLi stI ndex=1att ri butes( gener ate, CKO_PRI VATE_KEY,* ) = { CKA_PRI VATE = t r ue CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_TOKEN = t r ue}

Note

An ECC key could not be used with preload (at least not the curve secp160r1). Such a key is generated OK and could be used aslong as the current preload is running. But if all preload processes are stopped and then if then preload is restarted the key couldnot be used. This means that ECC could only be used with a 1/n OCS.

Now 3 keys protected by the key set 'ejbca' are created like this:

j boss@donny: ~/ wor k/ t est / keygen$ ~nf ast / bi n/ pr el oad - c ej bca $EJ BCA_HOME/ cl i ent Tool Box- di st / ej bcaCl i ent Tool Box. sh PKCS11HExecut i ng / home/ l ars/ work/ j ava/ ej bca/ cl i entTool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / ocs-sunpkcs11.PKCS11 Token [ SunPKCS11-NFast J ava] Pass wor d:Creati ng cert i f i cate wi th entry defaul t.

j boss@donny: ~/ wor k/ t est / keygen$ ~nf ast / bi n/ pr el oad - c ej bca $EJ BCA_HOME/ cl i ent Tool Box- di st / ej bcaCl i ent Tool Box. sh PKCS11HLoaded pkcs11 uc17cf c7c330e613af 5709789f f 823a476177e233c-d165e440baa8dc9963780c682836ba17513e8cbf key ( RSAPri vat e) on moExecut i ng / home/ l ars/ work/ j ava/ ej bca/ cl i entTool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / ocs-sunpkcs11.PKCS11 Token [ SunPKCS11-NFast J ava] Pass wor d:Creati ng cert i f i cate wi th entry crypt.

j boss@donny: ~/ wor k/ t est / keygen$ ~nf ast / bi n/ pr el oad - c ej bca $EJ BCA_HOME/ cl i ent Tool Box- di st / ej bcaCl i ent Tool Box. sh PKCS11HLoaded pkcs11 uc17cf c7c330e613af 5709789f f 823a476177e233c-27cf dae84bf4298f 2dde83cd00980a81bcf 095bf key ( RSAPri vat e) on moExecut i ng / home/ l ars/ work/ j ava/ ej bca/ cl i entTool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / ocs-sunpkcs11.PKCS11 Token [ SunPKCS11-NFast J ava] Pass wor d:Creat i ng cert i f i cate wi th entr y test .

j boss@donny: ~/ wor k/ t est / keygen$

Step 4. Start EJBCA with nShield HSM

To start EJBCA, preload must be running with the required key stores loaded. In this example this was done in step 2. Preload isnow used to start jboss:

j boss@donny: ~/ wor k/ t est / ca$ ~nf ast / bi n/ pr el oad - c ej bca $J BOSS_HOME/ bi n/ r un. sh

Step 5. Create a new CA in the web GUI of EJBCA

Choose PKCS#11 as "CA Token Type".

Properties are defined according to the "Generic PKCS#11 provider" section above.

All preloaded operator card sets (OCSs) has it's own slot. It is not possible to predict the slot ID. But the index of the slot in theslot list is predictable. "slotListIndex" must therefore be used. If only one OCS is preloaded this index is always 1.

If several CAs is sharing same OCS (and hence slot) each key (identified by a key label) may only be used for one CA but the testkey. Same test key could be used for all CAs.

Example with previous generated keys where signRoot is used for CAs signing, and defaultRoot is used for everything else(encryption):

When preload is used no authentication code is needed to activate a CA. You could give any value for the authentication codewhen activating. The 'pin' property could be used in the configuration to automatically activate a CA. The value of this propertycould be anything.

def aul t Key def aul t Roott estKey t estkeyEncrypt Key cr yptRoothardTokenEncrypt cr yptRootpi n dummysl otL ist I ndex 1sharedLibrary / opt / nfast / tool k i t s /pkcs11/ l i bcknfast . so

Using module protected keys

Module protected keys do not need an operator card set. Hence no PIN code is needed to active such a key. A CA could beconfigured to use a keystore with module protected keys.

When using PKCS#11 slot 0 is used to indicate module protection. The only other thing except using slot 0 you have to do is touse a slightly different configuration file when creating the key. The file could look like this:

name=NFast J aval i brary=/ opt / nfast / tool k i t s /pkcs11/ l i bcknf ast . sosl otLi stI ndex=0att ri butes( gener ate, CKO_PRI VATE_KEY,* ) = { CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_TOKEN = t r ue}

Not using preload.

If a 1/N card set is used then preload don't have to be used (but it can be used). If preload is not used then jboss could be made tostart automatically at boot time.

For PKCS#11 simple do not use the preload command. The authentication code is now needed when activating the CA.

Using more than one OCS.

It is also possible to use more than one OCS. This is needed when you want different CAs protected by different OCSs.

The key to get this working is to set the environment variable CKNFAST_LOADSHARING=1. This environment variable is alsoimplicitly set when running with preload.

To get a list of all available slots do:

l ars@mi l t on:~/ work/ t est / nCi pher$ CKNFAST_LOADSHARI NG=1 ~nfast / bi n/ cki nfoPKCS#11 l i brar y CK_I NFO i nterf ace versi on 2.01 f l ags 0 manuf act urer I D "nCi pher Corp. Lt d " l i braryDescri pti on "nCi pher PKCS#11 1.58.48 " i mpl ementat i on versi on 1. 58

sl ots[ 0] CK_SLOT_I NFO s l otDescr i pt i on " " manuf act urer I D "nCi pher Corp. Lt d " f l ags 5 f l ags & CKF_TOKEN_PRESENT


21 of 38

f l ags & CKF_HW_SLOT hardware versi on 0. 00 f i rmware versi on 0.00

sl ots [ 0] CK_TOKEN_I NFO l abel "l oadshared accel erator " manuf act urer I D "nCi pher Corp. Lt d " model " " seri al Number " " f l ags 201 f l ags & CKF_RNG f l ags & CKF_DUAL_CRYPTO_OPERATI ONS ul MaxSessi onCount 1024 ul MaxRwSess i onCount 1024 ul MaxPi nLen 18446744073709551615 ul Mi nPi nLen 0 ul Tot al Publ i cMemor y CK_UNAVAI LABLE_I NFORMATI ON ul Fr eePubl i cMemor y CK_UNAVAI LABLE_I NFORMATI ON ul Tot al Pr i vat eMemor y CK_UNAVAI LABLE_I NFORMATI ON ul Fr eePr i vat eMemor y CK_UNAVAI LABLE_I NFORMATI ON hardware versi on 0. 00 f i rmware versi on 0.00 utcTi me " "

sl ots[ 1] CK_SLOT_I NFO sl otDescri pti on "1of 2_0 " manuf act urer I D "nCi pher Corp. Lt d " f l ags 6 f l ags & CKF_REMOVABLE_DEVI CE f l ags & CKF_HW_SLOT hardware versi on 0. 00 f i rmware versi on 0.00

sl ots[ 1] Token not presentsl ots[ 2] CK_SLOT_I NFO sl otDescri pti on "2of 3_0 " manuf act urer I D "nCi pher Corp. Lt d " f l ags 6 f l ags & CKF_REMOVABLE_DEVI CE f l ags & CKF_HW_SLOT hardware versi on 0. 00 f i rmware versi on 0.00

sl ots[ 2] Token not presentsl ots[ 3] CK_SLOT_I NFO sl otDescri pti on "ej bca " manuf act urer I D "nCi pher Corp. Lt d " f l ags 6 f l ags & CKF_REMOVABLE_DEVI CE f l ags & CKF_HW_SLOT

hardware versi on 0. 00 f i rmware versi on 0.00

sl ots[ 3] Token not presentsl ots[ 4] CK_SLOT_I NFO sl otDescri pti on "2of 3_1 " manuf act urer I D "nCi pher Corp. Lt d " f l ags 6 f l ags & CKF_REMOVABLE_DEVI CE f l ags & CKF_HW_SLOT hardware versi on 0. 00 f i rmware versi on 0.00

sl ots[ 4] Token not presentsl ots[ 5] CK_SLOT_I NFO sl otDescri pti on "1of 2_1 " manuf act urer I D "nCi pher Corp. Lt d " f l ags 7 f l ags & CKF_TOKEN_PRESENT f l ags & CKF_REMOVABLE_DEVI CE f l ags & CKF_HW_SLOT hardware versi on 0. 00 f i rmware versi on 0.00

sl ots [ 5] CK_TOKEN_I NFO l abel "1of 2_1 " manuf act urer I D "nCi pher Corp. Lt d " model " " ser i al Number "ee6071c52a77370c" f l ags 20D f l ags & CKF_RNG f l ags & CKF_L OGI N_REQUI RED f l ags & CKF_USER_PI N_I NI TI ALIZED f l ags & CKF_DUAL_CRYPTO_OPERATI ONS ul MaxSessi onCount 1024 ul MaxRwSess i onCount 1024 ul MaxPi nLen 18446744073709551615 ul Mi nPi nLen 0 ul Tot al Publ i cMemor y CK_UNAVAI LABLE_I NFORMATI ON ul Fr eePubl i cMemor y CK_UNAVAI LABLE_I NFORMATI ON ul Tot al Pr i vat eMemor y CK_UNAVAI LABLE_I NFORMATI ON ul Fr eePr i vat eMemor y CK_UNAVAI LABLE_I NFORMATI ON hardware versi on 0. 00 f i rmware versi on 0.00 utcTi me " "

You then got to identify your OCSs with the slot index. The "label" in the list gives the name you gave to your OCS when creatingit. Then you get the slot list index from the x in "slot[x]. Use this for "slotListIndex" in the CA properties.

When using a 1/n OCS one card of the OCS must be inserted when activating a CA. If the OCS is persistent then the card could beremoved and you could then activate another CA by inserting its OCS.

To make the OCS persistent use the "-p" argument at "createocs" time, if this is not the case as soon as the card is removed thenthe cardset will unload itself.

When using k/n OCS where k>1 you got to load all OCSs to be used with preload and then start the application server also withpreload. Example:

l ars@mi l t on: ~/ work/ t est/ nCi pher$ ~nfast / bi n/prel oad -c 2of 3_0 pause- - fo l l ow i nstruct i on to i nsert cards and enter p ins . - -- - then press ct r -z - -l ars@mi l t on: ~/ work/ t est/ nCi pher$ bg


22 of 38

l ars@mi l t on: ~/ work/ t est/ nCi pher$ ~nfast / bi n/prel oad - c 2of 3_1 exit- - fo l l ow i nstruct i on to i nsert cards and enter p ins . - -

When the application server then is started with preload, CAs defined for slot list index 2 and 4 could be activated. Whenactivating a CA when running preload no PIN has to be given. Also when the application server is started with preload then onlyCAs of preloaded slots could be activated (not preloaded 1/n slots could not be used).

nCipher load balancing

If you want to use the Loadsharing with multiple modules, be it PCI cards of NetHSM's then you must ensure you have a 1/N OCSand the N quorum to be able to have enough cards to be inserted in every HSM you want to load balance the key at server/CAstart up when logging in.

Same security world got to be loaded in all modules participating.

After setting up the first netHSM, do the following on the second:

Use the panel of the second netHSM to configure the rfsUse the panel of the second netHSM to load the security worldUse the panel of the second netHSM to configure clientson each client run: /opt/nfast/bin/nethsmenroll

With load balancing you need to have CKNFAST_LOADSHARING=1. Preload implicitly sets CKNFAST_LOADSHARING.

Note

If preload is used fail-over to the other HSM if one of the HSMs is broken is not working.

Example of starting jboss:

ej bca@subcal l b:/ usr/ l ocal / ej bca> CKNFAST_LOADSHARI NG=1 . . / j boss/ bi n/r un. sh

When activating a CA you need a smart card from the OCS of the corresponding slot inserted in both HSMs. The OCS got to be 1/nsince preload can not be used.

Sample PKCS#11 configuration file for generating the CA keys.

name=NFast J aval i brary=/ opt / nfast / tool k i t s /pkcs11/ l i bcknf ast . sosl otLi stI ndex=1att ri butes( gener ate, CKO_PRI VATE_KEY,* ) = { CKA_PRI VATE = t r ue CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_TOKEN = t r ue}

Sample catoken.properties for generating the initial AdminCA on the netHSM, or entering in the admin-GUI when creating a newCA.

def aul t Key def aul t Keycert Si gnKey def aul t Si gncrl SignKey defaul tSi gnt estKey t estKeysharedLibrary / opt / nfast / tool k i t s /pkcs11/ l i bcknfast . sos l otL ist I ndex 1

AEP Keyper

The documement xxxxxxKeyperP11.pdf (xxxxxx is six digits) describes how the HSM is installed. As default there is only one slot -0.

The HSM needs a configuration file when generating the keys. It could look like this:

name=Keyperl i brary=/ Users/ f l ouri sh/Keyper/ PKCS11Provi der/ pkcs11. GCC4.0. 1_i 386.so. 4.04sl ot=0att ri butes( gener ate, CKO_PRI VATE_KEY,* ) = { CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_TOKEN = t r ue}

ARX CoSign

This HSM only works on Windows. The installation is done with an installer and the setup with a GUI.

All generated keys will be on slot 1. The PIN code used when activating the keys could be anything since the authentication ismade when login on to the user that runs EJBCA. The shared library is called C:\windows\system32\sadaptor.dll

Bull Trustway

Do the installation of the card according to Install_and_Use_cc2000.pdf. When the card is "installed" it is ready to use with EJBCA.Only one slot (slot index 0) is available. The slot is not protected by any PIN so an undefined 'pin' (empty) property may be usedin the configuration.

The configuration file used when generating a key with 'pkcs11HSM.sh' must look like this:

name=Trust Wayl i brary=. . / . . / bu l l I nsta l l / l i nux/ l i bgpkcs11cc2000. sosl otLi stI ndex=0att ri butes( gener ate, CKO_PRI VATE_KEY,* ) = { CKA_TOKEN = t r ue}

When using PKCS11HSMKeyTool and starting EJBCA, libcc2000_tok.so and libgpkcs11cc2000.so must be in the library path.Examples:

l ars@maud:~/ work/ test / ca$ l s -a l . . / . . / bul l I nsta l l / l i nuxtot al 412dr- xr- xr- x 4 l ars l ars 4096 28 nov 14. 28 .drwxr- xr- x 4 l ars l ars 4096 20 apr 21. 05 . .dr- xr- xr- x 6 l ars l ars 4096 20 apr 21. 38 CardAdmi n_j ava- r- xr- xr- x 1 l ars l ars 35804 28 nov 14. 15 cc2000_l x24.t gz- r- xr- xr- x 1 l ars l ars 74955 28 nov 14. 15 cc2000_sr c. t gz- r- xr- xr- x 1 l ars l ars 14 28 nov 14. 15 cc2000S_rel ease- r- xr- xr- x 1 l ars l ars 633 28 nov 14. 15 desi nstal l- r- xr- xr- x 1 l ars l ars 171 28 nov 14. 15 gpkcs11cc2000. rcdr- xr- xr- x 2 l ars lar s 4096 28 nov 14. 28 i nclude- r- xr- xr- x 1 l ars l ars 7209 28 nov 14. 15 i nstal l- r- xr- xr- x 1 l ars l ars 101788 28 nov 14.15 l i bcc2000_t ok.so


23 of 38

- r- xr- xr- x 1 l ars l ars 146820 28 nov 14.15 l i bgpkcs11cc2000.so- r- xr- xr- x 1 l ars lars 3843 28 nov 14. 15 Li sezMoi . t xt- r- xr- xr- x 1 l ars l ars 3410 28 nov 14. 15 ReadMe.t xtl ars@maud:~/ work/t est/ ca$ LD_LI BRARY_PATH=. . / . . / bul l I nstal l / l i nux . . / . . / j ava/j boss/bi n/r un. sh

l ars@maud:~/ work/ t est/ keygen$ LD_LI BRARY_PATH=~/ work/ bul l I nstal l / l i nux . . / . . / PWE/ej bca/ cl i ent Tool Box-di st / ej bcaCl i ent Too

SafeNet Luna

*** Install HW and SW ***

Please consult the SafeNet documentation regarding the installation of HW and SW.

*** Configuration ***

Do all steps (1-7 in the section) in "A - Configuration (Setup Appliance after Installing)" of in the html document "Luna SAOnline Help -- Document # 800274-xxx" that should be found on your installation CD. Some notes about our test setup:

Step 3: You may do nothing here. But note that changing many of the policies will reset the HSM. This means that you can'tchange any of these policies later on.

Step 4: Note that a new partition could be added at any time. Each partition will be represented as a PKCS#11 slot. Make sureto write the Record Partition Client Password (TP) in a text file. In the example the password is btqx-EFGH-3456-7/K9 for thefirst created partition (slot 1). The TP will later be used as PIN for the slot.

Step 5: A good idea is to allow partitions (p11 slots) to be "activated". If a partition is not activated you got to insert the blackkey in the PED and give PIN each time a resource in the HSM is used by the client. So in most cases you want to be able toactivate a partition: lunash:>partition changePolicy -partition partition1 -policy 22 -value 1

Step 6: You don't have to be in the '/usr/LunaSA/bin' directory as the documentation says. We think it is preferable to be in adirectory owned by yourself so you don't have to use sudo. Example of running in your own directory:

l ars@mi l t on: ~/ work/ t est/ l una$ / usr/ l unasa/ bi n/ct p admi n@l unasa. i nt. pri mekey. se: server. pem .

Example of occasions when sudo must be used is registration of server and adding client certificates (root owned files anddirectories are used and updated):

l ars@mi l ton:~/ work/t est/ l una$ sudo /usr/ l unasa/ bin/ vtl addServer - n l unasa. i nt. pri mekey. se - c server. peml ars@mi l ton:~/ work/t est/ l una$ sudo / usr/ l unasa/ bin/ vtl createCert - n mi l ton

Step 7: Each partition assigned to a client will be represented by a PKCS#11 slot for this client. It seems that each new addedpartition will be put last in the slot list and the number of a slot will be slot list index plus 1 (list index starting with 0 and slotnumber starting with 1). To get the partition slot mapping on the client do:

l ars@mi l ton:~/ work/t est/ l una$ / usr/ l unasa/ bin/ vtl veri f y

The f ol l owi ng Luna SA Sl ot s/ Par t i t i ons wer e f ound:

Sl ot Ser i al # Label==== ======== ===== 1 950784001 part i t i on1 2 950784002 part i t i on2

Now the client may use these slot with EJBCA and it's tools

*** Activating slots ***

Before a partition (slot) could be used by a client it must be activated. This is described in 'B - Administration & Maintenance >Activating and AutoActivating Partitions'. The partition policy required do the activation must have been set (see step5 above).Example to activate a partition:

l unash: >hsm l ogi nl unash: >part i t i on acti vate - part i t i on part i t i on1 - password btqx- EFGH-3456-7/K9

The password is from the configuration step 4. See above.

*** Generate keys on a slot ***

l ars@mi l t on: ~/ work/ t est/ l una$ ~/ work/ PWE/ej bca/ cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / s0 [mai n] I NFO org. ej bca. uti l . keyst ore. KeyTool s - Usi ng SUN PKCS11 provi der: sun.securi t y. pkcs11. SunPKCS11PKCS11 Token [SunPKCS11-Luna] Passwor d:Creat ed cert i f i cate wi t h ent ry rs a2048_1.l ars@mi l t on: ~/ work/ t est/ l una$ ~/ work/ PWE/ej bca/ cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / s0 [mai n] I NFO org. ej bca. uti l . keyst ore. KeyTool s - Usi ng SUN PKCS11 provi der: sun.securi t y. pkcs11. SunPKCS11PKCS11 Token [SunPKCS11-Luna] Passwor d:Creat ed cert i f i cate wi t h ent ry secp160r1_1.

The password btqx-EFGH-3456-7/K9 (see above) is used.

The contents of ./sunpkcs11.cfg :

name=Lunal i brary=/ usr / l unasa/ l i b / l i bCryptok i2_64. so#l i brary=/ usr/ l i b/pkcs11-spy. sos l ot = 1

attr i butes(generate,* , * ) = {CKA_TOKEN = t r ue

}att ri but es(generate, CKO_PUBLI C_KEY,* ) = { CKA_ENCRYPT = t r ue CKA_VERI FY = t r ue CKA_WRAP = t r ue}att ri but es(generate, CKO_PRI VATE_KEY,* ) = { CKA_EXTRACTABLE = f al se CKA_DECRYPT = t r ue CKA_SI GN = t r ue CKA_UNWRAP = t r ue}

*** List and test all keys that could be used by EJBCA ***

l ars@mi l t on: ~/ work/ t est/ l una$ ~/ work/ PWE/ej bca/ cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool t est / usr/ l u Test of keys t or e wi t h I D 1.0 [mai n] I NFO org. ej bca. uti l . keyst ore. KeyTool s - Usi ng SUN PKCS11 provi der: sun.securi t y. pkcs11. SunPKCS11PKCS11 Token [ SunPKCS11- l i bCr yptoki 2_64. sosl ot2] Password:

Test i ng of key: r sa2048_1SunJCE versi on 1. 7SunPKCS11-l i bCr ypt oki2_64.sosl ot2 versi on 1. 7; modul us l ength: 2048; byt e l ength 245. The docodedSignature test of key rsa2048_1: si gnature l ength 256; f i rst byte 28; veri f yi ng tr ueKey stat i s t i cs .Si gni ngs per s econd: 369; Decr ypti ons per second: 135


24 of 38

Test i ng of key: secp160r 1_1Signature test of key secp160r1_1: si gnature l ength 48; f i rst byte 30; veri f yi ng tr ueKey stat i st i cs .Si gni ngs per s econd: 68 No crypto avai l abl e for t hi s key.

*** Sample Hard Token Properties ***

This is a sample configuration of the Hard Token Properties for PKCS#11 token when creating a new CA.

sharedLi brary=/ usr/ l unasa/ l i b/l i bCryptoki2_64.sosl ot=1cer t Si gnKey=myECCKeycr l Si gnKey=myECCKeydef aul t Key=def aul tatt ri butesFi l e=/ home/ej bca/l unasatoken.cf g

Where lunasatoken.cfg is:

attr i butes(generate,* , * ) = { CKA_TOKEN = t r ue}att ri but es(generate, CKO_PUBLI C_KEY,* ) = { CKA_ENCRYPT = t r ue CKA_VERI FY = t r ue CKA_WRAP = t r ue}att ri but es(generate, CKO_PRI VATE_KEY,* ) = { CKA_EXTRACTABLE = f al se CKA_DECRYPT = t r ue CKA_SI GN = t r ue CKA_UNWRAP = t r ue}

SafeNet ProtectServer

*** install SW ***

Install the software according to the installation instructions for the ProtectServer. Below are sample commands for installingthe SDK rpm on an Ubuntu system, wich means first converting it to a deb.

Using the SDK you can use the SDK as a good emulator for testing and development. If you are installing with a realProtectServer you should install the Runtime instead of the SDK. When using the SDK you may use /opt/ETcpsdk/lib/linux-x86_64 instead of /opt/PTK/lib

f aker oot al i en - c $CDROM/ Li nux64/pt kc_sdk/ ETcpsdk-3. 32. 00- 1.x86_64. r pmsudo dpkg - i . / etcpsdk_3. 32. 00- 2_amd64. deb

*** Set passwords for admin SO och admin user ***

LD_LI BRARY_PATH=/ opt / PTK/ l i b / opt / PTK/bi n/ct conf

*** create 10 slots ***

LD_LI BRARY_PATH=/ opt / PTK/ l i b /opt/ PTK/bi n/ct conf - c10

*** Set no public crypto ***

See "Programming in FIPS mode" in the Protect Toolkit-C Programmers Manual for information about this flag.

LD_LI BRARY_PATH=/ opt / PTK/ l i b / opt / PTK/bi n/ct conf - f c

*** Initialize slot 5. Sets SO and user password ***

LD_LI BRARY_PATH=/ opt / PTK/ l i b /opt/ PTK/bi n/ct kmu t - s5 -l root

*** Generate keys on slot 5 ***

$EJ BCA_HOME/cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / sl ot5. cf g 2048 defaul t Si gn$EJ BCA_HOME/cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / sl ot5. cf g 2048 def aul t$EJ BCA_HOME/cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool generat e . / sl ot5. cf g 512 t est

If JBoss was started you have to restart JBoss before the keys becomes available in EJBCA.

*** Contents of ./slot5.cfg ***

name=Saf eNetl i brary=/ opt / PTK/ l i b/ l i bcryptok i . so#l i brary=/ usr/ l i b/pkcs11-spy. sosl ot=5at t r i but e s( * , * , * ) = { CKA_TOKEN = t r ue}att ri but es(*, CKO_PRI VATE_KEY,* ) = { CKA_PRI VATE = t r ue CKA_SI GN = t r ue CKA_DECRYPT = t r ue CKA_EXTRACTABLE = t r ue CKA_SENSI TI VE = t r ue}

*** Contents of CA Token Properties ***

When you create the CA in EJBCA you can now use the simple CA token properties below.

cert Si gnKey def aul t Si gncrl SignKey defaul tSi gndef aul t Key def aul tt estKey t estsharedLi brary=/ opt / PTK/ l i b/ l i bcryptok i . sosl ot=5attr i butesFi l e=/ opt / s l ot5p11. cfg

where /opt/slot5p11.cfg is:

at t r i but e s( * , * , * ) = { CKA_TOKEN = t r ue}att ri but es(*, CKO_PRI VATE_KEY,* ) = { CKA_PRI VATE = t r ue CKA_SI GN = t r ue CKA_DECRYPT = t r ue


25 of 38

CKA_EXTRACTABLE = t r ue CKA_SENSI TI VE = t r ue}

Note

The slot5p11.cfg is needed because the ProtectServer has some strange default attributes. If you do not specify an attributesfile the private key will not be 'sensitive' and will be possible to export in clear text by any user of the HSM. You can see theattributes of the keys by running the test command:

. / ejbcaCl i entTool Box. sh PKCS11HSMKeyTool t est / opt/ PTK/ l i b/l i bcryptoki . so 5

. . . Test i ng of key: t estSunJCE versi on 1. 7SunPKCS11-l i bcryptoki . so-sl ot3 versi on 1. 7; modul us l ength: 2048; byt e l ength 53. The docoded byteSunPKCS11-l i bcryptoki . so-sl ot3 RSA pri vate key, 512 bi ts ( i d 4, token obj ect, sensi t i ve, extr actabl e)Signature test of key t est1: si gnature length 64; f i rst byte 3d; veri f yi ng tr ueSi gni ngs per s econd: 257Decrypt i ons per second: 260

the attributes are listed as "token object, sensitive, extractable", and here is important that is says 'sensitive' (extractable onlymeans that the key can be backed up securely using SafeNet tools).

Note

The above means that if you have more than one CA using the same slot it is very important that BOTH CA token propertiesconfigurations contains the attributesFile. This is because the attributes are applied when the provider is installed duringstartup. If one configuration does not have the attributesFile it can not be applied later on by the other configuration.

*** Test and list keys on slot 5 ***

$EJ BCA_HOME/cl i ent Tool Box-di st / ej bcaCl i ent Tool Box.sh PKCS11HSMKeyTool t est / opt / PTK/l i b/l i bcryptoki . so 5

Note

The emulator has a bug. Each key of same length that are generated seems to be the same. This means that a slot may onlyhave one key. If a second key is generated for a slot the certificate object for the first key is deleted before writing the certificateobject for the new key. This is done since the Sun p11 wrapper provider does not allow two keys that are equal to be present in akeystore.

*** Generating keys using SafeNet tools ***

You can also generate keys, and the needed self signed certificate, using the SafeNet tools delivered with the HSM. This is forexample suitable when you want to generate ECC keys, since there is a bug in the JDK which prevents this without patchingthe JDK.

For example, the below commands generates an ECC key with curve P-256 on slot 1, storing it on the HSM with alias 'foo',assigning a selfsigned certificate to it and finally listing the object of slot 1.

cd / opt / ETCprt/ bin/ l i nux-x86- 64. / ct kmu c - t ec -nf oo - aPSVXxTRD - s1 -CP-256. / c t cer t c - s1 - l f oo. / ctkmu l -s1

Or you can wrap it all up in a single command...

. / c tcert c - k - l foo - t ec -s1 -CP-256 -d30y

If JBoss was started you have to restart JBoss before the keys becomes available in EJBCA.

Writing support for new HSMs

EJBCA have a modular API for HSMs, HardCAToken. For every CA that is created a HardCAToken object is also created. This objectcontains among other things references to keys (or the keys themselves of a soft token is used). For each HSM hardware thatshould be supported you need one HardCAToken class that implementes support for this particular HSM. A hard ca token plug-inmust:

implement ICAToken1.

it is recommended to extend BaseCAToken, since BaseCAToken implements handling of all properties, autoactivation and

such

2.

be loaded at the static initialization if CATokenManager where it is registered with the CATokenManager using the method

addAvailableCAToken()

3.

Provide a JCE Security Provider that is installed by the module and can be fetched by the EJBCA crypto module(BouncyCastle) through the name returned in ICAToken.getProvider().

4.

See HardCATokenSample and/or DummyHardCAToken for samples. Unlike the sample addAvailableCAToken() must be called withuse=true, or the token will not be usable in EJBCA (as the flag suggests).

LDAP and Publishers

EJBCA has a modular support for something we call Publishers. A publisher can be any external source where you want to send issuedcertificates and CRLs to be stored. The most common cases of Publishers, which are implemented by default in EJBCA are LDAPdirectories and Active Directory (which is a special case of LDAP directory).

The Publisher architecture is modular and it's possible to implement custom publishers that can also be easily integrated and set up inthe admin-GUI.

First we will start with describing the built-in publishers.

LDAP Naming

A good book to understand LDAP naming is "Understanding and Deploying LDAP Directory Services". The recommended method of choosing a naming suffix is the one described in RFC2247 that maps a DNS domain to a DN. If my DNS domain is bigcorp.com itwill map to the DN "dc=bigcorp,dc=com". The top node in my LDAP directory will then be "dc=bigcorp,dc=com".

The dc component support is mandated by all of the X.509 RFCs now. For example, if I have this directory:

dc=bi gcor p, dc=com | +- dc=f i | | +- dc=se | +- cn=Mi ke J ackson

The most understandable method is taking the subject name in forward order, like: cn=Mike Jackson,dc=se,dc=bigcorp,dc=com

If the DN is ordered like this it should be published to the correct object in the tree.


26 of 38

If the DN is ordered reverse, like: dc=bigcorp,dc=com,dc=se,cn=Mike Jackson EJBCA will reorder it incorrectly to forward order,so the publishing will be wrong.

Therefore... Use forward order like this: 'cn=Mike Jackson,dc=se,dc=bigcorp,dc=com' if using the dc model or'cn=Mike Jackson,o=bigcorp,c=se' if using the o,c model.

An example image of an LDAP structure can be seen below in HOWTO-LDAP-tree.png.

Making unique LDAP DNs is the next challenge. If you are in a small organization having the CN will probably work fine, but in alarger organization there are probably several people with the same name. Somehow the names must be made unique, and oneway is to introduce numbers, initials etc in the CN. Another way that we recommend is to use uid in the LDAP DN instead. LDAPDNs will then looks like "uid=tomas,dc=bigcorp,dc=com". Uid is the users username, normally used for login etc, and you probablyalready have some procedure to create unique usernames already.

LDAP Basics

LDAP has an unusual structure, if you are not used to X.500 style naming. Things are either branches, or leaf nodes. You can't just drop an object anywhere you like; You need to create the framework to support it. Sort of like if you wanted to put entries in /etc/hosts, if the directory /etc did not exist.

First you mkdir /etc, Then you create the file. Then you start putting things in the file. The difference with LDAP and x.500 is thatinstead of paths separate by slashes, you have paths separated by commas and '=' signs.

For example, if you want to make an object "cn=ldaphost,ou=hosts,dc=yourdom,dc=com", you first have to make sure"dc=yourdom,dc=com" exists.Then make sure"ou=hosts,dc=yourdom,dc=com" exists.THEN you can try"cn=ldaphost,ou=hosts,dc=yourdom,dc=com"

EJBCA does not create branches in LDAP. You have to put them there with other means, before you start publishing.

*** Using LDAP ***

In Firefox you can for example enter a URL like:ldap://ip-address-of-ldap-server:389/cn=Tomas Gustavsson,dc=se,dc=bigcorp,dc=comand it will fetch an address book entry with the information about the user, including the certificate.

The LDAP url format is described in RFC2255.

Examples of using LDAP with Firefox can be found in the howto-section of this web page.

To use LDAP top fetch user certificates and use them for encrypting email there seems to be a requirement to use SSLconnection to the LDAP server (Account Options->Compositions & Addressing->Edit directories->Edit->Use SecureConnection), see also below how to configure OpenLDAP for SSL.

Note: When fetching certificates from LDAP with Firefox for example with URL:ldap://ldap-server-host/dc=bigcorp,dc=com??sub?(cn=MyName)?(objectclass=*)To get a checkbox at the fetched certificate, the CA certificate must be installed in the Windows truststore, not only inFirefox's.

To use SSL against an LDAP server with MS Outlook you must make sure the CN in the LDAP servers certificate is the same asthe hostname. An example of adding a user for the LDAP server with the CLI interface is:

bi n/ ej bca.s h ra adduser l dap password " C=SE,O=Foo,CN=l dap. f oo.s e" nul l MyCA nul l 1 PEM SERVER

where ldap.foo.se is the hostname of the LDAP server that Outlook should use.

The CA certificate must also be imported into Windows properly.

*** Configure OpenLDAP ***

The objectclass 'inetOrgPerson' is used by default to store certificates.

Example:

dn: cn=Mi ke J ackson, ou=peopl e, dc=company,dc=comobj ectc l ass: topobj ectcl ass: personobj ectcl ass: organizati onalPersonobj ectcl ass: i netOrgPersoncn: Mi ke J acksonsn: J acksonuserCert i f i cate; bi nary: :

CAs are published in the form:

dn: cn=ej bca, dc=j ackson, dc=netobj ectCl ass: t opobj ectCl ass: appli cati onProcessobj ectClass: cert i f i cat i onAuthor i tycn: ejbcacACert i f i cate; bi nary:


27 of 38

cert i f i cateRevocat i onLi st ; bi nary:authori tyRevocati onLi st; binary:

To configure OpenLDAP (version 2.2.5) to include the 'inetOrgPerson' you must add the following lines to slapd.conf. This isalready the default in recent releases:

i nclude / etc/ l dap/schema/ cosi ne. schemai nclude / etc/ l dap/schema/ i net orgperson.schema

Don't forget to add the top object by creating an LDIF file (org.ldif):

dn: o=AnaTom, c=SEobj ectcl ass: dcObj ectobj ectcl ass: organi zati ono: AnaTomdc: AnaTom

dn: c n=Admi n, o=AnaTom, c=SEobj ectcl ass: organizati onalRol ecn: Admi n

And using the command:

l dapadd - x - D "cn=Admi n, o=AnaTom, c=SE" - W - f org. l di f

Check what you have in the LDAP by:

l dapsearch - x - b ' o=AnaTom, c=SE' ' ( obj ectcl ass=*) '

*** Configure SSL ***

Create a user in ejbca (this example is for adding a user with the cli interface, adding a user with the admin-GUI works just asfine). In the mail ejbca directory type (use simply 'ra' on windows):

bi n/ ej bca.s h r a adduser l dap foo123 "C=SE, O=Foo,CN=l dap" nul l Admi nCA1 nul l 1 PEM SERVERbi n/ej bca. sh ra setcl earpwd l dap foo123

Where foo123 is the ldap users password, C=SE... is the users DN and AdminCA1 is the name you chose for your CA. The usertype is end-user (1), keystore type is PEM, and if using the admin-GUI check 'use batch'). Batch generate the PEM keystore:

bin/ ejbca.sh batch

Copy the resulting files p12/pem/ldap.pem, p12/pem/ldap-CA.pem and p12/pem/ldap-Key.pem to your LDAP server. In thisexample the slapd.conf is located in /etc/ldap so we copy the files to that directory. Protect theses files so they are onlyreadable by the LDAP server. Add the following to your slapd.conf:

# Use SSL TLSCi pherSui t e HI GH: MEDI UM: +SSLv3 TLSCert i f i cat eFi l e / et c/ l dap/ l dap. pem TLSCert i f i cat eKeyFi l e / et c/ l dap/ l dap- Key. pem TLSCACer t i f i cat eFi l e / et c/ l dap/ l dap- CA. pem

Restart slapd:

. / s l apd -h " l dap: / / / l daps : / / / "

and check that it is running with 'ps -ef|grep slapd'.

On SuSE, if using the builtin OpenLDAP you have to enable ldaps in /etc/sysconfig/openldap:

OPENLDAP_START_LDAPS="yes "

and then run

SuSEconfi g

and then

rcl dap start

Configure your LDAP publisher in EJBCA to use SSL by checking the checkbox 'Use SSL', the port should change to port 636.

Note! The CA certificate of the (root)CA used to sign the ldap server certificate must be present in the java trust cert store($JAVA_HOME/jre/lib/security/cacerts). If you use the default CA created when ejbca was installed this is already included.Otherwise you will have to add it using something like: First get the CA cert:

bi n/ ej bca.s h ca getr ootcer t MyCA myca. der - der

Then add it to the java trust store:

keytool - i mport - tr ustcacert - al i as MyCA -keystore $J AVA_HOME/j re/ l i b/ securi t y/cacert s - storepass changeit - f i l e myca.

You have to re-start JBoss after adding anything to the java trust store.

A guide for configuring OpenLDAP on Solaris can be found at bolthole.com

*** Sample Ubuntu installation ***

- sudo apt- get i nsta l l s l apd ldap-ut i l s- sudo dpkg-r econfi gure sl apd Confi gur e sl apd wi t h your domai n and admi n password ( pri mekey. se i n thi s case).- sudo / etc / i n i t . d/ s l apd restart- ' ps -ef | grep s l ap'

shoul d show a sl apd runni ng- l dapsearch -x - b ' dc=pri mekey, dc=se' ' (obj ectcl ass=*) ' To l ook at the resul t s- s l apcat - l backup. l di f Make backup- sl apadd - l backup.l dif - / et c / i ni t . d/ s l apd resta r t Rest ore backup

Command to add new LDAP nodes:

- l dapadd - x - D "cn=admi n, dc=Pri meKey, dc=com" - W - f pri mekey.l di f where pri mekey. l dif i s:

dn: dc=Pr i meKey, dc=comdc: Pri meKeyobj ectcl ass: dcObj ectobj ectcl ass: organi zati on


28 of 38

o: Pri meKey Sol uti ons ABdescri pti on: Parent Obj ect f or Pri meKey LDAP Di rect ory

dn: ou=St andar d, dc=Pr i meKey,dc=comou: Standardobj ectCl ass: t opobj ectCl ass: organizati onalUni tdescri pti on: Parent Object f or al l Standard Certi f i cates

dn: ou=Hi gh, dc=Pr i meKey, dc=comou: Hi ghobj ectCl ass: t opobj ectCl ass: organizati onalUni tdescr i pt i on: Parent Obj ect for a l l Hi gh Cert i f i cates

Configure LDAP publishers

A Publisher is a session bean that implements the IPublishSession interface and is used to store certificates and CRLs for entities.EJBCA have support for endless number of publishers simply by defining publishers in the admin-GUI. The user of EJBCA canimplement own publishers, but EJBCA already comes with a publisher for LDAP.

EJBCA uses a notion of base DN to publish to different LDAP structures. The DN used in the certificate can be different from theLDAP structure.

*** Configuring EJBCA ***

To configure the publisher for LDAP:

Choose 'Edit Publishers' in the admin-GUI.1.

Add a new publisher with a name you define yourself. Edit the publisher and fill in all the necessary fields.2.

Generic parameters to LDAP Publisher:

'Hostnames' is ';'-separated li st of the hosts where the LDAP servers are located. E.g. "ldap.company.com" or"ldap1.company.com;ldap2.company.com". Only the first available of the listed hosts will be used.'Port' is the port on which the LDAP server listens, default non-SSL is 389.'Login DN' is the DN of a user on the LDAP server with permissions to add and update entities.'Login Password' is the password for the user above.'Connection timeout' is number of milliseconds a server has to respond before it is considered unavailable and the nextserver in the list of hostnames (if any) is used instead. This timeout is used to probe LDAP servers, to createconnections, to bind and to disconnect.'Read timeout' is number of milliseconds a server has to complete a LDAP search or read operation before it times outand fails.'Store timeout' is number of milliseconds a server has to complete a LDAP store operation before it times out and fails.This can take a little longer if you store very large CRLs in LDAP.'Create Nonexisting Users' defines if an LDAP object should be created by EJBCA if it is no existing object when EJBCApublishes the certificate.'Modify Existing Users' defines if attributes (such as email) in existing LDAP objects are replaced with new values and/oradded when an entry is updated with a new certificate. If this option is not activated, existing users will not be touchedat all, even not updated with a new certificate.'Overwrite Existing Attributes' When 'Modify Existing Users' is set to true this value determines whether to changevalues of attributes when they already exist.'Add Nonexisting Attributes' When 'Modify Existing Users' is set to true this value determines whether to add attributeswhen they do not already exist.'Add multiple certificates per user' defines if we should use multiple certificate entries for each user or only one. Defaultonly one certificate is added to a user entry in LDAP and if the user gets a new certificate the old one is deleted andreplaced with the new one. If this checkbox is checked certificates are instead appended in LDAP so each user can havemultiple certificate entries in LDAP. Make sure your applications can handle this before enabling this option. Revoking auser will remove all certificates entries for the user.'Remove certificates when revoked' if checked causes the publisher to remove a certificate from LDAP when thecertificate is revoked or suspended.'Remove ldap user when certificate revoked' if checked causes the publisher to remove the whole LDAP user entry whena certificate is revoked or suspended.'Set userPassword attribute' specifies if the LDAP publisher should set the userPassword attribute in the LDAP object. If auser entry with a non-null password is published, and this checkbox is checked, the userPassword attribute will bepopulated with the user's password.'User Object Class' is the objectclass for the LDAP entries for users, where user certificates are published. The entry ishierarchical separated by ';' to build a structure like:objectclass: topobjectclass: personobjectclass: organizationalPersonobjectclass: inetOrgPersonThis objectclass must allow the attribute 'userCertificate;binary'.Default 'top;person;organizationalPerson;inetOrgPerson''CA Object Class' is the objectclass for the LDAP entries for CAs, where CA certificates and CRLs are published. The entryis hierarchical separated by ';' to build a structure. This objectclass must allow the attributes 'cACertificate;binary','certificateRevocationList;binary' and 'authorityRevocationList;binary'.Default 'top;applicationProcess;certificationAuthority''User Certificate Attribute' is the attribute name, in the userObjectClass, for the users certificate.Default 'userCertificate;binary'.'CA Certificate Attribute' is the attribute name, in the cAObjectClass, for the CAs certificate.Default 'cACertificate;binary'.'CRL Attribute' is the attribute name, in the cAObjectClass, for CRLs (user CRLs) publisher by the CA.Default 'certificateRevocationList;binary'.'ARL Attribute' is the attribute name, in the cAObjectClass, for ARLs (CA CRLs) publisher by the CA.Default 'authorityRevocationList;binary' (note that pure ARLs are not implemented yet in EJBCA).'LDAP location fields from cert DN' When configuring the LDAP publisher the BaseDN will be used as the base for the DNpublished in LDAP, and it will be appended to the LDAP location fields selected to be used. example: If the user DN inEJBCA is "cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE" and the BaseDN is"dc=PrimeKey,dc=SE" and the selected LDAP location fields are "CN". The LDAP DN used for publishing will be "cn=tomasgustavsson, dc=PrimeKey, dc=SE", and the "uid=tomasg" will be added as an attribute in LDAP. The certificate storedunder "cn=tomas gustavsson, dc=PrimeKey, dc=SE" will have the subjectDN "cn=tomas gustavsson, uid=tomasg,O=PrimeKey Solutions AB, C=SE".

*** Setting up certificate profiles ***

You MUST make a custom certificate profile to publish to LDAP!

To publish in LDAP you must create a Certificate profile in EJBCA that publishes to LDAP. If the above is configured, there willbe a section for 'Publishers' available when creating/editing a certificate profile (with 'Edit Certificate Profiles'). Choose this,and then when adding end-entities, make sure they use the new certificate profile and voila, the certs will be published.

*** Different LDAP publishers ***

LDAP Publisher


29 of 38

The regular LDAP Publisher works by searching the DN in LDAP.

When ejbca creates an object to publish a certificate to LDAP it firsts builds the DN from the baseDN and 'LDAP location fieldsfor cert DN'. It checks if the entry exists in the ldap and either creates or modifies the entry.

Example: The certificate DN is "CN=Tomas Gustavsson,O=Foo,C=SE", the BaseDN in the publisher is "DC=primekey,DC=se"and the CN is selected in "LDAP location fields from cert DN".The resulting DN that EJBCA will search for in the LDAP and create if it does not already exist is "CN=TomasGustavsson,DC=primekey,DC=se".

Using this publisher, if you have multiple trees in your LDAP (for example "ou=foo,dc=primekey,dc=se" and"ou=bar,dc=primekey,dc=se") you can either:

Include both CN and OU in 'LDAP location fields from cert DN' and have your cert DNs like

"CN=Tomas,OU=foo,O=MyOrg,C=SE.

1.

Use different publishers for ou=foo and ou=bar and issue certificates for the different OUs with different certificate

profiles.

2.

LDAP Search Publisher (from EJBCA v3.2)

The LDAP Search Publisher works by searching the LDAP for existing entries using a user defined search filter. If no entriesexist in the LDAP when searching for an entry, one is created just like in the regular LDAP Publisher.

The search filter is defined in the two fields under "LDAP search settings":

Suffix base DN of LDAP Search - the base for your search filter.LDAP filter of the search - your LDAP filter.

If you build your search filter on DN components, you also have to select thos components as 'LDAP location fields'.

The best example of such a search filter is if base is "dc=primekey,dc=se" and filter is "uid=$USERNAME". The search done byejbca will be equal to the search:ldapsearch -x -b "dc=primekey,dc=se" "(uid=$USERNAME)"

$USERNAME is replaced by the EJBCA username of the user that has had a new certificate just generated. Other variablesapart from $USERNAME is $EMAIL, $UID, $CN, $O, $OU and $C where these values are taken from the certificate DN.

When a certificate is generated for say user "ldap" EJBCA will perform the search:ldapsearch -x -b "dc=primekey,dc=se" "(uid=ldap)"

The certificate generated for ldap will be published in the object returned by the search. This is very useful if you want topublish certificates to an LDAP directory where your users already exists, such as an email directory. The DN in the LDAP doesnot have to match the DN in the certificates at all.

If more than one entry matches the search, the first returned search result will be used.

*** Publishing to Active Directory ***

When configuring Active Directory LDAP, Bind DN for the users are usually, cn=user,cn=Users,dc=domain-component1,dc=domain-component2.For example: cn=Philip Vendil,cn=Users,dc=primekey,dc=se for the domain primekey.se

If your DN is like "cn=Ejbca1,0=MyOrg,c=SE"and your base DN is like "DC=Security,DC=Software,DC=MyOrg".The publisher for AD should have base DN like"cn=Users,dc=Security,dc=Software,dc=MyOrg"

For Login DN you should use the full ldap name, for example:"CN=Administrator,CN=Users,dc=primekey,dc=se"

In order to connect to AD though SSL you should issue a LDAP SSL P12 to the domain controller. According to MS Article ID321051

The same certificate is used for both the AD and global catalogue (GC). Remember to add the CA certificate to the machinethat stores trusted root certificates.

To publish a CRL to Active Directory use a Base DN similar to

CN=somename, CN=CDP, CN=Publ i c Key Ser vi ces, CN=Ser vi ces , CN=Conf i gurat i on, DC=somemachi ne, DC=pr i mekey, DC=se

and the "CRL Distribution Point" in the certificate should point to

l dap: / / / CN=Tes t %20MS%20SC%20Logon%20CA%20v1, CN=somename, CN=CDP, CN=Publ i c%20Key%20Ser vi ces , CN=Ser vi ces ,CN=Confi gur ati on,DC=somemachi ne,DC=pri mekey,DC=se?cert i f i cat eRevocat i onLi st ?base?obj ectCl ass=cRLDi st r i but i onPoi nt

*** Constructing the DN for an entity to be published ***

The DN to be published is constructed from the certificate DN of the entity to be published. But if the publisher requires a DNobject that is not a part of the certificate DN then the DN defined for entity might be used instead.

The DN of the entity (user or CA) could have more objects than the certificate if "Use a Subset of Subject DN" is defined in theused certificate profile.

The "LDAP Publisher" and the "LDAP Search Publisher" tries the DN of the entity when the certificate DN is missing an objectneeded in the publishing DN

*** What EJBCA stores/creates/modifies ***

Apart from the DN in the entry a number of attributes are also stored, some are required by schema, some are optional.EJBCA find attributes in the certificate, if it is an OU (organizational unit) in the certificate EJBCA uses that to populate the OUattribute in the ldap entry.

When updating an entry that already exists EJBCA uses replace on the existing attributes, so if an email attributes alreadyexists and EJBCA finds an email address in the certificate, the email attribute in ldap is replaced with the email address fromthe certificate.

Note that attributes are only replaced/updated if the flag "Modify Existing Users" in the Publisher is active. The certificateattribute is always updated though.Attributes that are part of the DN, i.e. that reflects the location of the entry in LDAP is not modified, since this is usually notallowed.

The attributes that EJBCA creates or replaces are:

cn (common name)l (locality)ou (organizational unit)sn (surname)gn (givenname)st (state)


30 of 38

o (organization)uid (user id)initialstitleserialnumber - If we have selected to use the SN (serialNUmber DN field) in 'Ldap Location fields', we will also add it asan attribute.

Extra device schema

To store certificates for devices (e.g. routers, toasters etc) in LDAP it is no really suitable standard object class. inetOrgPersonrequires surnames etc, and the device objectclass does not include a certificate attribute.

Mike Jackson has kindly contributed additional objects that extend the standard device class with a certificate attribute. TheejbcaDevice uses object ids from PrimeKey Solutions AB.

*** Installation ***

For the Netscape/SUN servers, on UNIX, copy the 85ejbca.ldif file into:

/ usr/ nets cape/ser vers/ sl apd-hostname/confi g/schema/

and restart the LDAP server.

For OpenLDAP, copy the ejbca.schema file into, e.g.:

/ etc/ l dap/schema/

and edit slapd.conf to add the following line:

i nclude / etc/ l dap/schema/ej bca. schema

then restart the server.

Custom publishers

*** Developing a custom publisher ***

If your setup makes it very complex to configure multiple certificate profiles and multiple publishers you might consider writinga custom publisher that handles things directly according to you needs.

Look in the directory src/java/org/ejbca/core/model/ca/publishers for more information about writing your own solution. Thereis an empty custom publisher called DummyCustomPublisher.java that can be extended.

*** Publishing with an external application ***

A lightweight alternative to developing a new custom publisher for exporting CRLs, certificates and revokations is to use theGeneral Purpose Custom Publisher (GPCP). This makes it possible to export DER-encoded CRLs, certificates and/or revokationswith a simple script (using scp or similar). The GPCP creates a temporary file and executes the script with the full pathname tothe temporary file as an argument.

It's possible to let the publisher ignore an error in the execution of a script by altering the publishers properties. By default,the publisher detects both output to standard error and a non-zero errorlevel set by the script.

To start using the GPCP, select "Edit Publishers" in the Administration GUI. Add a publisher "GPCP" and then "Edit" the same.Choose

Publisher type: Custom PublisherClass Path: org.ejbca.core.model.ca.publisher.GeneralPurposeCustomPublisherProperties of Custom Publisher:

cr l . appl i cat i on / fu l l pathname/export scr i pt . shcrl . f ai l OnSt andardErr or <tr ue | f alse>crl . f ai l OnErr orCode <tr ue | f alse>cr l . cal c lu l ateDelt aCr l Local l y <tr ue | f a lse>cert . appli cati on / f ul l pathname/exportscr i pt. shcert . fai l OnStandardErr or <tr ue | f alse>cert . fai l OnErr orCode <t rue | f alse>revoke. appli cati on / f ul l pathname/exportscr i pt. shrevoke. f ail OnStandardErr or <tr ue | f alse>revoke. f ai l OnErr orCode <t rue | f al se>

and click "Save and Test Connection" to save the entered information and validate that the specified applications exist. Select"Edit Certificate Authorities" in the Administration GUI and select "GPCP" as your new CRL publisher. Click "Save".

Test CRL publishing by selecting "Basic Functions" in the Administration GUI and click "Create CRL".Test certificate publishing by selecting "Edit Certificate Authorities" in the Administration GUI, select a CA, click "Edit"and then "Republish CA Certificates".

More advanced scripts or applications have the ability to use the additional argument

cert.application fulltempfilepathname x509type certificateDN issuerDN certHexSerialNumberrevoke.application fulltempfilepathname x509reason certificateDN issuerDN certHexSerialNumber

Depending on application, the GeneralPurposeCustomPublisher can calculate whether a CRL is a delta CRL. Set the parameter

crl.calclulateDeltaCrlLocally to true in order to do this, or false if you wish to check this in an external script (or not at all). The

result of this check, if run, will be last in the argument list to the script.

Publisher Queue and failures

To achieve robust publishing there is a publisher queue. When a publisher fails the published data is stored in a separate table inthe database, the PublishQueue. This queue can then be processed by a service (see Services Framework).

Publishers can also be configured not to publish directly at all, but to store everything in the queue, which is later processed. Thebenefit of this approach is that publishing is instant. When issuing certificates the CA does not have to wait for all publishers tofinish. If there are many publishers this might delay the issuing process slightly.

Publisher Settings:

'Current length' - displays the number of new entries in the queue in the intervals <1 min, 1-10 min, 10-60 min and >60min.'No direct publishing, only use queue' - when enabled, the publisher does not try to publish directly but instead pushes theupdate to the queue for later processing by a Publish Queue Process Service.'Keep successfully published items in database' - when enabled items stored in the publisher queue will not be removedwhen real publishing has been done, status will merely be changed from PENDING to SUCCESS.'Use queue for CRLs' - determines if the publisher queue should handle CRLs or not for this publisher.'Use queue for certificates' - determines if the publisher queue should handle certificates or not for this publisher.

ECDSA keys and signatures


31 of 38

EJBCA support ECDSA signature keys in addition to RSA. You can create a CA using ECDSA keys both using the admin-GUI and usingthe cli (bin/ejbca.sh ca init).

Generated keys and certificate

When generating a CA in EJBCA up to three keys and certificates are generated:

A CA signing keypair and certificateAn encryption keypair, used for encrypting keyrecovery informationAn OCSP signer keypair and certificate

When using ECDSA keys, the CA signing keypair and the OCSP signer keypair will be the ECDSA keytype you select when creating

the CA. The CA signing and OCSP signing certificate will be signed using your selected signature algorithm.

The encryption keypair will always be RSA, using 1024 or 2048 bit key length. It uses the key length set in the admin-GUI or

2048 bit by default using the cli. A dummy encryption certificate will be created using SHA1WithRSA.

Using ECDSA with an HSM

See the section about HSM property parameters to see which keys can be of different sorts. Note that the keyEncryptKey can notbe ECDSA, but should be an RSA key. Your HSM must support both ECDSA and RSA keys. You can use PKCS11HSMKeyTool fromthe clientToolBox to generate keys and certificate requests from an HSM.

ECC named curves vs explicit parameters

Normally you want to generate requests and certificates using named curves encoded in certificates and requests, this i s whatIETF recommends. In some cases you need to generate the request and certificate with explicit parameters instead, this is forinstance mandated by ICAO for usage in CSCA's and DS's for ePassports.

When generating requests with clientToolBox PKCS11HSMKeyTool certreq you can specify a flag to use explicit parametersinstead of named curves. Named curves is the default.When EJBCA issues certificate with public keys from certificate requests (csr's) the key in the certificate will be the same asin the csr. If the csr uses explicit parameters, so will the issued certificate.

Named curves

EJBCA supports the curves that BouncyCastle supports, they include named curves from Nist, SEC and X9.62. New curves may besupported without this list being updated, give it a try! SeeBouncycastle wiki for more information about ECDSA curves.

X9.62 curves:

prime192v1prime192v2prime192v3prime239v1prime239v2prime239v3prime256v1

SEC curves:

sect571r1sect409r1sect283r1sect233r1sect163r2secp521r1secp256r1secp224r1secp384r1

Nist curves:

P-224P-256P-384P-521B-163B-233B-283B-409B-571

Teletrust curves:

brainpoolp160r1brainpoolp160t1brainpoolp192r1brainpoolp192t1brainpoolp224r1brainpoolp224t1brainpoolp256r1brainpoolp256t1brainpoolp320r1brainpoolp320t1brainpoolp384r1brainpoolp384t1brainpoolp512r1brainpoolp512t1

ImplicitlyCA curves

X9.62 provides 3 alternatives for the parameters that can be found in an EC public key. One of these is named implicitlyCA andindicates that the parameters are defined else where, implicit in the name of the certification authority (CA) that issued the key.In this situation the actual parameters appear in the ASN.1 encoding of the key as a DER encoded NULL.As the definition says, when the key is used, the parameters will have to come from elsewhere. In EJBCA the parameters areconfigured in conf/ejbca.properties.

When creating a new CA using the implicitlyCA facility, you first configure your curve parameters in conf/ejbca.properties andissue commands:

ant cleanant deploy

After restarting the application server you can now create a new CA using the name 'implicitlyCA' instead of a curve name as

keyspec in the admin-GUI or CLI.


32 of 38

The CA certificate will now be created with the NULL encoding of the public key.

When issuing client certificates where the client public key uses implicitlyCA, you must allow key length 0 in the certificate profile,because EJBCA can not read the key length, since the parameters are defined elsewhere.

See Bouncycastle wiki for more information about the implicitlyCA facility.

The curve parameters in conf/ejbca.parameters are configured in Bouncycastle using the following code:'

ECCurve curve = new ECCur ve. Fp( new Bi gI nteger(ecdsa. i mpl i c i t l yca.q) , / / q new Bi gI nteger(ecdsa. i mpl i c i t l yca.a, 16) , / / a new Bi gI nteger(ecdsa. i mpl i c i t l yca.b, 16)) ; / / borg. bouncycast l e. j ce.spec.ECParameter Spec i mpl i ci t Spec = new org. bouncycast l e.j ce.spec.ECParameter Spec( curve, curve.decodePoint( Hex. decode(ecdsa.i mpli ci t l yca. g)) , / / G new Bi gI nteger(ecdsa. i mpl i c i t l yca.n)) ; / / nConf i gurableProvi der conf i g = (Confi gurableProvi der) Securi ty. getProvi der( "BC") ;conf i g.set Parameter ( Conf i gurabl ePr ovider. EC_I MPLICI TLY_CA, i mpl i ci t Spec);

Creating client certificates

You can also issue normal requests for client certificates using ECDSA keys.All certificates signed by an ECDSA CA will naturally use ECDSA signatures, regardless if the client keys are RSA or ECDSA.

When batch generating client keys using the cli command 'bin/ejbca.sh batch' you configure the type of client keys that will begenerated in the file bin/batchtool.properties. The possible parameters are explained there. If using the implicitlyCA facility thesame parameters as configured for the ca in conf/ejbca.properties are used.

Limitations

When using the 'implicitlyCA' mode only one set of curve parameters can be set for the whole EJBCA instance. This means that if you have several CAs using ECDSA with 'implicitlyCA', they will all use the same curve parameters. You can mix 'implicitlyCA' withnamed curves any way you like though.

Internationalization

To customize EJBCA admin GUI for your languages special characters you will probably have to change the default page encoding in'web.contentencoding' (in conf/web.properties file) to for example UTF-8 instead of the default ISO-8859-1.

Displaying, receiving, decoding and storing different char sets is rather complicated and the architecture is multilayered. There arethe web browser, application server, database and operating system, all working together. If you change to UFT-8 to handle your charset, you must probably also specify that the database connection should use UTF-8. For MySQL this can be done in the connection-url in your datasource description (APPSRV_HOME/server/default/deploy/ejbca-ds.xml): jdbc:mysql://yourhost /ejbca?characterEncoding=UTF-8

You will also want to configure the database, for example in my.cnf, to use UTF-8.

You also want to configure your machine to use the locale you are using, otherwise some encoding/decoding to the database may getmixed up and throw a lot of errors (java XML decoding). For example in SUSE this is done with 'yast' and in Debian it is done with'dpkg-reconfigure locales'.

For some languages (for example Chinese) the java scripts in the admin GUI will fail to recognize the characters when doing checksfor allowed characters in DN etc. The easiest way to resolve this is to go into the file:src/adminweb/ejbcajslib.jsAnd change all methods 'checkfield*()' to always return true directly.

If you can't get you national characters to work with the admin GUI, you can try using the cli instead (bin/ejbca.sh ra adduser ...).That usually works.

EJBCA have for example been tested on Windows/JBoss 4.2.0/MySQL and Linux/JBoss4.2.0/HSQL with the default configuration usingSwedish national characters, and it works nicely both with the cli and admin-GUI.

To make everything work perfect you MAY have to also configure JBoss to encode URIs according to your settings, this is done withthe 'URIEncoding' directory in APPSRV_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml:

<Connect or port ="8443" addr ess="${j boss. bi nd. addr ess}" maxThr eads="100" mi nSpareThr eads=" 5" maxSpar eThr eads="15" scheme="ht t ps" secure="t r ue" cl i entAuth="t r ue" keystoreFil e="${j boss.server. home.di r}/ . . / . . / bin/ tomcat . j ks" keyst orePass="t 0mcat. " ssl Prot ocol = "TLS" URI Encodi ng="UTF-8"/ >

Adding a new language to the admin GUI

Java uses unicode internally, so the things that needs to be taken care of are:

Make sure your system locale is set correctly, so Java will recognize input of your nations language. If Java does not

automatically recognize your locale you might need to specify it as options to java during startup (i.e. in JBoss and cmd linecommands such as ca.sh and ra.sh). java -Duser.language=2-char-language-code -Duser.region=2-char-country-codeexample for Swedish: java -Duser.language=sv -Duser.region=SE

1.

Your database must also recognize the locale so it does not strip down to plain ascii. This is database and JDBC-driver

dependent.

2.

The admin GUI is meant to support multiple languages through language files in src/adminweb/languages. In order to add alanguage you should do the following:

Rename the languagefile you have created to language.languagecode .properties. In case of chinese it should be 'zh', and

place it in the src/adminweb/languages directory.

1.

Edit conf/web.properties (create with conf/web.properties.sample as template if you don't have one). Change

'web.availablelanguages' and add your language code to the value. i.e: <env-entry-value>EN,FR,IT</env-entry-value>

2.

You may have to change the default page encoding in 'web.contentencoding' to for example ISO-8859-1 instead of the

default UTF-8.

3.

Clean and re-deploy ejbca with 'ant clean' followed by 'ant deploy'. Restart JBoss and your browser after this.4.

Now it should be possible to select EN, FR and IT in the system configuration as default language and in the administratorpreferences page. The language will be changed next time the administrator logs in.

Internal Internationalization

It's also possible to translate internal log comments, some exception messages and approval notifications. This is done separatelyin it's own resource files since this is done internally in the core application and not in the web-layer.

The language used internally is configured in the conf/web.properties file by setting the properties intresources.preferredlanguageand intresources.secondarylanguage to the language you want to use. The letters should be the same as the xx name in theintresources.xx.properties files in the src/intresources directory. The secondary resource file is used if the resource isn't found inthe preferred language. This is a global setting that cannot be overridden by administrators own settings in the web-layer.


33 of 38

Custom DN and altName oids

EJBCA supports custom (your own) oids in DN components.

In order to add such a DN you can simply call the DN for example: CN=MyCommonName,1.1.1.1=MyCustomOid,C=SEWhere 1.1.1.1 is your custom oid.

Custom OIDs are always encoded as UTF8String in the DN.

To get support for custom OIDs in the Admin-GUI you must edit the file src/java/profilemappings.properties and add your new OID inthe end. Just follow the example in the file, and you will get the possibility to add you oid in the End Entity Profile, and following thatalso when adding new users. If you edit profilemappings.properties, you should also add an entry i n src/adminweb/languages /languagefile.XX.properties (where XX is you language). Otherwise your new field will be displayed as the key that you entered(which is probably ok also) in the admin-GUI. The new field you must add in the language file is the last field inprofilemappings.properties, i.e. the LanguageConstant.

EJBCA wil l by defaul t put unknown OIDs i n the end so the DN will probably be displayed as:CN=MyCommonName,C=SE,1.1.1.1=MyCustomOid (if looking at the asn1 coding, different application display in a different orderregardless of the asn1 coding).If you need a particular order of DN components, you can add a file 'dncomponents.properties' in the directory ejbca/src/java. There isa file called dncomponents.properties.sample in the distribution as a starting point (it shows the default ordering in EJBCA). Youcustom oid must be placed in the right place in that file, and all components from the sample file should be included, or you will getstrange behaviour.Using the dncomponents.properties file is only needed if you need to control the asn1 ordering of DN elements.After updating dncomponents.properties you need to run 'ant clean' before re-deploying EJBCA.

A word of caution:If you use custom oids, they better not become standard ones later on, because if the underlying asn.1 library in EJBCA starts toknow the oids as standard ones, things will be renamed in the database and you will have to do a database migration. Also you mustkeep track of dncomponents.properties when upgrading EJBCA.

Stick to the standard is my advice!

Having all these customizations off-course requires some maintenance on your part, so don't forget your customizations whenupgrading EJBCA to a new version.Check RELEASE_NOTES for important changes!

altNames

Adding custom OIDs in altNames works the same way as for DN. When a custom oid is used the altName string in the databasewill be for example "[email protected], 1.1.1.1=foobar".A Custom oid is always added as OtherName using a simple UTF8String. See rfc3280 for definition of the OtherName altName.The OtherName consists of:

The custom oidAn UTF8String with the value

Custom Certificate Extensions

From EJBCA 3.4 it is possible to add customized certificate extensions to certificates. Simple extensions only containing a static valuecan be added by simply editing a property file, these are called "basic certificate extension". It is also possible to generate advancedcertificate extension by implementing a simple java interface.

Configuring Custom Certificate Extensions

Certificate extensions is configured in the file 'src/java/certextensions.properties' All extensions should have a id ranging from 1up to 255, the number order is important.

oid : The unique OID of the extension (Required)classpath : Classpath to the CertificateExtention implementing class. (Required)displayname : Display name of the extension in the 'Edit Certificate Profile' page (Required)used : Defines if the extensions should be used or be disabled. (Required)translatable : If the display name should be translated in the language resources. (Required)critical : Defines if the extension should be marked as critical in the certificate. (Required)property.'property' : It is possible to define properties to the actual implementation of the CertificateExtention, for exampledoes the BasicCerticateExtension require the properties 'encoding' and 'value' to be set.

After the file is configured rebuild and deploy EJBCA.

After extensions have been added it is possible to select them for a certificate profile in the 'Edit Certificate Profile' page.

Basic Certificate Extension

In order to create a Basic Certificate Extension you use the classpathorg.ejbca.core.model.ca.certextensions.BasicCertificateExtension and specify the properties idX.property.encoding andidX.property.value. See the following table for the available encodings and how their value is interpreted

DERBITSTRING : A String containing the characters '0' and '1'.DERINTEGER : A String containing digits only in decimal digits.DEROCTETSTRING : A String containing hex data representation.DERBOOLEAN : The string 'true' or 'false'.DERPRINTABLESTRING : A string containing valid printable string characters (a-z, 0-9).DERUTF8STRING : A string in UTF-8 format.DERIA5STRING : An ASN.1 IA5String containing valid printable string characters (a-z, 0-9).DERNULL : Value isn't used, an empty value.DEROBJECT : The hex encoded DER value of the extensions. You can use this to create any extension with sequences etc.

Examples of certificate extensions that you can configure with the BasicCertificateExtension are given in 'src/java /certextensions.properties'.

MS application policiesNetscapeCertTypeNetscapeCommentNetscapeCARevocationURLNetscapeRevocationURL...

Implementing an Advanced Cer tificate Extension

To create an advanced extension it is required to create a java class extending the CertificateExtension abstract class. Onemethod getValue is required and the current user data, ca and certificate profile is sent to the extension in order to generatedynamic extensions.

Here is an example of a simple advanced extension. To add this extension to EJBCA add it to to the classpath incertextensions.properties, make sure the class is accessible in the classpath and redeploy.


34 of 38

publ i c cl ass SomeAdvancedCert i f i cateExt ensi on extends Cert i f i cateExt ensi on {

pri vate st at i c Str i ng PROPERTY_SOMEPROPERTY = "somepropert y";

/ ** * The mai n met hod t hat s houl d ret urn a DEREncodabl e * usi ng the i nput data ( opti onal) or def i ned propert i es (opt i onal) ** @see org. ej bca. core. model . ca.cert extensi ons. Cert i f i cateExt ensi on#get Val ue( org. ej bca. core. model . ra. UserDataVO,*/

publ i c DEREncodabl e getVal ue(User DataVO userDat a, CA ca,Cer t i f i catePro f i l e cer tP ro f i l e) {

Str i ng val ue = getPr oper t i es( ) . getPr oper t y( PROPERTY_SOMEPROPERTY);

return new DERPri ntabl eStr i ng(val ue);}

}

Logging

The are three different logging devices available for official events (creation of certificate etc) from EJBCA 3.6. These devices shouldnot be confused with the info/debug output that is sent to Log4J directly. You can find more information on how to configure Log4J in$EJBCA_HOME/doc/howto/log4j.txt.

What log devices to use, can be configured in $EJBCA_HOME/conf/log.properties.

It is recommended to only allow new log-posts to the database-tables. More information on this can be found in $EJBCA_HOME/doc /howto/HOWTO-database.txt.

Log4JLogDevice

Appends the information from the offical event to the console or file. This is the same target where all the other info/debug outputis sent to. There are no protection from alteration and events sent to this device cannot be fetched back to EJBCA for display inthe Admin GUI.

OldLogDevice

OldLogDevice stores log-events in the database. By using the addon HMAC-protection, alterations in a log event can be detected.Viewed events can be exported from the Admin GUI.

ProtectedLogDevice

The P r o t ec tedLo gDev i ce has been dep r e ca ted i n E J BCA 3 . 1 0 , s i n c e i t ' s h ar d t o c onf i g u r e r i g h t and e x tr emel y inef f ic ient .

The ProtectedLogDevice stores log-events in the database and has the ability to detect changed or missing log-events. In anenvironment where at least one node (EJBCA-instance) is constantly running, the log cannot even be rolled back to a an earlierstate without detection.

Features:

No event can be removed or changed without detection (as long as one node is still runnning)Can perform regular signed export of log for backup (mitigates damage of offline rollback)Can send emails, run a script and/or kill the JVM if alterations are detectedCan use a CA-token (hard or soft) or a soft JKS keystore (stored encrypted with CA-key in database)Can set a signature intensity to allow slower HSMs to use the featureNodes can be added or removed dynamically

Drawbacks:

Very database intensive.Cannot yet export viewed part of log from Admin GUI

It is good practise to

use secure communication with the database.use asymmetric log-signing key and a HSM.use a database/database engine that supports transaction (e.g. InnoDB and not MyIsam for MySQL).

The log can be verified manually using "ejbca.sh/cmd log" CLI.

See conf/logdevices/propectedlog.properties.sample for more information on how to configure and use the device.

Reference manual

All configuration options, JNDI names etc is configured through the use of properties files in conf/*.properties file. You can copy the.sample files to respective .properties files and configures. Most options are documented in the .samples files.

Command line interface

EJBCA have command line interfaces (cli) to both the CA and RA, and some other operations.

The best documentation for the cli can be found by running it.

bin/ejbca.sh bin/ejbca.sh ca bin/ejbca.sh ra this will give a list of all available cli commands. To find out which options are

available for a specific command, simply run the command with no options: bin/ejbca.sh ra adduser This will give documentation

about available options. To access the usage information for some commands, that does not take parameters, the option '-?' can

normally be provided.

Other Configuration

To setup an initial hard token issuer with alias 'local' and queue a superadmin user for card issuing. Card issuing using the hardtoken issuers is normally done using PrimeCard.

bi n/ej bca. sh setup i ni t i al i zehardtokeni ssui ng <caname>Ex: bi n/ej bca. sh setup i ni t i al i zehardtokeni ssui ng Admi nCA1

This is a utility function to quickly and easily issue an initial administration smart card using PrimeCard.

If you want to change the baseurl of the admin-web after installation use the command:

bi n/ej bca. sh setup setbaseurl comput ername appl i cati onpat hEx: bin/ ej bca.sh setup setbaseurl l ocalhost ej bca

You should never have to do this in version >= 3.2.

To change ports (default public http=8080, public https=8442, private https=8443) you must edit conf/ejbca.properties. Change


35 of 38

the properties httpserver.pubhttp, httpserver.pubhttps and httpserver.privhttps. After changing, run 'ant deploy' and re-start theapplication server.

Asn1Dump

You can make an asn1 dump of a certificate in order to study the asn1 produced:

bi n/ ej bca.s h asn1dump <f i l ename- of - pem- encoded- cert s or fi l ename- of - der- encoded- asn1>Ex: bi n/ ej bca.sh asn1dump admi nca1. pem

Batch creation of certificates

Certificates can be created batch-wise with EJBCA. The class org.ejbca.ui.cli.batch.BatchMakeP12 creates keystore files for allusers designated as NEW or FAILED in the local RA database. To be able to batch generate certificates, the users must beregistered with clear text passwords. To set a clear text password for a user use

bi n/ ej bca.s h ra set cl earpwd username passwordbi n/ej bca. sh ra set user st atus username 10

The same is accomplished in the Admin-GUI by checking the checkbox 'Batch generation' when adding the user.

To generate keystore files for all users with status NEW or FAILED, run

bin/ ejbca.sh batch

This will generate files for users if their clear text passwords are NOT null.

Without arguments 'batch' generates keystore files for all NEW or FAILED users. To generate a keystore file for a specific user,enter command

bi n/ ej bca.s h batch user name

Generated keystore files are stored in a subdirectory (to the current directory) called 'p12'. If the directory does not exist, it willbe created. Make sure this directory is WELL protected, since the information contained in keystore files are secret (private keys).The format of keystores generated, PKCS12, JKS or PEM, is defined when adding the user in the database (using 'bin/ejbca.sh raadduser' or the admin-GUI).

Fetching certificates and CRLs

Certificates and CRLs can be fetched through the public web-interface. They can also be fetched directly from the'CertificateStoreSession' session bean or using the command 'bin/ejbca.sh ca getcrl'

Other deployment scenarios

EJBCA can be run with servlets and EJBs or only with EJBs. The servlets are only a publicly available front-end to the beans. If theCA is deployed integrated in another J2EE application, this front-end may not be needed.

Customizing EJBCA

You can change any part of EJBCA to better suit your specific needs.

Handling changes in a separate tree (EJBCA >= 3.5)

You can keep your personal modifications of EJBCA in a separate tree. Set the location of your personal modifications inconf/custom.properties or use the default location '$EJBCA_HOME/../ejbca-custom'. Your modifications will automatically overwriteany existing file(s) found in the EJBCA_HOME-directory or its subdirectories before executing an 'ant'-command. A sample,conf/custom.properties.sample, is provided.

Example usage:You have a working set of configuration files and database from the latest stable release, and want to try the latest trunksnapshot.

Backup your databaseCopy $EJBCA_HOME/conf/ to $EJBCA_HOME/../ejbca-custom/conf/Copy $EJBCA_HOME/p12/ to $EJBCA_HOME/../ejbca-custom/p12/Copy $EJBCA_HOME/src/java/*.properties to $EJBCA_HOME/../ejbca-custom/src/java/*.properties

You can now remove the entire $EJBCA_HOME-directory and replace it with the a fresh snapshot from the trunk. Restore the

database and all the config and generated keys will be restored to $EJBCA_HOME next time you run "ant deploy".

Please note that

there is no way to recover overwritten files, so you have to manually restore files if needed.ant will not be able to detect if your changes are incompatible with newer versions of EJBCA. Always use 'diff' on thedifferent versions to see if any file you override is affected.committing new features or improvements, that many would benefit from, is greatly appreciated by the community andmakes your maintenance easier

Adding your own public web-pages

The public web-pages are written in JSP and can be found under src/publicweb/publicweb. Modify the pages (directly or by using aseparate tree), rebuild and redeploy. The changes should show on http://ejbcahost :8080/ejbca.

Adding your own rules to regulate the values of End Entity Fields

It is possible to define a set of rules to control the format of the End Entity fields. For example, it is possible to ensure that thesubject DN serial number is always a number of six digits, or should always end with the letter 'N'.

Setting such rules is done by implementing the static function org.ejbca.core.model.ra.FieldValidator.validate(). In this function,you can define a rule that is applicable to a specific field in a specific End Entity profile. Should the field value not match the rule,a CustomFieldException should be thrown and the error message you set in the exception will be shown as the error message inthe GUI. This rule will be checked each time an end entity is added or changed, whether is was added or changed by the GUI orotherwise.

To avoid losing these rules when updating the EJBCA version, the new FieldValidator class should be stored in a ejbca-customcatalog. Please see the "Handling changes in a separate tree" section above.

Using the demo servlet

It is a demo servlet that will accept any incoming post, create a user with a unique username, and instantly send back a certificate.The entity- and certificate profiles used are sent as parameters in the post. To set up the demo servlet:

Find out the CA id of the CA you want to use for signing of the demo certificates. Use the admin-GUI or 'ejbca.sh ca listcas' to

find the integer value that is the CA id.

1.

Configure the CA id in rc/java/org/ejbca/ui/web/pub/DemoCertReqServlet.java, it's the parameter DEFAULT_DEMOCAID.2.

Edit src/publicweb/publicweb/WEB-INF/web.xml and uncomment the two sections for the demo servlet.3.

If using UTF-8 to display the web-page containing the demo form to the users, change ISO-8859-1 to UTF-8 for the env-entry4.


36 of 38

'contentEncoding'. Otherwise national characters in names will be encoded/displayed incorrectly in the certificates.

Deploy with 'ant deploy'.5.

Create an end entity profile and a certificate profile that should be used for the demo certificates.6.

Create a demo apply page containing something similar to the sample form below for Firefox. There are some sample scripts

under src/publicweb/publicweb.

7.

<f orm name="demoreq" act i on="ht t p: / / 127. 0. 0. 1: 8080/ ej bca/democert r eq" method="post "> Please f i l l out the f orm and cl i ck Enrol l to recei ve your cert i f i cate. Read our <a href ="ht t p: / / www. pri mekey.se/ pri mekey/ en/Demo. html ">pri vacy pol i cy</ a>. Ful l name: E-mail : Choose key l ength f rom t he l i st bel ow. The defaul t i s recommended i n most cases. <keygen t ype="hi dden" name="keygen" val ue=" chal l enge" > </ f or m>

You can use some hidden fields and some java script to for example only ask for a name, and concatenate it with a hidden partial DNto produce a full dn for the 'user' parameter. Use your imagination!

Samples

A collection of samples are in the directory src/java/se/anatom/ejbca/samples.

Troubleshooting

Add Debug output from the console administration commands by replacing:

l og4j . rootCategory=I NFO, Consol e

in the file 'log4j.properties' with:

l og4j . r ootCategory=DEBUG, Consol e

Extra info about the admin-GUI

If you had problems using the install script this small part describes briefly what the setup of the adminweb does. It's explained usingout-of-the-head commands so don't expect it to work by copying and pasting these commands, it just something to l ook at.

0. Set the baseurl of the server with the command 'setup.sh/cmd setbaseurl computername applicationpath ' Set the BASEURL toreflect your hostname, to be able to use the adminpages from external machines, this must be a real hostname or ip-address. Run'ant deploy' to install the changes.

1. Tomcat: Copy src/appserver/jboss/tomcat55/server.xml (or similar depending on your JBoss version) to$APPSRV_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml.

Edit the fi le so 'keyStorePass' is the same as the password you specify below for 'tomcat'.

2. Edit parameters in conf/ejbca.properties.

3. Create a tomcat server keystore with the 'ejbca.sh batch' tool (this can also be done with Suns 'keytool' by creating a keystore andthen generating a certificate request that is processed by EJBCA, and last import the returned certificate and the CA-certificate intothe keystore).

Create a user in EJBCA, DN="C=SE,O=PrimeKey,CN=your-host-name".

bi n/ ej bca. sh ra adduser t omcat f oo123 "C=SE, O=Pr i meKey, CN=yourhost - name" nul l caname nul l 1 J KS SERVER

Set a clear text password for the tomcat:

bi n/ej bca. sh ra set cl earpwd tomcat f oo123

Generate a JKS-keystore for tomcat:

bi n/ej bca. sh bat ch t omcat

4. Name the generated keystore 'tomcat.jks' and put in $APPSRV_HOME/server/default/conf/keystore.

5. Download the CA certificate in PEM-format from http://localhost:8080/ejbca/retrieve/ca_certs.jsp (call it ejbca-ca.pem).

6. Add the EJBCA CA certificate to the EJBCA Java trust-keystore in p12/truststore.jks

keytool - i mport - t rustcacert s -f i l e ejbca- ca. pem- keystore p12/ t rustst ore.j ks - storepass changeit

Deploy the new truststore with 'ant deploy'.The command 'ant javatruststore' does the above automatically.After this you must restart JBoss.

7. Create a user for EJBCA admin with CN=SuperAdmin and the RAADMIN bit (temporarily CN=SuperAdmin gives admin rights).

bi n/ ej bca. sh r a adduser r aadmi n f oo123 "C=SE, O=Pr i meKey, CN=Super Admi n" nul l caname nul l 65 USERGENERATED

Alternative: Create a PKCS12 file with EJBCA for a user with CN=SuperAdmin and the RAADMIN bit (temporarily CN=SuperAdmingives adminrights).

bi n/ ej bca. sh ra adduser r aadmi n foo123 "C=SE, O=Pr i meKey, CN=Super Admi n" nul l caname nul l 65 P12bi n/ej bca. sh ra set cl earpwd raadmi n f oo123bin/ ejbca.sh batch

8. Fetch the certificate using your browser a http://localhost:8080/ejbca/

Alternative: Install the generated PKCS12 (p12/superadmin.p12) file in the browser. In Firefox this is done byEdit->Preferences->Privacy&Security-> Certificates->Manage Certificates->Import In IE it is done by double-clicking on the .p12 file.

9. Start JBoss.

10. Go to https://hostname:8443/ejbca

Reference: to generate a JKS with keytool


37 of 38

keytool - genkey - al i as t omcat - keystor e t omcat. j ks - keyal g RSA - dname " C=SE, O=AnaTom, CN=hostname" - st orepass f oo123keyt ool - cert req -al i as t omcat - keyst ore tomcat. j ks -si gal g SHA1Wi t hRSA - st orepass foo123 - f i l e t omcat. reqbi n/ ej bca. sh r a adduser t omcat f oo123 "C=SE, O=AnaTom, CN=host name" nul l caname nul l 1 USERGENERATED SERVER( go to EJ BCA publ i c web and get a ' Server cert i f i cate' by pasti ng the request i nto t he web form and save as tomcat. pem)bin/ ejbca.sh ca getr ootcert ca. der - derkeytool - i mport - t rustcacert s -al i as cacert - f i l e ca.der -keystore tomcat. j ks -st orepass f oo123keytool - i mport - al i as tomcat - f i l e tomcat. pem- keystore t omcat. j ks -st orepass foo123

keytool - i mport - t rustcacert s -f i l e ca. der - keystore p12/ tr ust store. j ks -storepass changei tant depl oy

Character limitations

Since the Admin GUI still uses some JSP and EJBCA at some occasions uses string concatenation to build SQL querys, we have toban some characters to avoid XSS-attacks and SQL-injections:

\ " \ n \ r \ \ ; ! \ 0 % ` < > ? $ ~

(\n is newline, \r is carriage return, \\ is backslash, \0 is null)

These characters will be replaced by /. ',' can be escaped ,'\,'.

Code signing

Being able to verify the integrity of a release or deployed EAR-archive might be required for some setups. Currently both ant targets"ziprelease" and "ca.ear" (invoked from "deploy", "bootstrap" and the default target) supports jar-signing with the "jarsigner"command included with Java. Note that you still could remove files from a signed archive without anyone noticing since the files aresigned individually. To create a signed ziprelease of EJBCA:

ant zi prelease - Dej bca.zi pversi on=x_y_z - Dsi gnj ar. keystore=p12/r eleasesi gner. j ks - Dsi gnj ar. keystoreal i as=rel easesi gner - Dsi g

The certificate used for the signature must have key usage "Digital Signature" and extended key usage "Code Signing". The signedarchive can be verified using the "jarsigner" command and the CA-certificate. This example will output any unsigned file or file with abad signature:

j boss@ser ver : ~/ ej bca$ j ar si gner - ver i f y - keys t or e p12/ t r ust st or e. j ks - ver bose . . / ej bca_x _y_ z. zi p | gr ep - v " smk" | gr ep - v

246809 Tue Oct 21 13: 28: 48 CEST 2008 META- I NF/ MANI FEST. MF 246930 Tue Oct 21 13: 28: 48 CEST 2008 META- I NF/ RELEASES. SF 1859 Tue Oct 21 13: 28: 48 CEST 2008 META- I NF/ RELEASES. RSA

s = si gnature was veri f i edm= entr y is l i s ted i n mani fest

k = at l east one certi f i cate was f ound i n keystore i = at l east one cert i f i cate was f ound i n i denti ty scope

j ar ver i f i ed.

OpenSSL can be used to sign and verify an entire archive, but requires the public key from the signing certificate:

j boss@ser ver : ~/ ej bca$ openssl dgst - sha1 - si gn p12/ pem/ r el eases i gner - Key. pem - out . . / ej bca_x_y_z . zi p. SHA1wi t hRSA . . / ej bca_x_ j boss@ser ver : ~/ ej bca$ openssl x509 - i nf or m pem - i n p12/ pem/ r el eases i gner . pem - pubkey - noout > p12/ pem/ r el eases i gner - Pub. pem j boss@ser ver : ~/ ej bca$ openssl dgst - sha1 - ver i f y p12/ pem/ r el eases i gner - Pub. pem - si gnat ur e . . / ej bca_x_y_z . zi p. SHA1wi t hRSA . . /Veri f i ed OK

Copyright © 2001-2009 EJBCA team. All rights reserved. - Last Published: 06/17/2010 14:55:15


38 of 38

Documents

37007259 EJBCA Admin Guide