installing ejbca 6.1.1 and jboss on centos 6

8/18/2019 Installing EJBCA 6.1.1 and Jboss on CentOS 6

1/64

4/25/2016 Installing EJBCA 6.1.1 and Jboss on CentOS 6.5

http://ejbcacentos.blogspot.co.id/ 1/64

A thorough, detailed, and impartial guide to installing the EJBCA Certificate Authority 6.1.1 on CentOS 6.5 usingJboss 7.1.1. Included is a review of elliptic curve encryption and openssl certificate generation.

Installing EJBCA 6.1.1 and Jboss on CentOS 6.5

S u n d a y , A p r i l 2 7 , 2 0 1 4

How to Install EJBCA 6.1.1 on CentOS 6.5

Hello, and welcome to this blog.

I've needed a CA in my lab for quite some time, and I decided to try ejbca for the following reasons:

1. It's linux‐based.

2. It has a native web interface.

3. It's written on a reasonably mature middleware platform.

4. It seems fairly full‐featured.

I'm writing this because installing ejbca is harder than it should be.

I have never been impressed by "documentation" that destroys time rather than saving it.I believe that software is only as good as a user's ability to use it.

So I am documenting each step of my installation for use as a "cookbook" by others.

But before I begin: it's a litt le‐known fact that all material publ ished on Blogger is automatically copyrighted. Not a GPL copyleft,but a full‐blown Unites States of America copyright. This blog and its content are copyrighted in 2014 by VES Group Incorporatedand all rights are reserved.

After (too) much thought, I've decided that the best license to provide this document under is: "Creative Commons Attribution‐NonCommercial‐ShareAlike International 4.0". The license details are included at the end of the document.

I have tried to write this how‐to in the form of a teaching document. Ideally, even a novice linux user should be able to followthese instructions and have a functional, stable, and secure ejbca installation at the end. And, honestly, even the mostknowledgeable sysadmin has days where they feel like a complete beginner. So hopefully both ends of the experience spectrum

will get something out of reading this.

Installation requires a significant amount of planning . Here are a few things I'd like to point out.

The product can be built on distributed platforms for HA and load‐spreading purposes. This guide assumes a singleserver for test purposes only.

Storage and memory: assume that the CA will take 512MB of RAM, as a rule of thumb. The code itself is ~200MB or so,so give yourself at least a few gigs of space for logs, etc.

Software versions: there are several pieces of software that ejbca depends on. Each has its own version dependencies.This can be challenging.

How you will configure your CAs, what encryption packages to use, etc, will be detailed later in this guide. None of those specifics really matter until you have the product fully installed.

The reader should have a working knowledge of directory services and their formats. At a minimum, you should thoroughlyunderstand:

The difference between a DNS hostname and a FQDN.

The basics of PKI, at least to the point of knowing how root chain validation works.

Introduction

Preparation

2 More Next Blog» [email protected] Dashboard Sign Out

https://www.blogger.com/next-blog?navBar=true&blogID=5605306478325833806https://www.blogger.com/homehttp://ejbcacentos.blogspot.com/logout?d=https://www.blogger.com/logout-redirect.g?blogID%3D5605306478325833806http://ejbcacentos.blogspot.com/logout?d=https://www.blogger.com/logout-redirect.g?blogID%3D5605306478325833806https://www.blogger.com/homehttps://www.blogger.com/next-blog?navBar=true&blogID=5605306478325833806https://www.blogger.com/http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/com.ibm.mq.csqzas.doc/sy10600_.htmhttp://ejbca.org/download.htmlhttp://ejbcacentos.blogspot.co.id/2014/04/how-to-install-ejbca-611-on-centos-65.html


2/64



A minimum of X.500 notation:

CN = Common Name, usually is the FQDN of your CA

DN = Distinguished Name, which is the CN followed by information about the organization that owns the CA

O = Organization, usually is your company name, and can include spaces

C = Country, in ISO 3166‐1 alpha‐2 format (US, CA, SE, MX, etc)

You are not required to have an expert understanding of java and jboss, but some knowledge is helpful. At the least, you shouldunderstand:

What a .jar file is

What an .ear file is

The rudiments of XML (about 10 minutes of study is enough)

The notion of "deploying" an application to a platform like Jboss

You will need to create a fairly large (10+) number of unique passwords just to install ejbca. So get the passwordsafe utility fromSourceforge . Originally co‐written by Bruce Schneier, it is the only password repository I trust. I'll keep a running tally of thepasswords we create, and have included a list of them at the end of this document.

I cannot emphasize the importance of using strong passwords enough.

All of our other security steps are meaningless without strong passwords.

Use passwords of at least 24 characters.Use upper and lower cases, numbers, and punctuation.I suggest using a pseudorandom password generator (such as the one in PasswordSafe) to create them.

The terminology ejbca uses is very confusing, even to someone experienced. Describing each term fully is more than I can do in thisdocument, but hopefully a brief description of the basics will be helpful:

Authentication Code ‐ Each Crypto Token has an associated Authentication Code that is used to encrypt the contents of that particular Crypto Token.

Certificate ‐ A data structure (usually) in X.509 format that typically contains:

A Public Key

Information about the owner of the key (in X.500 format)

"Certificate Extensions" defining how the certificate is meant to be used

The CA certificates that validate the certificate we are examining

Certificate Extension ‐ Data field in a Certificate that "suggests" how a certificate is meant to be used.Certificate Signing Request (CSR) ‐ A file containing a Public Key, as well as optional Certificate Extension informationthat a CA *may* use when generating a Certificate.

Crypto Token ‐ The logical unit that stores all the public/private keypairs owned by a particular CA. By default, theyare held in ejbca's database.

Enrollment Code ‐ The password (or other "Token") used to validate a certificate request.HSM ‐ Hardware Security Module. A physical device used to generate and/or store Keys.JKS ‐ Java Key Store. An unencrypted, file‐based method of storing encryptions keys.Key ‐ What ejbca refers to as a "Key" is actually a "Keypair": a Public key and its matching Private key.Key Algorithm ‐ The asymmetric cryptographic algorithm used to perform public key encryption. Usually RSA orElliptic Curve. One must be specified in every certificate.

Key Alias ‐ A "friendly" name for a Key(pair) that is used for a particular purpose. Ejbca uses the following Key Aliasesto refer to the Keys every ejbca CA must have for basic functionality:

defaultKey : The key used by default (Required).certSignKey : The key used for certificate signing. It must comply with the Signature Algorithm defined forthe CA using the key.

crlSignKey : The key used for CRL signing. The use of this key is deprecated ‐ the certSignKey will always beused for this purpose.

keyEncryptKey : The key used for key recovery when reversible encryption is enabled. It must use the RSA

Passwords

Ejbca's Terminology

http://passwordsafe.sourceforge.net/


3/64



algorithm.

testKey : The key used by the healthcheck process to verify that a Crypto Token is usable. A 1024‐bit RSAkey is recommended to reduce computation time.

Key Specification ‐The length of the modulus used by the Key Algorithm. For RSA, it is usually 2048 or 4096 bits long.For Elliptic Curve, it is usually 192, 256, 384, or 512 bits long.

Keystore ‐ A file used to store certificate information outside of the database. Normally only holds the certificates forejbca's web interface. See: JKS

Private Key ‐ Half of a Keypair generated for use with asymmetric encryption. This is the half that is kept private, andnot shared.

Public Key ‐ The other half of a Keypair, which is shared with anyone/anything you wish to establish securecommunications with.

Signature Algorithm ‐The cryptographic hash algorithm used by a CA to guarantee a certificate's validity.Soft Token ‐ A Token (Crypto, or otherwise) held in the database, rather than in a different format like a JKS or HSM.Token ‐ A generic term for a secret key. This could be anything from an 8‐character ASCII password to an 8192‐bit RSAmodulus. In the context of an "end entity", ejbca specifically uses this word to refer to the key used to encrypt acertificate issued to that "end entity".

A final word of advice before we begin: You are building a device that will be the source of all trust in your environment. Detailsmatter. Accuracy matters ‐ even more than usual. And if it isn't right, it's wrong. Go fix it.

I use CentOS in my lab, generally speaking. This is because the vast majority of actual enterprise linux installations run on RedHat/Fedora. Debian/Ubuntu is prolific in software development environments, but that's really the only place I find it.

I'm performing this installation using 64‐bit CentOS 6.5 on a vm. There is a single root partition for storage, a two‐core CPU, 2 GBof RAM (which is more than it needs), and a single ethernet network interface.

I am using ejbca version 6.1.1 , community edition. It is written in java, and runs on the jboss platform. It uses ant for jbossmanagement, and requires a database (I use mysql) for storage.

Java : DO NOT waste time trying to get java 1.7 to work with this app at present.

It can be done, but the payoff compared to the work involved makes it undesirable.

Running 1.6 has ramifications for Elliptic Curve support, but the way that ejbca uses java makes them largelyirrelevant.

Just use the openjdk version of java 1.6 that is distributed by the standard CentOS online repos.

