Administrative tutorials

There are additional documentation and administrative tutorial movies at http://wiki.ejbca.org/.

Administrating EJBCA

You can administer 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

Finally you can also use the EJBCA client toolbox to perform administrative tasks using web services.

Publish queue status

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

CA Status

The CA status overview shows ok or error if CAs are off line and if CRLs are not valid.
CA Status shows a red error if the CA is not on-line or the CA token is not in line. External CAs are always show as ok.
CRL status show a red error is a CRL or delta CRL has expired without a new one being created. Delta CRLs are only monitored if used.

Creating CAs

After installation, which creates a default admin CA you can create more CAs.
Creating CAs can be made using the Admin GUI or the command line interface (CLI). The recommended way is using the Admin GUI, since it gives more control of all parameters.

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.

ejbca.sh ca init

bin/ejbca.sh ca init TestRoot "C=SE,O=PrimeKey,CN=TestRoot" soft foo123 2048 RSA 265 2.5.29.32.0 SHA256WithRSA

CA fields

Creating a SubCA signed by an external CA

Some CA hierarchies have the requirement of being signed by an external Certificate Authorities and sometimes other external CA:s need to be signed by your CA.

When creating a CA that is signed by an external CA, you create a PKCS10 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.

In order to have your CA signed by an external CA you have to go through the following steps.

1. Go the the 'Edit Certificate Authorities' page in the Administration GUI.
2. Create a new CA in the same way as internal CA:s. But when selecting signing CA, select 'External CA' instead. The fields 'Certificate Profile', 'Validity', 'Subject Alternative Name' and 'Policy Id' will become gray and are no longer editable. Fill in the Description and CRL Specific data and click on the 'Make Certificate Request' button in the bottom of the page.
3. At the next page called 'Make Certificate Request' you can upload the external CA certificate chain that you want to sign your CA certificate with, or you can wait until later by checking 'No CA chain file available'. This file should be in PEM encoding. If there is more than one top CA certificate then all their certificates should be appended into one single file. It should be in plain PEM format without blank lines before or after. An example is below.
4. After successfully clicking 'Make Certificate Request' the generated PKCS10 certificate request will be displayed. You can copy and paste it to the signing CA or download the PEM file if that approach is preferred.
5. The external CA should sign the certificate request and return a certificate. Meanwhile, the newly created CA will have the status 'Waiting for Certificate Response' and will not appear anywhere in the system except in the 'Edit CA' page.
6. When the Certificate Response has arrived, it is time to activate the new CA. You mark the waiting CA and click on 'Edit' button in the 'Edit CA' page. Go to the bottom of the page and click on 'Receive Certificate Response' (you can leave the password field blank). Then upload the received certificate and click again on 'Receive Certificate Response'.
7. If the received certificate forms a valid certificate chain with the previously uploaded top CA certificates, the status of the CA will be set to 'Active'.
8. If you did no upload a certificate chain when the request was created, you can do so now by uploading the complete PEM formatted chain. The CA's own certificate should be first in the file, followed by the issuing CAs certificate(s). When uploading a chain, the certificates must be converted to PEM format if it isn't already so. This can be accomplished with OpenSSL among other tools with the following command if you have received a file in DER encoding (.cer ending):
   openssl x509 -inform DER -in filename.cer -outform PEM -out filename.pem
9. If you want to activate OCSP functionality for this new CA you have to edit it once again and mark the OCSP functionality as active.
10. The new externally signed CA is ready to use.

Example of a plain PEM file for uploading as a certificate chain:

