EJBCA User Guide

hada2006

soure:http://ejbca.sourceforge.net/manual.html

User Guide

• About
  
• Security
  
• Upgrade
  
• Quick start guide
  
  
  
  • Prerequisites
    
  • Configure
    
  • Install
    
  • Additional howtos
    
  • Running optional tests
    
  
  
• After the installation
  
  
  
  • Administrative tutorials
    
  • Administrating EJBCA
    
  • SSL certificate expire
    
  • Creating more CAs
    
  • Creating a SubCA signed by en external CA
    
  • Converting an OpenSSL CA
    
  
  
• Using EJBCA
  
  
  
  • Creating Users
    
  • Create User certificates
    
  • Create server certificates
    
  
  
• CRL generation
  
  
  
  • CRL Update service worker
    
  • JBoss service
    
  • Cron job
    
  
  
• Scep
  
  
  
  • Level of SCEP support
    
  • Tested devices
    
  
  
• CMP (EJBCA >=3.4)
  
  
  
  • Configuration
    
  • CMP over http
    
  • CMP over TCP
    
  • User authentication
    
  • Proof of possession
    
  • Normal or RA mode for CMP
    
  • Certificate validity
    
  • Certificate Key Usage
    
  • Interoperability
    
  
  
• Ocsp
  
  
  
  • Stand-alone OCSP responder
    
  • Simple OCSP client
    
  • Adobe Acrobat Reader
    
  
  
• EJBCA Web Service Interface
  
  
  
  • Configuring Web Services CLI
    
  • Using the Web Services CLI
    
  • Using the Web Service API for Intergration
    
  • Accessrules required when using the Web Service API
    
  
  
• XKMS Service
  
  
  
  • Introduction
    
  • How to configure the XKMS Service
    
  • Implementation Specific Notes
    
  • Using the XKMS client
    
  • Running the XKMS test script
    
  
  
• External RA API
  
• Key recovery
  
• Email notifications
  
  
  
  • Dynamic Substitution Variables
    
  
  
• Printing of User Data
  
• Approving Actions
  
• Framework for External User Data Sources
  
• Framework for Reports
  
• Monitoring Services Framework
  
  
  
  • Currently Available Services
    
  • Writing Customized Services
    
  
  
• Hardware Security Modules (HSM)
  
  
  
  • Auto-activation of CA tokens
    
  • HSMs and ECDSA
    
  • Generic PKCS#11 provider (EJBCA 3.5)
    
  • Utimaco PKCS#11
    
  • nCipher PKCS#11
    
  • nCipher NFast
    
  • SafeNet Luna SA HSM
    
  • Eracom HSM with PKCS#11
    
  • Eracom HSM using Eracom provider
    
  • Writing support for new HSMs
    
  
  
• LDAP and Publishers
  
  
  
  • LDAP Naming
    
  • LDAP Basics
    
  • Configure LDAP publishers
    
  • Using LDAP
    
  • Configure OpenLDAP
    
  • Extra device schema
    
  • Custom publishers
    
  
  
• ECDSA keys and signatures
  
  
  
  • Genarated keys and certificate
    
  • Using ECDSA with an HSM
    
  • Named curves
    
  • ImplicitlyCA curves
    
  • Creating client certificates
    
  • Limitations
    
  
  
• Export and import profiles
  
• Export and import CAs
  
  
  
  • Using command line interface
    
  • Using admin-GUI
    
  
  
• Internationalization
  
  
  
  • Adding a new language to the admin GUI
    
  • Internal Internationalization
    
  
  
• Custom DN and altName oids
  
  
  
  • altNames
    
  
  
• Custom Certificate Extensions
  
  
  
  • Configuring Custom Certificate Extensions
    
  • Basic Certificate Extension
    
  • Implementing an Advanced Certificate Extension
    
  
  
• Reference manual
  
  
  
  • Administrating CA
    
  • Administrating RA
    
  • Other Configuration
    
  • Asn1Dump
    
  • Batch creation of certificates
    
  • Fetching certificates and CRLs
    
  • Other deployment scenarios
    
  • Certificate- and EndEntity Profiles
    
  
  
• Customizing EJBCA
  
  
  
  • Handling changes in a separate tree (EJBCA >= 3.5)
    
  • Adding your own public web-pages
    
  
  
• Using the demo servlet
  
• Samples
  
• Troubleshooting
  
• Extra info about the admin-GUI
  

About
　　EJBCA is a fully functional Certificate Authority built in Java. Based on J2EE technology it constitutes a robust, high performance and component based CA. Both flexible and platform independent, EJBCA can be used standalone or integrated in any J2EE application.
　　The EJBCA Homepage can be found at http://ejbca.sourceforge.net/. Information about contacting the EJBCA team, contributing to EJBCA, etc can be found through the Homepage.
　　More documentation can also be found on the homepage and on the documentation site http://docs.primekey.se/.
　　EJBCA is completely written in Java and should as such run on any platform where a J2EE server runs. Development and testing is performed on Linux and Windows platforms.

Security
　　Security is discussed below in the chapter about configuration and in Security.
　　Please take a minute to thoroughly consider the security implications and make sure you know what you are doing when you are setting up a CA.
　　If running on Linux, you should consider using the sample firewall script provided in 'ejbcafirewall.sh'. If running on Windows, a similar approach should be taken with firewall software/hardware.

Upgrade
　　See doc/RELEASE_NOTES and UPGRADE for information about upgrading from an earlier version of EJBCA.

Quick start guide

Prerequisites

Note
EJBCA makes use of strong crypto and keystore passwords longer than 7 characters. For this to work you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK. The policy files can be found at the same place as the JDK download at java.sun.com. The text "Using exportable cryptography" is shown on the first page in the Admin GUI if you fail to install this package. Further information on this can be found in the Sun documentation on the JCE.
Note
The default, and easiest, installation is done on JBoss. EJBCA can however also run on Glassfish and Weblogic. If you want to deploy on these application servers, read the file doc/howto/HOWTO-Appserver.txt.　　Needed to build and run are:

• JDK 1.5.x or 1.6.x (support for 1.4.x was dropped in EJBCA 3.5).
  
• Unlimited Strength Jurisdiction Policy Files for your JDK
  
• JBOSS >=4.0.4 (latest tested verison is JBoss 4.2.0)
  
• Ant >= 1.6.5 to build (http://jakarta.apache.org/ant/)
  

　　Set the environment variable APPSRV_HOME (or JBOSS_HOME) to the directory where JBoss's root is (/jboss-version). This is done so the deploy script will know where files are to be copied, they are copied to the directory $APPSRV_HOME/server/default/deploy.
　　Windows/Unix: When we describe command line commands below we use unix notation, e.g. 'ejbca.sh' for the executable command files. The same command files are available for windows as cmd-files, e.g. 'ejbca.cmd.'
　　Java 1.6.0
Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6.0
http://java.sun.com/javase/downloads/index.jsp
　　Java 1.5.0
Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 5.0
http://java.sun.com/j2se/1.5.0/download.jsp
　　NOTE: If you are unsure what version of EJBCA you are running, type 'ant ejbcaversion' in the EJBCA_HOME directory. (EJBCA 3.5 and newer.)

Configure
　　If you are only testing EJBCA at this stage and is not setting up a production environment, you can skip this step.
　　Now when everything is prepared, there are a few things to configure before starting JBOSS and running everything in a production environment.
　　In a production environment you should use something like the following structure:

• Go through the install process creating an AdminCA. Use a simple DN. This CA should only used to issue the administrator certificates. Not published in LDAP. If you want to use an HSM for this CA, see the documentation in the configuration file conf/ejbca.properties.sample.
  
• Once installed, create all your REAL CAs using the admin-GUI. Now you can use the certificate profiles etc that you like. These certificates can be published in LDAP. See doc/howto/HOWTO-multiplecas.txt for example of a detailed configuration guide.
  

　　In a production environment you should use something else than the default Hypersonic database that comes with JBoss for the reasons:

• Hypersonic database is in-memory, which means that over time it will consume more memory. If a large number of certificates is issued, it will become an issue after a while.
  
• Hypersonic does not support full SQL, in particular ALTER statements. When a new version of EJBCA is released we can not create scripts that updates the database if some tables changed. This will make upgrades much much harder.
  

　　For information about installing JDBC drivers for other databases, see the document 'doc/howto/HOWTO-database.txt' in the distribution.

*** Memory configuration ***
　　The memory parameters for Java is by default configured very low, for JBoss it is set by default to allow a maximum memory usage of 512mb, which is sufficient for most configurations. We still recommend that you check your configuration of java memory arguments to set them to at least '-Xms128m -Xmx512m'. For JBoss this is done in APPSRV_HOME/bin/run.conf where the line:

JAVA_OPTS="-server -Xms128m -Xmx512m"

　　can be changed.

Install
　　Note that the installation must be done with a user with privileges to write to APPSRV_HOME and subdirs.
　　1) Set the environment variable APPSRV_HOME to where your JBoss is installed, example /opt/jboss-4.2.0 or C:/jboss-4.2.0.
Also make sure the right java tools (javac/keytool) are available in your system PATH, ie. /usr/local/jdk1.5.0_11/bin.
　　2) Copy conf/ejbca.properties.sample to conf/ejbca.properties and customize if needed. The default values works fine for a test installation.
　　

• Customize the CA properties if you need to do so. For production use you need to do this, don't forget to edit passwords to be secure and secret. Keep conf/ejbca.properties as secret as possible. DO NOT forget the passwords, if you need to re-install the software sometime.
  
• To use a hard ca token from start change ca.tokentype, ca.tokenpassword and ca.tokenproperties. You also need to add the appropriate values to the ca.tokenproperties file for the HSM. Read the HSM documentation for the right values.
  
• To put the initial superadmin certificate on a smartcard, set superadmin.batch=false in web.properties. Enroll from public web after the installation is complete, as you would with any other smartcard user. Username is "superadmin" and password is superadmin.password from web.properties.
  
• Customize the database if needed but easiest thing is to keep the default as it is, it will use the JBoss embedded HSQLDB and everything will be easier for you. For production use you should use a real database instead of the embedded one.
  
• Small note, in the ca.dn you can not use DC components for the initial CA, you can create CAs using DC components later on once the admin GUI is up and running.
  

　　3) Open a console and type 'ant bootstrap' it will compile, jar, war, ear everything and deploy it to JBoss.
　　4) Open a console (terminal) and start JBoss. You can start JBoss with 'ant j2ee:run' from EJBCA_HOME or the normal command 'run.sh/cmd' from APPSRV_HOME/bin. You should see JBoss picking up everything and deploying the ear without errors.
　　5) Type 'ant install' it will generate all certificates, keys, etc needed to run with an initial CA. You will find admin keys in ${ejbca.home}/p12. (do not delete those files!)
The command 'ant install' is only run once, when the CA is first installed. It creates lots of things in the database, and can not be run again (it will give an error if you try).

• tomcat.jks is for the servlet container (don't bother with it)
  
• superadmin.p12 should be imported in your browser, that's your administration certificate.
  

　　You will need administrative privileges (e.g. root) for the CA-certificate to be installed in Javas trust-keystore ($JAVA_HOME/jre/lib/security/cacerts, default pwd 'changeit'). If you don't have root permission now, you can do it manually later after step 9. It's important so don't forget!
　　6) Stop JBoss (ctrl+c or whatever)
　　7) type 'ant deploy', this will deploy everything again and configure the servlet container with the keystore file (this is why we needed to stop the container). If you want to use jboss specific service for automatic creation of the CRL:s you should enable this option in ejbca.properties, see the chapter about 'CRL generation'.
　　8) Import the certificate from EJBCA_HOME/p12/superadmin.p12 in your web browser. This is the super administrators certificate used to access the admin GUI. Other administrators with specific privileges can be created later on. The default password for superadmin.p12 is ejbca, and is configured in ejbca.properties.
　　9) Start JBoss again and go to https://localhost:8443/ejbca/ to access the admin-GUI, or http://localhost:8080/ejbca for the public pages.
　　If you did not have root permission and get an error during installation step 5, you can install the root certificate afterwards with the following commands, WITH the right permissions:

ant javatruststore

　　For example on Ubuntu you can run:

sudo ant javatruststore

　　What this does in the background are the following commands. You do not have to run these command manually.

bin/ejbca.sh ca getrootcert AdminCA1 ca.crt -der
keytool -import -trustcacerts -alias AdminCA1 -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file ca.crt

　　where AdminCA1 is the CA name as configured in conf/ejbca.properties (default is AdminCA1). You must stop and start JBoss after doing this.
　　You can use this command to install the certificate of any CA in the java truststore by giving an argument:
ant javatruststore -Dca.name=MyCaName

Additional howtos
　　In the directory doc/howto in the distribution there are additional howtos for some specific platforms and configurations.

Running optional tests
　　If you want to run a thorough test of your new CA, run the automated tests with 'ant test:run'. To run the tests you must copy the file lib/ext/junti-1.5.8 to ANT_HOME/lib.
　　NOTE: After running tests with 'ant test:run', you might consider deleting the database since some leftovers are left in the database. The tests will create and revoke some test certificates, so afterwards your CRLs will be populated with a few entries. 'ant test:run' should not be run on a production system, only to test the installation.
　　NOTE! Don't forget to configure JBoss for security! See security. Security is CRITICAL for a CA.

After the installation

Administrative tutorials
　　There are additional documentation and administrative tutorial movies at http://docs.primekey.se/.

Administrating EJBCA
　　You can administrate EJBCA using a web browser and the admin-GUI, this is the easiest way. The admin-GUI requires SSL with authentication using client certificate, i.e. strong authentication.
　　You can also use the command line interface (cli) which is called by 'bin/ejbca.sh'. If you call ejbca.sh you get a list of available commands, and you can get help for all commands by calling them without arguments, i.e:

bin/ejbca.sh ca
bin/ejbca.sh ra adduser
etc etc

SSL certificate expire
　　The SSL certificate used for SSL in JBoss (SSL is used for the admin-GUI) is stored in APPSRV_HOME/server/default/conf/keystore.jks. The default validity time for the SSL certificate is two years. When this expire, you must generate a new one.
　　You can do this through the admin-GUI by:

• Go to 'List/Edit End Entities' and search for user 'tomcat'.
  
• 'Edit_End_Entity' and set the 'Password' to the same as httpsserver.password in your conf/ejbca.properties and 'Status' to 'New'.
  
• Open up a command line in EJBCA_HOME and run 'bin/ejbca.sh batch'.
  
• Copy EJBCA_HOME/p12/tomcat.jks to APPSRV_HOME/server/default/conf/keystore.jks, or run 'ant deploy'. Ant deploy will do some other things as well, so if you are not sure, just copy the file.
  