If you install java 1.7, then the " java " command will invoke 1.7 by virtue of alternatives . Theoretically, alternativesshould take care of redirecting all java‐related executable paths to the correct executables. However, what I found is that the the1.7 implementation from openjdk is incomplete, and ejbca will end up needing to use portions of version 1.6. This inevitably endsup with a non‐working ejbca install.

If you truly must use 1.7, you'll need to manually compile and install updated versions of gcc , gcj , and Oracle Java. This may benecessary in a fully‐certified production environment, but I will stay with 1.6 until everything becomes part of the standard CentOScode stream.

Jboss : I'm using 7.1.1 Final . It actually is the least painful thing to deal with in this setup. Previous versions of jboss are built withthe idea of multiple application deployments on a single platform ‐ the current 7.1.1 download installs with a single standalonedeployment.

Ant: You'll need to download and install a current version of ant ‐ the one from CentOS is too old. I'm using ant‐1.9.3‐2.fc21.noarch.rpm from the Fedora repository.

Mysql: I'm using the standard mysql version 5.1.73‐3.el6_5 from the CentOS repos. The version really doesn't matter, other thanthe various inevitable security problems you have with mysql.

Java Mysql Connector : I'm using the mysql‐connector‐java.noarch from Oracle, version 5.1.30. There is a configuration tweak injboss that is necessary in order to use this version. Older versions do not have this problem (but may have others).

Final Advice

CentOS Installation

Required Software

ftp://rpmfind.net/linux/fedora/linux/development/rawhide/x86_64/os/Packages/a/ant-1.9.3-2.fc21.noarch.rpm


4/64



You do not need: tomcat/httpd, phpmyadmin, or any of the CentOS distro PKI apps.

Adding more detail to the internals of ejbca itself, the application essentially has seven distinct components:

A Database

Java and its database connector

Jboss

The ejbca Certificate Authority

The ejbca Registration Authority

The ejbca Validation Authority

Ejbca's OCSP code

No Internet "howto" is complete without at least one goofy ASCII diagram, so here it is.We will install and configure ejbca in essentially left‐to‐right order:

mysql --> java-sql-connector --> jboss --> ejbca CA --> ejbca VA --> OCSP

^ ^| | ------ java -----

We will ignore the "Registration Authority" for now, and treat it as part of the "Certificate Authority".

This build will be on a single server, so all of these functions will be performed on one box. But you can build ejbca as a set of distributed servers if you wish. There are some sensible reasons for this:

CAs aren't very loaded when only issuing certs. But when answering CRL/OCSP queries, their load can becomesignificant.

You may not issue many certs, and want to take the core CA offline for security reasons. Distributed "validation" and"registration" authorities can handle the validation work and registration work while the core services are offline.

But the usefulness of distributing out every little portion of an app can get a little ... hazy. My opinion is that most "distributed"applications are written by insecure devs to show how awesome they are, and needlessly complicate things. As evidence of this:WhatsApp runs over two million connections per server , and it earned those guys $19 Billion .

This how‐to only covers a standalone installation. But I'll try to point out the distributed stuff as I go along.

To begin:

I suggest using a "Minimal Desktop" CentOS installation in order to have gnome and a web browser. This becomesimportant later, as there are administrative sites and tools in Jboss and ejbca that are only reachable from localhost .If I were building a production server, I would use the "Basic Server" CentOS installation.

No need to set up user accounts for now ‐ just use root .

Set the timezone, etc.

Set your hostname in /etc/hosts ‐ it should look something like:

127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4

::1 localhost localhost.localdomain localhost6 localhost6.localdomain6

192.168.12.34 rootca rootca.yourcompany.com

In this how‐to, I will always use the FQDN of " rootca.yourcompany.com " to represent the server. This seems like a simpledecision, but there are several things to keep in mind when choosing your hostname:

In a production environment, you could potentially have multiple ejbca instances configured on a single jbossinstallation. This would have ramifications for hostname resolution, and this level of complexity is beyond the scope of this how‐to.

Application Logical Layout

Beginning the Installation

http://blog.whatsapp.com/196/1-million-is-so-2011


5/64



When running ejbca in a lab environment, it is tempting to disregard the full FQDN and only use the hostname whenidentifying your CAs. You would be able to get away with this by virtue of your lab's isolation from public DNSresolution. Trust me ‐ Don't do this. Define a full FQDN for your server that would be compatible with public DNS, andcontinue with your build as if this were true.

For someone who is not familiar with Certificate Authorities, it can be very confusing to keep track of the various certificates usedby a CA for different functions. Here are the basics as they relate to ejbca:

First, you must understand that it is possible to host multiple production CA instances on a single ejbca installation. In thisexample, we will configure only a single "Production CA" in order to try to keep it simple.

However, ejbca uses a "Management CA" instance to generate certificates used both internally by the application, as well as toissue certificates used to secure initial access to ejbca's web administration pages.

The "Management CA" is automatically created during installation, and cannot be removed. This implies that there will always beat least two CA instances on an ejbca server:

The Management CA used to generate certificates for the administration of ejbca

The Production CA that will be used to issue certificates for external users and devices

Each CA will have unique X.500 CN field information, and will be configured separately.

The Management CA is purely an internal CA that will never be resolved via DNS, so I will set the CN of the managementCA to be " mgmtca ".

The Production CA will use the actual FQDN of your server for its CN.

All this being said, there is an additional "very important thing" to understand about how the naming of the server relates to thecertificates created by the Management CA for web administration purposes.

When accessing the web interface of your ejbca server, a TLS certificate is used to encrypt the HTTPS connections to the webservice hosting the interface. The initial version of this certificate will be a "self‐signed" one issued by the Management CA andcreated during installation.

However, toward the end of this how‐to, we will replace this certificate with one issued by a "Production" CA.

We do this to ensure that the server itself participates in the PKI that we establish with our "Production" CA.

Also, the Management CA cert does not use an FQDN for the CN, which breaks all kinds of browser functionality.

Replacing this initial certificate with one issued by the Production CA creates a situation that can be quite confusing to a beginner.

The "Root Certificate" used by the Production CA to identify itself and sign new certificates will use the FQDN of theserver (rootca.yourcompany.net) for its CN.