-----BEGIN CERTIFICATE-----
MIIDSjCCAjKgAwIBAgIIEvabM2CgLZcwDQYJKoZIhvcNAQEFBQAwMzETMBEGA1UE
AxMKV2FsdGVyIENBMTEPMA0GA1UEChMGV2FsdGVyMQswCQYDVQQGEwJTRTAeFw0w
MzA5MjkwOTI2MzRaFw0wNDA5MjgwOTM2MzRaMDMxEzARBgNVBAMTCldhbHRlciBD
QTExDzANBgNVBAoTBldhbHRlcjELMAkGA1UEBhMCU0UwggEgMA0GCSqGSIb3DQEB
AQUAA4IBDQAwggEIAoIBAQC3hXksEud68WwPWWHLJQQkTCuX/K32KHPPn/uPUzab
Cpc/FnaTmF9yEHmpFdAUr0v5ZPnxVQpcuwrDZc4YfaTLfyUHicQbkftsPAj/2hE4
UukS2j+nQQcJEnIY0vSZOAOLU3j4bf/RlS6Jl7TPFFfWTxuQF8AruQ+YhaE52JFi
SapGGXKQJxhsvKT91rLaWSFWNMTTLSDPaBXYEYFuFhLNclDJWf4whfxHSHHkARB/
3Z0XlT4sFj0fmqEQ6yQb6/WqMFK+1XAIBXZO2MXe26IigWkXw1GfkIx1+fbUPrzu
8EI2jb0TWl21j1+Mvh3APZtVj5FJNuZN9bgdbrq88hLXAgERo2QwYjAPBgNVHRMB
Af8EBTADAQH/MA8GA1UdDwEB/wQFAwMHBgAwHQYDVR0OBBYEFNhHOtAwo8MOE/nI
zzg9KFxCYs8YMB8GA1UdIwQYMBaAFNhHOtAwo8MOE/nIzzg9KFxCYs8YMA0GCSqG
Sib3DQEBBQUAA4IBAQBHpvicbuJTACtpdwe6cF1nQ57FHnnYr+aAe+ZpH43R6R9d
eMps02nFAMSs5o8sbPokrpwAtk2yYwCohEFDkZ5JPzIBkgNlNnVHNNRHQTRJ6v6Q
F2MWUEPc1u5kxSjXEVMmZerG9oknMwpYFmkOnKF46vP3Njt/ExOeRAvCEQq2b8pz
2QGg8/IK6Omfi7IwxtVYUpgvhdcWekbFIlxkXZiEdlHNBIV1GzzPK1VEzg5kugD/
h6jeykrsKASx+55AkkBPt2kI+ZikVtp3SVhfZQMGY86c5QMQGlPWYNsr4ociyhfX
I52Qby+/HNG1ijpx66Z30lUMmXTtWtL4Cu8s7UvC
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICxzCCAa+gAwIBAgIIBfqGjbQu14swDQYJKoZIhvcNAQEFBQAwMzETMBEGA1UE
AxMKV2FsdGVyIENBMTEPMA0GA1UEChMGV2FsdGVyMQswCQYDVQQGEwJTRTAeFw0w
MzA5MjkwOTMzMDFaFw0wNDAxMDcwOTQzMDFaMDQxETAPBgNVBAMTCER1ZGUgQ0Ex
MRIwEAYDVQQKEwlEdWRlIEluYy4xCzAJBgNVBAYTAlNFMIGdMA0GCSqGSIb3DQEB
AQUAA4GLADCBhwKBgQCM1hR/DYPXfKDa3oVJbppV4OcYtn2XP9W5Kc1d0+U4qLOm
JsqIFHDWR07o1QFiPhc9z0UGtwYeE3CpQ8fG8zeur5e286PYptZIST77B9vOdQdl
PA+dFKFIaEwdzcS7H3Lf38WTE4D1OnyRX5jsiUe+YIQRtjv/Bmem+kSR84G9TwIB
EaNkMGIwDwYDVR0TAQH/BAUwAwEB/zAPBgNVHQ8BAf8EBQMDBwYAMB0GA1UdDgQW
BBTDrXZGYXS9GyIUBOZrglhwNjjcnTAfBgNVHSMEGDAWgBTYRzrQMKPDDhP5yM84
PshcQmLPGDANBgkqhkiG9w0BAQUFAAOCAQEAdmTP1qVUcAKOf+/zvb2lcLKvFwKT
6KqDlO5NofjqCIfNgCjO2mO176cslnFIbEZQqgGIUnJ3AwfHKHj+U3kM3n5T29kF
xiLKxIDfjsY6qC03KHeGAgxI92XZyPsO1is6Y6qUnAmiwhIp5HS6E0+xIP1shmtJ
ZvqU8bueKUWSjx3JDzq+UNLX5pFkK0P0R90TCUEkBx1FNWqoWwb8zfAuO5zcNTEj
5E9esLjwxJQnIVPiA2l3FfZN9yomK+q7kTZJkX2kMx7G850lPR8CneXZT6bIOfck
Dw3PqQiroMNx2+gzC/f/wTXsF92aujyG+IZx1FIcNg/MoHXBWG7T8YrjnQ==
-----END CERTIFICATE-----