• Restart JBoss.
  

　　You can also do everything using the CLI:

• bin/ejbca.sh ra setuserstatus tomcat 10
  
• bin/ejbca.sh ra setclearpwd tomcat <password from httpsserver.password>
  
• bin/ejbca.sh batch
  
• cp p12/tomcat.jks $APPSRV_HOME/server/default/conf/keystore.jks
  
• Restart JBoss.
  

Creating more CAs
　　After installation, that creates a default admin CA you can create more CAs using the admin GUI.
　　Your CAs can be either root CAs, subordinate CAs to another CA in EJBCA or subordinate CAs to an external CA. The initial admin CA is a RootCA.
　　You can also use the command line interface (cli) 'bin/ejbca.sh ca init' to create new CAs, although a better idea is to do it from the Admin GUI. Ex: 'bin/ejbca.sh ca init TestRoot &quot;C=SE,O=PrimeKey,CN=EJBCA&quot; 2048 365 2.5.29.32.0' will create a root CA with the DN 'C=SE,O=PrimeKey,CN=EJBCA'. The keylength is 2048 bit (RSA) and the validity of the root certificate is 365 days. Quote the DN so it is treated as one argument.
　　PKIX requires that a CRL always is available even if it is empty. When creating a new CA the CA certificate is stored and published (if any Publishers are configured), and the initial CRL is created and stored/published.
　　Subordinate CAs are created using the admin GUI, you can not use the cli for that.

Creating a SubCA signed by en external CA
　　When creating a CA that is signed by an external CA, you actually create a PKCS10 certificate request that is sent to the external CA. When the external CA returns your CAs certificate, this is processed and the CA becomes activated.
When creating the certificate request you give the certificate chain of the CA that will sign your CA. This is given in PEM format, and EJBCA can be a bit picky about the format. It should be in plain PEM format without blank lines before or after like:

-----BEGIN CERTIFICATE-----
MIICIDCCAYmgAwIBAgIIVP8CMpl0En0wDQYJKoZIhvcNAQEFBQAwIDEOMAwGA1UE
AxMFUVhMVkExDjAMBgNVBAoTBVFYTFZBMB4XDTA1MTAxOTA4MjYxMloXDTA2MTAx
OTA4MzYxMlowIDEOMAwGA1UEAxMFUVhMVkExDjAMBgNVBAoTBVFYTFZBMIGfMA0G
CSqGSIb3DQEBAQUAA4GNADCBiQKBgQCRJvog0sJIzWr2VvpI86dzGBaLazqp+dY7
E/IleqQPRNMQIe8OjCuADNFiSfaiCC6MH4dTm6LwaxmX36eLHSU9/jH5/QZllolC
7sttv/ay8cAtIKYCjcsjyNmFzU7BcxxhiY0CWWlemz3eXMkQLZbgR5lR8ce5m0Jg
OZeLAoOfxwIDAQABo2MwYTAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIB
JjAdBgNVHQ4EFgQUrpCjRSqqOYm5qOyRKHpZin+0EWkwHwYDVR0jBBgwFoAUrpCj
RSqqOYm5qOyRKHpZin+0EWkwDQYJKoZIhvcNAQEFBQADgYEABJK+RVZiOJdB2uqs
LHprk3VPMtUck4exh+/52WnzNaUIpALDFaKB5XKSk0OGQE3S0ltMlsdCJIU1iNff
QcVC7vrCjlnv9sUa22YIzK4ZBuY8a0cRC/GhfpoX9o+vp1wNWVtTwOLAuNRuZJxw
U03ZXi1b1HuLtSXrFb6d/3BQq8Y=
-----END CERTIFICATE-----

　　To process an external request in EJBCA, type the name of new CA in the 'Add' field in 'Edit Certificate Authorities' and press 'Process Certificate Request'. The argument is the certificate request exactly as created by the subCA, no blank lines etc.
　　When you have received the signed certificate back from the external CA, edit the CA that created the request and press 'Receive Certificate Response'. The PEM file must have no blank lines etc.

Converting an OpenSSL CA
　　You can convert a PEM-style Root CA key to a PKCS12 file that can be imported in EJBCA.

openssl pkcs12 -export -out server1.p12 -inkey cakey.pem -in ca.pem -name privateKey

　　You can import the CA with the cli command 'bin/ejbca.sh ca importca'.

Using EJBCA

Creating Users
　　Users are added in the admin-GUI, 'Add End Entity' or with the cli 'bin/ejbca.sh ra adduser'. The users DN is normally entered in the cli as &quot;C=SE,O=MyOrg,OU=MyOrgUnit,CN=MyName&quot;. If a ',' is needed in the DN the comma must be escaped using '/,'.

Create User certificates
　　To enroll for a certificate using a browser, go to http://your_server_name:servlet_container_port/ejbca/ (e.g. http://127.0.0.1:8080/ejbca/) and select &quot;Create Browser Certificate&quot;. Enter username and password, click the &quot;OK&quot;-button and follow the instructions.
　　To enroll for certificates manually (e.g. for server certificates), go to http://your_server_name:servlet_container_port/ejbca/, select &quot;Create Server Certificate&quot; and fill out the form.
　　Note that application for certificates only work when the status of a user is NEW, FAILED or INPROCESS (one time password thing). The status is set to GENERATED after a certificate has been issued. To issue a new certificate, the status must be reset to NEW, which can be done through the admin-GUI or the cli.
　　During batch generation of certificates, users with status NEW or FAILED are generated. This is due to the possibility that a batch generation for some reason failed. If it fails status is set to FAILED and you can try again after fixing the error.

Create server certificates
　　The best way to create server certificates is to generate a PKCS12, JKS or PEM file for the server, depending on what server it is. To do this:

• Create desired profiles (the default entity and certificate profiles work fine, but are perhaps too generic). You certificate profile should have:
  - KeyUsage: Digital signature, Key encipherment
  - Extended key usage: Server Authentication
  
• Create a user with the admin-GUI or 'bin/ejbca.sh ra'.
  The Distinguished name (DN) of the server should have the the servers full hostname (host.domain.com) in the CommonName (CN) field.
  Example DN for webserver: &quot;C=SE,O=AnaTom,CN= www.anatom.se&quot;, or for mailserver &quot;C=SE,O=AnaTom,OU=Engineering,CN=mail.anatom.se&quot;.
  You can also put the same name (or several names) as a DNSName in SubjectAlternativeNames.
  For so-called wildcard certificates, use *.anatom.se.
  Set the token type to match the kind of token that should be generated for your server.
  
• To be able to batch-generate certificates, the batch generation program must have access to the users (servers) password in order to request a certificate on behalf of the user. Normally the password is stored in hashed form, so the password must be stored in clear text form by running 'bin/ejbca.sh ra setclearpwd username password'
  
• Generate private keys and certificates by running 'bin/ejbca.sh batch'
  