The Production CA will issue a "Server Certificate" that will replace the one issued by the Management CA. Thisreplacement certificate will permanently secure connections to the web administration pages (athttps://rootca.yourcompany.net), and will also use "rootca.yourcompany.net" for the CN.

Despite having the same CN, these are two separate certificates used for two distinct purposes. To try and keep this clear, I willalways use the phrases "Root CA Certificate" and "Server Certificate" to denote these certs.

To have a healthy and sane experience when building an ejbca server, it is important to understand that by the end of our install:

There will be two certificates

They are used for separate purposes (Root Certificate vs. Web Administration TLS)

They are both issued by the same Production CA

They use the same CN

Set up resolv.conf and make sure an A record for rootca.yourcompany.net exists on the configured DNS servers. PTRrecords are also a good idea.

Set up NTP and make sure it works ( ntpdate , etc)‐ correct time is mandatory.

Set up ssh/vnc access as you see fit.

A Word on CA Naming and Certificates

Continuing the Installation...


6/64



Run yum update

Ejbca uses 8080, 8442, and 8443 for CA services. Everything else is internal (3306 for sql, 9990 for jboss admin web interface,etc). The application doesn't run as root , so you can't set the ports to anything


7/64



cp /etc/sysconfig/iptables /etc/sysconfig iptables.initial

There really is no point in having IPv6, so I remove it:

In /boot/grub/grub.conf , edit the boot kernel line to include:

ipv6.disable=1

It will look something like:

kernel /vmlinuz-2.6.32-431.11.2.el6.x86_64 ro root=/dev/mapper/vg_rootca-lv_root rd_NO_LUKS

rd_LVM_LV=vg_rootca/lv_root rd_NO_MD SYSFONT=latarcyrheb-sun16 rd_LVM_LV=vg_rootca/lv_swap KEYBOARDTYPE=pc

KEYTABLE=us rd_NO_DM LANG=en_US.UTF-8 rhgb quiet crashkernel=auto ipv6.disable=1

In /etc/sysctl.conf , change/create these entries:

net.ipv6.conf.all.disable_ipv6 = 1 net.ipv6.conf.default.disable_ipv6 = 1

In /etc/sysconfig/network , change/create these entries:

NETWORKING_IPV6=no IPV6INIT=no

In /etc/modprobe.d/blacklist.conf , change/create these entries:

blacklist net-pf-10 blacklist ipv6

Disable iptables for IPv6:

service ip6tables stop chkconfig ip6tables off

To be extra awesome, make sure that IPv6 driver loads will always silently fail:

echo "install ipv6 /bin/true" > /etc/modprobe.d/ipv6_disabled.conf

To be extra EXTRA awesome, follow the "extra notes" on disabling IPv6 located at:

http://wiki.centos.org/FAQ/CentOS6

Now we install our CentOS software packages. When reviewing your installation, you may have noticed that there's a version 1.5

gjc installed ‐ It's used for compilation of the java packages. It can't be removed without causing problems, and alternativesprevents it from affecting anything. Just ignore it.

yum install java-1.6.0-openjdkyum install /path/to/your/ant-noarch.rpmyum install mysql-serveryum install mysql-connector-java

It's a pretty good idea to verify our java version with java -version , both with the implicit path and the full path you willdefine as JAVA_HOME in standalone.conf : /usr/lib/jvm/java/bin/java -version . Once this is done, you can be surethat java works, and executes the expected version regardless of path:

/usr/lib/jvm/java/bin/java -versionjava version "1.6.0_30"OpenJDK Runtime Environment (IcedTea6 1.13.3) (rhel-5.1.13.3.el6_5-x86_64)OpenJDK 64-Bit Server VM (build 23.25-b01, mixed mode)

Disabling IPv6

Installing Software Packages


8/64



This is a basic mysql setup that isn't particularly tuned for security, but is secure enough for lab purposes. Be sure to create themysql directories and update /etc/my.cnf before starting the service for the first time, as you can't easily change the binary loglocation once it has been created.This config also forces utf‐8 encoding, which is a requirement of ejbca.

Some of the utf‐8 config can throw errors on startup (depending on your version of mysql), so it is commented out.

I enable binary logging in order to make database recovery as bulletproof as I can. But there's no substitute for aregular mysqldump .

Ejbca includes a sample backup script for this purpose.

mkdir -p /var/log/mysql/binchown -R mysql:mysql /var/log/mysql

vi /etc/my.cnf

### Start my.cnf ###

datadir=/var/lib/mysql

socket=/var/lib/mysql/mysql.sock

user=mysql

# Disabling symbolic-links is recommended to prevent assorted security risks

symbolic-links=0

#UTF-8

character-set-server=utf8

collation-server=utf8_unicode_ci

init-connect='SET NAMES utf8'

#character-set-client = utf8

# Logging Config

# Binary logging

log-bin

server-id = 1

log_bin = /var/log/mysql/mysql-bin.log

expire_logs_days = 10

max_binlog_size = 100M

#log

#log-error

#log-slow-queries

[mysqld_safe]

log-error=/var/log/mysql/mysqld.log pid-file=/var/run/mysqld/mysqld.pid

# Custom config

#[client]

#default-character-set=utf8

### End my.cnf ###

To make a point about the mysql user continuing to own everything mysql‐related:

chown mysql:mysql /etc/my.cnf

Now, run the "secure installation" script (take the default actions), log in to mysql, and create the database and user account forejbca:

service mysqld start

Configuring Mysql


9/64



mysql_secure_installation mysql -u root -p

create database ejbcadb;grant all privileges on ejbcadb.* to 'ejbcadbuser'@'localhost' identified by 'password';flush privileges;exit

Verify that you can log in to mysql as ejbcadbuser and test your access:

mysql -u ejbcadbuser -puse ejbcadb;show grants for ejbcadbuser@localhost;exit

Later, we will change the permissions on the ejbcadb database to make ejbcadbuser@localhost 's access a little more limited.

Finalize the mysql installation by performing a service mysqld restart and checking the log at/var/log/mysql/mysqld.log .

Now we're going to set up the directory structure for the app itself. I prefer to put my apps in /opt . By default, all the ejbcadocumentation assumes that you install it in the service user's homedir.

I like to use links to generic paths so that upgrading code is easier. This method also works well with Atlassian products.

The /opt/default directory is used to hold vanilla versions of code so you can easily wipe things out and start over.

mkdir /opt/defaultcd /opt/default

wget http://download.jboss.org/jbossas/7.1/jboss-as-7.1.1.Final/jboss-as-7.1.1.Final.zip

wget http://downloads.sourceforge.net/project/ejbca/ejbca6/ejbca_6_1_1/ejbca_ce_6_1_1.zipunzip *.zipcd ..ln -s /opt/ejbca_ca_6_1_1 ejbcaln -s /opt/jboss-as-7.1.1.Final jbosscp -rp default/jboss-as-7.1.1.Final .cp -rp default/ejbca_ce_6_1_1 .

Now we set up our service accounts. I made two ‐ a system account named jboss , and an ejbca account for administrative useafter the server is built.

It is important that jboss has /bin/bash for a shell and a /opt/jboss as a homedir.

useradd -s /bin/bash -r -d /opt/jboss -M -U jbossuseradd -m -U -G jboss,wheel ejbca

Now that our service user has been created, we can create the directory that will hold our jboss console logs:

mkdir -p /var/log/ejbcachown jboss:jboss /var/log/ejbca

At this point, the server is built, mysql is running, and we're ready to start with installing jboss. It's a good time to takea vm snapshot.

Creating the Directory Structure

Creating the OS User Accounts

Creating the Console Log Directory


10/64



It's time to install jboss. We will not configure every detail (no mail, default logging), but we will do enough to get the platformrunning and tweaked the way ejbca needs for installation.

We begin by configuring the jboss instance that ejbca will use. It's named " standalone ", and exists by default in version 7.1.1.

The /opt/jboss/bin directory contains a script named standalone.sh that is the primary start point for jboss. This scriptreferences a configuration file in the same directory named standalone.conf . We will not need to modify the startup script, butwe will need to modify the configuration file.

First, we make a backup of the default config:

cd /opt/jboss/bincp standalone.conf standalone.conf.orig

The config file also contains a set of jvm options that I tweak a little bit. This is not a mandatory change, but it does allocate more

memory to the jvm. I always seem to be increasing this variable for my jvms, so I'm simply doing this ahead of when I actuallyneed to.

Important: The bits below are only the parts I modified ‐ don't delete the rest of the files!

I've added some commented entries that you might need to use if you're troubleshooting, but really the only things thatmatter are JAVA_HOME and JAVA_OPTS .

Just add the comments to the top of the file and replace the default JAVA_HOME and JAVA_OPTS .

### Start standalone.conf Delta ###

#ejbca config

#

#javaHome=/usr/lib/jvm/java

#jbossHome=/opt/jboss

#jbossClasspath=/usr/share/java/mysql.jar

JAVA_HOME="/usr/lib/jvm/java"

JAVA_OPTS="-Xms128m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -

Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

### End standalone.conf Delta ###

The /opt/jboss/bin/standalone.sh script can always be used to start and stop jboss manually. However, we need toconfigure a service instance named " ejbca " to handle the startup and shutdown of jboss (and subsequently, ejbca). Thankfully,the jboss folks give us an example script to use.

I know it is confusing to name the jboss service " ejbca ", but I am assuming that this jboss instance will only run theejbca application and not be used for any other purpose.

The init script itself contains a very important variable: the path of the jboss home directory.

First, we copy the examples to their proper locations:

cp /opt/jboss/bin/init.d/jboss-as-standalone.sh /etc/init.d/ejbca mkdir /etc/ejbca

cp /opt/jboss/bin/init.d/jboss-as.conf /etc/ejbca/ejbca-init.conf

Then, we modify both files to be appropriate for our installation. Below are my examples.

Again, these are only the changes that must be made to the default file content.

Installing Jboss

Configuring the Standalone Jboss Instance

Creating the Jboss Init Service


11/64



vi /etc/init.d/ejbca

### Start ejbca init.d Delta ###

### BEGIN INIT INFO

# chkconfig - 345 97 17

# Provides: ejbca

# Required-Start: $remote_fs $syslog $network mysqld

# Required-Stop: $remote_fs $syslog $network

# Short-Description: ejbca jboss instance

# Description: ejbca jboss instance

# Default-Start: 3 4 5

# Default-Stop: 0 1 2 6

### END INIT INFO

#

# processname: ejbca

# pidfile: /var/run/jboss-standalone.pid

# config: /etc/ejbca/ejbca-init.conf

JBOSS_CONF="/etc/ejbca/ejbca-init.conf"

JBOSS_HOME=/opt/jboss

prog='ejbca jboss instance'

### End ejbca init.d Delta ###

The ejbca-init.conf file has two very important variables in it: the jboss process username, and the logfile name.

vi /etc/ejbca/ejbca-init.conf

### Start ejbca-init.conf ###

# General configuration for the init.d scripts,

# not necessarily for JBoss AS itself.

# The username who should own the process.#

JBOSS_USER=jboss

# The amount of time to wait for startup

#

# STARTUP_WAIT=10

# The amount of time to wait for shutdown

#

# SHUTDOWN_WAIT=10

# Location to keep the console log

#JBOSS_CONSOLE_LOG=/var/log/ejbca/console.log

### End ejbca-init.conf ###

Lastly, we use chkconfig to add our services to the rc hierarchy and set the runlevels:

chkconfig --add ejbcachkconfig --level 345 mysqld onchkconfig --level 345 ejbca on

The init files should remain owned by root:root , with the default permissions.

Although we have added the ejbca service with chkconfig , and have set a start order value in the chkconfig portion of the init

Setting the Service Order


12/64



script header, we still need to review the service order during startup and shutdown.

In my case, I have the ejbca service set with a start integer of 97 , and a kill integer of 17 . This puts it before the local service,but after everything else. The mysqld is set with a start of 64 , and a kill of 36 .

By default, the mysqld service is configured to wait for the the network service to initialize before starting, and the example initscript for ejbca will wait for mysqld to start. However, you still must read the contents of each runlevel init directory ( rc3.d ,rc4.d , rc5.d ) and create/modify the needed links to manage mysqld and ejbca .

Theoretically, chkconfig and yum are supposed to build these links for us automatically. But sometimes, well, thingsjust don't work out that way.

In the example below, I noted that while ejbca was added correctly, there was a missing start entry for mysqld .

cd /etc/rc.d/rc3.d

ls -al|grep ejbcalrwxrwxrwx. 1 root root 15 May 1 13:30 K17ejbca -> ../init.d/ejbca

lrwxrwxrwx. 1 root root 15 Apr 25 22:24 S97ejbca -> ../init.d/ejbca

ls -al|grep mysqld

lrwxrwxrwx. 1 root root 16 Apr 25 22:24 K36mysqld -> ../init.d/mysqld

ln -s ../init.d/mysqld S64mysqld

ls -al|grep mysqld

lrwxrwxrwx. 1 root root 16 Apr 25 22:24 K36mysqld -> ../init.d/mysqld

lrwxrwxrwx. 1 root root 16 May 1 13:32 S64mysqld -> ../init.d/mysqld

We are now ready to begin tweaking the jboss configuration in earnest. We'll start by enabling certain security functions that ejbcarequires.

cd /opt/jboss/modules/sun/jdk/mainvi module.xml

Add the following entries to the to system export paths:

Do not include the hashed start and end comments.

### Start module.xml Delta ###

### End module.xml Delta ###

Adding the java mysql connector to jboss is a little convoluted. As mentioned, I am using the latest Oracle version, which is version5.1.30. This version breaks jboss, as it requires an additional config variable that jboss doesn't expect. You can assume all versionsof the connector from 5.1.30 onward will have this problem (at least until jboss fixes their side of the code).

Instead of attacking this problem immediately, we will proceed with the CentOS‐distributed version of the connector, ensure thatwe have a working jboss installation, and then deal with updating it.

First, install the CentOS‐distributed version:

yum install mysql-connector-java

Adding Jboss Class Exports

Installing the Mysql Connector


13/64



Now, create the directory that will hold jboss' link to mysql-connector-java.jar , and the link itself:

mkdir -p /opt/jboss/modules/com/mysql/main/cd /opt/jboss/modules/com/mysql/mainln -s /usr/share/java/mysql-connector-java.jar mysql-connector-java.jar

Now, build the module.xml file that describes the connector.

Again, do not include the triple‐hashed lines in this file, as XML does not recognize " #" as denoting a comment.

vi module.xml

### Start module.xml ###

### End module.xml ###

Our next set of tweaks must be made after jboss has been started.

Because our actions until now have been performed as root , we must first make the jboss user the owner of the jboss directorytree.

Don't run "chown -R root:root /opt/jboss " ‐ we want root to remain the owner of the symbolic link.

chown -R jboss:jboss /opt/jboss-as-7.1.1.Final

Now, we test how well our init scripting works:

service ejbca start

Now that we've (hopefully!) started the service, we can check the console log (as it has just been created).

It's a good idea to keep a running console session open from now on.

tail -f /var/log/ejbca/console.log

You should see something like this at the end of the file:

22:51:40,482 INFO [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-2) Starting Coyote HTTP/1.1 on

http--127.0.0.1-8080

22:51:40,688 INFO [org.jboss.as.remoting] (MSC service thread 1-3) JBAS017100: Listening on /127.0.0.1:4447

22:51:40,690 INFO [org.jboss.as.remoting] (MSC service thread 1-2) JBAS017100: Listening on /127.0.0.1:9999

22:51:40,699 INFO [org.jboss.as.server.deployment.scanner] (MSC service thread 1-3) JBAS015012: Started

FileSystemDeploymentService for directory /opt/jboss/standalone/deployments

22:51:40,773 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on

http://127.0.0.1:9990

22:51:40,774 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS 7.1.1.Final "Brontes" started in1528ms - Started 130 of 204 services (74 services are passive or on-demand)

This tells you several important things:

The jboss admin webpage is only available to localhost by default, so you should install Firefox in your gnome session

Starting Jboss


14/64



if you don't already have it.

The default URL for the admin webpage is something like: http://localhost:9990/console/App.html#server-overview

When you see this in the log, jboss has finished loading:

"7.1.1.Final "Brontes" started in xxxx ms"

Now that the jboss service is running, we can enable our mysql connector. We will do this using the jboss command line interface,which will update the configuration of the standalone instance. But before we make the change, we will first back up theconfiguration:

cd /opt/jboss/standalone/configurationcp standalone.xml standalone.xml.initial

Now, we run a registration command from the jboss CLI (the small text is a single line):

cd /opt/jboss/bin sh jboss-cli.sh connect /subsystem=datasources/jdbc-driver=com.mysql.jdbc.Driver:add(driver-name=com.mysql.jdbc.Driver,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource)

:reload exit

This cli action defines our mysql driver in /opt/jboss/standalone/configuration/standalone.xml , then reloads jboss.

The actual definition is:

### Start standalone.xml Snip ###

com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource

### End standalone.xml Snip ###

The standalone.xml file is the primary configuration file in jboss, and we will be working with it several times duringinstallation. However, it does not normally need to be changed once our installation is complete.

If we have been successful with our changes, we should see the following message appear in the console log when restarting jboss:

22:46:29,580 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 27) JBAS010404:

Deploying non-JDBC-compliant driver class com.mysql.jdbc.Driver (version 5.1)

By default, the standalone instance is defined with an h2/hsqldb database connector, and an example database. If leftunchanged, ejbca is preconfigured to use it for example purposes. We will not use it, so we modify standalone.xml to disable it.

vi standalone.xml

### Start standalone.xml Delta ###

Remove the following:

jdbc:h2:mem:test;DB_CLOSE_DELAY=-1

Enabling the Mysql Connector

Removing the Default h2 Datasource and Driver


15/64



h2

sa

sa

Also remove:

org.h2.jdbcx.JdbcDataSource

### End standalone.xml Delta ###

Now, if you watch the console log when restarting jboss, you should no longer see:


Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)

But you should continue to see:


Deploying non-JDBC-compliant driver class com.mysql.jdbc.Driver (version 5.1)

Now that we have a functioning mysql connector, let's break it!

First, download the latest platform‐independent version of the connector from Oracle (I assume this will be version 5.1.30).

Oracle, of course, has to do things its own way, and refers to the connector as "Connector/J".

Now expand the .tar or .zip file that you downloaded, and copy the mysql-connector-java-5.1.30-bin.jar file to/usr/share/java :

cp /your/download/location/mysql-connector-java-5.1.30-bin.jar /usr/share/java

Verify its permissions:

ls -al /usr/share/java/mysql-connector-java-5.1.30-bin.jar

-rw-r--r--. 1 root root 954041 May 1 01:22 mysql-connector-java-5.1.30-bin.jar

Next, delete and recreate the link " mysql-connector-java.jar " such that it points to the new file:

cd /usr/share/javarm mysql-connector-java.jarln -s mysql-connector-java-5.1.30-bin.jar mysql-connector-java.jar

Once this is done, jboss will fail to load the connector at startup, as shown in the console log:

01:16:31,500 ERROR [org.jboss.as.controller.management-operation] (management-handler-thread - 17) JBAS014612:

Operation ("add") failed - address: ([

("subsystem" => "datasources"),

("jdbc-driver" => "com.mysql.jdbc.Driver")

]): org.jboss.msc.service.DuplicateServiceException: Service jboss.jdbc-driver.com_mysql_jdbc_Driver is already

registered

The fix for this is quite simple: add a single line to standalone.xml to update the driver stanza:

Updating the Mysql Connector


16/64




com.mysql.jdbc.Driver

com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource


Restart the service, and the updated connector now loads properly.

Our last jboss installation step is to create the account used to access the jboss admin webpage. We use a specific script for this:

sh /opt/jboss/bin/add-user.sh

What type of user do you wish to add?

a) Management User (mgmt-users.properties)

b) Application User (application-users.properties)

(a): a

Enter the details of the new user to add.

Realm (ManagementRealm) :

Username : jadmin

Password :

Re-enter Password :

About to add user 'jadmin' for realm 'ManagementRealm'

Is this correct yes/no? yes Added user 'jadmin' to file '/opt/jboss-as-7.1.1.Final/standalone/configuration/mgmt-users.properties'

Added user 'jadmin' to file '/opt/jboss-as-7.1.1.Final/domain/configuration/mgmt-users.properties'

You should now be able to reach the jboss web console interface and view/change various config items. At this time, you do notneed to change anything.

This is a jboss‐specific user account not used anywhere else in our build.

This is a good time to take a vm snapshot.

Before we proceed, you should know that ejbca's initial configuration can be divided into a few specific parts:

The .properties files in the /opt/ejbca/conf directory

The initial keystore files in /opt/ejbca/p12