You can treat an internal CA (a CA residing on the same EJBCA instance as another CA) as an external CA. From the SubCA this works just like the normal case, but on the RootCA you must choose the exact same CA Name as the already existing internal CA when you choose to "Process Certificate Request".
This can be useful if you have an HSM setup where only one set of keys can be active at one time, for example using nCipher with two different, non-persistence, operator cards sets for the RootCA and the SubCA. Using the SubCA as an external CA you can still create the PKI but with only one CA active at a time.

Signing an External CA

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

1. Create a certificate profile and an end entity profile for Sub CAs. The certificate profile must be of type 'Sub CA' (almost at the bottom of the edit certificate profile page).
2. Create an End Entity where you select a SubCA certificate profile when adding the end entity.
3. Issue the CA certificate as you would normally issue any end entity certificate.
4. The SubCA can be managed and revoked conveniently just as other end entities.

You can however also get the external Sub CA visible as a CA in EJBCA.

1. In the 'Edit CA' page, enter a CA name of the external CA you are about to sign and click on 'Process Certificate Request'.
2. Then you are requested to upload the certificate request sent from the external CA. This should be a file in PEM-encoding.
3. The next step is to fill in the data about the CA certificate you are about to create. This is very similar to when you are creating an internal CA but with a fewer fields. The Subject DN is taken from the request. But the signing CA, certificate profile, validity, subject alt name and policy id have to filled in manually.
4. After clicking 'Process Certificate Request' the certificate is created and displayed in PEM format. You can also download it as a regular PEM file or as a PKCS7 PEM file.
5. Send the processed certificate back to the external CA for activation.
6. In the 'Edit CA' page will the newly processed CA be displayed with the status 'External'. This processed CA will only be shown in the 'Edit CA' pages and nowhere else since the system cannot use it. If you want to view the processed certificate, go to the edit page and click on the 'View CA Certificate' link in the bottom of the page.

Renewing a SubCA signed by an external CA

When you renew a SubCA signed by an external CA you create a new request that is sent to the external CA. The External CA issues a new certificate that you import in your SubCA.

You can renew the SubCA in two ways:

1. Using the same CA signing keys.
2. Generating new CA signing keys.

1. Activate keys (default) - immediately activates the new keys. This makes the SubCA off-line waiting for the certificate response. The SubCA can not issue certificates until the response from the External CA is received.
2. Do not activate keys - generates new keys and a request, but does not activate the new keys. The SubCA can continue to issue certificates with the old signing keys until the response is received from the External CA.

Note how PKCS#11 sessions works, once logged in to the session you are logged in and it does not matter which password you use in the GUI. Don't be surprised that it works with any password when using PKCS#11 CA tokens.

Requesting a cross or bridge certificate

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

1. In the 'Edit CA' page, choose a CA that you intend to get cross certified by another CA by and click on 'Edit'.
2. In the lower part of the screen, click on 'Make Certificate Request'.
3. Now check 'No CA chain file available' and click 'Make Certificate Request'.
4. Save the created PKCS#10 certificate request to disc and send to the other CA.

Now you have a certificate request to send to the other CA or Bridge CA. When the other CA have issued a certificate for you, everything is completed. You don't need to (and you can not) import the cross-certificate or bridge-certificate in EJBCA. What you need to do is make sure the clients using the certificates issued by your CA have access to the correct certificate chain. If you are cross-certified with several other CA, multiple possible certificate chains exist.
Handling the certificate chains on clients is out of the scope for EJBCA.

Signing a roll-over certificate (NewWithOld)