　　Many servers (ex Apache, Tomcat) wants keys and certificates in PEM-format (Apache) or SUN JKS (Tomcat). To generate PEM-files use token type PEM. The PEM-files will be stored in a separate subdirectory, 'pem'. The generated PEM-files can be used with Apache etc, and are NOT protected by any password. To generate JKS-files use token type JKS. The JKS-files will be stored in the subdirectory, 'p12' instead of PKCS12-files. The generated JKS- files can be used with Tomcat etc, and are protected (both private key password and keystore password) by the users password.
　　If the server generates the keys and a certificate request (CSR) for you, select token type &quot;User generated&quot;. You can use the public enrollment web pages (http://127.0.0.1:8080/ejbca/) to paste the request and receive the certificate. This function is under &quot;Certificate Enrollment->manually for a server&quot;.
　　It is also possible to use openssl to transform a PKCS12 file to PEM- format.

openssl pkcs12 -in pkcs12-file -nodes

　　copy and paste the private key to key file, the first certificate to server cert file and last certificate to CA cert file (If your CA is a subordinate CA to another Root CA, the CA cert file may need to contain the whole cert chain). Exactly how your server wants the files is server dependent.
　　For your convenience, here is the standard text (RFC2818) how browsers validate the name(s) in the certificate.

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


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/cmd createcrl caname'.
　　Note on CRL Distribution Points (CDPs): it is possible to configure multiple URLs for CDPs if they are separated by ';'. For example:
http://cdpurl-1/mycrl.der;http://cdpurl-2/crl.crl
　　The same applies to CRLIssuer, for example:
CN=Foo,C=SE;CN=Bar,C=US
　　Note that you are responsible for the order and encoding of your CRLIssuer, if this is important check it!
　　A CRLDistributionPoint for a CA in EJBCA could look like:

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

　　It should also be possible to use an LDAP distribution point, if you have configued a publisher to publish CRLs to LDAP.

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

　　(such as the link from the web distribution pages)
　　When defining CRL distribution point and CRL issuer in a certificate profile, you can choose to set the values in either the certificate profile, or in the CA configuration (edit CAs). By having the setting in the CA configuration it is possible to use the same certificate profile for several CAs, otherwise you would have to create a new certificate profile for all CRL distribution points.
　　There are three settings in CA configuration dictating the times when CRL generation is done:

• CRL Expire Period (Hours): Mandatory. The validity period for generated CRLs. If set to for example 24, the nextUpdate for a generated CRL will be the issue time + 24 hours.
  
• CRL Issue Interval (Hours): Optional. A fixed interval when CRLs will be issued. If set to for example 1 hour a new CRL will be issued every hour, even though the old one is still valid for another 23 hours. The default value here is 0, which means that a new CRL will be issued when the old one is about to expire (see also overlap time). Keeping the default value 0 has the same as effect as setting this value to the same value as CRL Expire Period.
  
• CRL Overlap Time (Minutes): Optional. When checking if a CRL should be generated (if the old one is about to expire), the new CRL is generated this amount of minutes before the old CRL expires. The default value is 10 minutes, meaning that if CRL Expire period is 24 hours, a new CRL will be issued after 23h50m. This ensures that there is no time period (even a few seconds) when there is no valid CRL issued. It also gives clients a time-slot to download a new CRL before the old one expires.
  

　　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 new service. 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.

JBoss service
　　Another way to have CRLs generated automatically is to build and deploy the JBOSS CRL Service. This is done by setting the option 'createcrl.service.enabled' to true in ejbca.properties. After settin the option you must re-deploy EJBCA and re-start JBoss.
　　This service will by default check if CRL generation is needed every minute. If this default behaviour can be changed by editing the attribute 'Polltime' in src/appserver/jboss/crlcreate-service.xml. A new CRL is created if the old one expires within the polltime + 10 minutes, so a CRL is always created at least 10 minutes before the old one expires. In this way we will in the worst case get the overlap time (10 min) as the time when applications can fetch the new CRL before the old one expires. The attribute can have the following values:

DAILY   =  Every midnight
HOURLY  =  At XX:00 every hour.
30MIN   =  At XX:30 and XX:00 every hour
15MIN   =  At XX:15, XX:30, XX:45,XX:00, every hour
1MIN    =  Every minute

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' command will 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/java/jdk1.4.2_01/bin
@daily cd /home/ejbca;/home/ejbca/ca.sh 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' located.
　　Sample crontab to be installed with 'crontab -e':

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
CLASSPATH=$CLASSPATH:/root/ejbca:/root/ejbca/admin.jar
APPSRV_HOME=/usr/local/jboss
# m h dom mon dow command
00 0    * * *   cd /root/ejbca;./ca.sh createcrl


Scep
　　Since SCEP uses encryption, you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK. The policy files can be found at the 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 or not. The CA certificate is optional but some, Cisco VPN client, seems to require it while others, Juniper, seems to dislike it. Therefore EJBCA has two SCEP URLs.
　　The default including the CA certificate (use if nothing else specified):

http://localhost:8080/ejbca/publicweb/apply/scep/pkiclient.exe

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

http://localhost:8080/ejbca/publicweb/apply/scep/noca/pkiclient.exe

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

• PKCSReq
  
• GetCRL
  
• GetCACert
  
• GetCACertChain
  
• GetCACaps
  

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

• GetCertInitial
  

The following CA capabilities are supported:

• POSTPKIOperation
  
• SHA-1
  

*** CA mode ***
　　EJBCA does successfully receive SCEP 'PKCSReq' requests and send back the certifificate/CRL immediately in a proper SCEP reply message. EJBCA (standard) does not support the 'polling' model, EJBCA uses the direct CA method, where a request is granted 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' when authenticating the request in EJBCA. Create the Scep request with a CN mathing the username registered in EJBCA. The challengePassword in the PKCS#10 request, which is part of the Scep request, will be used as the 'password' when authenticating the request in EJBCA. Create the Scep request with a challengePassword mathing the password registered in EJBCA.
　　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, from ExtRA version 3.4.2. Using this a SCEP client can send a request to the External RA, and then wait, polling the RA for updates. When the request is processed by the CA, which fetches the pkcs10 request from the External RA, the certificate is sent back to the External RA. When the certificate is complete on the External RA, the RA sends back the SCEP certificate response the next time the SCEP client polls the RA.
This feature is very useful to securely insulate the CA from the SCEP clients throughout the network.
See the documentation in the ExtRA API for more information how to set up and configure this RA.
　　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 that causes 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 test.pemreq -c ejbca-ca.pem -q foo123 -u http://localhost:8080/ejbca/publicweb/apply/scep

　　Where test.key is generated with:

openssl genrsa -out test.key

　　test.req is generated with:

openssl req -key test.key -new -days 30 -out test.req -outform DER -config ../openssl/openscep.cnf

　　and test.pemreq is generated with:

openssl req -key test.key -new -days 30 -out test.pemreq -outform PEM -config ../openssl/openscep.cnf

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

*** 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. To create a new certificate request:

• New - enter the DN that your box will receive:
  
  
  
  • Name=netscreen.foo.se
    
  • Organization=PrimeKey
    
  • Country=SE
    
  • IP Address=192.168.1.1
    
  • FQSN=netscreen.foo.se
    
  
  Click generate.
  
• 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 http://<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.
  
• You can now see the request in Objects->Certificates. If you are using polling RA mode, you can click 'Retrieve' after the request has been approved in the CA and the certificate has been generated.
  

*** 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. This is reasonable, since SCEP requires the CA to actually encrypt data (which generally is a bad thing, since a special encryption certificate 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.
　　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 EJBCA
  
• In the DN screen simply enter the username (as added in EJBCA) as 'Name [CN]'
  

*** 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 RA module (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 for CAs. Create a new certificate profile before creating the Scep CA, you can use ROOTCA as template for the new certificate profile.
  
• When enrolling for certificate using SCEP with for example a Cisco PIX it is a 'ca_nickname'. This nickname should be the CA-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 when enrolling.
  
• 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 &quot;CN=pix.primekey.se, unstructuredName=pix.primekey.se&quot;. You can also include O, C etc in the certificate. A normal DN for a PIX is &quot;CN=pix.primekey.se,unstructuredName=pix.primekey.se,O=PrimeKey,C=SE&quot;.
  
• Certificates used for PIX MUST include the DN component unstructuredName (fqdn) and could also include unstructuredAddress (ip) being the IP-address of the PIX.
  
• The certificate used on the Cisco PIX MUST have a SubjectAltName field dNSName, matching the DN component unstructuredName. This is needed in order for Cisco VPN clients to connect to the PIX. The DNS Name field is not necessary 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 have specified, otherwise the connection will fail.
  
• Cisco PIX needs the SCEP response messages to use MD5 as hash algorithm, not SHA1, this is handled by EJBCA automatically.
  

　　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 or allow 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 with pix and enter admin mode
telnet 10.1.1.1 (default pwd cisco)
enable (default blank pwd)
configure terminal
-- Enable CA logging
debug crypto ca
-- Clear current PKI config
clear ca identity
-- Enter PKI config, i.e location of CA etc. Don't require CRLs, it's easier
ca identity pixca ca-ip:/ejbca/publicweb/apply/scep/pkiclient.exe
ca configure pixca ca 1 0 crloptional
ca authenticate pixca
-- wait --
-- Look at the fetched certificate
show ca certificate
ca save all
wr mem
-- Get a CRL if you really want to (if you did not configure CRL as optional you must)
ca crl request pixca
-- wait --
show ca crl
-- Generate keys and enroll for the certificate (user in ejbca has password foo123)
ca generate rsa key 1024
ca enroll pixca foo123
-- wait, wait, this will take a long time --
-- Look at the fetched certificate, this should now show both the pix cert and the ca cert
show ca certificate
pix(config)# show ca cert
Certificate
Status: Available
Certificate Serial Number: 594f643a6916d78d
Key Usage: General Purpose
Subject Name:
C = SE
O = PrimeKey
CN = pix.primekey.se
UNSTRUCTURED NAME = pix.primekey.se
UNSTRUCTURED IP = 10.1.1.1
Validity Date:
start date: 14:42:29 GMT Sep 17 2005
end   date: 14:52:29 GMT Sep 17 2007
CA Certificate
Status: Available
Certificate Serial Number: 7c7cf75236955a51
Key Usage: General Purpose
C = SE
O = PrimeKey
CN = pixca
Validity Date:
start date: 15:59:20 GMT Sep 16 2005
end   date: 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).　　From EJBCA 3.5, CMP support in RA mode (see below) can support several CAs and profiles based on the keyId of the password used to 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 documented there.

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 far JBoss 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 the default port, since it is a low port (<1024). See the documentation in conf/cmp.properties for information about configuration options 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 a zillion 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 from the 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 from the 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 any verification 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 (the standard 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 User authentication 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 is pre-registered in EJBCA. When EJBCA receives the request, the message will be authenticated using PasswordBasedMAc, as defined in the CMP spec, using a pre-shared password. When the message has been authenticated, a user is created in EJBCA and 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 the RA).
  
• 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 new values 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 the options 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 the resulting username will be: cmp<UsersUID>. End entity profiles names CMP_ENTITY and CMP_CERT is created in EJBCA allowing the request DN.

cmp.operationmode=ra
cmp.allowraverifypopo=true
cmp.responseprotection=pbe
cmp.ra.authenticationsecret=password
cmp.ra.namegenerationscheme=DN
cmp.ra.namegenerationparameters=UID
cmp.ra.namegenerationprefix=cmp
#cmp.ra.namegenerationpostfix=
cmp.ra.endentityprofile=CMP_ENTITY
cmp.ra.certificateprofile=CMP_CERT
cmp.ra.caname=AdminCA1


Certificate validity
　　Normally the validity period of issued certificates are controlled by the certificate profile. If you enable 'Allow validity override' in the certificate profile, and the CMP initialization- or certificattion 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 Usage Override' in the certificate profile, and the CMP initialization- or certificattion request contains a key usage in the CRMF request template, this key usage will be used.

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

• cmp.operationmode=ra
  
• cmp.allowraverifypopo=true
  
• cmp.responseprotection=pbe
  
• cmp.ra.authenticationsecret=your shared password
  
• and 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 an RA with the same configuration options as for jCert.

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 a specific certificate to an OCSP responder. The responder may or may not be the same as the CA. The OCSP responder sends a signed reply, containing the requested status information back to the client. The client uses this status information to determine whether the certificate 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 for certificates 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 responder certificate.
　　For a CA to be valid as an OCSP-responder it must have the KeyUsage 'Digital Signature' in the certificate profile used to create the CA. This KeyUsage must be included if the CA is to sign OCSP-responses. The default certificate profiles for CAs includes the key usage '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 CAs OCSP responder. If set to false, the CAs special OCSP responder certificate is used to sign the OCSP responses. The OCSP responder 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 the request. This is used to generate 'unknown' responses when a request is received for a certificate that is not signed by any CA on 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 -issuer Test-CA.pem -CAfile Test-CA.pem -cert Test.pem -req_text -url http://localhost:8080/ejbca/publicweb/status/ocsp

　　If Mozilla 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).
  
• If using a Certificate Profile that includes a OCSP Service URL for client certificates, the Validation option in Mozilla 'Use OCSP to validate only certificates that specify an OCSP service URL' also works fine. When this option is checked you may need to restart Mozilla.
  

　　When the validation settings are set, Mozilla will query the OCSP server when for example double-clicking on a certificate in the certificate 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 Mozilla 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 to answer 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 need high-performance for the OCSP responders. This should be a usual setup, if the CA only issues certificates once every year for one million users, this does not put much pressure on the CA, but the OCSP responders can be put under high load continuously.
　　See the document doc/howto/HOWTO-OCSP-RESPONDER.txt for information how to set up stand-alone, separated OCSP responders.
See the image HOWTO-OCSP-RESPONDER.jpg for an overview of a sample setup.

Simple OCSP client
　　You can build a simple OCSP client with 'ant ocspclient.jar'. This will place ocspclient.zip in the directory EJBCA_HOME/ocsp-dist. You can unzip this file and use the 'ocsp.sh' shell script on Linux/Unix. You can also use the API directly from your java program.
　　See the document doc/howto/HOWTO-OCSP-Unid-client.txt for information how to use the simple OCSP client.

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 that in the menu Document->Trusted Identities. Choose Certificates in the drop-down list and click 'Add contacts', now you can browse to the CA-certificate that you have downloaded in DER format (for example by choosing download to IE on the public EJBCA pages). 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 internal and external OCSP responders.
　　Certificates that have an 'OCSP service locator' will be verified against the OCSP responder. You can configure this in the certificate 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 HTTPS.
　　The JAX-WS interface depends on java 1.5 or later and will otherwise not be included in the EJBCA installation.
　　The functionality currently available through the Web Service Interface are:

• editUser : Edits/adds userdata
  
• findUser : Retrieves the userdata for a given user
  
• findCerts : Retrieves the certificates generated for a user
  
• pkcs10Req : Deprecated method previously used to generate a certificate using the given userdata and the public key from the PKCS10
  
• pkcs10Request : Newer method that generates a certificate or PKCS7 using the given userdata and the public key from the PKCS10
  
• pkcs12Req : Generates a PKCS12 keystore (with the private key) using the given userdata
  
• revokeCert : Revokes the given certificate
  
• revokeUser : Revokes all certificates for a given user, it's also possible to delete the user
  
• revokeToken : Revokes all certificates placed on a given hard token
  
• checkRevokationStatus : Checks the revokation status of a certificate
  
• isAuthorized : Checks if an admin is authorized to an resource
  
• fetchUserData : Method used to fetch userdata from an existing UserDataSource
  
• genTokenCertificates : Method used to add information about a generated hardtoken
  
• existsHardToken : Looks up if a serial number already have been generated
  
• getHardTokenData : Method fetching information about a hard token given it's hard token serial number.
  
• getHardTokenDatas: Method fetching all hard token informations for a given user.
  
• republishCertificate : Method performing a republication of a selected certificate
  
• isApproved : Looks up if a requested action have been approved by an authorized administrator or not
  
• customLog : Logs a CUSTOM_LOG event to the logging system
  
• deleteUserDataFromSource : Method used to remove user data from a user data source
  
• getCertificate : Returns a certificate given its issuer and serial number
  

　　There is also a cli tool that can be used for remote scripting. See following section for more information. Note: All these call isn't available through the CLI.

Configuring Web Services CLI
　　There exists one propertyfile in conf/jaxws.properties.sample that is used to configure the behaviour of the WS service. To configure it copy it and name it jaxws.properties.
　　See the sample file for details of how to configure the Web Service interface.

Using the Web Services CLI
　　When building EJBCA, a Web Service CLI tool is also generated. The tool is placed in the directory dist/ejbcacli and consists of the all 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. Then create a JKS file with the appropriate access rights (See the Using API section for details) and finally configure the file ejbcawsracli.properties. In this file you should specify the hostname of the CA server, the name of the JKS keystore and the password to unlock it.
　　Use 'ejbcaraws.sh/cmd' for a list of each subcommand and 'ejbcaraws.sh/cmd &quot;subcommand&quot;' for detailed help how to use the cli.
　　Example usage: ejbcawsracli.cmd pkcs12req testuser2 foo123 2048 NONE tmp
　　ejbcawsracli.cmd revokeuser testuser2 false

Using the Web Service API for Intergration
　　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.installBCProvider();
String urlstr = &quot;https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl&quot;;
System.setProperty(&quot;javax.net.ssl.trustStore&quot;,&quot;p12/wstest.jks&quot;);
System.setProperty(&quot;javax.net.ssl.trustStorePassword&quot;,&quot;foo123&quot;);  
System.setProperty(&quot;javax.net.ssl.keyStore&quot;,&quot;p12/wstest.jks&quot;);
System.setProperty(&quot;javax.net.ssl.keyStorePassword&quot;,&quot;foo123&quot;);      
QName qname = new QName(&quot;http://ws.protocol.core.ejbca.org/&quot;, &quot;EjbcaWSService&quot;);
EjbcaWSService service = new EjbcaWSService(new URL(urlstr),qname);
ejbcaraws = service.getEjbcaWSPort();  

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

  UserMatch usermatch = new UserMatch();
usermatch.setMatchwith(org.ejbca.util.query.UserMatch.MATCH_WITH_DN);
usermatch.setMatchtype(org.ejbca.util.query.UserMatch.MATCH_TYPE_CONTAINS);
usermatch.setMatchvalue(&quot;Vendil&quot;);
List(UserDataVOWS) result= ejbcaraws.findUser(usermatch);

　　Example to generate a certificate form a PKCS10 request:

  UserDataVOWS user1 = new UserDataVOWS();
user1.setUsername(&quot;WSTESTUSER1&quot;);
user1.setPassword(&quot;foo123&quot;);
user1.setClearPwd(true);
user1.setSubjectDN(&quot;CN=WSTESTUSER1&quot;);
user1.setCaName(&quot;AdminCA1&quot;);
user1.setEmail(null);
user1.setSubjectAltName(null);
user1.setStatus(10);
user1.setTokenType(&quot;USERGENERATED&quot;);
user1.setEndEntityProfileName(&quot;EMPTY&quot;);
user1.setCertificateProfileName(&quot;ENDUSER&quot;);
ejbcaraws.editUser(user1);
KeyPair keys = KeyTools.genKeys(1024);
PKCS10CertificationRequest  pkcs10 = new PKCS10CertificationRequest(&quot;SHA1WithRSA&quot;,
CertTools.stringToBcX509Name(&quot;CN=NOUSED&quot;), keys.getPublic(), null, keys.getPrivate());
CertificateResponse certenv =  ejbcaraws.pkcs10Request(&quot;WSTESTUSER1&quot;,&quot;foo123&quot;,new String(Base64.encode(pkcs10.getEncoded())),null,CertificateHelper.RESPONSETYPE_CERTIFICATE);
X509Certificate cert = (X509Certificate) CertificateHelper.getCertificate(certenv.getData());

　　Example checking the revocation status of a certificate:

  RevokeStatus revokestatus = ejbcaraws.checkRevokationStatus(cert.getIssuerDN.toString,cert.getSerialNumber().toString(16));
if(revokestatus != null){
if(revokestatus.getReason() != RevokeCertInfo.NOT_REVOKED)){
// Certificate is revoked
}else{
// Certificate isn't revoked
}
}else{
// Certificate doesn't exist
}  

　　See the file src/java/org/ejbca/core/protocol/ws/common/IEjbcaWS for more detailed instructions of the API. And src/test/java/org/ejbca/core/protocol/ws/TestEjbcaWS for more examples on using the API.

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 with the administrator flag set and access rules according to the following:
　　Common for all calls (except isAuthorized, existsHardToken, isApproved that only needs a valid trusted certificate):

• Administrator flag set
  
• /administrator
  
• /ca/'related CA'
  

　　editUser:

• /ra_functionality/create_end_entity and/or edit_end_entity
  
• /ra_functionality/'end entity profile of user'/create_end_entity and/or edit_end_entity
  

　　findUser, findCert:

• /ra_functionality/view_end_entity
  
• /ra_functionality/'end entity profile of the user'/view_end_entity
  

　　pkcs10req, pkcs10Request, pkcs12req:

• /ra_functionality/view_end_entity
  
• /ra_functionality/'end entity profile of the user'/view_end_entity
  
• /ca_functionality/create_certificate
  

　　revokeCert, revokeToken: These calls support approvals.

• /ra_functionality/revoke_end_entity
  
• /ra_functionality/'end entity profile of the user owning the cert'/revoke_end_entity
  

　　revokeUser: This call support approvals.

• /ra_functionality/revoke_end_entity
  
• /ra_functionality/'end entity profile of the user'/revoke_end_entity
  
• /ra_functionality/delete_end_entity (only if users should be deleted)
  
• /ra_functionality/'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 in the jaxws.properties file.

• /ra_functionality/create_end_entity and/or edit_end_entity
  
• /endentityprofilesrules/'end entity profile of user'/create_end_entity and/or edit_end_entity
  
• /ra_functionality/revoke_end_entity (if overwrite flag is set)
  
• /endentityprofilesrules/'end entity profile of user'/revoke_end_entity (if 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 in the jaxws.properties file.

• /ra_functionality/view_hardtoken
  
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken
  
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)
  

　　getHardTokenDatas:

• /ra_functionality/view_hardtoken
  
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken
  
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)
  