The jboss config in standalone.xml

You should also know these general rules for working with ejbca's configuration:

First, assume that nothing in the configuration will be changed during deployment, and that only the ejbca.ear file istouched by this action.

The mysql database will be auto‐populated when we first deploy ejbca, but will not otherwise be touched by any of theant scripts.

The database does not store any configuration data, but it can be affected by every configuration change you make.

The ant install command tries to create the keystore files each time it is run, even if the files exist.

Portions of standalone.xml can be changed by both ant build and ant install , but only in response to changesmade to our .properties files.

Configuring the Jboss Web Admin User

Installing Ejbca


17/64



Once our initial installation is complete, ant will not change standalone.xml unless we have changed a.properties file.

Ejbca uses flat text " .properties " files for its primary configuration. These files are referenced when compiling ejbca.ear withant , and generally are not referenced by the running application.

The install.properties file is only referenced when running ant install , and is not referenced by ant deploy .Some files actually contain parameters to allow runtime parsing of variables in the properties files, but thisfunctionality is disabled by default.

Initially, ejbca has sample versions of all properties files in the /opt/ejbca/conf directory. The ones that are required by ourbuild are:

certstore.properties ‐ Defines the certificate store variables

cesecore.properties ‐ Defines the core security engine variables

crlstore.properties ‐ Defines the CRL store variables

database.properties ‐ Defines how ejbca will access the db

ejbca.properties ‐ Defines the basic variables for ejbca itself install.properties ‐ Used by " ant install " during installation

mail.properties ‐ Defines how the ejbca SMTP connector will function

ocsp.properties ‐ Defines how OCSP itself will function

va.properties ‐ Defines how the validation authority will function

va-publisher.properties ‐ Defines how the validation authority will access the db

web.properties ‐ Defines variables for ejbca's web interface

There are multiple jndi.* files, and a file called extendedkeyusage.properties in the conf directory as well. They arerequired, but will not be configured further, and can be ignored. There are also two directories, logdevices and plugins , thatcan also be ignored.

First, we create a new directory called: /opt/ejbca/conf/sample , and move all .sample files to it for clarity and backuppurposes:

cd /opt/ejbca/conf mkdir sample mv *.sample sample

Now we copy a specific subset of files back to the main directory:

cp sample/certstore.properties.sample certstore.propertiescp sample/cesecore.properties.sample cesecore.propertiescp sample/crlstore.properties.sample crlstore.properties

cp sample/database.properties.sample database.propertiescp sample/ejbca.properties.sample ejbca.propertiescp sample/install.properties.sample install.propertiescp sample/mail.properties.sample mail.propertiescp sample/web.properties.sample web.properties

We will configure these files, then test our installation before proceeding. With only these files defined, ejbca will be operatewithout validation functionality.

There are a great number of variables to set, and I will not go into detail on each one. However, here are simplified configurationsthat I am using for each file.

Each file is a complete working config.

I have stripped out most of the default comments and added some of my own.

It's a very good idea to take the configs I give here and use them as a reference for your own configuration rather thancutting and pasting. It's the best way to learn all of the variables.

You must enter your own email addresses, passwords, FQDNs, and X.500 CN / DN values.

The Start and End comments are not needed in each config.

Ejbca Properties Files


18/64



### Start certstore.properties ###

# ------------ RFC 4387 Certificate store configuration ---------------------

certstore.enabled=true

# This is the web directory that the web interface for the cert store will use.

# It is not the full path!certstore.contextroot=/certificates

# This is an unused alternate location

#certstore.contextroot=/ejbca/publicweb/certificates

### End certstore.properties ###

### Start cesecore.properties ###

#allow.external-dynamic.configuration=false

# You do not need to configure this password!

#ca.keystorepass=!secret!

#ca.rngalgorithm=SHA1PRNG

#ca.serialnumberoctetsize=8

ca.toolateexpiredate=80000000

#ca.toolateexpiredate=2038-01-19 03:14:08+00:00

#ca.doPermitExtractablePrivateKeys=true

#forbidden.characters = \n\r;!\u0000%`?$~

#intresources.preferredlanguage=EN

#intresources.secondarylanguage=SE

#These variables will enable explicit logging. You can turn them off later

securityeventsaudit.implementation.X=org.cesecore.audit.impl.log4j.Log4jDevice

securityeventsaudit.implementation.X=org.cesecore.audit.impl.integrityprotected.IntegrityProtectedDevice

#securityeventsaudit.implementation.0=null

#securityeventsaudit.implementation.1=null

#securityeventsaudit.exporter.X=org.cesecore.audit.impl.AuditExporterDummy (default)

#securityeventsaudit.exporter.X=org.cesecore.audit.impl.AuditExportCsv

#securityeventsaudit.exporter.X=org.cesecore.audit.impl.AuditExporterXml

#securityeventsaudit.deviceproperty.X.key.subkey=value

# More log config below

securityeventsaudit.implementation.0=org.cesecore.audit.impl.log4j.Log4jDevice

securityeventsaudit.implementation.1=org.cesecore.audit.impl.integrityprotected.IntegrityProtectedDevice

securityeventsaudit.exporter.1=org.cesecore.audit.impl.AuditExporterXml

#securityeventsaudit.deviceproperty.1.export.dir=/tmp/

#securityeventsaudit.deviceproperty.1.export.fetchsize=1000

#securityeventsaudit.deviceproperty.1.validate.fetchsize=1000

#ecdsa.implicitlyca.q=883423532389192164791648750360308885314476597252960362792450860609699839

#ecdsa.implicitlyca.a=7fffffffffffffffffffffff7fffffffffff8000000000007ffffffffffc

#ecdsa.implicitlyca.b=6b016c3bdcf18941d0d654921475ca71a9db2fb27d1d37796185c2942c0a

#ecdsa.implicitlyca.g=020ffa963cdca8816ccc33b8642bedf905c3d358573d3f27fbbd3b3cb9aaaf

#ecdsa.implicitlyca.n=883423532389192164791648750360308884807550341691627752275345424702807307

certstore.properties

cesecore.properties


19/64



### End cesecore.properties ###

### Start crlstore.properties ###

# This is all very similar to certstore.properties

# ------------ RFC 4387 CRL store configuration ---------------------

crlstore.enabled=truecrlstore.contextroot=/crls

#crlstore.contextroot=/ejbca/publicweb/crls

### End crlstore.properties ###

### Start database.properties ###

# ------------- Database configuration ------------------------

#This variable is used in our standalone.xml stanzadatasource.jndi-name=EjbcaDS

# This is the TYPE of db, not the NAME OF the db

database.name=mysql

# Be sure to use utf-8

database.url=jdbc:mysql://127.0.0.1:3306/ejbcadb?characterEncoding=UTF-8

database.driver=com.mysql.jdbc.Driver

database.username=ejbcadbuser

# Change this to your mysql user password:

database.password=pumpkin

### End database.properties ###

### Start ejbca.properties ###

# The next two variables are very important... appserver.home=/opt/jboss

appserver.type=jboss

# Initially, we will set this to false. Once the install is complete, we change

# this to true.

# But DO NOT set it to "ca"!

#ejbca.productionmode=true

ejbca.productionmode=false

#allow.external-dynamic.configuration=false

# Don't set these!

#ca.xkmskeystorepass=

#ca.cmskeystorepass=

approval.defaultrequestvalidity=28800

approval.defaultapprovalvalidity=28800

#approval.excludedClasses=org.ejbca.extra.caservice.ExtRACAServiceWorker

#approval.excludedClasses=org.ejbca.core.protocol.cmp.CmpMessageDispatcherSessionBean

#approval.excludedClasses=org.ejbca.core.protocol.cmp.RevocationMessageHandler

#approval.excludedClasses=

crlstore.properties

database.properties

ejbca.properties


20/64



healthcheck.amountfreemem=32

healthcheck.dbquery=Select 1 From CertificateData where fingerprint='XX'

healthcheck.authorizedips=127.0.0.1

healthcheck.catokensigntest=true

healthcheck.publisherconnections=true

#healthcheck.maintenancefile=~/maintenance.properties

#healthcheck.maintenancepropertyname=DOWN_FOR_MAINTENANCE

healthcheck.okmessage=ALLOK

healthcheck.sendservererror=true

#healthcheck.customerrormessage=EJBCANOTOK

# It's important to change this to 8:

ejbca.passwordlogrounds=8

### End ejbca.properties ###

### Start install.properties ###

# In every case that "CA" is mentioned in this file, it refers to the "management" CA ONLY.

# This will be the initial name of the management CA instance

# ejbca will use this for administration purpose, not your production CAs

# Note that the CN given here is NOT the FQDN of your CA!

# Why does this matter? This certificate will be temporarily installed

# on your browser as a trusted root CA, but will not be communicated

# with.

ca.name=mgmtca

ca.dn=CN=mgmtca,O=Your Company,C=US

ca.tokentype=soft

ca.tokenpassword=null

# This is the path to a "catoken.properties" file that will be created when 'ant

# install' is run. It will contain encryption parameters used by the mgmt CA.