One way to handle update of trust points when renewing a Root CA is to generate a certificate that contains the new key signed with the old key. For X.509 CAs you can create such a certificate:

1. In 'Edit CA' screen, renew a Root CA, selecting to also renew keys.
2. Download the new Root CA certificate.
3. In the Edit Certificate Authorities screen, type the name of the CA in the input field and click 'Sign Certificate Request'.
4. Upload the new Root CA certificate, select the checkboxes 'Use previous key' and 'Create link certificate' and click 'Sign Certificate Request'.

The certificate that you upload must have the same DN as the CA you selected, and the certificate must also be verifiable using the CAs currently active signature keys. This means that you can only use this function to create a 'NewWithOld' certificate, and not for other signing purposes.

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 Admin GUI or the CLI. See the section 'Export and import CAs'.
After importing CAs you can also import users and certificates. See the section 'Import users'.

Create a Certificate Profile for SSL servers

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

• Under "CA Functions", press "Edit Certificate Profiles".
• Enter a name for your end entity certificate profile e.g. "SSLServerCertificateProfile", and press "Add".
• Select "SSLServerCertificateProfile" and press "Edit Certificate Profile".
• Under "Validity" enter 365d (1 year validity).
• Under "Key usage", choose "Digital Signature" and "Key encipherment (ctrl-click to select multiple).
• Un-check "Allow Key Usage Override".
• Check "Use Extended Key Usage".
• Under "Extended Key Usage", choose "Server Authentication".
• Under "Available bit lengths", "1024 bit", "2048 bit" and "4096 bit".
• Under "Available CAs", choose your CA "AdminCA1" (the CA you use to issue server certificates).
• Under "Type", select "End Entity".
• Press "Save"

Another way of creating a new Certificate Profile is to use an existing profile as template:

• In the list of certificate profiles, select the filed profile SERVER.
• Enter a name for your end entity certificate profile e.g. "SSLServerCertificateProfile", and press "Use selected as template".
• Press "Save"

Certificate Profile fields

create unique index certificatedata_idx1 on CertificateData (issuerDN,serialNumber);

JAVA_OPT="-DmaxCertSN=16" $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh EjbcaWsRaCli stress WsCA1 20 2000 wsCreatedUser wsCreatedUser

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

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

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

An optional system to which a CA delegates the publication of certificate revocation lists;

notBefore = cert.notBefore + startOffset
notAfter = notBefore + periodLength

Create an End Entity Profile for SSL servers

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

• Under "RA Functions", press "Edit End Entity Profiles".
• Enter a name for your end entity profile e.g. "SSLServerEndEntityProfile", and press "Add".
• Select "SSLServerEndEntityProfile" and press "Edit End Entity Profile".
• Under the "Subject DN Fields" select "O, Organization" and press "Add".
• At "O, Organization" enter "EJBCA Edu" in the textbox, check the "required" checkbox and uncheck the "modifiable" checkbox.
• Under the "Subject DN Fields" select "C, Country" and press "Add".
• At "C, Country" enter "SE" in the textbox, check the "required" checkbox and uncheck the "modifiable" checkbox.
• Under the "Subject Alternative Fields" select "DNS Name" and press "Add".
• Uncheck "Use" at "Email Domain".
• Under "Default Certificate Profile", choose "SSLServerCertificateProfile" (created earlier).
• Under "Available Certificate Profiles", choose "SSLServerEndEntityCertificateProfile".
• Under "Default CA", choose "AdminCA1" (the CA you use to issue server certificates).
• Under "Available CAs", choose "AdminCA1" (same as above).
• Under "Default Token", choose "User Generated".
• Under "Available Tokens", choose "User Generated", "P12", "JKS" and "PEM" (ctrl-click to select multiple).
• Press "Save".

End Entity Profile fields

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

org.ejbca.core.model.ra.raadmin.UserDoesntFullfillEndEntityProfile: Subject DN field 'ORGANIZATIONUNIT' must exist. 

192.168.2.54

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

user@PRIMEKEY.SE

krbtgt/PRIMEKEY.SE@PRIMEKEY.SE

1.2.3.4.value = 65486c6c206f6f776c720064
1.5.6.value = Hello world