　　republishCertificate:

• /ra_functionality/view_end_entity
  
• /endentityprofilesrules/'end entity profile of the user'/view_end_entity
  
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)
  

　　customLog: No CA access rule is required.

• /log_functionality/log_custom_events
  

　　deleteUserDataFromSource:

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

　　getCertificate: no requirement of the '/administrator' flag

• /ca_functionality/view_certificate
  

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 included (but can be disabled) in the standard installation. And have the Web Service URL http://&quot;hostname&quot;:8080/ejbca/xkms/xkms

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: true)
  
• 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 (default: 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 be specified. (default 'AdminCA1')
  
• xkms.keyusage.signatureisnonrep: Setting specifying the keyusage in a X509 certificate that is mapped to XKMS KeyUsage Signature, Default is non-repudiation but if set to false will XKMS KeyUsage Signature be mapped against digital signature X509 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 is only 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 the user. The password of the user Must be marked as cleartext in order for KRSS to work. In KeyInfo is one RSAKeyInfo required if the user have the type 'USERGENERATED'. All other UseKeyWith or KeyUsage is ignored. since it is the register userdata that is used when issuing the certificate. If the user have the type &quot;P12&quot; in it's userdata then will a server generated key be inserted in a PrivateKey in the response. It is the same password to encrypt the key as for the enrollment. RespondWith RSAPublicKey, 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 for the new certificate. Revoked certificates cannot be renewed. The generated key will be inserted in a PrivateKey in the response. It is the same password to encrypt the key as for the enrollment. RespondWith RSAPublicKey, X509Certificate and X509CertificateChain.
　　The recover listener expects one X509Certificate KeyInfo in the request and is used to select the user in the database. Before a 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 be revoked. A revokation code is required, authentication tag is not supported. RespondWith RSAPublicKey, X509Certificate and X509CertificateChain is supported.

*** XKMS Mappings ***
　　The RespondWith tag supports X509Certificate, X509CertificateChain, X509CRL, KeyName, KeyValue (and PrivateKey for register and recover).
　　The QueryKeyBinding The query of a QueryKeyBinding is performed in the following way: If KeyInfo is included, the certificate is extracted and the is used for checking the key usage and validity of the certificate If UseKeyWith is included (and no KeyInfo) 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 configuration
  
• ENCRYPTION: data encipherment
  
• EXHANGE: digital signature and key encipherment
  

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

• XKMS: Subject Altname, UNIFORMRESOURCEIDENTIFIER
  
• XKMS/profile: Subject Altname, UNIFORMRESOURCEIDENTIFIER
  
• S/MIME: Subject Altname, RFC822 addr-spec
  
• PGP: Subject Altname, RFC822 addr-spec
  
• TLS: Subject Altname, UNIFORMRESOURCEIDENTIFIER
  
• TLS/HTTPS: SubjectDN, Common Name
  
• TLS/SMTP:Subject Altname, DNS Name
  
• IPSEC:Subject Altname, IP Address
  
• PKIX: Entire SubjectDN
  

Using the XKMS client
　　When building EJBCA, a XKMS CLI tool is also generated. The tool is placed in the directory dist/xkmscli and consists of the all 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 you should 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 &quot;subcommand&quot;' 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 report will be generated in tmp/bin/junit/xkms/reports/html/index.html

External RA API
　　In some cases, for security reasons, is it preferable to deny all inbound traffic to the CA and instead let the CA periodically fetch and process information from external trusted data sources.
　　The ExtRA API contains the most basic functions like:

• Generate Certificate from PKCS10
  
• Generate PKCS12 for the end user
  
• KeyRecovery of the users key (if requested using PKCS12)
  
• Edit users
  
• Revoke Certificates
  

　　The external API, named extra, is downloaded separately, or checked out separately from the CVS using the module name 'extra'.
　　Documentation about the ExtRA API is in the doc subdirectory of the extra subproject.

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'.
  
• Create a new End Entity Profile and set to use 'Key Recoverable'.
  
• Add users with this End Entity Profile.
  

　　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 key pair:
　　# First revoke username, with revocation reason reason,

bin/ejbca.sh ra revokeuser $username $reason

　　# then mark the certificate for keyrecovery,

bin/ejbca.sh ra keyrecovernewest $username

　　# then set clear text password for Batch session to use

bin/ejbca.sh ra setclearpwd $username $userpass

　　# and finally reissue the certificate.

bin/ejbca.sh batch

Email notifications
　　Mail settings in JBoss is created when running the 'ant deploy' using the values specified in conf/ejbca.properties (or default).
It is configured in $APPSRV_HOME/server/default/deploy/ejbca-mail-service.xml. For other containers you must create a mail service with the same JNDI name as specified in conf/ejbca.properties.
　　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 &quot;Edit End Entity Profiles&quot; and add a new profile. Select the profile and go into 'Edit End Entity profile'. In this page you can Enable Send Notifications and create the notification message. Make sure the checkbox 'Use Send Notification' is checked.
  
• Add a new end entity. You must select the new end entity profile you created above. Make sure the checkbox 'Send Notification' is checked. Enter the from-address and subject. Enter a message using the variables defined for dynamic substitution in the next section. Use ${NL} for newline in the mail message.
  

　　Tip: If you configure autogenerated password in end entity profile you don't need to enter one in the adduser page. A generated one will automatically be sent with the email.
　　If you want to re-send a notification for a user, reset the status to NEW. If the status is already NEW, set the status to GENERATED and then back 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 input data.
　　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
  

　　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.
  
• ${approvalReqiest.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
  
• ${approvalAdmin.USERNAME} = The requesting administrator's username
  
• ${approvalAdmin.CN} = The common name of the requesting administrator.
  
• ${approvalAdmin.SN} = The common name of the requesting administrator.
  
• ${approvalAdmin.O} = The requesting administrator's organization
  
• ${approvalAdmin.OU} = The requesting administrator's organization unit
  
• ${approvalAdmin.C} = The requesting administrator's country
  

　　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
  

The variables ${CN}, ${SN}, ${O}, ${OU}, ${C} are also available.
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 is practically 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://docs.primekey.se/documentation/en/appendixes/hardtokenprofiles.html
　　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 Entity
  
• Edit End Entity
  
• Change User Status
  
• Revoke End Entity
  
• Revoke Token (approval for each certificate)
  
• Revoke Certificate
  
• Reactivate 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 data and finally gives his approval or reject the action.
　　Configuring Approvals
　　Approvals are configured for each CA, in the 'edit CA' page. Just select the actions that needs approval and the number of approvers required and save. The actions 'Add End Entity', 'Change End Entity' and 'Change User Status' are all covered by the setting 'Add/Edit End Entity'. 'Revoke End Entity', 'Revoke Certificate', 'Revoke Token' and 'Reactivate Certificate' are covered by setting 'Revocation'.
　　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 CA configuration (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 editing and creation (not implemented yet). An administrator must have either this rule or the '/rafunctionalty/approve_end_entity' in order 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 entity profile 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, and that 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 is approved when the last administrator gives his consent and is valid for a defined period of time (in conf/ejbca.properties). In this case is 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 time specified 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 by approval.defaultapprovalvalidity in conf/ejbca.properties. After this it is set to Expired. Used by action requests that are not executable.
  
• Rejected: Means that the action request is rejected and won't be allowed. The rejection lasts the amount of time specified by approval.defaultapprovalvalidity in conf/ejbca.properties. After this it is set to Expired and a new request can be done. Used by action 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 make a 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 his request 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 by action 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 the requesting 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 also required to set the email-address to the approving administrators. This should be a mail-alias to all administrators that should be able to 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 his user data) and to the approval administrators.
　　When the approving administrators have recieved the mail, there is a link directly to the approve request page where he can review the 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 this manual 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 should be fixed. Important, there is not connection between the user data source, isModifyable data and the end entity profile isModifyable data. The userdata source is only an instruction to the RA gui then when the userdata is added will it be matched against the end entity 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 as disabled.
　　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 an simple example implementation.
  
• Create a jar file containing the class and deploy it to the application server.
  
• Make the user data source available to EJBCA by adding a userdata source, choose 'Custom user data source' as type and enter it's classpath and properties (using the same semantics as a regular java property file).
  
• 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.
  

Framework for Reports
　　From EJBCA 3.5, there is a framework for reports using 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 is under src/adminweb/WEB-INF/reports/reports.jrxml. There are a few pre-defined reports, and suggestions for more real-usage reports are welcome.
　　To create a new report:

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

Monitoring Services Framework
　　New to EJBCA 3.4 is a framework for monitoring services, i.e. procedures that should be run on a timely basis. Currently there exists two 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 end user and/or the administrator.
  

It is also possible to 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 service should run and an action (optional) of what should be done if a certain condition occurs.

Currently Available Services

*** Workers ***
　　CRL Update Worker
　　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 interval and no action.
　　Certificate Expiration Check Worker
　　A worker that checks if a CA have certificates about to expire and sends an email notification the the end user and/or administrator. 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 validity before 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 the end user must have an email set in the user database (not necessarily in the certificate) in order for the service to send the notification.
  
• 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 'Email Notifications' 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 'Email Notifications' section.
  

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

*** Actions ***
　　Mail Action
　　Action that's sends an email notification 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.
  

Writing Customized Services
　　It is possible to write customized component plug-ins that can be used with other standard (or customized plug-ins) and this section 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 to create a jar containing the necessary plug-in classes and deploy it to application server so it is included in the class-path. The next step is to create a service using the custom component by specifying the class path and optionally the custom properties used by the 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 the BaseWorker class. Then you have to implement one method 'void work()' doing the actual work every time the service framework 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 must implement 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 the BaseInterval class. You then have to implement one method 'public long getTimeToExecution();' which should return the time in 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 inherit the BaseAction class. Then should only one method be implemented 'performAction(ActionInfo actionInfo)' that should perform the action 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.


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 and independent 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 is specified. All implemented HSM modules are using the same property keywords to define the identity and the purpose of the keys to be 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 be used for all purposes.
  
• pin - optional pin code used for auto-activation of CA token, see below. Not recommended for high security set-ups, but very useful 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's recommended that the certificate and CRL signing keys are linked to the same key since different keys are rarely supported by verifying applications.
　　When implementing support for a new HSM the 'KeyStrings' class could be used to manage the key properties described above. When it is an JCA/JCE API for the HSM it could also be wise to extend the BaseCAToken class.
　　Same activation code must be used for all keys used by a CA.
　　EJBCA 3.1 and later has build-in support for the nCipher NFast HSM.
　　EJBCA 3.2 and later also has an implementation for the Eracom HSM. The configuration was changed to 3.3.
　　
　　EJBCA 3.3 and later has an implementation for the SafeNet Luna HSM.
　　EJBCA 3.5 and later has an implementation for a generic PKCS#11 provider, tested with Utimaco and nCipher.
　　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 property field with the keyword 'pin'. If this property is not specified then the CA has to be manually activated after each restart or re-deployment of EJBCA.
Manual activation is done in the admin-GUI under 'Basic Functions->View Information', or using the cli 'bin/ejbca.sh ca activateca'.
　　The 'pin' property can use a clear text password or an encrypted one.
(encrypted is only available in EJBCA >= 3.5):

pin foo123
pin 6bc841b2745e2c95e042a68b4777b34c

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

$ bin/ejbca.sh encryptpwd foo123
Using JBoss JNDI provider...
Please note that this encryption does not provide absolute security, ....
Enter word to encrypt:
foo123
Encrypting pwd 'foo123'
6bc841b2745e2c95e042a68b4777b34c

　　NOTE: This encryption is not high security encryption, it is only meant to protect the password for accidental viewing. The encryption uses a build in encryption key in EJBCA. With an encrypted pin you can for example bring up the 'Edit CAs' page in the admin-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 ECDSA
　　Support for ECDSA in HSMs are dependant on the support for ECDSA in the HSM manufacturers JCE provider. You have to check if that support is available.

Generic PKCS#11 provider (EJBCA 3.5)
　　The PKCS#11 wrapper from SUN has been used to implement support for tokens with PKCS#11 libraries. The PKCS#11 provider have been tested with Utimaco Cryptoserver, nCipher nFast/netHSM and Eracom.
　　Besides the keys previously described the property field of the administration GUI should contain the following properties:

• slot - the slot of the CA.
  
• sharedLibrary - the shared PKCS#11 library to be used.
  

　　The tool $EJBCA/bin/pkcs11HSM.sh is used administrate generate keys. Use it without parameters to get all valid options.

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

[Global]
Timeout = 5000
Logging = 0
Logpath = /tmp
[CryptoServer]
Device     = TCP:3001@172.16.175.128
Timeout    = 600000
AppTimeout = 172800
SlotCount  = 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/bin/pkcs11HSM.sh 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 slot must 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:

./p11tool lib=./libcs2_pkcs11.so slot=1 InitToken=officer1
./p11tool lib=./libcs2_pkcs11.so slot=1 loginSO=officer1 initpin=user1
$EJBCA/bin/pkcs11HSM.sh generate ./libcs2_pkcs11.so 4096 signKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry signKey.
$EJBCA/bin/pkcs11HSM.sh generate ./libcs2_pkcs11.so 2048 defaultKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry defaultKey.
$EJBCA/bin/pkcs11HSM.sh generate ./libcs2_pkcs11.so 512 testKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry testKey.

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

slot 1
defaultKey defaultKey
certSignKey signKey
crlSignKey signKey
testKey testKey
pin user1
sharedLibrary /opt/utimaco/p11/libcs2_pkcs11.so

　　Utimaco have an emulator for their CryptoServer LAN HSM that can be used for test and development. If you have the emulation kit 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:

./csadm Device=TCP:3001@172.16.175.128 GetState

nCipher PKCS#11
　　For nCipher the slot name is some vritual slot that we don't know the number of. Luckily we can simply use the default slot by leaving out the slot number.
When using nCipher PKCS#11 you first set some options. Create the file /opt/nfast/cknfastrc with the following contents:

CKNFAST_LOADSHARING=1
CKNFAST_NO_ACCELERATOR_SLOTS=1
CKNFAST_NO_UNWRAP=1
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=import

　　Now you can generate keys with for example keytool. You can use keytool if you edit $JAVA_HOME/jre/lib/security/java.security and add a new provider for the SUN PKCS#11 wrapper:

# configuration for security providers 1-6 omitted
security.provider.7=sun.security.pkcs11.SunPKCS11 /opt/nfast/nfast-sunpkcs11.cfg

　　The file /opt/nfast/nfast-sunpkcs11.cfg should contain:

name=NFastJava
library=/opt/nfast/toolkits/pkcs11/libcknfast.so

　　You can generate keys with keytool with the command:

keytool -genkey -keystore NONE -storetype PKCS11-NFastJava -storepass foo123 -alias fooSign -keyalg RSA -keysize 4096
keytool -genkey -keystore NONE -storetype PKCS11-NFastJava -storepass foo123 -alias fooDefault -keyalg RSA -keysize 2048
keytool -genkey -keystore NONE -storetype PKCS11-NFastJava -storepass foo123 -alias fooTest -keyalg RSA -keysize 1024

　　(in Java 6 it's called -genkeypair instead of -genkey)
　　AFTER you have generated the keys, you can now start JBoss. If you start JBoss before generating the keys JBoss will not find them, it seems the PKCS#11 session is cached so new stuff don't appear for already present PKCS#11 sessions.
　　Now it is possible to access the nCipher PKCS#11 default slot, protected by operator cards.
　　This is a example of a property field when creating the CA:

defaultKey fooDefault
certSignKey fooSign
crlSignKey fooSign
testKey fooTest
pin user1
sharedLibrary /opt/nfast/toolkits/pkcs11/cknfast.so

　　If you have generated keys with the nCipher tools, you must also associate a certificate (can be dummy) with the key.

nCipher NFast
　　Follow these steps to create a CA that is using a nFast card:

1. Install the nFast card　　Make sure you have all necessary software and drivers installed and created the user and group nfast. In Linux should the software 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/lars/work$ /opt/nfast/bin/enquiry
Server:
enquiry reply flags  none
enquiry reply level  Six
serial number        41C5-BA04-6D2C
mode                 operational
version              2.23.6
speed index          147
rec. queue           442..642
level one flags      Hardware HasTokens
version string       2.23.6cam5, 2.22.6cam7 built on Apr 25 2005 18:15:46
checked in           00000000431dca98 Tue Sep  6 18:58:00 2005
level two flags      none
max. write size      8192
level three flags    KeyStorage
level four flags     OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred
module type code     0
product name         nFast server
device name
EnquirySix version   4
impath kx groups
feature ctrl flags   none
features enabled     none
version serial       0
remote server port   9004
Module #1:
enquiry reply flags  none
enquiry reply level  Six
serial number        41C5-BA04-6D2C
mode                 pre-initialisation
version              2.22.6
speed index          147
rec. queue           9..152
level one flags      Hardware HasTokens InitialisationMode PreMaintInitMode
version string       2.22.6cam7 built on Apr 25 2005 18:15:46
checked in           00000000426636cd Wed Apr 20 13:02:37 2005
level two flags      none
max. write size      8192
level three flags    KeyStorage
level four flags     OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred
module type code     6
product name         nC1002P/nC3022P
device name          #1 nFast PCI device, bus 0, slot 13.
EnquirySix version   5
impath kx groups     DHPrime1024
feature ctrl flags   LongTerm
features enabled     StandardKM
version serial       24
rec. LongJobs queue  8
SEE machine type     gen1AIF
nfast@donny:/home/lars/work$

　　Create the security world with the command :

nfast@donny:/home/lars/work$ /opt/nfast/bin/new-world -i -Q 1/1
15:04:50 WARNING: Module #1: preemptively erasing module to see its slots!
Create Security World:
Module 1: 0 cards of 1 written
Module 1 slot 0: empty
Module 1 slot 0: unknown card
Module 1 slot 0:- passphrase specified - overwriting card
Card writing complete.
security world generated on module #0; hknso = 6807e0b031c4f797b739ec33ca7dba05279cf54f
nfast@donny:/home/lars/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 module with 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 in production.
　　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/lars/work$ /opt/nfast/bin/createocs -m 1 -Q 2/3 -N ejbca -M -p -T 0
Creating Cardset:
Module 1: 0 cards of 3 written
Module 1 slot 0: Admin Card #1
Module 1 slot 0: empty
Module 1 slot 0: blank card
Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 1')
Module 1: 1 card of 3 written
Module 1 slot 0: remove already-written card #1
Module 1 slot 0: empty
Module 1 slot 0: blank card
Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 2')
Module 1: 2 cards of 3 written
Module 1 slot 0: remove already-written card #2
Module 1 slot 0: empty
Module 1 slot 0: blank card
New passphrases do not match; please try again.
Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 3')
Card writing complete.
cardset created; hkltu = 8d30f2ab5bdccacd8a4333aefed2c0ea1ff0e6db
nfast@donny:/home/lars/work$

　　This will generate 3 cards of the card set named 'ejbca'. Any 2 of these cards will be needed when generating keys and starting ejbca. Different card sets could be used for different CAs.
　　Open the file '/opt/nfast/kmdata/config/config' and set 'nonpriv_port=9000' and 'priv_port=9001'. Optional: In the same config file you can set 'impath_port=0' to disable remote connections to the machine.
　　Restart from scratch: 'sudo /etc/init.d/nfast restart'.

2. Create keys that should be used on the NFast card　　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.5.0_11 or similar)
  
• APPSRV_HOME (/home/jboss/jboss-4.2.0.GA or similar)
  
• EJBCA_HOME (/home/jboss/ejbca or similar)
  
• NFAST_HOME (/opt/nfast)
  

Note
The preload command (see below) must always be called as the same user unless the directory /opt/nfast/kmdata/preload is removed.
If you get a &quot;HostDataAccessDenied&quot; error when running preload or starting JBoss, it is because the file permissions on the directory /opt/nfast/kmdata/preload is wrong. It's probably because you (sometime) ran preload as another user, such as root or nfast.　　Load the card set so that keys protected by the card set could be generated:

jboss@donny:~$ /opt/nfast/bin/preload -c ejbca pause
Loading cardsets:
ejbca on modules 1
Loading `ejbca':
Module 1 slot 0: `ejbca' #3 (`EJBCA card 3')
Module 1 slot 0:- passphrase supplied - reading card
Module 1 slot 0: `ejbca' #3 (`EJBCA card 3'): already read
Module 1 slot 0: empty
Module 1 slot 0: `ejbca' #2 (`EJBCA card 2')
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.
Loading complete; now pausing

　　Start a new window and login as the same user (jboss user). Now 3 keys protected by the key set 'ejbca' are created like this:

jboss@donny:~$ /opt/nfast/bin/preload $EJBCA_HOME/bin/nCipherHSM.sh generate 4096 signRoot
Executing /home/jboss/ejbca/bin/nCipherHSM.sh generate 4096 defaultRoot
Creating certificate with entry defaultRoot in KeyStore of type nCipher.sworld with provider nCipherKM.
Give password of inserted card in slot:
pass2
Next line will contain the identity identifying the keystore:
03842f5bffefd9a73ac4f6caea27fb7287e7eff0
jboss@donny:~$ /opt/nfast/bin/preload $EJBCA_HOME/bin/nCipherHSM.sh generate 2048 defaultRoot 03842f5bffefd9a73ac4f6caea27fb7287e7eff0
Executing /home/jboss/ejbca/bin/nCipherHSM.sh generate 2048 encryptRoot 03842f5bffefd9a73ac4f6caea27fb7287e7eff0
Creating certificate with entry encryptRoot in KeyStore of type nCipher.sworld with provider nCipherKM.
Give password of inserted card in slot:
pass2
Next line will contain the identity identifying the keystore:
03842f5bffefd9a73ac4f6caea27fb7287e7eff0
jboss@donny:~$ /opt/nfast/bin/preload $EJBCA_HOME/bin/nCipherHSM.sh generate 512 testRoot 03842f5bffefd9a73ac4f6caea27fb7287e7eff0
Executing /home/jboss/ejbca/bin/nCipherHSM.sh generate 512 testRoot 03842f5bffefd9a73ac4f6caea27fb7287e7eff0
Creating certificate with entry testRoot in KeyStore of type nCipher.sworld with provider nCipherKM.
Give password of inserted card in slot:
pass2
Next line will contain the identity identifying the keystore:
03842f5bffefd9a73ac4f6caea27fb7287e7eff0
jboss@donny:~$

　　Different CAs may share the same keystore but may also have different key stores. Different key store may be protected by different card sets. Use the '-c' parameter of preload to select card set when you are generating new keys. Only one key set should be loaded at a time when creating keys.
　　The last key in the example is used to check the status of the HSM by EJBCA. This key is small (512 bit) to enhance performance.

3. Start EJBCA with NFast HSM　　To start EJBCA, preload must be running with the required key stores loaded. In this example this was done in step 2. A provided script may be used to start EJBCA:

jboss@donny:~/tmp$ $EJBCA_HOME/bin/nCipherJboss.sh start
CMD_START = /opt/nfast/bin/preload /home/jboss/jboss/bin/run.sh
Executing /home/jboss/jboss/bin/run.sh
=========================================================================
JBoss Bootstrap Environment
JBOSS_HOME: /home/jboss/jboss
JAVA: /usr/local/jdk/bin/java
JAVA_OPTS: -server -Xms128m -Xmx512m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dprogram.name=run.sh
CLASSPATH: /opt/nfast/java/classes/kmcsp.jar:/opt/nfast/java/classes/kmjava.jar:/opt/nfast/java/classes/nfjava.jar:/opt/nfast/java/classes/rsaprivenc.jar:/home/jboss/jboss/bin/run.jar:/usr/local/jdk/lib/tools.jar
=========================================================================
09:36:49,419 INFO  [Server] Starting JBoss (MX MicroKernel)...
09:36:49,432 INFO  [Server] Release ID: JBoss [Zion] 4.0.4.GA (build: CVSTag=JBoss_4_0_4_GA date=200605151000)
09:36:49,471 INFO  [Server] Home Dir: /home/jboss/jboss-4.0.4.GA
09:36:49,472 INFO  [Server] Home URL: file:/home/jboss/jboss-4.0.4.GA/
09:36:49,474 INFO  [Server] Patch URL: null
09:36:49,475 INFO  [Server] Server Name: default
09:36:49,475 INFO  [Server] Server Home Dir: /home/jboss/jboss-4.0.4.GA/server/default
09:36:49,476 INFO  [Server] Server Home URL: file:/home/jboss/jboss-4.0.4.GA/server/default/
09:36:49,477 INFO  [Server] Server Log Dir: /home/jboss/jboss-4.0.4.GA/server/default/log
09:36:49,478 INFO  [Server] Server Temp Dir: /home/jboss/jboss-4.0.4.GA/server/default/tmp
09:36:49,479 INFO  [Server] Root Deployment Filename: jboss-service.xml
09:36:50,495 INFO  [ServerInfo] Java version: 1.5.0_06,Sun Microsystems Inc.
09:36:50,496 INFO  [ServerInfo] Java VM: Java HotSpot(TM) Server VM 1.5.0_06-b05,Sun Microsystems Inc.
09:36:50,496 INFO  [ServerInfo] OS-System: Linux 2.6.15-26-server,i386
09:36:52,755 INFO  [Server] Core system initialized

4. Create a new CA in the web GUI of EJBCA　　Choose NFastCAToken as &quot;CA Token Type&quot;.
　　Define the keystore on the nFast card that should be used. The keystore is defined by the hexadecimal hash string from the output of the key generation. Define which keys in the keystore that should be used and the purpose of these keys.
　　Use one row for each definition. Begin the row with a key word. It is one row for the keystore and one for each key definition. Key word and value is separated by one or more spaces. A row with the keyword keyStore must always be present.
　　The keys in the property field are defined by their keystore alias. See general text above about key definition.
　　You must use a unique keystore for each CA.
　　Example with previous generated keys where signRoot is used for CAs signing, and defaultRoot is used for everything else (encryption):

keyStore 03842f5bffefd9a73ac4f6caea27fb7287e7eff0
defaultKey defaultRoot
certSignKey signRoot
crlSignKey signRoot
testKey testRoot

Importing an existing CA or sub-CA to EJBCA.　　Importing existing keys is not as safe as generating them in the HSM, since the original key or a copy of the key might still be around. The security world has to be initialized in the default FIPS 140-2 Level 2 for this to work. First backup and edit $JAVA_HOME/jre/lib/security/java.security and change

security.provider.1=sun.security.provider.Sun
...

　　to

security.provider.1=com.ncipher.provider.km.nCipherKM
security.provider.2=sun.security.provider.Sun
...

　　Then create an empty a keystore with

jboss@host$ $EJBCA_HOME/bin/nCipherHSM.sh createkeystore
...
Next line will contain the identity of the keystore:
f7e825134fe23f58b1575d8efb487babe7ebd1ed

　　This hash should be written to a file that has to be exactly 40 bytes long:

• Linux: 'cat > temp.keystore' and copypaste the string, press Ctrl-D and Ctrl-C.
  
• Windows: 'copy con: temp.keystore' and copypaste the string, press Ctrl-Z and Enter.
  

　　Import a RSA key protected by 1/X operator cardset 'OperatorCardset' without passphrase from file 'rsaprivatekey.pem' as 'importedKey':

jboss@host$ $NFAST_HOME/bin/nfkminfo -k
AppName jcecsp Ident f7e825134fe23f58b1575d8efb487babe7ebd1ed
jboss@host$ export CLASSPATH=$CLASSPATH:$JAVA_HOME/jre/lib/jce.jar:$NFAST_HOME/java/classes/nfjava.jar:$NFAST_HOME/java/classes/kmjava.jar:$NFAST_HOME/java/classes/kmcsp.jar
jboss@host$ $NFAST_HOME/bin/generatekey --import -m 1 -c OperatorCardset jcecsp alias=importedKey pemreadfile=rsaprivatekey.pem type=RSA keystore=temp.keystore
...
ERROR: Could not write to temp.keystore
...
jboss@host$ $NFAST_HOME/bin/nfkminfo -k
AppName jcecsp Ident f7e825134fe23f58b1575d8efb487babe7ebd1ed
AppName jcecsp Ident f7e825134fe23f58b1575d8efb487babe7ebd1ed-key-832c8a89fe813dc99ae61e094fe5d195ca3e405d

　　Despite the error message the key is still imported.
　　Important: Restore $JAVA_HOME/jre/lib/security/java.security now or EJBCA will stop working!
　　Start JBoss with $EJBCA_HOME/bin/nCipherJboss.sh as described earlier. Create a new CA 'ImportedCA' in the Administration GUI. Choose CA Token Type 'NFastCAToken', enter the imported key's properties

keyStore f7e825134fe23f58b1575d8efb487babe7ebd1ed
defaultKey importedKey

　　Also enter the algorithm, the DN and the CRL Expire Period.
　　If you are replicating an existing root CA choose Signed By 'Self Signed' and make sure everything is the same as in the original. Press 'Create' and activate the CA-token from Basic Functions to start using the CA.
　　When importing a sub-CA, choose Signed by 'External CA'. Edit other properties if you like and press 'Make certificate request'. Ignore the request and edit the same 'ImportedCA'. Press 'Receive Certificate Response' and upload the old sub-CA's certificate. Activate the CA-token from Basic Functions when needed.

Using module protected keys　　The security world has to be initialized in the default FIPS 140-2 Level 2 for this to work. First backup and edit %JAVA_HOME%/jre/lib/security/java.security and insert com.ncipher.provider.km.nCipherKM as the first provider

security.provider.1=com.ncipher.provider.km.nCipherKM
security.provider.2=sun.security.provider.Sun
...

　　Then create an empty a keystore with

host> %EJBCA_HOME%/bin/nCipherHSM.cmd createkeystoremodule
...
Next line will contain the identity identifying the keystore:
0acea7eb80528b15851e6a3e7969d4a21eb2d57c

　　This hash should be written to a file that has to be exactly 40 bytes long:

• Linux: 'cat > temp.keystore' and copypaste the string, press Ctrl-D and Ctrl-C.
  
• Windows: 'copy con: temp.keystore' and copypaste the string, press Ctrl-Z and Enter.
  

　　Generate module protected key &quot;defaultRoot&quot; in this keystore

host> %NFAST_HOME%/bin/nfkminfo.exe -k
AppName jcecsp Ident 0acea7eb80528b15851e6a3e7969d4a21eb2d57c
host> %NFAST_HOME%/bin/generatekey.exe --batch --generate jcecsp type=rsa size=4096 protect=module alias=defaultRoot keystore=temp.keystore
...
ERROR: Could not write to temp.keystore
...
host> %NFAST_HOME%/bin/nfkminfo.exe -k
AppName jcecsp Ident 0acea7eb80528b15851e6a3e7969d4a21eb2d57c
AppName jcecsp Ident 0acea7eb80528b15851e6a3e7969d4a21eb2d57c-key-a68f3efde60a519b7c9d4e4df22fd2b53ded37f3

　　Despite the error message the key is still created.
　　Important: Restore %JAVA_HOME%/jre/lib/security/java.security now or EJBCA will stop working!
　　Start JBoss as for any soft token and create a new CA 'ModuleProtectedCA' in the Admin GUI. Choose CA Token Type 'NFastCAToken' and enter the generated key's properties.

keyStore 0acea7eb80528b15851e6a3e7969d4a21eb2d57c
defaultKey defaultRoot

　　Complete the form and press &quot;Create&quot;. Go to Admin GUI -> Basic Functions -> View Information for 'ModuleProtectedCA' -> Activate. Create a CRL to verify functionality by Admin GUI -> Basic Functions -> Create CRL for 'ModuleProtectedCA'.

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 to start automatically at boot time. Use the &quot;-np&quot; switch to the starting script if you don't want preload:

$EJBCA_HOME/bin/nCipherJboss.sh -np start
Setting public exponent.　　To choose the public exponent the &quot;nCipherHSM.sh&quot; script can not be used. nCipher has not implemented the initialization method of &quot;KeyPairGenerator&quot; that is used to set the public exponent. But there is another way to generate keys with the public exponent as a parameter. You must have this before you start:

• A card that belongs to a 1/n card set in the nCipher reader
  
• A keystore protected by this card set
  

The keystore may be created with &quot;$EJBCA_HOME/bin/nCipherHSM.sh createKeyStore&quot; or &quot;$EJBCA_HOME/bin/nCipherHSM.sh generate ...&quot;. Put the ID of the keystore (same as is used in the EJBCA web GUI) in a file. This file may not contain any other characters other than the characters of the ID. Check that the length of the file is 40 byte. If the file is called &quot;single.jks&quot; then the key is created like this:
/opt/nfast/bin/generatekey -g -csingle -b jcecsp alias=default keystore=single.jks type=RSA pubexp=3 size=2048 keystorepass=single
SafeNet Luna SA HSM
　　Hopefully it is possible to use PKCS#11 interface of the HSM instead of using the java provider of the HSM. It will better to use PKCS#11 since the Luna java provider is using the PKCS#11 Using PKCS#11 will change the keygeneration (step 3). The CA creation (step 5) should then be done with the PKCS#11 token.
　　If you have succeeded to create keys without the java provider that could be used with a PKCS#11 token please update this documentation.
　　Follow these steps to create a CA that is using a Luna SA HSM:

1. Install the Luna SA HSM　　The host that CA is running on must be a client to the HSM. This client should be assigned to a partition of the HSM. It is only possible for the CA to use one partition. The reason for this limitation is that a client can only be logged in to a partition at a time.
　　Do the setup according the documentation from SafeNet. After &quot;Assign a Client to a Partition&quot; is done you should check that you have access to a partition with the &quot;vtl verify&quot; command. The label of the partition returned in the response should be used later as 'slotLabel'.

2. Build EJBCA　　Do the following:

• 1. Put LunaJCASP.jar from SafeNet in $EJBCA_HOME/lib and in $APPSRV_HOME/server/default/lib
  
• 2. Define the property 'hsm.luna' in conf/ejbca.properties (see uncommented line in conf/ejbca.properties.sample).
  
• 3. ant deploy
  

3. Create keys that should be used on the Luna SA HSM　　Use the tool $EJBCA_HOME/bin/lunaHSM':

lunaHSM generate 'key alias' 'key size' ['partition label'] 'partition password'
　　'partition label' has to be used if there are more than one partitions assigned to the client. Only CAs from the same partition may be activated at a time.
　　When using the tool, the directory of the file libLunaAPI.so must be in LD_LIBRARY_PATH.
　　At least one key should be generated for each CA in EJBCA. Maybe several if different keys for different purposes are used. When referring to a key in EJBCA the 'key alias' is used.

4. Make EJBCA aware of the Luna SA HSM　　Do the following:

• 1. Stop the application server.
  
• 2. Start the application server with the directory of the file libLunaAPI.so in LD_LIBRARY_PATH.
  

5. Create a new CA in the web GUI of EJBCA　　Choose SafeNetLunaCAToken as &quot;CA Token Type&quot;.
　　Define which keys on the slot that should be used and the purpose of these keys. If more than one partition is assigned to the client the label of this partition has to be defined too.
　　Use one row for each definition. Begin the row with a key word. It is one row for the 'partition label' (may be omitted if only one partition) and one for each key definition. Key word and value is separated by one or more spaces.
　　'slotLabel' (if present) defines the 'partition label' of the partition to be used. A row with the keyword 'slotLabel' must be present if more than on partition is assigned to the client with the name of the label of the used partition.
　　The keys in the property field are defined by their key alias. See general text above about key definition.
　　Example:

slotLabel p1
certSignKey rootCertSign
defaultKey rootCRLSign

　　It ought to be better to create a PKCS#11 token instead. But this has not been verified. It configuration should look like this:

slot 1
certSignKey rootCertSign
defaultKey rootCRLSign

　　Using PKCS#11 may work even if the keys has been created with &quot;lunaHSM generate&quot;.

Note.　　When activating Luna CAs in EJBCA the given password is only validated for the first one that is activated. When this first CA is activated a login is performed to the used partition. Logout from the partition is performed when all Luna CAs in EJBCA for a partition has been deactivated.
　　Different partitions may be used for different CAs. But only CAs from one partition may be activated at a certain time.

Eracom HSM with PKCS#11
　　Follow these steps to create a CA that is using a Eracom HSM (tested with a SW emulator):

1. Install the Eracom software　　You need an access library (ex ETnethsm) and the Toolkit C runtime.

2. Create the required slots　　Create the required slots (one PIN per slot) and keys (with keylabels) using the Eracom tools or your own java classes.
　　Sample Slot Initialization:

ctconf
ctconf -c10
ctconf -fc
ctkmu t -s5 -lroot

　　Key generation
$EJBCA_HOME/bin/pkcs11HSM.sh generate 4096 defaultKey 5

3. If you use an external HSM, set its hostname/IP-Address as unix environment variable
CT_SERVER=eracom
export CT_SERVER

　　4. Start the J2EE container
　　5. Create a new CA
　　The keys in the property field are defined by their key alias and slot by the number. See general text above about key definition and PKCS#11.
　　Create a CA with &quot;CA Token Type&quot; = PKCS#11
　　The keys in the property field are defined by their key alias. See general text above about key definition.
　　Fill in the hard token properties. Example:

slot 5
defaultKey defaultKey
sharedLibrary /opt/ETcpsdk/lib/linux-i386/libcryptoki.so
pin user5

Eracom HSM using Eracom provider
　　This tooken type is depreciated. Please follow &quot;Eracom HSM with PKCS#11&quot; instead. But this description was written with experience from a real HSM. When writing the PKCS#11 description an emulator was used.
　　Follow these steps to create a CA that is using a Eracom HSM (tested with Eracom ProtectServer Orange (csa8000) external):

1. Install the Eracom software　　You need an access library (ex ETnethsm), the Toolkit C runtime and the Toolkit J runtime.

2. Create the required slots　　Create the required slots (one PIN per slot) and keys (with keylabels) using the Eracom tools or your own java classes.
　　Sample Slot Initialization:

• ctconf -x
  'tamper' HSM, erases complete key store memory
  
• ctconf
  sets Administrator SO and Administrator PINs (first use of ctconf after tamper)
  
• ctconf -fF
  set FIPS 140-2 compliant mode
  
• ctconf -c2
  create 2 new user slots
  
• ctstat
  list user slots (for verification)
  
• ctconf -n 0
  label: userpki, initialize slot 0, set slot's SO PIN
  
• ctconf -n 1
  label: serverpki, initialize slot 1, set slot's SO PIN
  
• ctkmu p -s 0
  set user PIN slot 0
  
• ctkmu p -s 1
  set user PIN slot 1
  

　　Key generation
( Use the samples / tools provided with the Eracom software.)
( You can write a helper app using the Eracom crytoki interface )
　　Key Backup
( Make key backups on smart cards as described.)

3. Make sure the required Eracom Java Security Provider (jprov) is on the classpath　　Only need if you want to use the Eracom provider. If PKCS#11 is used (recomended) continue with step 5.
　　For example, for WEBLOGIC, add:
WEBLOGIC_CLASSPATH=${WEBLOGIC_CLASSPATH}:...:/opt/Eracom/lib/jprov.jar

4. Add the native library dir for HSM communication to your path　　Only need if you want to use the Eracom provider. If PKCS#11 is used (recomended) continue with step 5.
　　The native library dir is where libjcprov.so and libcryptoki.so are located.

LD_LIBRARY_PATH=/opt/Eracom/lib/linux-i386
export LD_LIBRARY_PATH

　　For Windows this is done by adding the location where DLLs are located to the system path. This is normally done by the installer programs.
　　5. If you use an external HSM, set its hostname/IP-Address as unix environment variable

CT_SERVER=eracom
export CT_SERVER

　　6. Start the J2EE container
　　7. Create a new CA
　　Create a CA with &quot;CA Token Type&quot; = Eracom, the type should appear automatically in the list when the Eracom keystore classes are found.
　　The keys in the property field are defined by their key alias. See general text above about key definition.
　　Fill in the hard token properties. Example:

slot 1
defaultKey cakey1
pin secret

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 object contains among other things references to keys (or the keys themselves of a soft token is used). For each HSM hardware that should be supported you need one HardCAToken class that implementes support for this particular HSM. A hard ca token plug-in must:

• implement ICAToken
  
• it is recommended to extend BaseCAToken, since BaseCAToken implements handling of all properties, autoactivation and such
  
• be loaded at the static initialization if CATokenManager where it is registered with the CATokenManager using the method addAvailableCAToken()
  
• 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().
  

　　See HardCATokenSample and/or DummyHardCAToken for samples. Unlike the sample addAvailableCAToken() must be called with use=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 issued certificates and CRLs to be stored. The most common cases of Publishers, which are implemented by default in EJBCA are LDAP directories 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 in the admin-GUI.
　　First we will start with describing the built-in publishers.

LDAP Naming
　　A good book to understand LDAP naming is &quot;Understanding and Deploying LDAP Directory Services&quot;. 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 it will map to the DN &quot;dc=bigcorp,dc=com&quot;. The top node in my LDAP directory will then be &quot;dc=bigcorp,dc=com&quot;.
　　The dc component support is mandated by all of the X.509 RFCs now. For example, if I have this directory:

dc=bigcorp,dc=com
|
+-dc=fi
|
|
+-dc=se
|
+-cn=Mike Jackson

　　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.
　　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 a larger organization there are probably several people with the same name. Somehow the names must be made unique, and one way is to introduce numbers, initials etc in the CN. Another way that we recommend is to use uid in the LDAP DN instead. LDAP DNs will then looks like &quot;uid=tomas,dc=bigcorp,dc=com&quot;. Uid is the users username, normally used for login etc, and you probably already 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 that instead of paths separate by slashes, you have paths separated by commas and '=' signs.
　　For example, if you want to make an object &quot;cn=ldaphost,ou=hosts,dc=yourdom,dc=com&quot;, you first have to make sure &quot;dc=yourdom,dc=com&quot; exists.
Then make sure
&quot;ou=hosts,dc=yourdom,dc=com&quot; exists.
THEN you can try
&quot;cn=ldaphost,ou=hosts,dc=yourdom,dc=com&quot;
　　EJBCA does not create branches in LDAP. You have to put them there with other means, before you start publishing.

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 can implement 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 the LDAP structure.

*** Configuring EJBCA ***
　　To configure the publisher for LDAP:

• Choose 'Edit Publishers' in the admin-GUI.
  
• Add a new publisher with a name you define yourself. Edit the publisher and fill in all the necessary fields.
  

　　Generic parameters to LDAP Publisher:

• 'Hostname' is the host where the LDAP server is located.
  
• '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.
  
• 'Create Nonexisting Users' defines if an LDAP object should be created by EJBCA if it is no existing object when EJBCA publishes the certificate.
  
• 'Modify Existing Users' defines if attributes (such as email) in existing LDAP objects are replaced with new values when an entry is updated with a new certificate.
  
• 'Add multiple certificates per user' defines if we should use multiple certificate entries for each user or only one. Default only one certificate is added to a user entry in LDAP and if the user gets a new certificate the old one is deleted and replaced with the new one. If this checkbox is checked certificates are instead appended in LDAP so each user can have multiple certificate entries in LDAP. Make sure your applications can handle this before enabling this option. Revoking a user will remove all certificates entries for the user.
  
• 'User Object Class' is the objectclass for the LDAP entries for users, where user certificates are published. The entry is hierarchical separated by ';' to build a structure like:
  objectclass: top
  objectclass: person
  objectclass: organizationalPerson
  objectclass: inetOrgPerson
  This 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 entry is 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 DN published in LDAP, and it will be appended to the LDAP location fields selected to be used. example: If the user DN in EJBCA is &quot;cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE&quot; and the BaseDN is &quot;dc=PrimeKey,dc=SE&quot; and the selected LDAP location fields are &quot;CN&quot;. The LDAP DN used for publishing will be &quot;cn=tomas gustavsson, dc=PrimeKey, dc=SE&quot;, and the &quot;uid=tomasg&quot; will be added as an attribute in LDAP. The certificate stored under &quot;cn=tomas gustavsson, dc=PrimeKey, dc=SE&quot; will have the subjectDN &quot;cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE&quot;.
  

*** 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 will be 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　　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 fields for cert DN'. It checks if the entry exists in the ldap and either creates or modifies the entry.
　　Example: The certificate DN is &quot;CN=Tomas Gustavsson,O=Foo,C=SE&quot;, the BaseDN in the publisher is &quot;DC=primekey,DC=se&quot; and the CN is selected in &quot;LDAP location fields from cert DN&quot;.
The resulting DN that EJBCA will search for in the LDAP and create if it does not already exist is &quot;CN=Tomas Gustavsson,DC=primekey,DC=se&quot;.
　　Using this publisher, if you have multiple trees in your LDAP (for example &quot;ou=foo,dc=primekey,dc=se&quot; and &quot;ou=bar,dc=primekey,dc=se&quot;) you can either:

• Include both CN and OU in 'LDAP location fields from cert DN' and have your cert DNs like &quot;CN=Tomas,OU=foo,O=MyOrg,C=SE.
  
• Use different publishers for ou=foo and ou=bar and issue certificates for the different OUs with different certificate profiles.
  

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 entries exist 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 &quot;LDAP search settings&quot;:

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

The best example of such a search filter is if base is &quot;dc=primekey,dc=se&quot; and filter is &quot;uid=$USERNAME&quot;. The search done by ejbca will be equal to the search:
ldapsearch -x -b &quot;dc=primekey,dc=se&quot; &quot;(uid=$USERNAME)&quot;　　$USERNAME is replaced by the EJBCA username of the user that has had a new certificate just generated. Other variables apart from $USERNAME is $CN, $O, $OU and $C where these values are taken from the certificate DN.
　　When a certificate is generated for say user &quot;ldap&quot; EJBCA will perform the search:
ldapsearch -x -b &quot;dc=primekey,dc=se&quot; &quot;(uid=ldap)&quot;
　　The certificate generated for ldap will be published in the object returned by the search. This is very useful if you want to publish certificates to an LDAP directory where your users already exists, such as an email directory. The DN in the LDAP does not 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 &quot;cn=Ejbca1,0=MyOrg,c=SE&quot;
and your base DN is like &quot;DC=Security,DC=Software,DC=MyOrg&quot;.
The publisher for AD should have base DN like
&quot;cn=Users,dc=Security,dc=Software,dc=MyOrg&quot;
　　For Login DN you should use the full ldap name, for example:
&quot;CN=Administrator,CN=Users,dc=primekey,dc=se&quot;
　　In order to connect to AD though SSL you should issue a LDAP SSL P12 to the domain controller. According to MS Article ID 321051
　　The same certificate is used for both the AD and global catalogue (GC). Remember to add the CA certificate to the machine that stores trusted root certificates.
　　To publish a CRL to Active Directory use a Base DN similar to

CN=somename,CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,DC=somemachine,DC=primekey,DC=se

　　and the &quot;CRL Distribution Point&quot; in the certificate should point to

ldap:///CN=Test%20MS%20SC%20Logon%20CA%20v1,CN=somename,CN=CDP,CN=Public%20Key%20Services,CN=Services,
CN=Configuration,DC=somemachine,DC=primekey,DC=se?certificateRevocationList?base?objectClass=cRLDistributionPoint

*** 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 OU attribute in the ldap entry.
　　When updating an entry that already exists EJBCA uses replace on the existing attributes, so if an email attributes already exists and EJBCA finds an email address in the certificate, the email attribute in ldap is replaced with the email address from the certificate.
　　Note that attributes are only replaced/updated if the flag &quot;Modify Existing Users&quot; in the Publisher is active. The certificate attribute 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 not allowed.
　　The attributes that EJBCA creates or replaces are:

• cn (common name)
  
• l (locality)
  
• ou (organizational unit)
  
• sn (surname)
  
• gn (givenname)
  
• st (state)
  
• o (organization)
  
• uid (user id)
  
• initials
  
• title
  
• serialnumber - If we have selected to use the SN (serialNUmber DN field) in 'Ldap Location fields', we will also add it as an attribute.
  

Using LDAP
　　In Mozilla you can for example enter a URL like:
ldap://ip-address-of-ldap-server:389/cn=Tomas Gustavsson,dc=se,dc=bigcorp,dc=com
and 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 Netscape/Mozilla 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 SSL connection to the LDAP server (Account Options->Compositions & Addressing->Edit directories->Edit->Use Secure Connection), see also below how to configure OpenLDAP for SSL.
　　Note: When fetching certificates from LDAP with Mozilla 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 in Mozillas.
　　To use SSL against an LDAP server with MS Outlook you must make sure the CN in the LDAP servers certificate is the same as the hostname. An example of adding a user for the LDAP server with the CLI interface is:

bin/ejbca.sh ra adduser ldap password &quot;C=SE,O=Foo,CN=ldap.foo.se&quot; null MyCA null 1 PEM

　　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=Mike Jackson,ou=people,dc=company,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Mike Jackson
sn: Jackson
userCertificate;binary::

　　CAs are published in the form:

dn: cn=ejbca,dc=jackson,dc=net
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
cn: ejbca
cACertificate;binary:
certificateRevocationList;binary:
authorityRevocationList;binary:

　　To configure OpenLDAP (version 2.2.5) to include the 'inetOrgPerson' you must add the following lines to slapd.conf:

include         /usr/local/etc/openldap/schema/cosine.schema
include         /usr/local/etc/openldap/schema/inetorgperson.schema

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

dn: o=AnaTom,c=SE
objectclass: dcObject
objectclass: organization
o: AnaTom
dc: AnaTom
dn: cn=Admin,o=AnaTom,c=SE
objectclass: organizationalRole
cn: Admin

　　And using the command:

ldapadd -x -D &quot;cn=Admin,o=AnaTom,c=SE&quot; -W -f org.ldif

　　Check what you have in the LDAP by:

/usr/local/bin/ldapsearch -x -b 'o=AnaTom,c=SE' '(objectclass=*)'

*** 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 as fine). In the mail ejbca directory type (use simply 'ra' on windows):

bin/ejbca.sh ra adduser ldap foo123 &quot;C=SE,O=Foo,CN=ldap&quot; null AdminCA1 null 1 PEM
bin/ejbca.sh ra setclearpwd ldap 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 user type 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 this example the slapd.conf is located in /usr/local/etc/openldap so we copy the files to that directory. Protect theses files so they are only readable by the LDAP server. Add the following to your slapd.conf:

# Use SSL
TLSCipherSuite HIGH:MEDIUM:+SSLv3
TLSCertificateFile /usr/local/etc/openldap/ldap.pem
TLSCertificateKeyFile /usr/local/etc/openldap/ldap-Key.pem
TLSCACertificateFile /usr/local/etc/openldap/ldap-CA.pem

　　Restart slapd:

./slapd -h &quot;ldap:/// ldaps:///&quot;

　　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=&quot;yes&quot;

　　and then run

SuSEconfig

　　and then

rcldap 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:

bin/ejbca.sh ca getrootcert MyCA myca.der -der

　　Then add it to the java trust store:

keytool -import -trustcacert -alias MyCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file myca.der

　　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 ***

- apt-get install slapd ldap-utils
- dpkg-reconfigure slapd
Configure slapd with your domain and admin password.
- /etc/init.d/slapd restart
- 'ps -ef|grep slap'
should show a slapd running
- ldapsearch -x -b 'dc=PrimeKey,dc=com' '(objectclass=*)'
To look at the results
- slapcat -l backup.ldif
Make backup
- slapadd -l backup.ldif
- /etc/init.d/slapd restart
Restore backup

　　Command to add new LDAP nodes:

- ldapadd -x -D &quot;cn=admin,dc=PrimeKey,dc=com&quot; -W -f primekey.ldif
where primekey.ldif is:
dn: dc=PrimeKey,dc=com
dc: PrimeKey
objectclass: dcObject
objectclass: organization
o: PrimeKey Solutions AB
description: Parent Object for PrimeKey LDAP Directory
dn: ou=Standard,dc=PrimeKey,dc=com
ou: Standard
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all Standard Certificates
dn: ou=High,dc=PrimeKey,dc=com
ou: High
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all High Certificates

Extra device schema
　　To store certificates for devices (e.g. routers, toasters etc) in LDAP it is no really suitable standard object class. inetOrgPerson requires 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. The ejbcaDevice uses object ids from PrimeKey Solutions AB.

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

/usr/netscape/servers/slapd-hostname/config/schema/

　　and restart the LDAP server.
　　For OpenLDAP, copy the ejbca.schema file into, e.g.:

/usr/local/etc/openldap/schema/

　　and edit slapd.conf to add the following line:

include /usr/local/etc/openldap/schema/ejbca.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 writing a 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. There is 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 the General Purpose Custom Publisher (GPCP). This makes it possible to export DER-encoded CRLs, certificates and/or revokations with a simple script (using scp or similar). The GPCP creates a temporary file and executes the script with the full pathname to the 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 &quot;Edit Publishers&quot; in the Administration GUI. Add a publisher &quot;GPCP&quot; and then &quot;Edit&quot; the same. Choose

• Publisher type: Custom Publisher
  
• Class Path: org.ejbca.core.model.ca.publisher.GeneralPurposeCustomPublisher
  
• Properties of Custom Publisher:
  

crl.application /fullpathname/exportscript.sh
crl.failOnStandardError <true | false>
crl.failOnErrorCode <true | false>
cert.application /fullpathname/exportscript.sh
cert.failOnStandardError <true | false>
cert.failOnErrorCode <true | false>
revoke.application /fullpathname/exportscript.sh
revoke.failOnStandardError <true | false>
revoke.failOnErrorCode <true | false>

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

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

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

• <cert.application> fulltempfilepathname x509type
  
• <revoke.application> fulltempfilepathname x509reason
  

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

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

• A CA signing keypair and certificate
  
• An encryption keypair, used for encrypting keyrecovery information
  
• An 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 not be ECDSA, but should be an RSA key. Your HSM must support both ECDSA and RSA keys.

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

• prime192v1
  
• prime192v2
  
• prime192v3
  
• prime239v1
  
• prime239v2
  
• prime239v3
  
• prime256v1
  

SEC curves:

• sect571r1
  
• sect409r1
  
• sect283r1
  
• sect233r1
  
• sect163r2
  
• secp521r1
  
• secp256r1
  
• secp224r1
  
• secp384r1
  

Nist curves:

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

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 and indicates 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 are configured in conf/ejbca.properties.
　　When creating a new CA using the implicitlyCA facility, you first configure your curve parameters in conf/ejbca.properties and issue commands:

• ant clean
  
• ant 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.
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 ECCurve.Fp(
new BigInteger(ecdsa.implicitlyca.q), // q
new BigInteger(ecdsa.implicitlyca.a, 16), // a
new BigInteger(ecdsa.implicitlyca.b, 16)); // b
org.bouncycastle.jce.spec.ECParameterSpec implicitSpec = new org.bouncycastle.jce.spec.ECParameterSpec(
curve,
curve.decodePoint(Hex.decode(ecdsa.implicitlyca.g)), // G
new BigInteger(ecdsa.implicitlyca.n)); // n
ConfigurableProvider config = (ConfigurableProvider)Security.getProvider(&quot;BC&quot;);
config.setParameter(ConfigurableProvider.EC_IMPLICITLY_CA, implicitSpec);

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 be generated in the file bin/batch.properties. The possible parameters are explained there. If using the implicitlyCA facility the same 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' with named curves any way you like though.

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 instance after 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 will be given unique names containing profile name and profile id. When importing profiles the profile name and id will be read from the filename. All profiles present in the specified directory will be imported.
　　Fixed profiles will not be imported, they will simply be skipped during import. If a profiles with the same name as the one being imported already exist, the profiles will not be imported.
　　Import of profiles try to keep the same profile id. If it already exist a profile with the same id in the database, you might have to edit the filename to choose another id. This can only be done if it is a new profile. The reason the id is kept is that there are references to the profile id from users belonging to the profile.
　　One issue to notice regarding import/export of profiles is that if you export an entity profile with 'Available CAs' put to a CA that does not exist where you import the profile, you will not see it. Before exporting the profiles, you should set 'Available CAs' to a CA that is also present (with the same DN=caid) on the other CA. This is not ideal, but it is a consequence of how the authorization system works, you are not authorized to see the imported profiles when the caid is unknown.

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 in the 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 the HSMs 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 &quot;TestCA&quot; to the PKCS#12-file &quot;/path/TestCA.p12&quot; with password &quot;foo123&quot; enter the following from the $EJBCA_HOME directory:

[user@host ejbca]$ bin/ejbca.sh ca exportca TestCA ./TestCA.p12
Using JBoss JNDI provider...
Enter keystore password: foo123
[user@host ejbca]$

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

[user@host ejbca]$ bin/ejbca.sh ca importca TestCA /path/TestCA.p12 SignatureKeyAlias EncryptionKeyAlias
Using JBoss JNDI provider...
Enter keystore password: foo123
[user@host ejbca]$

　　Enter the command:

[user@host ejbca]$ bin/ejbca.sh ca importca

　　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 sure that .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:

• Select &quot;Edit Certificate Authorities&quot; from the administrator menu.
  
• Select the CA you want to export and press the &quot;Edit&quot;-button.
  
• Go to the line where the help-text say &quot;CA export requires the keystore password&quot;.
  
• Enter the keystore password in the box to the right of the help-text.
  
• Press the &quot;Export CA keystore..&quot;-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 &quot;Edit Certificate Authorities&quot; from the administrator menu.
  
• Press the &quot;Import CA keystore..&quot;-button.
  
• Fill out the form with the CA's name, full pathname to the PKCS#12-file and keystore password.
  
• Keep the two &quot;Alias..&quot;-fields to the default value, if you used EJBCA to export the CA's keys.
  
• Press the &quot;Import CA keystore&quot;-button.
  

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/ejbca.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 are the web browser, application server, database and operating system, all working together. If you change to UFT-8 to handle your char set, 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 get mixed 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 checks for allowed characters in DN etc. The easiest way to resolve this is to go into the file:
src/adminweb/ejbcajslib.js
And 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 using Swedish 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 with the 'URIEncoding' directory in APPSRV_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml:

<Connector port=&quot;8443&quot; address=&quot;${jboss.bind.address}&quot;
maxThreads=&quot;100&quot; minSpareThreads=&quot;5&quot; maxSpareThreads=&quot;15&quot;
scheme=&quot;https&quot; secure=&quot;true&quot; clientAuth=&quot;true&quot;
keystoreFile=&quot;${jboss.server.home.dir}/../../bin/tomcat.jks&quot;
keystorePass=&quot;t0mcat.&quot; sslProtocol = &quot;TLS&quot; URIEncoding=&quot;UTF-8&quot;/>

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 line commands such as ca.sh and ra.sh). java -Duser.language=2-char-language-code -Duser.region=2-char-country-code example for Swedish: java -Duser.language=sv -Duser.region=SE
  