# You will not edit this properties file yourself.

ca.tokenproperties=/opt/ejbca/conf/catoken.properties

# THIS IS IMPORTANT

# You can assume that ejbca cannot use EC algorithms for the management CA.

# This does not mean that ejbca cannot issue certificates that use EC.

# It just means that the management CA will use RSA for internal purposes.

# The reason for this limitation is that the various EC algorithms are

# not equally supported by the various java flavors that could be used.

# More importantly, ejbca does not include any sort of logic to identify

# the version of java you are using to limit or correct your options.

# Choosing an unsupported algorithm here leads to a corrupt installation.

# This can waste a great amount of time, so just avoid EC.

# You can use EC later with the actual production CAs you define.

# Keyspec for RSA keys is size of RSA keys (1024, 2048, 4096, 8192).

ca.keyspec=4096

# The keytype for the administrative CA, can be RSA, ECDSA or DSA

ca.keytype=RSA

# Even though SHA1 is still largely in use as a certificate hashing

# algorithm, I strongly suggest that you go with SHA256WithRSA.

# Also, please note that the "with/With" in the hash names is indeed

# case-sensitive. Stay classy, Oracle.

# SHA1WithRSA, SHA1withECDSA, SHA256WithRSA, SHA256withECDSA.

ca.signaturealgorithm=SHA256WithRSA

# I set a CA validity of 10 years (including the leap years, rain man)

install.properties


21/64



ca.validity=3652

ca.policy=null

ca.certificateprofile=ROOTCA

### End install.properties ###

### Start mail.properties ###

# This config is for the ejbca application mailer, not the jboss mailer. We will

# set that up later. For now, we just point to the local mail server in order to

# prevent errors in the console log.

mail.jndi-name=java:/EjbcaMail

mail.user=ejbca

mail.password=honeybunny

mail.smtp.host=localhost

mail.smtp.port=25

#mail.smtp.auth=false

#mail.smtp.starttls.enable=false

[email protected]

#mail.debug=false

mail.contentencoding=UTF-8

### End mail.properties ###

### Start web.properties ###

# The key to this portion of the config is understanding that this file affects

# the certificate used by the ejbca admin webpage. In install.properties, we

# defined variables for the management CA root certificate. But that certificate

# is not used for session TLS. The management CA issues a separate "server

# certificate" for that purpose that is defined here.

#

# ------------ Web GUI configuration ---------------------

# Can not be set to false, commented away means that web will be configured.

#web.noconfigure=true

# Can not be set to false, commented away means that web will be configured.

# web.nosslconfigure=true

# You do not need to set this password!

#java.trustpassword=changeit

superadmin.cn=superadmin

superadmin.dn=CN=${superadmin.cn},O=Your Company,C=US


#superadmin.password=ejbca

superadmin.batch=true


#httpsserver.password=serverpwd

httpsserver.hostname=rootca.yourdomain.net

httpsserver.dn=CN=${httpsserver.hostname},O=Your Company,C=US

# This is the port that will host the unencrypted Ejbca Public Web page.

httpserver.pubhttp=8080

# This is the port that will host the encrypted Ejbca Public Web page,

mail.properties

web.properties


22/64



# without client certificate authentication.

httpserver.pubhttps=8442

# This is the port that will host the encrypted Ejbca Public Web page,

# as well as the Administration page. Accessing content hosted on

# this port requires client certificate authentication.

# Note that the Ejbca Public Web page link to the administration

# page will try to include this port in the URL, regardless of any

# port redirection you may be using. This will fixed at the end of

# the how-to.httpserver.privhttps=8443

#httpserver.external.privhttps=443

#Don't set these up unless you use an apache proxy for port translation

#httpserver.external.fqdn=

#httpserver.external.fqdn=${httpsserver.hostname}

#httpsserver.bindaddress.pubhttp=0.0.0.0

#httpsserver.bindaddress.pubhttps=0.0.0.0

#httpsserver.bindaddress.privhttps=0.0.0.0

web.availablelanguages=EN,DE,ES,FR,IT,JA,PT,SE,UA,ZH,BS

web.contentencoding=UTF-8

#hardtoken.diplaysensitiveinfo=true

#web.docbaseuri=disabled

#web.docbaseuri=internal

#web.docbaseuri=http://www.ejbca.org

#web.reqcertindb=true

web.selfreg.enabled=false

web.selfreg.defaultcerttype=1

web.selfreg.certtypes.1.description=User certificate

web.selfreg.certtypes.1.eeprofile=SOMEPROFILE

web.selfreg.certtypes.1.certprofile=ENDUSER

#web.selfreg.certtypes.1.usernamemapping=CN

web.renewalenabled=false

#web.manualclasspathsenabled=true

web.errorpage.notification=An exception has occurred.

web.errorpage.stacktrace=true

#web.enableproxiedauth=true

web.log.adminremoteip=true

#web.log.adminforwardedip=true

### End web.properties ###

Now that we have a basic set of properties files, we can do our initial deployment of ejbca to jboss.

Open a terminal session to solely monitor the jboss console file:

tail -f /var/log/ejbca/console.log

The jboss user must be the owner of both the jboss directory tree and the ejbca directory tree. Before running our initial

deployment, it's a requirement to ensure that this is the true.

service ejbca stopchown -R jboss:jboss /opt/jboss-as-7.1.1.Finalchown -R jboss:jboss /opt/ejbca_ce_6_1_1service ejbca start

Initial Deployment


23/64



cd /opt/ejbcasudo -u jboss ant deploy

Always execute ant as the jboss user. Otherwise, the files it creates will be owned by root , and you'll have 99problems .

Also, you must always execute ant from the /opt/ejbca directory, as that is where build.xml is located. You coulduse a path variable when executing ant , but I find that just changing directory to /opt/ejbca is easier.

Lastly, jboss must be running when you run ant .

The deployment process itself pulls information from our config data, uses that information to compile an ejbca.ear file, thenprompts jboss to deploy it. Because this is our first deployment, ant also does the following:

Adds our ejbca mail configuration to standalone.xml

Adds our ejbca datasource information to standalone.xmlPopulates the database with the initial schema

While all this is happening, you'll see new messages quickly arrive in the console log, but you can usually spot a nice summarysection that is given before the actual compilation of ejbca.ear begins:

display-properties:

[echo]

[echo] ---------- EJBCA 6.1.1 (working copy) CONFIGURATION PROPERTIES ----------

[echo] appserver.type = jboss

[echo] appserver.subtype = jboss7

[echo] appserver.home = /opt/jboss

[echo] java.version = 1.6.0_30

[echo] ocsp.defaultresponder = CN=rootca.yourcompany.net,O=Your Company,C=US

[echo] ocsp.signaturealgorithm = SHA1WithRSA;SHA1WithECDSA;SHA1WithDSA

[echo] datasource.jndi-name = EjbcaDS

[echo] datasource.jndi-name-prefix = java:/

[echo] database.name = mysql

[echo] database.url = jdbc:mysql://127.0.0.1:3306/ejbcadb?characterEncoding=UTF-8

[echo] database.driver = com.mysql.jdbc.Driver

[echo] database.username = ejbcadbuser

[echo] database.password = *** [echo] database.useSeparateCertificateTable = false

[echo] database.valid.connection.sql = select 1

[echo] mail.jndi-name = java:/EjbcaMail

[echo] mail.from = [email protected]

[echo] mail.user = ejbca

[echo] mail.password = ***

[echo] mail.smtp.host = localhost

[echo] mail.smtp.port = 25

[echo] mail.smtp.auth = false

[echo] mail.debug = false

[echo] httpserver.pubhttp = 8080

[echo] httpserver.pubhttps = 8442

[echo] httpserver.privhttps = 8443 [echo] httpserver.external.privhttps = 8443

[echo] httpsserver.hostname = rootca.yourcompany.net

[echo] httpsserver.password = ***

[echo] httpserver.external.fqdn =

[echo] web.contentencoding = UTF-8

[echo] web.renewalenabled = false

[echo] ejbcaws.enabled = true

[echo] cmp.tcp.enabled = false

[echo] cmp.tcp.portno = 829

[echo] cmp.tcp.logdir = ./log

[echo] cmp.tcp.conffile =

[echo] xkms.enabled = false

[echo] xkms.serviceport = 8080

You'll also see various log messages showing errors on compilation. The following errors can be ignored ‐ they're bugs in jboss:

Deployment Error Messages

https://www.youtube.com/watch?v=WwoM5fLITfk


24/64



06:05:16,848 ERROR [org.jboss.as.controller.management-operation] (management-handler-thread - 1) JBAS014612:

Operation ("composite") failed - address: ([]): java.lang.IllegalArgumentException

06:05:39,477 ERROR [org.hibernate.internal.util.xml.ErrorLogger] (MSC service thread 1-4) HHH000196: Error parsing

XML (21) : cvc-complex-type.3.1: Value '1.0' of attribute 'version' of element 'entity-mappings' is not valid with

respect to the corresponding attribute use. Attribute 'version' has a fixed value of '2.0'.