id1.oid = 1.2.3.4
id1.classpath=org.cesecore.certificates.certificate.certextensions.BasicCertificateExtension
id1.displayname=SingleExtension
id1.used=true
id1.translatable=false
id1.critical=false
id1.property.dynamic=true
id1.property.encoding=RAW

Plug in field restrictions

Administrators can develop further custom user field restictions using the Fieldvalidator as described in Customizing 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 "C=SE,O=MyOrg,OU=MyOrgUnit,CN=MyName". If a ',' is needed in the DN the comma must be escaped using '\,'.

Create server certificates

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

1. Create desired profiles (the default entity and certificate profiles work fine, but are perhaps too generic). You certificate profile should have:
   - KeyUsage: Digital signature, Key encipherment
   - Extended key usage: Server Authentication
   
2. Create a user with the Admin GUI 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: "C=SE,O=AnaTom,CN= www.anatom.se", or for mailserver "C=SE,O=AnaTom,OU=Engineering,CN=mail.anatom.se".
   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.
3. 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'
4. 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 "User generated". 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 "Certificate Enrollment->manually for a server".

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.

Issue a new PKCS#12 keystore for an SSL server

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

• Goto "RA Functions" -> "Add End Entity".
• Choose the end entity profile "SSLServerEndEntityProfile".
• At "Username" enter "testsrv.domain.com".
• At Password enter a password.
• Under "CN, Common Name" enter "testsrv.domain.com".
• And at "DNS Name" enter "testsrv.domain.com".
• Under "Certificate Profile" you should not be able to choose anything but the default "SSLServerCertificateProfile".
• Under "CA" you should not be able to choose anything but the default "AdminCA1".
• Under "Token", choose "P12".
• Press "Add End Entity".
• Goto "Public Web" and then "Create Keystore".
• Enter the username, testsrv.domain.com, and password for the user you created, and press "OK".
• Choose "Key length" "1024".
• Under "Certificate Profile" you should not be able to choose anything but the default "SSLServerCertificateProfile" .
• Press "OK".
• A new certificate will be generated and downloaded to your desktop.
• If you like you can import the P12 file (double-click it on windows) to look at the certificate inside.

Issue a new server certificate from a CSR

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

• Goto "RA Functions" -> "Add End Entity".
• Choose the end entity profile "SSLServerEndEntityProfile".
• At "Username" enter "testsrv.domain.com".
• At Password enter a password.
• Under "CN, Common Name" enter "testsrv.domain.com".
• And at "DNS Name" enter "testsrv.domain.com".
• Under "Certificate Profile" you should not be able to choose anything but the default "SSLServerCertificateProfile".
• Under "CA" you should not be able to choose anything but the default "AdminCA1".
• Under "Token", choose "User Generated".
• Press "Add End Entity".
• Goto "Public Web" and then "Create Certificate from CSR".
• Enter the username, testsrv.domain.com, and password for the user you created. Paste the CSR from the server and press "OK".
• A new certificate will be generated so you can download it to your desktop.

Create User certificates

To enroll for a certificate using a browser, go to http://your_server_name:servlet_container_port/ejbca/ (e.g. http://127.0.0.1:8080/ejbca/) and select "Create Browser Certificate". Enter username and password, click the "OK"-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 "Create Server Certificate" 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.

Certificate Renewal

Certificate renewal is a often missunderstood term. Certificate renewal simply means issuance of a new certificate containing the same public key as an already issued certificate. It does not mean issuing a new certificate with the same certificate serial number, and it does not mean that the CA in some magical way has access to the end entitys private key.

To renew a certificate using the admin GUI, simply:

1. Go to 'Search/Edit End Entities' and find the end entity in question.
2. Set status to NEW.
3. Have the end entity create a new certificate request (CSR), using the same public key as the first certificate.
4. Send the new certificate request to the CA (the same way you did when getting the first certificate).
5. Get the certificate back.

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

Request Browser Certificate Renewal

If renewal is enabled there is an extra link under "Enroll" on the public web page called "Renew Browser Certificate". The page requires authentication with a client certificate and makes it possible for the user to request the certificate to be renewed.