• Your database must also recognize the locale so it does not strip down to plain ascii. This is database and JDBC-driver dependent.
  

　　The admin GUI is meant to support multiple languages through language files in src/adminweb/languages. In order to add a language 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.
  
• Edit conf/ejbca.properties (create with conf/ejbca.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>
  
• You may have to change the default page encoding in 'web.contentencoding' to for example UTF-8 instead of the default ISO-8859-1.
  
• Clean and re-deploy ejbca with 'ant clean' followed by 'ant deploy'. Restart JBoss and your browser after this.
  

　　Now it should be possible to select EN, FR and IT in the system configuration as default language and in the administrator preferences 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 separately in 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 ejbca.properties file by setting the properties intresources.preferredlanguage and intresources.secondarylanguage to the language you want to use. The letters should be the same as the xx name in the intresources.xx.properties files in the src/intresources directory. The secondary resource file is used if the resource isn't found in the preferred language. This is a global setting that cannot be overridden by administrators own settings in the web-layer.

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=SE
Where 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 in the 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 that also when adding new users. If you edit profilemappings.properties, you should also add an entry in src/adminweb/languages/languagefile.XX.properties (where XX is you language). Otherwise your new field will be displayed as &quot;No text available&quot; in the admin-GUI. The new field you must add in the language file is the last field in profilemappings.properties, i.e. the LanguageConstant.
　　EJBCA will by default put unknown OIDs in 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 order regardless 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. There is a file called dncomponents.properties.sample in the distribution as a starting point (it shows the default ordering in EJBCA). You custom oid must be placed in the right place in that file, and all components from the sample file should be included, or you will get strange behaviour.
Using the dncomponents.properties file is only needed if you need to control the asn1 ordering of DN elements.
　　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 to know the oids as standard ones, things will be renamed in the database and you will have to do a database migration. Also you must keep 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 when upgrading 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 database will be for example &quot;rfc822Name=foo@bar.com, 1.1.1.1=foobar&quot;.
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 oid
  
• An 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 value can be added by simply editing a property file, these are called &quot;basic certificate extension&quot;. It is also possible to generate advanced certificate 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 1 up 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 example does 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 classpath org.ejbca.core.model.ca.certextensions.BasicCertificateExtension and specify the properties idX.property.encoding and idX.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.
  

Implementing an Advanced Certificate Extension
　　To create an advanced extension it is required to create a java class extending the CertificateExtension abstract class. One method getValue is required and the current user data, ca and certificate profile is sent to the extension in order to generate dynamic extensions.
　　Here is an example of a simple advanced extension. To add this extension to EJBCA add it to to the classpath in certextensions.properties, make sure the class is accessible in the classpath and redeploy.

public class SomeAdvancedCertificateExtension extends CertificateExtension {
private static String PROPERTY_SOMEPROPERTY = &quot;someproperty&quot;;
/**
* The main method that should return a DEREncodable
* using the input data (optional) or defined properties (optional)
*
* @see org.ejbca.core.model.ca.certextensions.CertificateExtension#getValue(org.ejbca.core.model.ra.UserDataVO, org.ejbca.core.model.ca.caadmin.CA, org.ejbca.core.model.ca.certificateprofiles.CertificateProfile)
*/
public DEREncodable getValue(UserDataVO userData, CA ca,
CertificateProfile certProfile) {
String value = getProperties().getProperty(PROPERTY_SOMEPROPERTY);
return new DERPrintableString(value);
}
}


Reference manual
　　All configuration options, JNDI names etc is configured through the use of a conf/ejbca.properties file.

Administrating CA
　　The CA has a command line interface 'bin/ejbca.sh ca. Options are:

• info - prints information about a CA.
  
• init - creates a new Root CA.
  
• listcas - lists all CAs in the system.
  Stores CA certificates and publishes first CRL. Quote the DN (&quot;) so it is treated as one argument.
  
• getrootcert - exports the CA certificates to file.
  
• createcrl - issues a CRL. With no CA name given it issues all CRLs that are 'due'. If a CA name is given CRL generation for that CA is 'forced'.
  
• getcrl - retrieves the latest CRL.
  
• listexpired - List certificates that will expire within a given number of days.
  
• exportprofiles - exports entity and certificate profiles to xml-files.
  
• importprofiles - imports entity and certificate profiles from xml-files. When you export a profile that should be imported in another CA, make sure the 'Available CAs' is set to 'Any CA' for the profiles you export. Otherwise you can get into trouble with authorization if you don't have the same CAs with the same caids (DNs) where you import the profiles.
  
• importca - creates a new CA by importing keys from en existing PKCS12 file. A PKCS12 file can be generates from PEM files with openssl.
  
• importcert - creates a user and imports a certificate for him/her.
  
• republish - republishes certificates for a CA and all users. Can be used to add a publisher to a CA after some time, and then publish all certs. You can add the flag '-a' after the command to publish all certificates for all users. Note, that this command relies upon the publisher for the users profiles to do it's job. So if you have changed profiles for users, the result may not be as expected, but ut may be depending on how your profiles are constructed.
  

Administrating RA
　　The RA has a command line interface 'bin/ejbca.sh ra'. Options are:

• adduser - adds a user to the database, after addition a user may apply for a certificate. If email address is set to 'null', no email is put in certificates. Quote the DN (&quot;) so it is treated as one argument. Altnames is a string similar to the DN string but using alternative names from RFC3280, i.e. &quot;rfc822Name=email, dNSName=hostname, uri=http://whatever, iPAddress=10.56.32.245&quot; The full list is: otherName, rfc822Name, dNSName, x400Address, directoryName, ediPartyName, uniformResourceIdentifier, iPAddress, registeredID Only rfc822Name, dNSName, iPAddress, uniformResourceIdentifier (uri) and directoryName is supported at the moment. Also the MS UPN and GUID are supported.
  
• deluser - removes a user from the database, any issued certificates remain active and present in the database.
  
• setpwd - set a new password for a user. The password is stored as a hash in the database.
  
• setclearpwd - set a clear text password for a user, needed to generate certificates batch-wise.
  
• setuserstatus - sets status of a user, users can only apply for certificates when their status is NEW.
  
• finduser - find a user in the database and lists details.
  
• getusercert - get all certificates for a specific user on stdout.
  
• listnewusers - lists all users with status NEW.
  
• listusers - lists users with specified status (give command to see list of status codes).
  
• revokeuser - revokes a user and all certificates issued to the user.
  
• keyrecover - recovers keys related to a specific certificate.
  
• keyrecovernewest - recovers the latest keys for a user.
  
• setsubjectdirattr - add subject directory attributes for a user.
  

Other Configuration
　　To setup an initial hard token issuer with alias 'local' and queue the admin user for card issuing:

bin/ejbca.sh setup initializehardtokenissuing <caname>
Ex: bin/ejbca.sh setup initializehardtokenissuing AdminCA1

　　This is a utility function to quickly an easily issue an initial administration smart card.
　　If you want to change the baseurl of the admin-web after installation use the command:

bin/ejbca.sh setup setbaseurl computername applicationpath
Ex: bin/ejbca.sh setup setbaseurl localhost ejbca

　　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 the properties httpserver.pubhttp, httpserver.pubhttps and httpserver.privhttps. After changing, run 'ant deploy' and re-start the application server.

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

bin/ejbca.sh asn1dump <filename-of-pem-encoded-certs or filename-of-der-encoded-asn1>
Ex: bin/ejbca.sh asn1dump adminca1.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 all users designated as NEW or FAILED in the local RA database. To be able to batch generate certificates, the users must be registered with clear text passwords. To set a clear text password for a user use

bin/ejbca.sh ra setclearpwd username password

　　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

bin/ejbca.sh batch username

　　Generated keystore files are stored in a subdirectory (to the current directory) called 'p12'. If the directory does not exist, it will be 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 ra adduser' 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 the CA is deployed integrated in another J2EE application, this front-end may not be needed.

Certificate- and EndEntity Profiles
　　CertificateProfiles define different types of certificates, with regards to DN-contents, extensions etc. We also have EndEntityProfiles, where users are grouped, and you can determine which parts of their DN that is already pre-set, and which can be altered etc.
　　An EndEntityProfile can be connected to specific CertificateProfiles so users belonging to a specific EndEntityProfile can only get certificates from the specified CertificateProfile.

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 in conf/custom.properties or use the default location '$EJBCA_HOME/../ejbca-custom'. Your modifications will automatically overwrite any 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.
　　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 the different 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 and makes 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 a separate tree), rebuild and redeploy. The changes should show on http://ejbcahost:8080/ejbca.

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.
  