15:29:58,915 SEVERE [javax.enterprise.resource.webcontainer.jsf.application] (MSC service thread 1-2) JSF1051:

Service entry 'org.jboss.as.web.deployment.jsf.JsfInjectionProvider' does not extend

DiscoverableInjectionProvider. Entry will be ignored.

This message refers to the fact that the community version of ejbca does not support database integrity protection:

06:06:13,175 INFO [org.cesecore.dbprotection.ProtectedData] (MSC service thread 1-4) No database integrity

protection available in this version of EJBCA.

You'll always see these errors no matter what you do. Any other errors and failures should be dealt with before trying to proceed toan installation. But eventually you'll see something like these messages if the deployment is successful:

01:38:38,724 INFO [org.jboss.as] (MSC service thread 1-1) JBAS015874: JBoss AS 7.1.1.Final "Brontes" started in

7761ms - Started 2855 of 2968 services (111 services are passive or on-demand)01:38:38,769 INFO [org.jboss.as.server] (DeploymentScanner-threads - 2) JBAS018559: Deployed "ejbca.ear"

Finally, note that you will see tons of the following messages returned directly by ant during every operation:

appserver.error.message:

[echo] jndi.properties.file: /opt/ejbca_ce_6_1_1/conf/jndi.properties.jboss7

These messages can be safely ignored.

Why did we do an ant deploy before an ant install ? There are two reasons:

To test that the ejbca.ear file is successfully compiled from what we have built so far. Running ant deploy whilereading the logs gives us a chance to fix mistakes before proceeding. Once installation is complete, it becomes muchmore difficult to fix configuration mistakes.

More importantly, the ejbca.ear file must exist before the install script can execute.

It is worth taking the time to describe what the various ant command scripts do in slightly greater detail, and to learn a few newones. They are very useful when fixing with troublesome installations.

As you know, the ant deploy script creates temporary files used to compile ejbca.ear , compiles the ejbca.earfile, and then prompts jboss to deploy it. It is worth mentioning that there are two distinct functions ("targets") beingcalled:

First, ant runs the build target that performs the preparation and compilation.

Then ant uses the jboss jee.deploy target to perform the actual transfer to jboss.

The build process can be called directly using ant build . But ant deploy always runs both targets.

The ant install script takes your configuration files, uses their information to create further configuration (such asthe keystore files), and copies these new files to their proper locations. Various changes to jboss are also made by thisscript, and a full deployment must be performed manually once installation is complete.

A separate script for installation is required to segregate one‐time actions (like generating the keystores)from the repetitive actions of deployment. You do not need to rebuild everything each time you deploy!

The ant clean command will clear temporary files created by prior deployments that may accidentally persist.

Deleting them can help resolve deployment errors that may arise.If you continue to receive errors during deployment after trying ant clean , you may need to use a deprecatedcommand: ant bootstrap . Theoretically, all of its functions are now performed by ant deploy .

More Detail on Ant


25/64



As you might expect, all of these commands must be executed as the jboss user. If this is not done, you'll likely see these errorsupon service start or deployment:

06:31:45,480 SEVERE [javax.enterprise.resource.webcontainer.jsf.application] (MSC service thread 1-4) JSF1051:

Service entry 'org.jboss.as.web.deployment.jsf.JsfInjectionProvider' does not extend

DiscoverableInjectionProvider. Entry will be ignored.

06:31:43,811 INFO [org.jboss.as.controller] (Controller Boot Thread) JBAS014774: Service status report

JBAS014777: Services which failed to start: service jboss.web.connector.httpspub:

org.jboss.msc.service.StartException in service jboss.web.connector.httpspub:

JBAS018007: Error starting web connector service jboss.web.connector.httpspriv:org.jboss.msc.service.StartException in service jboss.web.connector.httpspriv:

JBAS018007: Error starting web connector

Assuming that we are not seeing these (or any other) errors, we can proceed with our installation. It is a good idea to restart jboss,then perform the install. This avoids out‐of‐memory errors that jboss can occasionally throw.

If you do happen to lock up jboss with an out‐of‐memory condition, just " kill -9 " the jboss process and do a serviceejbca restart . You should then be able to perform your ant command successfully.

If this does not resolve the errors, try the new ant commands given above.

service ejbca restartcd /opt/ejbcasudo -u jboss ant install

I've mentioned the keystore files several times, but haven't fully described what they are. The keystores hold the certificates usedby ejbca to secure its web portal, nothing more. Their prominence during installation makes them seem very important, but theyhave little relevance to the actual "Certificate Authority" functions of ejbca.

They are not used to store keys and certificates generated by ejbca once the application is in production ‐ thatinformation is (usually) held in the database.

In a distributed installation, they have an important role in cross‐server authentication.

When the install script runs, it will perform various operations until it must prompt you for the passwords to be used for yourkeystore files. Again, the keystore files are located in /opt/ejbca/p12 , and are:

tomcat.jks ‐ Holds the actual certificate (and its signing chain) used by jboss to secure the ejbca web portals withTLS.

truststore.jks ‐ Stores a copy of the root CA key that issued the TLS certificate (initially this is the managementCA).

After creation, these files are copied by the install script to /opt/jboss/standalone/configuration/keystore , andtomcat.jks is renamed keystore.jks in the new directory.

It is critical to understand that while ant creates the keystores in /opt/ejbca/p12 , jboss uses the keystores in the/opt/jboss/standalone/configuration/keystore directory for TLS.

The superadmin.p12 file that contains the client certificate used to authenticate the default administrator account isalso located in /opt/ejbca/p12 . It is not copied to the jboss directory with the other keystores.

The java tool used to manage the keystores is called keytool , and (in our installation) is called by a link in /usr/bin/ . Throughalternatives , this link points to /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/keytool . This tool seems to be theprimary source of my problems with Elliptic Curve support ‐ the 1.6 version isn't fully‐functioned for EC algorithms, and ejbca isn'tsmart enough to parse EC keystore requests and prevent unsupported ones from being passed to the tool. The easiest way to dealwith this problem is to simply use RSA encryption for our keystores, as I have done in the examples.

Note that keytool is only used to manage keystore files. The targets used by ejbca to respond to certificate requestswill be able to generate EC certificates just fine.

Also note that the ejbca configuration files for the keystores refer to EC support in various places. You are welcome toplay with your setup to try and find a working EC config, but I will not discuss this further.

The Initial Keystores


26/64



As mentioned, ant install generates the initial copies of the keystores based on the configuration in install.properties and web.properties . Depending on how thoroughly you configured these files, ant install may prompt you for a good deal of

information required to create the initial certificates. But if you have stayed close to the examples, you should only be promptedfor the three passwords that will be used to authenticate the keystores:

Please enter the password of the truststore with the CA certificate for https? [changeit]

Please enter the password of the keystore with the TLS key for https [serverpwd]

(and later)

Please enter the superadmin password (default: ejbca) ? [ejbca]

To clarify what each password is for:

The " truststore with the CA certificate for https " is the truststore.jks file.

The " keystore with the TLS key for https " is the tomcat.jks file.

The " superadmin password " is the password for the superadmin.p12 file.

You can include these passwords in the .properties files, and not be prompted for them. However, my personal feeling is that

you should never have passwords stored in clear text.

Unfortunately, ejbca keeps clear copies of the keystore passwords in standalone.xml .

Ideally, ejbca would only store these passwords in hashed form, but there is nothing we can do about this at the moment, short of rewriting the install script.

While keystore creation is taking place, ant install will return messages like these:

[echo] Initializing CA with 'mgmtCA' 'CN=mgmtca,O=Your Company,C=US' 'soft' '4096''RSA' '3650' 'null' 'SHA384withRSA' /home/ejbca/conf/catoken.properties -superadmincn 'SuperAdmin'...

After this, you will see another summary stanza describing the management CA being created:

[echo]

[echo] ------------------- CA Properties ----------------

[echo] ca.name : mgmtca

[echo] ca.dn : CN=mgmtca,O=Your Company,C=US

[echo] ca.tokentype : soft

[echo] ca.keytype : RSA

[echo] ca.keyspec : 4096

[echo] ca.signaturealgorithm : SHA256WithRSA

[echo] ca.validity : 3650

[echo] ca.policy : null

[echo] ca.tokenproperties : /opt/ejbca/conf/catoken.properties [echo] httpsserver.hostname : rootca.yourcompany.net

[echo] httpsserver.dn : CN=rootca.yourcompany.net,O=Your Company,C=US

[echo] superadmin.cn : superadmin

[echo] superadmin.dn : CN=superadmin,O=Your Company,C=US

[echo] superadmin.batch : true

[echo] appserver.home : /opt/jboss

[echo]

If the keystore creation fails due to an invalid encryption configuration (like trying to use EC), ant install will return a messagelike:

[java] org.ejbca.ui.cli.ErrorAdminCommandException: org.cesecore.certificates.ca.InvalidAlgorithmException:Signature algorithm SHA384withRSA is not one of the allowed signature algorithms. Available algorithms:

{SHA1WithRSA,SHA256WithRSA,SHA384WithRSA,SHA512WithRSA,SHA256WithRSAAndMGF1,

SHA1withECDSA,SHA224withECDSA,SHA256withECDSA,SHA384withECDSA,SHA1WithDSA,

GOST3411withECGOST3410,GOST3411withDSTU4145}.


27/64



and the console log will include messages like:

06:21:15,184 ERROR [org.apache.tomcat.util.net.jsse.JSSESocketFactory] (MSC service thread 1-2) Failed to load

keystore type JKS with path /opt/jboss/standalone/configuration/keystore/keystore.jks due to

/opt/jboss/standalone/configuration/keystore/keystore.jks (No such file or directory):

java.io.FileNotFoundException: /opt/jboss/standalone/configuration/keystore/keystore.jks (No such file or

directory)

06:21:15,188 ERROR [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-2) Error initializing endpoint:

java.io.FileNotFoundException: /opt/jboss/standalone/configuration/keystore/keystore.jks (No such file or

directory)

Troubleshooting keystore creation boils down to interpreting the errors in both ant output and the console log. But problemsusually stem from the keytool command syntax that ant install puts together. You can infer this syntax from the messagesgiven in the ant console output.

Aside from keystore creation, the install script also does the following:

Builds the actual management CA instance in the database

Updates standalone.xml with keystore, web session, and security information.

In the log file, you will see many new messages, primarily relating to encryption functions for the keystore files. But the best wayto get a feeling for how your installation is proceeding is to look for the following messages spread through the output:

06:20:59,482 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context:

/${app.name}/publicweb/status


/ejbca/publicweb/apply


/ejbca/publicweb/webdist

06:20:59,506 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context: /ejbca/publicweb


/ejbca/publicweb/healthcheck06:20:59,521 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context: /ejbca/clearcache

06:20:59,521 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context: /ejbca/ejbcaws

06:20:59,571 INFO [org.jboss.web] (MSC service thread 1-4) JBAS018210: Registering web context: /ejbca

06:20:59,727 INFO [org.jboss.web] (MSC service thread 1-1) JBAS018210: Registering web context: /crls

06:20:59,728 INFO [org.jboss.web] (MSC service thread 1-2) JBAS018210: Registering web context: /certificates

06:21:00,141 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context: /ejbca/adminweb

06:21:16,576 INFO [org.jboss.web] (MSC service thread 1-1) JBAS018210: Registering web context: /ejbca/doc

WSDL published to: file:/opt/jboss-as-7.1.1.Final/standalone/data/wsdl/ejbca.ear/ejbca-ws-

ejb.jar/EjbcaWSService.wsdl

If you see these contexts being successfully registered, you can feel assured that the various functions of ejbca are beingsuccessfully built. But note that most of these contexts are dynamic in nature, and usually cannot be browsed to check theirfunction ‐ you must create your own CAs first. Also, some services, like the healthcheck, are only available from localhost (asshown in the properties files).

The installation will likely end with an error message that will go away once we manually perform a deployment (although ant willreport the installation as " BUILD SUCCESSFUL"):

06:31:43,812 ERROR [org.jboss.as] (Controller Boot Thread) JBAS015875: JBoss AS 7.1.1.Final "Brontes" started

(with errors) in 162ms - Started 135 of 218 services (2 services failed or missing dependencies, 80 services are

passive or on-demand)

Chances are that you will discover mistakes after your first installation attempt. If you did not (or could not) make a vm snapshotimmediately prior to running ant install , all hope is not lost! Perform these steps, and verify that you no longer receiveunexpected errors in your console log before proceeding. If you just can't shake weird errors in the log, you really have no otherchoice than to completely start over.

Finalizing the Installation

Recovering from a Failed Install


28/64



service ejbca stop mysql -u root -p

drop database ejbcadb;create database ejbcadb;exit

rm /opt/ejbca/p12/tomcat.jksrm /opt/ejbca/p12/truststore.jksrm /opt/ejbca/p12/superadmin.p12 rm /opt/jboss/standalone/configuration/keystore/keystore.jksrm /opt/jboss/standalone/configuration/keystore/truststore.jksvi /opt/jboss/standalone/configuration/standalone.xml


Remove:


service ejbca startsudo -u jboss ant cleansudo -u jboss ant deploysudo -u jboss ant install

Regardless of whether or not we had problems with their creation, it is quite important to check the contents of the keystore filesprior to continuing with the build. This ensures not only that the contents are correct, but also that the passwords associated withthe files are the ones we expect. We will check both the ejbca and the jboss copies:

cd /opt/ejbca/p12keytool -list -v -keystore tomcat.jkskeytool -list -v -keystore truststore.jks

cd /opt/jboss/standalone/configuration/keystorekeytool -list -v -keystore keystore.jkskeytool -list -v -keystore truststore.jks

Again, the contents of tomcat.jks/keystore.jks should initially be:

The root CA certificate used to identify your management CA.

The TLS certificate for your server, which will be issued to the FQDN of your server.

An additional copy of the management CA certificate chained to the TLS certificate as the signing authority.

Checking the Keystores


29/64



A "key" thing to note regarding keytool : when running the list commands above, you may notice that the keys will be successfullylisted regardless of the password (or lack of one) that you enter. However, you will see the following stanza at the top of the listoutput:

***************** WARNING WARNING WARNING ****************** The integrity of the information stored in your keystore ** has NOT been verified! In order to verify its integrity, ** you must provide your keystore password. *

***************** WARNING WARNING WARNING *****************

This functionality is by design. Ejbca, for its part, takes the passwords that are entered during installation and uses them as theauthentication codes for the keystores, storing them in the standalone.xml stanzas mentioned in the previous section.

If jboss cannot validate the keystores with the passwords stored in standalone.xml at start time, the service will eventuallystart, but will fail to start ejbca.ear , and will report the following message in the console log:

20:45:43,566 ERROR [org.apache.tomcat.util.net.jsse.JSSESocketFactory] (MSC service thread 1-4) Failed to load

keystore type JKS with path /opt/jboss/standalone/configuration/keystore/keystore.jks due to Keystore was tampered

with, or password was incorrect: java.io.IOException: Keystore was tampered with, or password was incorrect

Returning to our own tests of the keystores, the output of a list operation (with the proper password) will look something like this(some of the extensions are omitted for brevity):

### Start keystore.jks ###

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 2 entriesAlias name: cacert

Creation date: Apr 26, 2014

Entry type: trustedCertEntry

Owner: C=US, O=Your Company, CN=mgmtca

Issuer: C=US, O=Your Company, CN=mgmtca

Serial number: 1e1369e62435a307

Valid from: Sat Apr 26 06:20:16 GMT-08:00 2014 until: Tue Apr 23 06:20:16 GMT-08:00 2024

Certificate fingerprints:

MD5: CB:04:B3:2A:5A:AA:AA:AA:54:BB:C1:3E:72:A2:F1:62

SHA1: 07:89:0F:48:97:35:FF:AA:B5:69:35:97:69:8B:B1:40:D8:2A:02:2A

Signature algorithm name: SHA256withRSA

Version: 3

Extensions:

#1: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

DigitalSignature

Key_CertSign

Crl_Sign

]

...

]

*******************************************

*******************************************

Alias name: rootca.yourcompany.net


Entry type: PrivateKeyEntry

Certificate chain length: 2


30/64



Certificate[1]:

Owner: C=US, O=Your Company, CN=rootca.yourcompany.net


Serial number: 5a797a3381345da2

Valid from: Sat Apr 26 06:10:21 GMT-08:00 2014 until: Mon Apr 25 06:10:21 GMT-08:00 2016


MD5: AF:C1:26:10:24:9D:FE:08:45:F0:45:CA:57:33:BB:FE

SHA1: 11:5F:8F:A2:AC:E6:D2:3C:1E:CC:6A:A8:3B:9F:57:8D:4E:D6:59:3C


Version: 3

Extensions:


KeyUsage [

DigitalSignature

Key_Encipherment

]

...

]

Certificate[2]:

Owner: C=US, O=Your Company, CN=MgmtCA

Issuer: C=US, O=Your Company, CN=MgmtCA

Serial number: 1e1369ef834ea307

Valid from: Sat Apr 26 06:20:16 GMT-08:00 2014 until: Tue Apr 23 06:20:16 GMT-08:00 2024


MD5: CB:04:B3:2A:5A:7B:40:72:54:BB:C1:3E:72:A2:F1:62

SHA1: 07:89:0F:48:97:35:FF:AA:B5:69:35:97:69:8B:B1:40:D8:2A:02:2A


Version: 3

Extensions:


KeyUsage [

DigitalSignature

Key_CertSign

Crl_Sign

]

...

]

*******************************************

*******************************************

### End keystore.jks ###

The truststore.jks file contains the keys of all authorities trusted by jboss, which initially is only the management CA:

### Start truststore.jks ###

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 1 entry

Alias name: mgmtca


Entry type: trustedCertEntry


31/64



Owner: C=US, O=Your Company, CN=mgmtca


Serial number: 1

installing ejbca 6.1.1 and jboss on centos 6

Documents