The renewal functionality is provided in a separate web module called renew.war which is not deployed and linked to by default. It can be enabled in conf/web.properties by setting web.renewalenabled=true and then (re-)deploy EJBCA.

Administrators issued by external CAs

Administrator certificates in EJBCA does not have to be issued by a CA in the same installation, but can be issued by any other CA. By leveraging this feature you can for example use a national ID for administration of an organizational PKI

To use a certificate issued by an external CA as Administrator:

1. Add the CA-certificate to p12/truststore.jks with keytool -import -trustcacerts -file externalca.pem -keystore p12/truststore.jks -storepass changeit -alias externalca
2. Redeploy EJBCA (ant deploy) and restart the application server to make sure the new truststore is in use
3. Import the CA-certificate under "Admin GUI - Edit Certificate Authorities - Import CA Certificate.." or use the CLI
4. Add the Administrator to the desired Administrator group under "Admin GUI - Edit Administrator Privileges"
5. To allow administrators to log in when their certificates are not present in the EJBCA database you have to set web.reqcertindb=false in conf/web.properties.

bin/ejbca.sh ca importcacert AdminCA adminca.pem -initauthorization

Renewing Superadmin

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

Using the admin GUI:

• Go to Search/Edit End Entities.
• Search for user 'superadmin'.
• Click Edit End Entity.
• Set a new password and set status to NEW, click Save.
• Go to Public Web and then Create Keystore.
• Enter superadmin username, and the password you gave.
• In the next screen, select key length 2048 and click OK.
• Your new superadmin keystore is downloaded. You can install it in your browser.

Using the CLI:

bin/ejbca.sh ra setuserstatus superadmin 10
bin/ejbca.sh ra setclearpwd superadmin password
bin/ejbca.sh batch

Your new superadmin keystore is generated and stored in sudirectory p12. The password is password, as given to the setclearpwd command.

Pre-defined roles

The current predefined administrator roles that exists in EJBCA are:

• The CA administrator:
• manages certificate profiles
• manages end entity profiles
• manages log configuration
• can create RA administrators
• can renew a CA with new certificate and new keys
• The RA administrator:
• can create end entities
• can modify end entities
• can revoke end entities
• can delete end entities
• can view existing end entities and their history
• The supervisor:
• can view created end entities
• can search the log and see who have done what
• The super administrator:
• has overall access to EJBCA
• can edit system configuration
• can manage CAs
• can manage publishers (LDAP, AD, custom)
• can create CA administrators

Creating a Certificate Profile For the Administrator

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

• Under "CA Functions" -> "Edit Certificate Profiles"
• Enter a name for your end entity certificate profile e.g. "AdministratorEndEntityCertificateProfile"
• Select "ENDUSER"
• Press "Use Selected as Template"
• Select "AdministratorEndEntityCertificateProfile"
• Press "Edit Certificate Profile"
• Under "Validity" enter 365d (1 year validity).
• Under "Key usage", choose "Digital Signature" and "Key encipherment (ctrl-click to select multiple).
• Un-check "Allow Key Usage Override".
• Check "Use Extended Key Usage".
• Under "Extended Key Usage", choose "Client Authentication".
• Under "Available bit lengths", "1024 bit", "2048 bit" and "4096 bit".
• Under "Available CAs", choose "AdminCA1" (the CA you use to issue admin certificates).
• Press "Save".

Creating an End Entity Profile for the Administrator

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

• Under "RA Functions" -> "Edit End Entity Profiles"
• Enter a name for your end entity profile, "AdministratorEndEntityProfile"
• Press "Create"
• Select "AdministratorEndEntityProfile" and press "Edit End Entity Profile"
• Under the "Subject DN Fields" add a few DN fields that you want in the admin DN, for example O, UID and C.
• Under "Default Certificate Profile", choose "AdministratorEndEntityCertificateProfile"
• Under "Available Certificate Profiles", choose "AdministratorEndEntityCertificateProfile"
• Under "Default CA", choose "AdminCA1"
• Under "Available CAs", choose "AdminCA1"
• Press "Save"

Creating a new RA Administrator group

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