• Configure the CA id in rc/java/org/ejbca/ui/web/pub/DemoCertReqServlet.java, it's the parameter DEFAULT_DEMOCAID.
  
• Edit src/publicweb/publicweb/WEB-INF/web.xml and uncomment the two sections for the demo servlet.
  
• 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-entry 'contentEncoding'. Otherwise national characters in names will be encoded/displayed incorrectly in the certificates.
  
• Deploy with 'ant deploy'.
  
• Create an end entity profile and a certificate profile that should be used for the demo certificates.
  
• Create a demo apply page containing something similar to the sample form below for Mozilla/Firefox. There are some sample scripts under src/publicweb/publicweb.
  

<form name=&quot;demoreq&quot; action=&quot;http://127.0.0.1:8080/ejbca/democertreq&quot; method=&quot;post&quot;>
Please fill out the form and click <b>Enroll</b> to receive your certificate.
Read our <a href=&quot;http://www.primekey.se/primekey/en/Demo.html&quot;>privacy policy</a>.<br>
<input name=&quot;certificateprofile&quot; value=&quot;DemoCertProfile&quot; type=&quot;hidden&quot;>
<input name=&quot;entityprofile&quot; value=&quot;DemoEntityProfile&quot; type=&quot;hidden&quot;><br>
<br>
Full name:
<input name=&quot;user&quot; value=&quot;C=SE,O=PrimeKey Solutions AB,OU=Demo,CN=&quot; size=&quot;25&quot; maxlength=&quot;60&quot; class=&quot;input&quot; type=&quot;text&quot;>
<p align=&quot;left&quot;> E-mail:
<input name=&quot;email&quot; size=&quot;25&quot; maxlength=&quot;60&quot; class=&quot;input&quot; type=&quot;text&quot;>
<input name=&quot;includeemail&quot; value=&quot;true&quot; type=&quot;hidden&quot;>
</p>
<p align=&quot;left&quot;> Choose key length from the list below. The default is recommended in most cases. <br>
<br>
<keygen type=&quot;hidden&quot; name=&quot;keygen&quot; value=&quot;challenge&quot;>
</p><p align=&quot;left&quot;>
<input value=&quot;Enroll&quot; name=&quot;submit&quot; type=&quot;submit&quot;>
</form>

　　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 DN to 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:

    log4j.rootCategory=INFO, Console

