A thorough, detailed, and impartial guide to installing the EJBCA Certificate Authority 6.1.1 on CentOS 6.5 using
A thorough, detailed, and impartial guide to installing the EJBCA Certificate Authority 6.1.1 on CentOS 6.5 using
Jboss 7.1.1. Included is a review of elliptic curve encryption and openssl certificate generation.
Jboss 7.1.1. Included is a review of elliptic curve encryption and openssl certificate generation.
Installing EJBCA 6.1.1 and Jboss on
Installing EJBCA 6.1.1 and Jboss on
CentOS 6.5
CentOS 6.5
S
S u n u n d a d a yy, , A p A p r i r i l l 2 7 2 7 , , 2 0 2 0 1 41 4
How to Install EJBCA 6.1.1 on CentOS 6.5
How to Install EJBCA 6.1.1 on CentOS 6.5
Hello, and welcome to this blog.Hello, and welcome to this blog.
I've needed a CA in my lab for quite some time, and I decided to try
I've needed a CA in my lab for quite some time, and I decided to try ejbcaejbca for the following reasons: for the following reasons:
1. It's linux‐based.
1. It's linux‐based.
2. It has a native web interface.
2. It has a native web interface.
3. It's written on a reasonably mature middleware platform.
3. It's written on a reasonably mature middleware platform.
4. It seems fairly f
4. It seems fairly full‐featured.ull‐featured.
I'm writing this because installing ejbca is harder than it should be.
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 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.
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.
So I am documenting each step of my installation for use as a "cookbook" by others.
But before I begin: it's
But before I begin: it's a litt a little‐known fact that all material publle‐known fact that all material publishedished on Bon Blogger is automatilogger is automatically cally copyrighted. Not a GPL copylcopyrighted. Not a GPL copyleft,eft,
but a full‐blown Unites States of America copyright. This blog and its content are copyrighted in 2014 by VES Group Incorporated
but a full‐blown Unites States of America copyright. This blog and its content are copyrighted in 2014 by VES Group Incorporated
and all
and all rights are reserights are reserved.rved.
After (too) much thought, I've decided that the best license to provide this document under is: "Creative Commons Attribution‐
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.
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 follow
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 follow
these instructions and have a functional, stable, and secure ejbca installation at the end. And, honestly, even the most
these instructions and have a functional, stable, and secure ejbca installation at the end. And, honestly, even the most
knowledgeable sysadmin has days where they feel like a complete beginner. So hopefully both ends of the experience spectrum
knowledgeable 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.
will get something out of reading this.
Installation requires a significant amount of planning
Installation requires a significant amount of planning..Here are a few things I'd like to point out.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 single
The product can be built on distributed platforms for HA and load‐spreading purposes. This guide assumes a single
server for test purposes only.
server 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,
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 l
so give yourself at least a few gigs of space for logs, etc.ogs, etc.
Software versions: there are several pieces of software that ejbca depends on. Each has its own version dependencies.
Software versions: there are several pieces of software that ejbca depends on. Each has its own version dependencies.
This can be challenging.
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
How you will configure your CAs, what encryption packages to use, etc, will be detailed later in this guide. None of
those speci
those specifics really fics really matter unmatter until you have til you have the product fully the product fully instinstalled.alled.
The reader should have a working knowledge of directory services and their formats. At a minimum, you should thoroughly
The reader should have a working knowledge of directory services and their formats. At a minimum, you should thoroughly
understand:
understand:
The difference between a DNS hostname and a FQDN.
The difference between a DNS hostname and a FQDN.
The basics of PKI, at least to the point of knowing how
The basics of PKI, at least to the point of knowing how root chain validationroot chain validation works. works.
Introduction
Introduction
Preparation
Preparation
2
A minimum of X.500 notation:
A minimum of X.500 notation:
CN = Common Name, usually is the FQDN of your CA
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
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
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)
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 should
You are not required to have an expert understanding of java and jboss, but some knowledge is helpful. At the least, you should
understand:
understand:
What a .jar file is
What a .jar file is
What an .ear file is
What an .ear file is
The rudiments of XML (about 10 minutes of study is enough)
The rudiments of XML (about 10 minutes of study is enough)
The notion of "deploying" an application to a platform like Jboss
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
You will need to create a fairly large (10+) number of unique passwords just to install ejbca. So get the passwordsafe utility frompasswordsafe utility from
Sourceforge
Sourceforge. Originally co‐written by Bruce Schneier, it is the only password repository I trust. I'll keep a running tally of the. Originally co‐written by Bruce Schneier, it is the only password repository I trust. I'll keep a running tally of the
passwords we create, and have included a list of them at the end of this document.
passwords 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.
I cannot emphasize the importance of using strong passwords enough.
All of our other security steps are meaningless without strong passwords.
All of our other security steps are meaningless without strong passwords.
Use passwords of at least 24 characters.
Use passwords of at least 24 characters.
Use upper and lower cases, numbers, and punctuation.
Use upper and lower cases, numbers, and punctuation.
I suggest using a pseudorandom password generator (such as the one in PasswordSafe) to create them.
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 this
The terminology ejbca uses is very confusing, even to someone experienced. Describing each term fully is more than I can do in this
document
document, but hopefully , but hopefully a brief description of the basics wia brief description of the basics will ll be helpful:be helpful:
Authentication Code
Authentication Code ‐ Each Crypto Token has an associated Authentication Code that is used to encrypt the contents of ‐ Each Crypto Token has an associated Authentication Code that is used to encrypt the contents of
that particular Crypto Token.
that particular Crypto Token.
Certificate
Certificate ‐ ‐ A data structure (usuA data structure (usually) ally) in X.509 format that typically in X.509 format that typically contaicontains:ns:
A Public Key
A Public Key
Information about the owner of the key (in X.500 format)
Information about the owner of the key (in X.500 format)
"Certificate Extensions" defining how the certificate is meant to be used
"Certificate Extensions" defining how the certificate is meant to be used
The CA certificates that validate the certificate we are examining
The CA certificates that validate the certificate we are examining
Certificate Extension
Certificate Extension ‐ Data field in a Certificate that "suggests" how a certificate is meant to be used. ‐ Data field in a Certificate that "suggests" how a certificate is meant to be used.
Certificate Signing Request (CSR) ‐
Certificate Signing Request (CSR) ‐ A file containing a Public Key, as well as optional Certificate Extension information A file containing a Public Key, as well as optional Certificate Extension information
that a CA *may* use when generating a Certificate.
that a CA *may* use when generating a Certificate.
Crypto Token
Crypto Token ‐ ‐ The logical unit that stoThe logical unit that stores all res all the public/private keypairs ownthe public/private keypairs owned by ed by a particular CA. By a particular CA. By default, theydefault, they
are held in ejbca's database.
are held in ejbca's database.
Enrollment Code
Enrollment Code ‐ The password (or other "Token") used to validate a certificate request. ‐ The password (or other "Token") used to validate a certificate request.
HSM
HSM ‐ Hardware Security Module. A physical device used to generate and/or store Keys. ‐ Hardware Security Module. A physical device used to generate and/or store Keys.
JKS
JKS ‐ Java Key Store. An unencrypted, file‐based method of storing encryptions keys. ‐ Java Key Store. An unencrypted, file‐based method of storing encryptions keys.
Key
Key ‐ What ejbca refers to as a "Key" is actually a ‐ What ejbca refers to as a "Key" is actually a "Keypair": a Public key "Keypair": a Public key and its matchiand its matching Private key.ng Private key.
Key Algorithm
Key Algorithm ‐ ‐ The asymmetThe asymmetric cryptographic algric cryptographic algorithorithm used to perform pm used to perform public key ublic key encryptionencryption. Usually . Usually RSA orRSA or
Elliptic Curve. One must be specified in every certificate.
Elliptic Curve. One must be specified in every certificate.
Key Alias
Key Alias ‐ A "friendly" name for a Key(pair) that is used for a particular purpose. Ejbca uses the following Key Aliases ‐ A "friendly" name for a Key(pair) that is used for a particular purpose. Ejbca uses the following Key Aliases
to refer to the Keys every ejbca CA must have for basic functionality:
to refer to the Keys every ejbca CA must have for basic functionality:
defaultKey
defaultKey: The key used by default (Required).: The key used by default (Required).
certSignKey
certSignKey: The key used for certificate signing. It must comply with the Signature Algorithm defined for: The key used for certificate signing. It must comply with the Signature Algorithm defined for
the CA using the key.
the CA using the key.
crlSignKey
crlSignKey: The key used for CRL signing. The use of this key is deprecated ‐ the certSignKey will always be: The key used for CRL signing. The use of this key is deprecated ‐ the certSignKey will always be
used for this purpose.
used for this purpose.
keyEncryptKey
keyEncryptKey: The key used for key recovery when reversible encryption is enabled. It must use the RSA: The key used for key recovery when reversible encryption is enabled. It must use the RSA
Passwords
Passwords
Ejbca's Terminology
A minimum of X.500 notation:
A minimum of X.500 notation:
CN = Common Name, usually is the FQDN of your CA
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
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
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)
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 should
You are not required to have an expert understanding of java and jboss, but some knowledge is helpful. At the least, you should
understand:
understand:
What a .jar file is
What a .jar file is
What an .ear file is
What an .ear file is
The rudiments of XML (about 10 minutes of study is enough)
The rudiments of XML (about 10 minutes of study is enough)
The notion of "deploying" an application to a platform like Jboss
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
You will need to create a fairly large (10+) number of unique passwords just to install ejbca. So get the passwordsafe utility frompasswordsafe utility from
Sourceforge
Sourceforge. Originally co‐written by Bruce Schneier, it is the only password repository I trust. I'll keep a running tally of the. Originally co‐written by Bruce Schneier, it is the only password repository I trust. I'll keep a running tally of the
passwords we create, and have included a list of them at the end of this document.
passwords 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.
I cannot emphasize the importance of using strong passwords enough.
All of our other security steps are meaningless without strong passwords.
All of our other security steps are meaningless without strong passwords.
Use passwords of at least 24 characters.
Use passwords of at least 24 characters.
Use upper and lower cases, numbers, and punctuation.
Use upper and lower cases, numbers, and punctuation.
I suggest using a pseudorandom password generator (such as the one in PasswordSafe) to create them.
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 this
The terminology ejbca uses is very confusing, even to someone experienced. Describing each term fully is more than I can do in this
document
document, but hopefully , but hopefully a brief description of the basics wia brief description of the basics will ll be helpful:be helpful:
Authentication Code
Authentication Code ‐ Each Crypto Token has an associated Authentication Code that is used to encrypt the contents of ‐ Each Crypto Token has an associated Authentication Code that is used to encrypt the contents of
that particular Crypto Token.
that particular Crypto Token.
Certificate
Certificate ‐ ‐ A data structure (usuA data structure (usually) ally) in X.509 format that typically in X.509 format that typically contaicontains:ns:
A Public Key
A Public Key
Information about the owner of the key (in X.500 format)
Information about the owner of the key (in X.500 format)
"Certificate Extensions" defining how the certificate is meant to be used
"Certificate Extensions" defining how the certificate is meant to be used
The CA certificates that validate the certificate we are examining
The CA certificates that validate the certificate we are examining
Certificate Extension
Certificate Extension ‐ Data field in a Certificate that "suggests" how a certificate is meant to be used. ‐ Data field in a Certificate that "suggests" how a certificate is meant to be used.
Certificate Signing Request (CSR) ‐
Certificate Signing Request (CSR) ‐ A file containing a Public Key, as well as optional Certificate Extension information A file containing a Public Key, as well as optional Certificate Extension information
that a CA *may* use when generating a Certificate.
that a CA *may* use when generating a Certificate.
Crypto Token
Crypto Token ‐ ‐ The logical unit that stoThe logical unit that stores all res all the public/private keypairs ownthe public/private keypairs owned by ed by a particular CA. By a particular CA. By default, theydefault, they
are held in ejbca's database.
are held in ejbca's database.
Enrollment Code
Enrollment Code ‐ The password (or other "Token") used to validate a certificate request. ‐ The password (or other "Token") used to validate a certificate request.
HSM
HSM ‐ Hardware Security Module. A physical device used to generate and/or store Keys. ‐ Hardware Security Module. A physical device used to generate and/or store Keys.
JKS
JKS ‐ Java Key Store. An unencrypted, file‐based method of storing encryptions keys. ‐ Java Key Store. An unencrypted, file‐based method of storing encryptions keys.
Key
Key ‐ What ejbca refers to as a "Key" is actually a ‐ What ejbca refers to as a "Key" is actually a "Keypair": a Public key "Keypair": a Public key and its matchiand its matching Private key.ng Private key.
Key Algorithm
Key Algorithm ‐ ‐ The asymmetThe asymmetric cryptographic algric cryptographic algorithorithm used to perform pm used to perform public key ublic key encryptionencryption. Usually . Usually RSA orRSA or
Elliptic Curve. One must be specified in every certificate.
Elliptic Curve. One must be specified in every certificate.
Key Alias
Key Alias ‐ A "friendly" name for a Key(pair) that is used for a particular purpose. Ejbca uses the following Key Aliases ‐ A "friendly" name for a Key(pair) that is used for a particular purpose. Ejbca uses the following Key Aliases
to refer to the Keys every ejbca CA must have for basic functionality:
to refer to the Keys every ejbca CA must have for basic functionality:
defaultKey
defaultKey: The key used by default (Required).: The key used by default (Required).
certSignKey
certSignKey: The key used for certificate signing. It must comply with the Signature Algorithm defined for: The key used for certificate signing. It must comply with the Signature Algorithm defined for
the CA using the key.
the CA using the key.
crlSignKey
crlSignKey: The key used for CRL signing. The use of this key is deprecated ‐ the certSignKey will always be: The key used for CRL signing. The use of this key is deprecated ‐ the certSignKey will always be
used for this purpose.
used for this purpose.
keyEncryptKey
keyEncryptKey: The key used for key recovery when reversible encryption is enabled. It must use the RSA: The key used for key recovery when reversible encryption is enabled. It must use the RSA
Passwords
Passwords
Ejbca's Terminology
algorithm.
algorithm.
testKey
testKey: The key used by the healthcheck process to verify that a Crypto Token is usable. A 1024‐bit RSA: The key used by the healthcheck process to verify that a Crypto Token is usable. A 1024‐bit RSA
key is recommended to reduce computation time.
key is recommended to reduce computation time.
Key Specification
Key Specification ‐The length of the modulus used by the Key Algorithm. For RSA, it is usually 2048 or 4096 bits long. ‐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
For Elliptic Curve, it is usually 192, 256, 384, or 512 b192, 256, 384, or 512 bits long.its long.
Keystore
Keystore ‐ A file used to store certificate information outside of the database. Normally only holds the certificates for ‐ A file used to store certificate information outside of the database. Normally only holds the certificates for
ejbca's web interface. See: JKS
ejbca's web interface. See: JKS
Private Key ‐
Private Key ‐ Half of a Keypair generated for use with asymmetric encryption. This is the half that is kept private, and Half of a Keypair generated for use with asymmetric encryption. This is the half that is kept private, and
not shared.
not shared.
Public Key ‐
Public Key ‐ The other half of a Keypair, which is shared with anyone/anything you wish to establish secure The other half of a Keypair, which is shared with anyone/anything you wish to establish secure
communications with.
communications with.
Signature Algorithm
Signature Algorithm ‐The cryptographic hash algorithm used by a CA to guarantee a certificate's validity. ‐The cryptographic hash algorithm used by a CA to guarantee a certificate's validity.
Soft Token
Soft Token ‐ A Token (Crypto, or otherwise) held in the database, rather than in a different format like a JKS or HSM. ‐ A Token (Crypto, or otherwise) held in the database, rather than in a different format like a JKS or HSM.
Token
Token ‐ A generic term for a secret key. This could be anything from an 8‐character ASCII password to an 8192‐bit RSA ‐ A generic term for a secret key. This could be anything from an 8‐character ASCII password to an 8192‐bit RSA
modulus. In the context of an "end entity", ejbca specifically uses this word to refer to the key used to encrypt a
modulus. In the context of an "end entity", ejbca specifically uses this word to refer to the key used to encrypt a
certificate issued to that "end entity".
certificate 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. Details
A final word of advice before we begin: You are building a device that will be the source of all trust in your environment. Details
matter. Accuracy matters ‐ even more than usual. And if it isn't right, it's wrong. Go fix it.
matter. 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 Red
I use CentOS in my lab, generally speaking. This is because the vast majority of actual enterprise linux installations run on Red
Hat/Fedora. Debian/Ubuntu is prolific in software development environments, but that's really the only place I find it.
Hat/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
I'm performing this installation using64‐bit CentOS 6.564‐bit CentOS 6.5 on a vm. There is a single root partition for storage, a two‐core CPU, 2 GB on a vm. There is a single root partition for storage, a two‐core CPU, 2 GB
of RAM (which is more than it needs), and a single ethernet network interface.
of RAM (which is more than it needs), and a single ethernet network interface.
I am using
I am usingejbca version 6.1.1ejbca version 6.1.1, community edition. It is written in java, and runs on the jboss platform. It uses, community edition. It is written in java, and runs on the jboss platform. It uses antant for jboss for jboss
management, and requires a database (I use mysql) for storage.
management, and requires a database (I use mysql) for storage.
Java
Java: DO NOT waste time trying to get: DO NOT waste time trying to get java 1.7 java 1.7 to work with this app at present. to work with this app at present.
It can be done, but the payoff compared to the work involved makes it undesirable.
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 largely
Running 1.6 has ramifications for Elliptic Curve support, but the way that ejbca uses java makes them largely
irrelevant.
irrelevant.
Just use the
Just use theopenjdk version of java 1.6openjdk version of java 1.6 that is distributed by the standard CentOS online repos. that is distributed by the standard CentOS online repos.
If you install java 1.7, then the "
If you install java 1.7, then the "javajava" command will invoke 1.7 by " command will invoke 1.7 by virtue ofvirtue ofalternativesalternatives. Theoreti. Theoretically,cally, alternativesalternatives should take care of redirecting all java‐related executable paths to the correct executables. However, what I found is that the the
should take care of redirecting all java‐related executable paths to the correct executables. However, what I found is that the the
1.7 implementation from openjdk is incomplete, and ejbca will end up needing to use portions of version 1.6. This inevitably ends
1.7 implementation from openjdk is incomplete, and ejbca will end up needing to use portions of version 1.6. This inevitably ends
up with a non‐working ejbca install.
up with a non‐working ejbca install.
If you truly
If you truly must use 1.7, you'll need to manually compile and must use 1.7, you'll need to manually compile and instinstall all updated versionupdated versions ofs of gccgcc,,gcjgcj, and Oracle Java. This may be, and Oracle Java. This may be
necessary in a fully‐certified production environment, but I will stay with 1.6 until everything becomes part of the standard CentOS
necessary in a fully‐certified production environment, but I will stay with 1.6 until everything becomes part of the standard CentOS
code stream.
code stream.
Jboss
Jboss: I'm using: I'm using7.1.1 Final7.1.1 Final. It actually is the least painful thing to deal with in this setup. Previous versions of jboss are built with. It actually is the least painful thing to deal with in this setup. Previous versions of jboss are built with
the idea of multiple application deployments on a single platform ‐ the current 7.1.1 download installs with a single standalone
the idea of multiple application deployments on a single platform ‐ the current 7.1.1 download installs with a single standalone
deployment.
deployment.
Ant
Ant: You'll need to download and install a current version of: You'll need to download and install a current version of antant ‐ the one from CentOS is too old. I'm using ‐ the one from CentOS is too old. I'm using ant‐1.9.3‐ant‐1.9.3‐
2.fc21.noarch.rpm
2.fc21.noarch.rpm from the Fedora repository. from the Fedora repository.
Mysql
Mysql: I'm using the standard: I'm using the standard mysql version 5.1.73‐3.el6_5mysql version 5.1.73‐3.el6_5 from the CentOS repos. The version really doesn't matter, other than from the CentOS repos. The version really doesn't matter, other than
the various inevitable security problems you have with mysql.
the various inevitable security problems you have with mysql.
Java Mysql Connector
Java Mysql Connector: I'm using the: I'm using the mysql‐connector‐java.noarchmysql‐connector‐java.noarch from Oracle, version 5.1.30. There is a configuration tweak in from Oracle, version 5.1.30. There is a configuration tweak in
jboss that is necessary in order to use this version. Older versions do not have this problem (but may have others).
jboss that is necessary in order to use this version. Older versions do not have this problem (but may have others).
Final Advice
Final Advice
CentOS Installation
CentOS Installation
Required Software
Required Software
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 become significant.
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 becomes
important 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 simple decision, 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 jboss
installation. This would have ramifications for hostname resolution, and this level of complexity is beyond the scope of this how‐to.
Application Logical Layout
When running ejbca in a lab environment, it is tempting to disregard the full FQDN and only use the hostname when identifying your CAs. You would be able to get away with this by virtue of your lab's isolation from public DNS
resolution. Trust me ‐ Don't do this. Define a full FQDN for your server that would be compatible with public DNS, and continue 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 used by 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 this example, 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 to issue 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 be at 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 management CA 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 the certificates 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 web service hosting the interface. The initial version of this certificate will be a "self‐signed" one issued by the Management CA and created 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 the
server (rootca.yourcompany.net) for its CN.
The Production CA will issue a "Server Certificate" that will replace the one issued by the Management CA. This replacement certificate will permanently secure connections to the web administration pages (at
https://rootca.yourcompany.net), and will al so use "rootca.yourcompany.net" f or the CN.
Despite having the same CN, these are two separate certificates used for two distinct purposes. To try and keep this clear, I will always 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 upresolv.conf and make sure an A record for rootca.yourcompany.net exists on the configured DNS servers. PTR records are also a g ood 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
Runyum 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 <1024 ‐ don't bother trying to change them in the application itself.
If you want to use the standard web ports, then set upiptables to do port forwarding. You can do this from the gnome firewall management app:
Add port forward 80 ‐‐> local 8080, protocol tcp Add port forward 442 ‐‐> local 8442, protocol tcp Add port forward 443 ‐‐> local 8443, protocol tcp
Once finished, it's a good idea to verify your /etc/sysconfig/iptables file:
vi /etc/sysconfig/iptables ### Start iptables ###
# Firewall configuration written by system-config-firewall # Manual customization of this file is not recommended. *mangle :PREROUTING ACCEPT [0:0] :INPUT ACCEPT [0:0] :FORWARD ACCEPT [0:0] :OUTPUT ACCEPT [0:0] :POSTROUTING ACCEPT [0:0]
-A PREROUTING -i eth0 -p tcp --dport 80 -j MARK --set-mark 0x64 -A PREROUTING -i eth0 -p tcp --dport 442 -j MARK --set-mark 0x65 -A PREROUTING -i eth0 -p tcp --dport 443 -j MARK --set-mark 0x66 COMMIT
*nat
:PREROUTING ACCEPT [0:0] :OUTPUT ACCEPT [0:0] :POSTROUTING ACCEPT [0:0]
-A PREROUTING -i eth0 -p tcp --dport 80 -m mark --mark 0x64 -j DNAT --to-destination :8080 -A PREROUTING -i eth0 -p tcp --dport 442 -m mark --mark 0x65 -j DNAT --to-destination :8442 -A PREROUTING -i eth0 -p tcp --dport 443 -m mark --mark 0x66 -j DNAT --to-destination :8443 COMMIT
*filter
:INPUT ACCEPT [0:0] :FORWARD ACCEPT [0:0] :OUTPUT ACCEPT [0:0]
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT -A INPUT -p icmp -j ACCEPT
-A INPUT -i lo -j ACCEPT
-A INPUT -i eth0 -m state --state NEW -m tcp -p tcp --dport 8080 -m mark --mark 0x64 -j ACCEPT -A INPUT -i eth0 -m state --state NEW -m tcp -p tcp --dport 8442 -m mark --mark 0x65 -j ACCEPT -A INPUT -i eth0 -m state --state NEW -m tcp -p tcp --dport 8443 -m mark --mark 0x66 -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT
-A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp --dport 442 -j ACCEPT -A INPUT -j REJECT --reject-with icmp-host-prohibited
-A FORWARD -j REJECT --reject-with icmp-host-prohibited COMMIT
### End iptables ###
If you are only working in the cli, I'd manually edit /etc/sysconfig/iptables , then reload the firewall:
service iptables reload
Regardless of how you do it, it's a good idea to back up the firewall config:
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 d river 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 alternatives
prevents it from affecting anything. Just ignore it.
yum install java-1.6.0-openjdk
yum install /path/to/your/ant-noarch.rpm yum install mysql-server
yum 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 will define asJAVA_HOME instandalone.conf : /usr/lib/jvm/java/bin/java -version . Once this is done, you can be sure that java works, and executes the expected version regardless of path:
/usr/lib/jvm/java/bin/java -version java 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
This is a basic mysql setup that isn't particularly tuned for security, but is secure enough for lab purposes. Be sure to create the
This is a basic mysql setup that isn't particularly tuned for security, but is secure enough for lab purposes. Be sure to create the
mysql
mysql directoridirectories and updatees and update /etc/my.cnf/etc/my.cnf before starting the service for the first time, as you can't easily change the binary log before starting the service for the first time, as you can't easily change the binary log
location once it has been created.
location once it has been created.
This config also forces utf‐8 encoding, which is a requirement of ejbca.
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.
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 a
I enable binary logging in order to make database recovery as bulletproof as I can. But there's no substitute for a
regular
regular mysqld mysqldumpump..
Ejbca includes a sample
Ejbca includes a sample backup script for backup script for this purposethis purpose..
mkdir
mkdir -p -p /var/l/var/log/mysog/mysql/binql/bin
chown -R mysql:mysql /var/log/mysql
chown -R mysql:mysql /var/log/mysql
vi /etc/my.cnf vi /etc/my.cnf ### Start my.cnf ### ### Start my.cnf ### datadir=/var/lib/mysql datadir=/var/lib/mysql socket=/var/lib/mysql/mysql.sock socket=/var/lib/mysql/mysql.sock user=mysql user=mysql
# Disabling symbolic-links is recommended to prevent assorted security risks # Disabling symbolic-links is recommended to prevent assorted security risks symbolic-links=0 symbolic-links=0 #UTF-8 #UTF-8 character-set-server=utf8 character-set-server=utf8 collation-server=utf8_unicode_ci collation-server=utf8_unicode_ci init-connect='SET NAMES utf8' init-connect='SET NAMES utf8' #character-set-client = utf8 #character-set-client = utf8 # Logging Config # Logging Config # Binary logging # Binary logging log-bin log-bin server-id server-id = = 11 log_bin
log_bin = = /var/log/mysql/mysql-bin.log/var/log/mysql/mysql-bin.log expire_logs_days expire_logs_days = = 1010 max_binlog_size max_binlog_size = = 100M 100M #log #log #log-error #log-error #log-slow-queries #log-slow-queries [mysqld_safe] [mysqld_safe] log-error=/var/log/mysql/mysqld.log log-error=/var/log/mysql/mysqld.log pid-file=/var/run/mysqld/mysqld.pid pid-file=/var/run/mysqld/mysqld.pid # Custom config # Custom config #[client] #[client] #default-character-set=utf8 #default-character-set=utf8 ### End my.cnf ### ### End my.cnf ###
To make a point about the
To make a point about the mysql mysql user continuing to own everything mysql‐related: user continuing to own everything mysql‐related:
chown mysql:mysql /etc/my.cnf
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 for
Now, run the "secure installation" script (take the default actions), log in to mysql, and create the database and user account for
ejbca:
ejbca:
service mysqld start
service mysqld start
Configuring Mysql
mysql_
mysql_securesecure_insta_installatiollationn
mysql
mysql -u -u root root -p-p
create database ejbcadb;
create database ejbcadb;
grant all privileges on ejbcadb.* to 'ejbcadbuser'@'localhost' identified by 'password';
grant all privileges on ejbcadb.* to 'ejbcadbuser'@'localhost' identified by 'password';
flush privileges;
flush privileges;
exit
exit
Verify that you can log in to mysql as
Verify that you can log in to mysql as ejbcadbuserejbcadbuser and test your access: and test your access:
mysql
mysql -u -u ejbcadejbcadbuser buser -p-p
use ejbcadb;
use ejbcadb;
show grants for ejbcadbuser@localhost;
show grants for ejbcadbuser@localhost;
exit
exit
Later, we will change the permissions on the ejbcadb database to make
Later, we will change the permissions on the ejbcadb database to make ejbcadbuser@localhostejbcadbuser@localhost's access a little more limited.'s access a little more limited.
Finalize the mysql installation by performing a
Finalize the mysql installation by performing a service mysqld restartservice mysqld restart and checking the log at and checking the log at
/var/log/mysql/mysqld.log
/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
Now we're going to set up the directory structure for the app itself. I prefer to put my apps in /opt/opt. By default, all the ejbca. By default, all the ejbca
documentation assumes that you install it in the service user's homedir.
documentation 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.
I like to use links to generic paths so that upgrading code is easier. This method also works well with Atlassian products.
The
The/opt/default/opt/default directory is used to hold vanilla versions of code so you can easily wipe things out and start over. directory is used to hold vanilla versions of code so you can easily wipe things out and start over.
mkdir
mkdir /opt/d/opt/defaultefault
cd /opt/default
cd /opt/default
wget
wget http:/http://downl/download.jboad.jboss.ooss.org/jborg/jbossas/7ssas/7.1/jbo.1/jboss-as-ss-as-7.1.1.7.1.1.Final/Final/jboss-jboss-as-7.1as-7.1.1.Fin.1.Final.zipal.zip
wget
wget http:/http://downl/downloads.soads.sourceourceforge.forge.net/prnet/project/oject/ejbca/ejbca/ejbca6ejbca6/ejbca/ejbca_6_1_1_6_1_1/ejbca/ejbca_ce_6__ce_6_1_1.zi1_1.zipp
unzip *.zip unzip *.zip cd .. cd .. ln -s /opt/ejbca_ca_6_1_1 ejbca ln -s /opt/ejbca_ca_6_1_1 ejbca ln -s /opt/jboss-as-7.1.1.Final jboss ln -s /opt/jboss-as-7.1.1.Final jboss cp -rp default/jboss-as-7.1.1.Final . cp -rp default/jboss-as-7.1.1.Final . cp -rp default/ejbca_ce_6_1_1 . cp -rp default/ejbca_ce_6_1_1 .
Now we set up our service accounts. I made two ‐ a system account named
Now we set up our service accounts. I made two ‐ a system account named jbossjboss, and an, and anejbcaejbca account for administrative use account for administrative use
after the server is built.
after the server is built.
It is important that
It is important thatjbossjboss has has/bin/bash/bin/bash for a shell and a for a shell and a/opt/jboss/opt/jboss as a homedir. as a homedir.
useradd -s /bin/bash -r -d /opt/jboss -M -U jboss
useradd -s /bin/bash -r -d /opt/jboss -M -U jboss
useradd -m -U -G jboss,wheel ejbca
useradd -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:
Now that our service user has been created, we can create the directory that will hold our jboss console logs:
mkdir
mkdir -p -p /var/l/var/log/ejbog/ejbcaca
chown jboss:jboss /var/log/ejbca
chown 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 take
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 take
a vm snapshot.
a vm snapshot.
Creating the Directory Structure
Creating the Directory Structure
Creating the OS User Accounts
Creating the OS User Accounts
Creating the Console Log Directory
It's time to install jboss. We will not configure every detail (no mail, default logging), but we will do enough to get the platform
It's time to install jboss. We will not configure every detail (no mail, default logging), but we will do enough to get the platform
running and tweaked the way ejbca needs for installation.
running and tweaked the way ejbca needs for installation.
We begin by configuring the jboss instance that ejbca will use. It's named "
We begin by configuring the jboss instance that ejbca will use. It's named "standalonestandalone", and exists by default in version 7.1.1.", and exists by default in version 7.1.1.
The
The/opt/jboss/bin/opt/jboss/bin directory contains a script named directory contains a script named standalone.shstandalone.sh that is the primary start point for jboss. This script that is the primary start point for jboss. This script
references a configuration file in the same directory named
references a configuration file in the same directory namedstandalone.confstandalone.conf. We will not need to modify the startup script, but. We will not need to modify the startup script, but
we will need to modify the configuration file.
we will need to modify the configuration file.
First, we make a backup of the default config:
First, we make a backup of the default config:
cd /opt/jboss/bin
cd /opt/jboss/bin
cp standalone.conf standalone.conf.orig
cp 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
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 actually
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 actually
need to.
need to.
Important: The bits below are only the parts I modified ‐ don't delete the rest of the files!
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 that
I've added some commented entries that you might need to use if you're troubleshooting, but really the only things that
matter are
matter areJAVA_HOMEJAVA_HOME and andJAVA_OPTSJAVA_OPTS..
Just add the comments to the top of the file and replace the default
Just add the comments to the top of the file and replace the default JAVA_HOMEJAVA_HOME and andJAVA_OPTSJAVA_OPTS..
### Start standalone.conf Delta ### ### Start standalone.conf Delta ### #ejbca config #ejbca config # # #javaHome=/usr/lib/jvm/java #javaHome=/usr/lib/jvm/java #jbossHome=/opt/jboss #jbossHome=/opt/jboss #jbossClasspath=/usr/share/java/mysql.jar #jbossClasspath=/usr/share/java/mysql.jar JAVA_HOME="/usr/lib/jvm/java" JAVA_HOME="/usr/lib/jvm/java"
JAVA_OPTS="Xms128m Xmx512m XX:PermSize=128m XX:MaxPermSize=256m Djava.net.preferIPv4Stack=true 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" Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000" ### End standalone.conf Delta ###
### End standalone.conf Delta ###
The
The/opt/jboss/bin/standalone.sh/opt/jboss/bin/standalone.sh script can always be used to start and stop jboss manually. However, we need to script can always be used to start and stop jboss manually. However, we need to
configure a service instance named "
configure a service instance named "ejbcaejbca" to handle the startup and shut" to handle the startup and shutdown of jboss (and down of jboss (and subsequsubsequently, ejbca). ently, ejbca). Thankfully,Thankfully,
the jboss folks give us an example script to use.
the jboss folks give us an example script to use.
I know it is confusing to name the jboss service "
I know it is confusing to name the jboss service "ejbcaejbca", but I am assuming that this jboss instance will only run the", but I am assuming that this jboss instance will only run the
ejbca application and not be used for any other purpose.
ejbca 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.
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:
First, we copy the examples to their proper locations:
cp /opt/jboss/bin/init.d/jboss-as-standalone.sh /etc/init.d/ejbca
cp /opt/jboss/bin/init.d/jboss-as-standalone.sh /etc/init.d/ejbca
mkdir
mkdir /etc/e/etc/ejbcajbca
cp /opt/jboss/bin/init.d/jboss-as.conf /etc/ejbca/ejbca-init.conf
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.
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.
Again, these are only the changes that must be made to the default file content.
Installing Jboss
Installing Jboss
Configuring the Standalone Jboss
Configuring the Standalone Jboss
Instance
Instance
Creating the Jboss Init Service
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 ###
Theejbca-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 usechkconfig to add our services to the rc hierarchy and set the runlevels:
chkconfig --add ejbca
chkconfig --level 345 mysqld on chkconfig --level 345 ejbca on
The init files should remain owned by root:root, with the default permissions.
Although we have added theejbca service withchkconfig, and have set a start order value in the chkconfig portion of the init
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 of97, and a kill integer of 17. This puts it before thelocal 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 init script forejbca 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 andejbca .
Theoretically,chkconfig andyum are supposed to build these links for us automatically. But sometimes, well, things just 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 ejbca
lrwxrwxrwx. 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 ejbca requires.
cd /opt/jboss/modules/sun/jdk/main vi 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 ###
<path name="sun/security/x509"/> <path name="sun/security/pkcs11"/>
<path name="sun/security/pkcs11/wrapper"/> <path name="sun/security/action"/>
### 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 version 5.1.30. This version breaks jboss, as it requires an additional config variable that jboss doesn't expect. You can assume all versions of 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 that we 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
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/main
ln -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 ###
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql"> <resources> <resource-root path="mysql-connector-java.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module> ### 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 directory tree.
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 in 1528ms - 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
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 the configuration:
cd /opt/jboss/standalone/configuration cp 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 ###
<driver name="com.mysql.jdbc.Driver" module="com.mysql">
<xa-datasource-class>com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> </driver>
### End standalone.xml Snip ###
Thestandalone.xml file is the primary configuration file in jboss, and we will be working with it several times during installation. 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, thestandalone instance is defined with an h2/hsqldb database connector, and an example database. If left
unchanged, 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:
<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
<connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
Enabling the Mysql Connector
<driver>h2</driver> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> Also remove:
<driver name="h2" module="com.h2database.h2">
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>
### End standalone.xml Delta ###
Now, if you watch the console log when restarting jboss, you should no longer see:
22:46:29,570 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 27) JBAS010403: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
But you should continue to see:
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)
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/java
rm mysql-connector-java.jar
ln -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 tostandalone.xml to update the driver stanza:
### Start standalone.xml Delta ### <datasources>
<drivers>
<driver name="com.mysql.jdbc.Driver" module="com.mysql"> <driver-class>com.mysql.jdbc.Driver</driver-class> <xa-datasource-class>com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> </driver> </drivers> </datasources> ### End standalone.xml Delta ###
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 not need 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 is touched by this action.
The mysql database will be auto‐populated when we first deploy ejbca, but will not otherwise be touched by any of the
ant scripts.
The database does not store any configuration data, but it can be affected by every configuration change you make. Theant install command tries to create the keystore files each time it is run, even if the files exist.
Portions ofstandalone.xml can be changed by b othant build andant install, but only in response to changes made to our.properties files.