• Choose "Edit Administrator Privileges" in the left frame.
• Press "Add".
• Choose a name for your new administrator group, "RAAdministratorGroup".
• When the group is created, press "Access Rules".
• Choose the administrator groups role, "RA Administrator".
• Under "Authorized CAs", choose which CAs the administrator group should have access to. Choose "AdminCA1".
• Under "Edit End Entity Profiles" Select "AdministratorEndEntityProfile".
• Press "Save".

Adding new Administrators to the RA Administrator group

• Choose "Search/Edit End Entities" and select your newly created end entity, choose "View Certificates".
• Copy the value of "Certificate Serial Number", e.g. "5F003A0113F507F9".
• Go to "Edit Administrator Privileges", press "Administrators" under "RAAdministratorGroup".
• Choose the CA that the administrator belongs to, "AdminCA1".
• Paste the text from "Certificate Serial Number" in the "Match value".
• Press "Add"

Test the new administrator

Try to log in with the new administrators to see the difference between that and the superadmin. You should also try the different roles and privileges to see the differences between them all.

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

Event

You can chose what kind of event to see. For example, Administrators logged in, CA related activities, certificate related activities, End Entity related activities, activities that caused error... etc.

CA

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

Module

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

Username

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

Certificate

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

Administrator Certificate

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

Comment

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

Administrator Type

You can chose to see all the logs created by a specific type of administrator. There are six types of administrators:

• An administrator who logs in with a certificate. Typically an administrator who logs into the Admin GUI to perfom tacks that need administrator privileges. An administrator who logs in with a certificate is loged with his certificate serialnumber and SubjectDN.
• An administrator who logs into the public web using only username and password. An administrator who logs into the public web is loges with his IP address.
• An RA user. The RA user is loged with his IP address.
• An administrator performing administrative tasks through commandline.
• An administrator performing administrative tasks through batch commandline.
• An internal user performing tasks within Ejbca.

Building and running

The application is built from the EJBCA directory by typing 'ant batchenrollment-gui' and can then be started with the scripts 'bin/batchenrollmentgui.sh' or 'bin/batchenrollmentgui.cmd'.

Using

When the application starts the connection dialog asks for connection information and login credentials. You need to supply some sort of truststore and keystore in the same way as when using the web services interface. When using PKCS11 the keystore file path should be the path to the PKCS#11 shared library.

Enroll end entities:

1. Drag and drop certificate signing requests to the table in the main window or use the button Add... to browse for the files.
2. For each request map it to an end entity and choose an output filename for the resulting certificate.
3. Click the button Enroll.

Signed requests

The application also supports signed certificate signing requests. That is requests that are wrapped in a PKCS#7/CMS structure also containing a signature and a signing certificate that can be verified by the application before issuing the certificate. In order for the verification to work the Batch Enrollment GUI needs to have a PEM file with trusted certificates configured under the menu Edit -> Settings....

Backup and restore of EJBCA

To backup an EJBCA installation you need to:

• Backup the database
• Backup all $EJBCA_HOME/conf/**
• Backup all $EJBCA_HOME/p12/**

• Restore database
• Unzip new EJBCA
• Restore conf and p12
• Run "ant deploy" to configure JBoss and deploy EJBCA. If you are using another application server, consult the Installation doc for deployment.

If you are using soft keystores for the CAs this is all that is needed. If you are using an HSM you need to backup your keys in the HSM as well. How this backup and restore is done depends on the HSM you are using. Consult the documentation for your HSM.

SSL certificate expire

The SSL certificate used for SSL in JBoss 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:

1. Go to 'List/Edit End Entities' and search for user 'tomcat'.
2. 'Edit_End_Entity' and set the 'Password' to the same as httpsserver.password in your conf/web.properties and 'Status' to 'New'.
3. Open up a command line in EJBCA_HOME and run 'bin/ejbca.sh batch'.
4. 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.
5. Restart JBoss.

You can also do everything using the CLI:

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

1. ant renew-keystore
2. cp p12/tomcat.jks $APPSRV_HOME/server/default/conf/keystore.jks
3. Restart JBoss.