　　in the file 'log4j.properties' with:

    log4j.rootCategory=DEBUG, Console

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 using out-of-the-head commands so don't expect it to work by copying and pasting these commands, it just something to look at.
　　0. Set the baseurl of the server with the command 'setup.sh/cmd setbaseurl computername applicationpath' Set the BASEURL to reflect 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 file 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 and then generating a certificate request that is processed by EJBCA, and last import the returned certificate and the CA-certificate into the keystore).
　　Create a user in EJBCA, DN=&quot;C=SE,O=PrimeKey,CN=your-host-name&quot;.

bin/ejbca.sh ra adduser tomcat foo123 &quot;C=SE,O=PrimeKey,CN=your-host-name&quot; null caname null 1 3

　　Set a clear text password for the tomcat:

bin/ejbca.sh ra setclearpwd tomcat foo123

　　Generate a JKS-keystore for tomcat:

bin/ejbca.sh batch tomcat

　　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 -import -trustcacerts -file ejbca-ca.pem -keystore p12/truststore.jks -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).

bin/ejbca.sh ra adduser raadmin foo123 &quot;C=SE,O=PrimeKey,CN=SuperAdmin&quot; null caname null 65 1

　　Alternative: Create a PKCS12 file with EJBCA for a user with CN=SuperAdmin and the RAADMIN bit (temporarily CN=SuperAdmin gives adminrights).

bin/ejbca.sh ra adduser raadmin foo123 &quot;C=SE,O=PrimeKey,CN=SuperAdmin&quot; null caname null65 2
bin/ejbca.sh ra setclearpwd raadmin foo123
bin/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 Mozilla this is done by Edit->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

keytool -genkey -alias tomcat -keystore tomcat.jks -keyalg RSA -dname &quot;C=SE,O=AnaTom,CN=hostname&quot; -storepass foo123
keytool -certreq -alias tomcat -keystore tomcat.jks -sigalg SHA1WithRSA -storepass foo123 -file tomcat.req
bin/ejbca.sh ra adduser tomcat foo123 &quot;C=SE,O=AnaTom,CN=hostname&quot; null caname null 1 JKS
bin/ejbca.sh ca processreq tomcat foo123 tomcat.req tomcat.pem
bin/ejbca.sh ca getrootcert ca.der -der
keytool -import -trustcacerts -alias cacert -file ca.der -keystore tomcat.jks -storepass foo123
keytool -import -alias tomcat -file tomcat.pem -keystore tomcat.jks -storepass foo123
keytool -import -trustcacerts -file ca.der -keystore p12/truststore.jks -storepass changeit
ant deploy