Invariant Properties

Anyone using low-level encryption libraries should know that you need both a SecretKey and a “random” IV. The easiest way to get a good IV is to use a SecureRandom instance to generate the necessary value.

This approach has one major drawback – it requires you to store or transmit a 16- or even 32-byte value. This is not always a trivial concern. As one example many applications require the user to enter a BASE-32-encoded license key and including a full IV can double the length of the license key. Longer keys can be a real headache when dealing with low-bandwidth channels such as a telephone call to customer support or stickers on optical media – people are more likely to mis-enter the key, you have to use a smaller font which could cause problems for visually impaired users, etc.

Another example is database records. A full IV can significantly increase the size of a record that contains only an integer primary key and an encrypted value – that means fewer records per page. Records/page isn’t a big concern on smaller databases but it matters as you scale up.

What if the full IV could be replaced by a 4-byte counter? That drops 12 bytes per record, or a staggering 20 characters when using BASE-32 encoding.

• Using the counter directly is insecure. Merging the counter with a salt, e.g. by using XOR or adding it using BigInteger math, is better but still relatively insecure.
• Encrypting the counter with the same encryption key as the data is also insecure.
• Encrypting the counter using a separate encryption key is secure. You don’t have to mix the counter with a salt but there’s no downside to it.

The last approach gives us another benefit – it’s a natural way to split the effective encryption key into two pieces that can be stored independently. (E.g., one key is stored on the filesystem outside of the webapp and the other key is provided via the application container using JNDI.) If we use a salt with the counter we have three pieces that can be stored independently.

This gives us a lot of flexibility when using a low-level library like JCE. Higher-level libraries like ESAPI or GPG handle IVs themselves but it’s often possible to explicitly set the IV. For instance the ESAPI CipherSpec class provides a mechanism to set the IV.

Does this mean that we should always use a sequence to generate an IV? No – it requires a little more effort to generate an IV from a sequence than to use a random byte array. You also have to consider the possibility that someone will “improve” the implementation later and use the same encryption key for IV and data, or remove the encryption altogether. However it’s a good tool to have in your arsenal for the times when it is appropriate.

I was recently reading Spring Security 3 and it made an interesting point about some LDAP servers.

The servers never provide the (hashed) password.

That raises the immediate question of how you can possibly authenticate the user. The answer is straightforward – the underlying database query becomes

select prop1, prop2, prop3 from users where username='user' and password='hashed.password'

instead of

select * from users where username='user'

This is hard to enforce in a standard database unless you use stored procedures or, maybe, use views and column-based access permissions. The former would work well, the latter would undoubtably be fragile and quietly relaxed by someone who “didn’t see the harm”.

However the benefits of this approach should be obvious. If an attaker is limited to SQL injection the first approach prevents attackers from seeing the hashed passwords (provided the column is properly protected). The second approach does not. Of course this is not a panacea since there are many other attack vectors.

How do you handle hashing?

This approach immediately raises the question of how you handle hashing. There are three immediate possibilities.

Use a system-wide salt. This is the easiest approach but it’s also the weakest.

Use a hybrid username-based/system-wide salt. Salts based on usernames alone are fairly weak since they’re easy to guess. Hybrid salts based on usernames and a system-wide salt are stronger. A minimum salt would be H(username.secret).

Use a random salt. Random salts are the strongest but they require two queries. The first gets the salt by username, the second gets the rest of the data by username and hashed password.

In all cases the standard hashing rules apply. If you use a different app, e.g., LDAP, to manage the authentication information then you should do whatever it expects. If you’re rolling your own you should use a trusted library like bcrypt or modern hashing techniques.

A quick hand-wave of the latter:

byte[] hash(String password, String username, String secret) {
   byte[] salt = crypto.hash(username + secret);
   byte[] hash = crypto.hash(password + salt);

   for (int round = 0; round < 1000; round++) {
      hash = crypto.hash(hash ^ salt);
   }

   return hash;
}

The multiple hashes are required since serious attackers now have access to complete rainbow tables and GPU farms.

LDAP

Going back a step – why does the spring security book discuss LDAP?

There are several reasons. First, there are now several good embedded LDAP implementations. It can be a separate .rar in your .ear file, it could even be a single .war file. This should be no more surprising than an embedded database implementation like Jetty or H2.

Second, the implementation has already been written. You have to configure it, of course, but you don’t have to write any code.

Finally, it integrates with enterprise systems. This isn’t an issue with a public-facing site but is very important with internal sites.

A few people have asked what’s on my desk since I’m posting (irregularly) on unusual topics. The answer is actually pretty boring. My posts are mostly the result of some lateral thinking and being unable to find any answers in google and stack exchange searches.

Scala

I’m taking the 7 week Functional Programming Principles in Scala course at Coursera. I’m also reading the book Programming In Scala. (I have the first edition.) I’ll probably also pick up Scala in Depth and/or Scala in Action.

As a rule I’ve found that it takes about 6 months in a new language to become familiar with the standard libraries and at least two years to become familiar with the ecosystem. (That’s the difference between being familiar with java.util.* etc and being familiar with Spring/EJB3, hibernate, at least one web framework, plus whatever you need for your specific tasks.)

So do I think I’ll be fluent in Scala in two months? No, of course not, but I should be able to work in the language even if I don’t yet have a good familiarity with, e.g., Play or Akka.

Sidenote: Ruby and JRuby are popular in many shops in the Boulder area.

Information Security

I’m also taking the 10 week Information Security and Risk Management in Context course at Coursera. The Coursera class is free but you can also enroll at the University of Washington for a certification program or for graduate level credit.

I’m still on the fence on this class. I’m a techie but have been studying for PMP and CISSP certs to get a broader perspective (but see below). The first week focused on the role of the CISO (C-level executive for information security – think CEO, CFO, CIO, CTO, etc.) and that’s a bit too far from my world. But we’ll see how the next few classes go.

Do Certificates Have Value?

There are two answers to this question. The less important one is that they can get you past the HR gatekeepers. Today the tech job market is extremely hot but at times in the past, and undoubtably at times in the future, there were far more applicants than positions and the HR gatekeepers would use things like certifications to winnow the resumes. The cert wouldn’t get you the job but it might get you the interview.

The more important answer is that studying for a cert forces you to take a broader view. I’ve never used much of what I learned when studying for my Security+ and java certs… but I did use things that I would have never seen unless I had studied for those exams.

Hence studying for the PMP and CISSP exams. I don’t have the practical experience for either cert but I’ve learned a tremendous amount by studying for them. And who knows – I’m still on the fence about getting a CISSP (Assoc) cert. I could have probably passed an earlier revision of the exam but it’s a moving target.

Prep Work For Next Job

EJB3 in Action. I know the Spring framework very well but some sites use EJB3. This should go quickly since I’ve read the first edition of the book and took a 3-day class on EJB 3.1 on the Sun Oracle campus in Broomfield, CO.

PCI DSS specification. These are the security requirements for any system that manages credit card data. I’ve touched on many of them previously. Again this should go quickly (cough) since I’ve already read the specification and I’ll just be refreshing my memory.

This is part of a series on Digital Certificates.

• Introduction
• IDs
• X.509v3 Certificates
• Creating Certs with Bouncy Castle
• CA, RA and Repository

I’ve casually mentioned a “Certificate Authority” earlier. What does this mean?

A “Certificate Authority” is the issuer in the “Public Key Infrastructure” (PKIX) system. It is actually composed of three components: a Registration Authority, a Certificate Authority and a Repository.

(Yes, one components has the same name as the whole. It’s usually not a problem since CA almost always refers to the whole.)

Casual implementations will put the three components in a single webapp but they have very different purposes and needs and should usually be split. At a minimum the architecture should reflect the internal structure.

Registration Authority

The Registration Authority is the component responsible for collecting information about the subject, vetting it, deciding on the appropriate policy and making the final approval. If successful it tells the Certificate Authority to produce the certificate.

Departmental and small enterprise CAs have an easy job – they can hook into the employee or student registrar systems. Is the person known? What is their job description? Done.

Issuing certs for servers is a little more complex but the RA can require any request for a server cert be vouched for by an employee’s cert.

Public CAs need to vet people and organizations from public information. A minimal cert for a person may link an email address to a certificate by requiring the user respond to an email sent to the provided address. This gives you reasonable confidence that this is the right person but you have no confidence that any name associated with the email address is valid.

A stronger requirement is that the person provides a credit card for a token payment. In essence you’re asking the credit card company to vouch for the person. If the charge goes through you have reasonable confidence that you have the correct name and address for the subject.

Really strong authentication requires the subject come into an office, in person, and provide strong ID like a driver’s license or passport.

The subject’s public key is provided by a self-signed cert or (Netscape and possibly other browsers) a signed ‘request’. The subject demonstrates he knows the public key by signing the cert or request.

Businesses can usually be authenticated by checking public business records. This can’t be easily automated and that’s why server certs cost more than individual certs. Open source projects are weird entities since they often don’t have business records and I don’t know if there’s a good way to authenticate them. You can’t just say “go to their mailing list” since anyone can create a rogue mailing list. Fortunately most open source projects have their own websites and it’s possible to put up a document containing a RA-provided value to prove that the subject controls that site. This is one way Google authenticates domain ownership, for example.

The registration authority is also responsible for requests to revoke a certificate from the subject. For instance the subject may realize that its server has been hacked and it can’t guarantee that its private key hasn’t been stolen.

How does the registration authority indicate approval to the certificate authority? One technique is for the RA to issue its own short-lived cert. The certificate authority can then copy all of the information to its own certificate before signing it and passing it on to the repository.

Vulnerabilities

Email accounts are hacked. Credit card information is stolen. Even business identity theft can happen. On a jury I would say there’s a preponderance of evidence but reasonable doubt short of measures like having the subject appear, in person, with a strong ID.

Another vulnerability is an attacker putting unauthorized approvals into the work queue for the certificate authority. This is a strong reason for keeping the certificate authority workqueue in a different database than the repository authority’s database. Fortunately this can be punted – either call the certificate authority directly (e.g., via a REST call) and let it handle it or hand the certificate off to a JMS server.

Finally the repository authority should maintain its own certificates in a secure location like a filesystem-based keystore. Never in the database itself.

Certificate Authority

The certificate authority is responsible for creating certificates based on the information provided by the registration authority. It can change the extensions based on policies associated with the signing certificate but it will generally create certificates based entirely on what the RA provided it.

There are four broad categories for how certs are signed.

1. Low value certs can be signed by an entirely automated process using code similar to what I published in the last post.
2. Medium value certs can require that an employee explicitly provide the decryption password for the issuing private key. This often requires the employee to be sitting at a console on the certificate authority.
3. High value certs can require that multiple employees explicitly provide decryption passwords. One employee is not enough.
4. Alternately high value certs can require the certification be signed by specialized hardware that never exports the private key. The higher the value the better the hardware. The details of how the hardware gets approval to issue the certificate vary by the hardware.

Certificate authorities are also responsible for signing Certificate Revocation Lists (CRLs) and (maybe) OCSP records. These are used to inform others that a certificate has been revoked.

The signed certs are passed on to the repository.

Vulnerabilities

The certificate authority should not be publicly available.

The certificate authority may get unauthorized approvals in the workqueue from the repository. It should consider performing its own sanity checks.

Again the certificate authority should maintain its own certificates in a secure location like a filesystem-based keystore. Never in the database itself.

Tighter security in the workqueue

With a little work it is possible to have much tighter security in the workqueue. Instead of the repository making blind submissions to the workqueue it can use a three-step process.

1. Request a random nonce from the certificate authority
2. Embed the nonce in the approval certificate, e.g., perhaps as a subject alternate name.
3. Put the approval certificate in the workqueue.

The certificate workqueue has a corresponding process.

1. Receive a nonce request from the registration authority. Create one and bind it to the subject DN in some way. (Use an HMAC digest of the subject DN as the nonce. This has the benefit of eliminating the need to maintain a local database.)
2. Receive the approval certificate in the workqueue.
3. Verify that the nonce is in the approval certificate.

This process seems burdensome but should be fairly easy to implement and will dramatically improve the security of the workqueue.

Repository

The repository is responsible for publishing the cert. It usually does this by some combination of HTTP, FTP and LDAP. It is also responsible for publishing Certificate Revocation Lists (CRLs) and OCSP.

Another option is providing a REST interface and an implementation of a java.security.cert.CertStore that maintains a local cache and will call the REST service for unfamiliar certs. This has the benefit of being standard and easily tested.

The repository is pretty dumb overall but the database behinds it needs to be very intelligent in order to prevent attackers from seeding it with unauthorized certificates.

Vulnerabilities

If the database behind the repository is compromised than the repository will feed unauthorized certs to users. One countermeasure is to maintain a list of approved root certificates in a local KeyStore and validate all certs before returning them to the caller. This will substantially improve the effort per request but that may be acceptable on lower volume repositories.

The repository may be subjected to denial-of-service attacks.

The repository may be subjected to unintentional denial-of-service attacks with naive use of OCSP requests by clients.

Database Security

Database security is crucial and in fact it appears to be a high risk factor for my efforts to deploy a prototype to the Google App Engine. (No final determination yet since Google is still working on a mysql-like database interface.)

The wrong way to do things is to extract the different attributes in a certificate and use normal object persistence to write the values to the database.

One right way to do things is to lock down the certificate table to revoke all INSERT, UPDATE and DELETE rights. Instead certificates use stored procedures:

INSERT: extract the cached values and use them to populate the appropriate columns.

UPDATE: certificates are never modified. Ancillary information, e.g., revocation date and reason, can be updated by a stored procedure.

DELETE: again certificates are never modified. A stored procedure can be used for soft deletions.

A variant is to use triggers that overwrite the cached fields on insertions and refuses to change those columns on updates. This has the benefit of allowing us to continue using ORM frameworks.

It’s important to remember that database backups and restorations sidestep stored procedures. You can lock the SQL but still have unauthorized certs put into the repository’s database by rogue administrators.

As always one database user should own the table and stored procedure and a different database user should own the data but have no rights to modify the table or stored procedures.

For More Information

RFC2459: Internet X.509 Public Key Infrastructure | Certificate and CRL Profile

RFC4387: Internet X.509 Public Key Infrastructure | Operational Protocols: Certificate Store Access via HTTP

RFC5019: The Lightweight Online Certificate Status Protocol (OCSP) Profile for High-Volume Environments

Danger, Danger, Will Robinson!

If you read nothing else in this series, read this!

Top 10 PKI Risks

Everything you Never Wanted to Know about PKI but were Forced to Find Out (Peter Gutmann)

This is part of a series on Digital Certificates.

• Introduction
• IDs
• X.509v3 Certificates
• Creating Certs with Bouncy Castle
• RA, CA and repository

Time for some code!

This implementation uses deprecated classes from Bouncy Castle. I’m still working on an implementation using the preferred classes.

The Unit Test

We’re good developers using Test-Driven Development so we start with the unit test. This is an abridged test that doesn’t attempt to verify policy issues.

package com.otterca.repository.util;

import static org.testng.Assert.assertEquals;
import static org.testng.Assert.fail;

import java.math.BigInteger;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.Provider;
import java.security.Security;
import java.security.cert.X509Certificate;
import java.util.Calendar;
import java.util.List;
import java.util.TimeZone;

import org.bouncycastle.asn1.x509.AuthorityKeyIdentifier;
import org.bouncycastle.asn1.x509.GeneralName;
import org.bouncycastle.asn1.x509.SubjectKeyIdentifier;
import org.bouncycastle.asn1.x509.X509Extension;
import org.bouncycastle.cert.jcajce.JcaX509ExtensionUtils;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.x509.extension.AuthorityKeyIdentifierStructure;
import org.bouncycastle.x509.extension.SubjectKeyIdentifierStructure;
import org.testng.annotations.Test;

/**
 * Unit tests for X509CertificateBuilder.
 *
 * @author bgiles@otterca.com
 */
@SuppressWarnings("deprecation")
public class X509CertificateBuilderTest {
    private final Provider provider;
    private final KeyPairGenerator keyPairGen;
    private final BigInteger serial = BigInteger.ONE;
    private final String subjectName = "DN=subject";
    private final String issuerName = "DN=issuer";
    private final Calendar notBefore;
    private final Calendar notAfter;
    private final KeyPair keyPair;

    public X509CertificateBuilderTest() throws Exception {
        TimeZone.setDefault(TimeZone.getTimeZone("UTC"));

        provider = new BouncyCastleProvider();
        Security.addProvider(provider);

        keyPairGen = KeyPairGenerator.getInstance("RSA", provider);
        keyPairGen.initialize(512);
        keyPair = keyPairGen.generateKeyPair();

        notBefore = Calendar.getInstance();
        notBefore.set(Calendar.MILLISECOND, 0);
        notAfter = Calendar.getInstance();
        notAfter.setTime(notBefore.getTime());
        notAfter.add(Calendar.YEAR, 1);
    }

    /**
     * Test builder when all properties are set.
     *
     * @throws Exception
     */
    @Test
    public void testBuilderSelfSignedCert() throws Exception {
        String email = "email";
        String dnsName = "otterca.com";
        String ipAddress = "127.0.0.1";
        String dirName = "CN=subject";
        String issuerEmail = "issuer email";
        String issuerDnsName = "issuer.otterca.com";
        String issuerIpAddress = "127.0.0.2";
        String issuerDirName = "CN=issuer";

        // create certificate
        X509CertificateBuilder builder = new X509CertificateBuilder();
        builder.setSerialNumber(serial);
        builder.setSubject(subjectName);
        builder.setIssuer(subjectName);
        builder.setNotBefore(notBefore.getTime());
        builder.setNotAfter(notAfter.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.setEmailAddresses(email);
        builder.setDnsNames(dnsName);
        builder.setIpAddresses(ipAddress);
        builder.setDirectoryNames(dirName);
        builder.setIssuerEmailAddresses(issuerEmail);
        builder.setIssuerDnsNames(issuerDnsName);
        builder.setIssuerIpAddresses(issuerIpAddress);
        builder.setIssuerDirectoryNames(issuerDirName);

        X509Certificate cert = builder.build(keyPair.getPrivate());

        // perform basic validation.
        cert.verify(keyPair.getPublic());

        // verify the mandatory attributes.
        assertEquals(cert.getSerialNumber(), serial);
        assertEquals(cert.getSubjectDN().getName(), subjectName);
        assertEquals(cert.getIssuerDN().getName(), subjectName);
        assertEquals(cert.getNotBefore(), notBefore.getTime());
        assertEquals(cert.getNotAfter(), notAfter.getTime());
        assertEquals(cert.getPublicKey(), keyPair.getPublic());

        JcaX509ExtensionUtils utils = new JcaX509ExtensionUtils();

        // verify that we have a SKID.
        SubjectKeyIdentifier kid = utils.createSubjectKeyIdentifier(keyPair.getPublic());
        SubjectKeyIdentifier skid = new SubjectKeyIdentifierStructure(
                cert.getExtensionValue(X509Extension.subjectKeyIdentifier.toString()));
        assertEquals(skid.getKeyIdentifier(), kid.getKeyIdentifier());

        // verify that we have an AKID.
        AuthorityKeyIdentifier akid = new AuthorityKeyIdentifierStructure(
                cert.getExtensionValue(X509Extension.authorityKeyIdentifier.toString()));
        assertEquals(akid.getKeyIdentifier(), kid.getKeyIdentifier());
        assertEquals(akid.getAuthorityCertSerialNumber(), serial);
        GeneralName[] akidNames = akid.getAuthorityCertIssuer().getNames();
        assertEquals(akidNames.length, 1);
        assertEquals(akidNames[0].getName().toString(), subjectName);

        // verify the subject alternative names.
        for (List obj : cert.getSubjectAlternativeNames()) {
            switch (((Number) obj.get(0)).intValue()) {
            case GeneralName.rfc822Name:
                assertEquals(obj.get(1), email);
                break;
            case GeneralName.dNSName:
                assertEquals(obj.get(1), dnsName);
                break;
            case GeneralName.iPAddress:
                assertEquals(obj.get(1), ipAddress);
                break;
            case GeneralName.directoryName:
                assertEquals(obj.get(1), dirName);
                break;
            default:
                fail("unexpected subject alternative name");
            }
        }

        // verify the issuer alternative names.
        for (List obj : cert.getIssuerAlternativeNames()) {
            switch (((Number) obj.get(0)).intValue()) {
            case GeneralName.rfc822Name:
                assertEquals(obj.get(1), issuerEmail);
                break;
            case GeneralName.dNSName:
                assertEquals(obj.get(1), issuerDnsName);
                break;
            case GeneralName.iPAddress:
                assertEquals(obj.get(1), issuerIpAddress);
                break;
            case GeneralName.directoryName:
                assertEquals(obj.get(1), issuerDirName);
                break;
            default:
                fail("unexpected issuer alternative name");
            }
        }

        // key usage
        // basic constraint
    }

    /**
     * Test builder when missing serial number.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderMissingSerialNumber() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSubject(subjectName);
        builder.setIssuer(issuerName);
        builder.setNotBefore(notBefore.getTime());
        builder.setNotAfter(notAfter.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.build(keyPair.getPrivate());
    }

    /**
     * Test builder when missing subject.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderMissingSubject() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSerialNumber(serial);
        builder.setIssuer(issuerName);
        builder.setNotBefore(notBefore.getTime());
        builder.setNotAfter(notAfter.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.build(keyPair.getPrivate());
    }

    /**
     * Test builder when missing issuer.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderMissingIssuer() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSerialNumber(serial);
        builder.setSubject(subjectName);
        builder.setNotBefore(notBefore.getTime());
        builder.setNotAfter(notAfter.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.build(keyPair.getPrivate());
    }

    /**
     * Test builder when missing 'not before' date.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderMissingNotBefore() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSerialNumber(serial);
        builder.setSubject(subjectName);
        builder.setIssuer(issuerName);
        builder.setNotAfter(notAfter.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.build(keyPair.getPrivate());
    }

    /**
     * Test builder when missing 'not after' date.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderMissingNotAfter() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSerialNumber(serial);
        builder.setSubject(subjectName);
        builder.setIssuer(issuerName);
        builder.setNotBefore(notBefore.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.build(keyPair.getPrivate());
    }

    /**
     * Test builder when missing public key.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderMissingPublicKey() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSerialNumber(serial);
        builder.setSubject(subjectName);
        builder.setIssuer(issuerName);
        builder.setNotBefore(notBefore.getTime());
        builder.setNotAfter(notAfter.getTime());
        builder.build(keyPair.getPrivate());
    }

    /**
     * Test builder when 'notBefore' date is after 'notAfter' date.
     *
     * @throws Exception
     */
    @Test(expectedExceptions = IllegalArgumentException.class)
    public void testBuilderBadDates() throws Exception {
        X509CertificateBuilder builder = new X509CertificateBuilder();

        builder.setSerialNumber(serial);
        builder.setSubject(subjectName);
        builder.setIssuer(issuerName);
        builder.setNotBefore(notAfter.getTime());
        builder.setNotAfter(notBefore.getTime());
        builder.setPublicKey(keyPair.getPublic());
        builder.build(keyPair.getPrivate());
    }
}

The Code

The actual builder. As the javadocs point out the final version should use dependency injection for a few strategy methods.

package com.otterca.repository.util;

import java.math.BigInteger;
import java.security.InvalidKeyException;
import java.security.KeyStore;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.NoSuchProviderException;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.SignatureException;
import java.security.cert.CertificateEncodingException;
import java.security.cert.CertificateException;
import java.security.cert.CertificateExpiredException;
import java.security.cert.CertificateNotYetValidException;
import java.security.cert.CertificateParsingException;
import java.security.cert.X509Certificate;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import javax.annotation.ParametersAreNonnullByDefault;

import org.bouncycastle.asn1.x509.AuthorityKeyIdentifier;
import org.bouncycastle.asn1.x509.BasicConstraints;
import org.bouncycastle.asn1.x509.ExtendedKeyUsage;
import org.bouncycastle.asn1.x509.GeneralName;
import org.bouncycastle.asn1.x509.GeneralNames;
import org.bouncycastle.asn1.x509.KeyUsage;
import org.bouncycastle.asn1.x509.X509Extensions;
import org.bouncycastle.jce.X509Principal;
import org.bouncycastle.x509.X509V3CertificateGenerator;
import org.bouncycastle.x509.extension.AuthorityKeyIdentifierStructure;
import org.bouncycastle.x509.extension.SubjectKeyIdentifierStructure;

/**
 * Convenience class that builds X509 certificates.
 *
 * @author bgiles@otterca.com
 */
@ParametersAreNonnullByDefault
@SuppressWarnings("deprecation")
public class X509CertificateBuilder {
    public static final String SIGNATURE_ALGORITHM = "SHA256WITHRSA";
    private KeyStore keyStore;
    private X509Certificate issuer;
    private BigInteger serial;
    private X509Principal subjectDN;
    private X509Principal issuerDN;
    private Date notBefore;
    private Date notAfter;
    private PublicKey pubkey;
    private final List<GeneralName> subjectNames = new ArrayList<>();
    private final List<GeneralName> issuerNames = new ArrayList<>();
    private KeyUsage keyUsage;
    private ExtendedKeyUsage extendedKeyUsage;
    private boolean basicConstraint;
    private int pathLengthConstraint = -1;

    /**
     * Default constructor that can be used to create self-signed certificates
     * but not certificate chains.
     *
     * @param keyStore
     */
    public X509CertificateBuilder() {
    }

    /**
     * Constructor that requires keystore to validate certificate chain for
     * issuer.
     *
     * @param keyStore
     */
    public X509CertificateBuilder(KeyStore keyStore) {
        this.keyStore = keyStore;
    }

    /**
     * Reset builder to default state.
     */
    public void reset() {
        issuer = null;
        serial = null;
        subjectDN = null;
        issuerDN = null;
        notBefore = null;
        notAfter = null;
        pubkey = null;
        subjectNames.clear();
        issuerNames.clear();
        keyUsage = null;
        basicConstraint = false;
        pathLengthConstraint = -1;
    }

    /**
     * Set serial number.
     *
     * @param serial
     * @return
     */
    public X509CertificateBuilder setSerialNumber(BigInteger serial) {
        this.serial = serial;
        return this;
    }

    /**
     * Set subject name (as X509Principal).
     *
     * @param dirName
     * @return
     */
    public X509CertificateBuilder setSubject(String dirName) {
        this.subjectDN = new X509Principal(dirName);
        return this;
    }

    /**
     * Set issuer name (as X509Principal).
     *
     * @param dirName
     * @return
     */
    public X509CertificateBuilder setIssuer(String dirName) {
        this.issuerDN = new X509Principal(dirName);
        return this;
    }

    /**
     * Set 'notBefore' date.
     *
     * @param notBefore
     * @return
     */
    public X509CertificateBuilder setNotBefore(Date notBefore) {
        this.notBefore = notBefore;
        return this;
    }

    /**
     * Set 'notAfter' date.
     *
     * @param notAfter
     * @return
     */
    public X509CertificateBuilder setNotAfter(Date notAfter) {
        this.notAfter = notAfter;
        return this;
    }

    /**
     * Set public key.
     *
     * @param pubkey
     * @return
     */
    public X509CertificateBuilder setPublicKey(PublicKey pubkey) {
        this.pubkey = pubkey;
        return this;
    }

    /**
     * Set issuer's X509 certificate. This provides issuer's DN and alternate
     * names and public key.
     *
     * @param issuer
     * @param pubkey
     * @return
     */
    public X509CertificateBuilder setIssuer(X509Certificate issuer) {
        this.issuer = issuer;
        return this;
    }

    /**
     * Set subject's email addresses (individual, server or CA).
     *
     * @param emailAddresses
     * @return
     */
    public X509CertificateBuilder setEmailAddresses(String... emailAddresses) {
        for (String address : emailAddresses) {
            subjectNames.add(new GeneralName(GeneralName.rfc822Name, address));
        }
        return this;
    }

    /**
     * Set subject's DNS names (server or CA?). Note: servers should use their
     * canonical hostname as the X.500 CommonName used as their subjectDN. (See
     * above.) This provides more flexibility but many clients won't look for
     * these extensions.
     *
     * @param dnsNames
     * @return
     */
    public X509CertificateBuilder setDnsNames(String... dnsNames) {
        for (String name : dnsNames) {
            subjectNames.add(new GeneralName(GeneralName.dNSName, name));
        }
        return this;
    }

    /**
     * Set subject's IP Address (server).
     *
     * @param ipAddresses
     * @return
     */
    public X509CertificateBuilder setIpAddresses(String... ipAddresses) {
        for (String address : ipAddresses) {
            subjectNames.add(new GeneralName(GeneralName.iPAddress, address));
        }
        return this;
    }

    /**
     * Set subject's directory names. I think this refers to alternate X.500
     * principal names, not filesystem directories.
     *
     * @param dirNames
     * @return
     */
    public X509CertificateBuilder setDirectoryNames(String... dirNames) {
        for (String name : dirNames) {
            subjectNames.add(new GeneralName(GeneralName.directoryName, name));
        }
        return this;
    }

    /**
     * Set issuer's email addresses (individual, server or CA).
     *
     * @param emailAddresses
     * @return
     */
    public X509CertificateBuilder setIssuerEmailAddresses(String... emailAddresses) {
        for (String address : emailAddresses) {
            issuerNames.add(new GeneralName(GeneralName.rfc822Name, address));
        }
        return this;
    }

    /**
     * Set issuer's DNS names (server or CA?). Note: servers should use their
     * canonical hostname as the X.500 CommonName used as their subjectDN. (See
     * above.) This provides more flexibility but many clients won't look for
     * these extensions.
     *
     * @param dnsNames
     * @return
     */
    public X509CertificateBuilder setIssuerDnsNames(String... dnsNames) {
        for (String name : dnsNames) {
            issuerNames.add(new GeneralName(GeneralName.dNSName, name));
        }
        return this;
    }

    /**
     * Set issuer's IP Address (server).
     *
     * @param ipAddresses
     * @return
     */
    public X509CertificateBuilder setIssuerIpAddresses(String... ipAddresses) {
        for (String address : ipAddresses) {
            issuerNames.add(new GeneralName(GeneralName.iPAddress, address));
        }
        return this;
    }

    /**
     * Set issuer's directory names. I think this refers to alternate X.500
     * principal names, not filesystem directories.
     *
     * @param dirNames
     * @return
     */
    public X509CertificateBuilder setIssuerDirectoryNames(String... dirNames) {
        for (String name : dirNames) {
            issuerNames.add(new GeneralName(GeneralName.directoryName, name));
        }
        return this;
    }

    /**
     * Set key usage. TODO: provide parameters that don't expose implementation
     * details.
     *
     * @param usage
     * @return
     */
    public X509CertificateBuilder setKeyUsage(KeyUsage usage) {
        this.keyUsage = usage;
        return this;
    }

    /**
     * Set extended key usage. TODO: provide parameters that don't expose
     * implementation details.
     *
     * @param usage
     * @return
     */
    public X509CertificateBuilder setExtendedKeyUsage(ExtendedKeyUsage extendedKeyUsage) {
        this.extendedKeyUsage = extendedKeyUsage;
        return this;
    }

    /**
     * Set the certificate's Basic Constraint (can this certificate be used to
     * sign other certificates?). There are no restrictions on certification
     * path length.
     *
     * @param basicConstraint
     * @return
     */
    public X509CertificateBuilder setBasicConstraints(boolean basicConstraint) {
        this.basicConstraint = basicConstraint;
        return this;
    }

    /**
     * Set the certificate's Basic Constraint (can this certificate be used to
     * sign other certificates?) and maximum certification path length. A value
     * of 0 means that this certificate can be used to sign leafs but cannot be
     * used to create other signing certs.
     *
     * @param basicConstraint
     * @param pathLengthConstraint
     * @return
     */
    public X509CertificateBuilder setBasicConstraints(boolean basicConstraint,
            int pathLengthConstraint) {
        this.basicConstraint = basicConstraint;
        this.pathLengthConstraint = pathLengthConstraint;
        return this;
    }

    /**
     * Perform any other validation checks on issuer. This method can be
     * replaced by an injected strategy.
     *
     * @param ex
     */
    public void checkIssuer(X509CertificateBuilderIllegalArgumentException ex)
            throws CertificateParsingException, KeyStoreException {
        if (issuer == null) {
            return;
        }
        if (keyStore == null) {
            ex.setIssuerCannotSignCertificates(true);
            return;
        }

        // look up issuer's certificate chain in our keystore using
        // the issuer's subject DN as the alias.
        String alias = issuer.getSubjectDN().getName();
        if (!keyStore.containsAlias(alias)) {
            ex.setUnknownIssuer(true);
            return;
        }

        // validate the certificate chain.
        X509Certificate last = null;
        X509Certificate[] chain = (X509Certificate[]) keyStore.getCertificateChain(alias);
        for (X509Certificate cert : chain) {
            if (cert.getBasicConstraints() < 0) {
                ex.setIssuerCannotSignCertificates(true);
            }
            try {
                cert.checkValidity();
            } catch (CertificateExpiredException e) {
                ex.setIssuerCannotSignCertificates(true);
            } catch (CertificateNotYetValidException e) {
                ex.setIssuerCannotSignCertificates(true);
            }
            if (last != null) {
                try {
                    last.verify(cert.getPublicKey());
                } catch (CertificateException e) {
                    ex.setIssuerCannotSignCertificates(true);
                } catch (SignatureException e) {
                    ex.setIssuerCannotSignCertificates(true);
                } catch (InvalidKeyException e) {
                    ex.setIssuerCannotSignCertificates(true);
                } catch (NoSuchProviderException e) {
                    ex.setIssuerCannotSignCertificates(true);
                } catch (NoSuchAlgorithmException e) {
                    ex.setIssuerCannotSignCertificates(true);
                }
            }
            last = cert;
        }

        // at this point we have a valid certificate chain and
        // have to trust that the keystore only contains trusted
        // certificates.
    }

    /**
     * Perform any other policy check. This method can be replaced by an
     * injected strategy.
     *
     * @param ex
     */
    public void checkPolicy(X509CertificateBuilderIllegalArgumentException ex) {

    }

    /**
     * Establish any other policy. For instance this might add (or remove)
     * alternative names, add or remove key usage constraints, etc. This method
     * can be replaced by an injected strategy.
     *
     * @param ex
     */
    public void establishPolicy() {
        // ensure keyCertSign is (only) available on signing keys.
        if (basicConstraint) {
            if (keyUsage == null) {
                keyUsage = new KeyUsage(KeyUsage.keyCertSign);
            } else {
                keyUsage = new KeyUsage(keyUsage.intValue() | KeyUsage.keyCertSign);
            }
        } else {
            if (keyUsage != null) {
                keyUsage = new KeyUsage(keyUsage.intValue()
                        & (Integer.MAX_VALUE ^ KeyUsage.keyCertSign));
            }
        }

        // other policies..
    }

    /**
     * Build the X509 certificate.
     *
     * Implementation note: this uses the deprecated methods until I can find
     * documentation on using the newer classes.
     *
     * @param pkey
     * @return
     * @throws InvalidKeyException
     * @throws NoSuchAlgorithmException
     * @throws SignatureException
     * @throws CertificateEncodingException
     * @throws CertificateParsingException
     */
    public X509Certificate build(PrivateKey pkey) throws InvalidKeyException,
            NoSuchAlgorithmException, SignatureException, CertificateEncodingException,
            CertificateParsingException, KeyStoreException {

        // verify we have everything we need....
        X509CertificateBuilderIllegalArgumentException ex = new X509CertificateBuilderIllegalArgumentException();

        if (issuer == null) {
            // require issuer cert for everything other than self-signed certs.
            if ((issuerDN != null) && (issuerDN.equals(subjectDN))) {
                ex.setMissingIssuerCertificate(true);
            }
        } else {
            // verify issuer&#039;s cert is active.
            Date now = new Date();
            if (!(issuer.getNotBefore().before(now) && now.before(issuer.getNotAfter()))) {
                ex.setInvalidIssuer(true);
            }

            // verify our &#039;notBefore&#039; is within range of issuer&#039;s certificate.
            if ((notBefore == null) || notBefore.before(issuer.getNotBefore())) {
                setNotBefore(issuer.getNotBefore());
            }
            if (notBefore.after(issuer.getNotAfter())) {
                ex.setUnacceptableDateRange(true);
            }

            // verify our &#039;notAfter&#039; is within range of issuer&#039;s certificate.
            if ((notAfter == null) || notAfter.after(issuer.getNotAfter())) {
                setNotAfter(issuer.getNotAfter());
            }
            if (notAfter.before(issuer.getNotBefore())) {
                ex.setUnacceptableDateRange(true);
            }

            // verify issuer can sign certificates
            int pathLenConstraint = issuer.getBasicConstraints();
            if (pathLenConstraint  0) {
            throw ex;
        }

        X509V3CertificateGenerator generator = new X509V3CertificateGenerator();

        // set the mandatory properties
        generator.setSerialNumber(serial);
        generator.setIssuerDN(issuerDN);
        generator.setSubjectDN(subjectDN);
        generator.setNotBefore(notBefore);
        generator.setNotAfter(notAfter);
        generator.setPublicKey(pubkey);
        generator.setSignatureAlgorithm(SIGNATURE_ALGORITHM);

        // can this certificate be used to sign more certificates?
        // make sure pathlenthconstraint is always lower than issuer's.
        if (basicConstraint) {
            if ((issuer != null) && (pathLengthConstraint > issuer.getBasicConstraints() - 1)) {
                pathLengthConstraint = issuer.getBasicConstraints() - 1;
            }
            if (pathLengthConstraint >= 0) {
                generator.addExtension(X509Extensions.BasicConstraints, true, new BasicConstraints(
                        pathLengthConstraint));
            } else {
                generator.addExtension(X509Extensions.BasicConstraints, true, new BasicConstraints(
                        true));
            }
        } else {
            generator.addExtension(X509Extensions.BasicConstraints, true, new BasicConstraints(
                    false));
        }

        // set the X509 optional stuff.

        // we always add the subject key identifier.
        SubjectKeyIdentifierStructure skis = new SubjectKeyIdentifierStructure(pubkey);
        generator.addExtension(X509Extensions.SubjectKeyIdentifier, false, skis);

        // we always add the authority key identifier if possible.
        if (issuer != null) {
            // signed certificates....
            AuthorityKeyIdentifierStructure akis = new AuthorityKeyIdentifierStructure(issuer);
            generator.addExtension(X509Extensions.AuthorityKeyIdentifier, false, akis);
        } else if (subjectDN.equals(issuerDN)) {
            // self-signed certificates....
            GeneralNames issuerName = new GeneralNames(new GeneralName(GeneralName.directoryName,
                    issuerDN));
            AuthorityKeyIdentifier akis = new AuthorityKeyIdentifierStructure(pubkey);
            akis = new AuthorityKeyIdentifier(akis.getKeyIdentifier(), issuerName, serial);
            generator.addExtension(X509Extensions.AuthorityKeyIdentifier, false, akis);
        }

        // establish any other policy.
        establishPolicy();

        // add subject alternative names if available - this is email, dns
        // names, etc.
        if (!subjectNames.isEmpty()) {
            generator.addExtension(X509Extensions.SubjectAlternativeName, false, new GeneralNames(
                    subjectNames.toArray(new GeneralName[0])));
        }

        // add issuer alternative names if available - this is email, dns
        // names, etc.
        if (!issuerNames.isEmpty()) {
            generator.addExtension(X509Extensions.IssuerAlternativeName, false, new GeneralNames(
                    issuerNames.toArray(new GeneralName[0])));
        }

        // add mandatory key usage constraints.
        if (keyUsage != null) {
            generator.addExtension(X509Extensions.KeyUsage, true, keyUsage);
        }

        // add optional extended key usage constraints.
        if (extendedKeyUsage != null) {
            generator.addExtension(X509Extensions.ExtendedKeyUsage, false, extendedKeyUsage);
        }

        X509Certificate cert = generator.generate(pkey);
        return cert;
    }
}

The Exception

The builder throws a specialized IllegalArgumentException if it is missing required values or there’s a problem with them. This exception allows multiple errors to be identified at one time.

The final version will have a better ‘message’ that lists all of the errors.

package com.otterca.repository.util;

/**
 * IllegalArgumentException that bundles multiple errors into a single
 * exception.
 *
 * @author bgiles@otterca.com
 */
public class X509CertificateBuilderIllegalArgumentException extends IllegalArgumentException {
    private static final long serialVersionUID = 1L;
    private boolean missingIssuerCertificate;
    private boolean missingSerialNumber;
    private boolean missingSubject;
    private boolean missingIssuer;
    private boolean missingNotBeforeDate;
    private boolean missingNotAfterDate;
    private boolean missingPublicKey;
    private boolean badDateRange;
    private boolean invalidIssuer;
    private boolean issuerCannotSignCertificates;
    private boolean unacceptableDateRange;
    private boolean missingKeyUsage;
    private boolean unknownIssuer;
    private int errorCount = 0;

    /**
     * @return the number of errors.
     */
    public int getErrorCount() {
        return errorCount;
    }

    /**
     * @return the missingIssuerCertificate
     */
    public boolean isMissingIssuerCertificate() {
        return missingIssuerCertificate;
    }

    /**
     * @return the missingSerialNumber
     */
    public boolean isMissingSerialNumber() {
        return missingSerialNumber;
    }

    /**
     * @return the missingSubject
     */
    public boolean isMissingSubject() {
        return missingSubject;
    }

    /**
     * @return the missingIssuer
     */
    public boolean isMissingIssuer() {
        return missingIssuer;
    }

    /**
     * @return the missingNotBeforeDate
     */
    public boolean isMissingNotBeforeDate() {
        return missingNotBeforeDate;
    }

    /**
     * @return the missingNotAfterDate
     */
    public boolean isMissingNotAfterDate() {
        return missingNotAfterDate;
    }

    /**
     * @return the missingPublicKey
     */
    public boolean isMissingPublicKey() {
        return missingPublicKey;
    }

    /**
     * @return the badDateRange
     */
    public boolean isBadDateRange() {
        return badDateRange;
    }

    /**
     * @return the invalidIssuer
     */
    public boolean isInvalidIssuer() {
        return invalidIssuer;
    }

    /**
     * @return the issuerCannotSignCertificates
     */
    public boolean isIssuerCannotSignCertificates() {
        return issuerCannotSignCertificates;
    }

    /**
     * @return the unknownIssuer
     */
    boolean isUnknownIssuer() {
        return unknownIssuer;
    }

    /**
     * @return the unacceptableDateRange
     */
    boolean isUnacceptableDateRange() {
        return unacceptableDateRange;
    }

    /**
     * @return the missingKeyUsage
     */
    boolean isMissingKeyUsage() {
        return missingKeyUsage;
    }

    /**
     * @param missingIssuerCertificate
     *            the missingIssuerCertificate to set
     */
    void setMissingIssuerCertificate(boolean missingIssuerCertificate) {
        this.missingIssuerCertificate = missingIssuerCertificate;
    }

    /**
     * @param missingSerialNumber
     *            the missingSerialNumber to set
     */
    void setMissingSerialNumber(boolean missingSerialNumber) {
        errorCount++;
        this.missingSerialNumber = missingSerialNumber;
    }

    /**
     * @param missingSubject
     *            the missingSubject to set
     */
    void setMissingSubject(boolean missingSubject) {
        errorCount++;
        this.missingSubject = missingSubject;
    }

    /**
     * @param missingIssuer
     *            the missingIssuer to set
     */
    void setMissingIssuer(boolean missingIssuer) {
        errorCount++;
        this.missingIssuer = missingIssuer;
    }

    /**
     * @param missingNotBeforeDate
     *            the missingNotBeforeDate to set
     */
    void setMissingNotBeforeDate(boolean missingNotBeforeDate) {
        errorCount++;
        this.missingNotBeforeDate = missingNotBeforeDate;
    }

    /**
     * @param missingNotAfterDate
     *            the missingNotAfterDate to set
     */
    void setMissingNotAfterDate(boolean missingNotAfterDate) {
        errorCount++;
        this.missingNotAfterDate = missingNotAfterDate;
    }

    /**
     * @param missingPublicKey
     *            the missingPublicKey to set
     */
    void setMissingPublicKey(boolean missingPublicKey) {
        errorCount++;
        this.missingPublicKey = missingPublicKey;
    }

    /**
     * @param badDateRange
     *            the badDateRange to set
     */
    void setBadDateRange(boolean badDateRange) {
        errorCount++;
        this.badDateRange = badDateRange;
    }

    /**
     * @param invalidIssuer
     *            the invalidIssuer to set
     */
    void setInvalidIssuer(boolean invalidIssuer) {
        errorCount++;
        this.invalidIssuer = invalidIssuer;
    }

    /**
     * @param issuerCannotSignCertificates
     *            the issuerCannotSignCertificates to set
     */
    void setIssuerCannotSignCertificates(boolean issuerCannotSignCertificates) {
        errorCount++;
        this.issuerCannotSignCertificates = issuerCannotSignCertificates;
    }

    /**
     * @param unacceptableDateRange
     *            the unacceptableDateRange to set
     */
    void setUnacceptableDateRange(boolean unacceptableDateRange) {
        errorCount++;
        this.unacceptableDateRange = unacceptableDateRange;
    }

    /**
     * @param missingKeyUsage
     *            the missingKeyUsage to set
     */
    void setMissingKeyUsage(boolean missingKeyUsage) {
        this.missingKeyUsage = missingKeyUsage;
    }

    /**
     * @param unknownIssuer
     *            the unknownIssuer to set
     */
    void setUnknownIssuer(boolean unknownIssuer) {
        this.unknownIssuer = unknownIssuer;
    }
}

Danger, Danger, Will Robinson!

If you read nothing else in this series, read this!

Top 10 PKI Risks

Everything you Never Wanted to Know about PKI but were Forced to Find Out (Peter Gutmann)

This is part of a series on Digital Certificates.

• Introduction
• IDs
• X.509v3 Certificates
• Creating Certs with Bouncy Castle
• RA, CA and repository

Now that we know what an “ID” is we can quickly understand the big picture with X509v3 certificates.

A X509v3 certificate must contain:

• Serial Number: unique for each issuer
• Subject Distinguished Name: subject’s Name (X500)
• Issuer Distinguished Name: issuer’s name (X500)
• Not Before: the earliest date/time the certificate may be used
• Not After: the last date/time the certificate may be used
• Public Key: how the certificate is bound to the subject
• Signature Algorithm: how the issuer’s signature is made
• Signature: how the certificate is bound to the issuer

As you can see the certificate contains the core characteristics of an ID – it identifies the subject, issuer, a way to identify the subject (the key), a way to prove the issuer produced the certificate (the signature), and immutability (again, the signature).

The serial number has an arbitrary length. Many CAs use a UUID so you must be prepared to handle at least that many digits.

The subject and issuer are identified by X500 names. This is the same format used by LDAP directories and in fact they’re part of the same set of standards. You should try to adhere to conventions even if you will only use your certificates internally – it gives you the best shot at reusing existing software libraries and applications.

The most important X500 name attribute for servers is the “Common Name” (CN) – many applications require it to match the server’s hostname or DNS name.

A “self-signed” certificate uses the same value for subject and issuer.

The “not before date” and “not after date” are self-explanatory. The date range of a certificate should not exceed the date range of the signing certificate.

The “signature” is a cryptographic signature of the contents of the certificate. It is made with the issuer’s private key and can be verified with the issuer’s public key. The issuer’s public key may be known to the client through other trusted means or via PKIX (public certificate authorities). The signature should not be blindly trusted.

Digital certificates are encoded in a well-known predecessor to XML: ASN.1 (Abstract Syntax Notation One). Each field is tagged with a tree of numbers, e.g., “1.2.840.113549.1.1.11″, to identify its contents. These numbers are registered at a central authority so they’re always unique – you don’t have to worry about two companies using the same tag for different purposes.

You should always use a library to read and write ASN.1 documents. The format is difficult to work with and there’s no benefit in rolling your own.

Extensions

X509v3 certificates offer several standard extensions and an issuer can always add its own extensions as well – just remember to go through the formal process to get unique ASN.1 tags.

Extensions can be marked ‘critical’ or ‘noncritical’. The user of a certificate is expected to gracefully handle noncritical extensions but must understand and handle any critical extensions. If a critical extension is not understood the certificate should be refused.

Basic Constraint

This critical extension indicates whether a certificate can be used to sign other certificates. There is no technical reason why you can’t use any certificate to sign another certificate but PKIX policy (discussed later) requires this.

The basic constraint has an optional “certificate path length” that indicates how deep the certificate chain can be below this point. It can be used to delegate authority by creating certificates that can be used to sign normal “leaf” certificates but not additional “signing” certificates.

Subject Alternate Names

This noncritical extension contains one or more alternate name for the subject. The most common uses are email address or IP Address (for servers).

N.B., there is a well-known hack that can embed an email address in an X500 name but this technique is more correct. In practice many clients ignore this extension so you should use both approaches.

Issuer Alternate Names

Same thing, but for issuers instead of subjects.

Key Usage

This critical extension indicates the acceptable usages for this certificate. There are a number of flags but the overall gist is that you can use these flags to indicate whether a certificate should be used to sign other certificates, for servers, or for individuals. You usually want separate certificates for each purpose.

Flags:

• Digital Signature
• Nonrepudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Key Certificate Signing
• CRL Signing
• Encipher Only
• Decipher Only

Extended Key Usage

This noncritical extension elaborates on acceptable usages.

Subject Key Identifier

This noncritical extension offers a standard shorthand reference for the certificate’s public key. It is a good searchable index since the public key itself can have arbitrary length.

Authority Key Identifier

This noncritical extension offers a standard shorthand reference for the certificate’s issuer’s public key. This can be used to quickly establish certificate chains.

Search Criteria

There are several search criteria identified by RFC4387. They can give you an idea about what creates a good search key. (Note: a truncated search key is fine for your own use – you only need the full search key if you have a public certificate repository.)

Certificate Hash / Fingerprint

This is the SHA-1 hash of the entire certificate (in DER format). You can easily get this using OpenSSL tools.

Name

The subject’s Common Name.

sHash

The Base64-encoded SHA-1 hash of the subject’s DN, in DER format. OpenSSL provides a truncated form of this in hex.

iHash

The same thing but for the issuer.

iAndSHash

The Base64-encoded SHA-1 hash of the certificate’s issuer and serial number. The last values should be unique.

sKIDHash

The base64-encoded SHA-1 hash of the certificate’s subject key identifier. This hash is on the key identifier itself, not the entire SKID extension.

In the real world…

In the real world clients often do not check or honor the extensions. Certificate authorities may use expired certificates or certificates lacking the basic constraint.

The bottom line is that you have to have very low standards if you accept public certificates. In contrast certificates intended for internal use can and should be carefully checked.

Vulnerabilities and Attacks

The serial number, X500 names, and public key have essentially unlimited length. This must be kept in mind if you accept certificates from the public – malicious certificates have been seen that attempt to trigger buffer overruns in order to execute arbitrary code.

For More Information

RFC2459: Internet X.509 Public Key Infrastructure | Certificate and CRL Profile

RFC4387: Internet X.509 Public Key Infrastructure | Operational Protocols: Certificate Store Access via HTTP

The Legion of the Bouncy Castle

X.509 Public Key Certificate and Certification Request Generation

Danger, Danger, Will Robinson!

If you read nothing else in this series, read this!

Top 10 PKI Risks

Everything you Never Wanted to Know about PKI but were Forced to Find Out (Peter Gutmann)

This is part of a series on Digital Certificates.

• Introduction
• IDs
• X.509v3 Certificates
• Creating Certs with Bouncy Castle
• RA, CA and repository

Before we get into the details of digital certificates we need to take a big step back and ask what an ID means in the big picture.

Any ID has several mandatory characteristics:

1. it is tangible. (Yes, computer files are tangible.)

2. it identifies a “subject”. For instance, the citizen of a passport, the driver of a state driver’s license, the employee, the student.

3. it identifies an “issuer”. In the examples above this is the country issuing the passport, the state issuing the driver’s license, the employer, the school.

4. it has some way to bind the subject to the person or organization. At a minimum it’s a photograph and/or signature, perhaps with basic biometric information like height and weight.

5. it has some way to bind the issuer to the document. For an employee badge or student ID this might just be a logo. For high security documents you may add watermarks, holograms or even laminated layers containing fluorescing content.

6. it is reasonably immutable.

An ID may include additional characteristics:

1. a unique serial number.

2. an expiration date, and possibly a ‘not valid before’ date as well.

3. usage restrictions. (E.g., there may be driving hours restrictions on a driver’s license.)

4. alternate names for the subject or issuer.

Vulnerabilities and Attacks

What are the vulnerabilities of IDs? How can they be attacked? Entire books have been written on this subject but we can quickly hit the highlights.

Impersonation

We can check that the person presenting the ID matches the description on the ID… but how can we trust that the person going to the issuer isn’t impersonating somebody else? It’s a valid ID issued to the wrong person.

What about the issuer itself? How can we trust the issuer is who it claims to be? Consider the classic student fake ID.

Outdated Information/Revocation

What do you do when the subject dies (if a person) or is acquired by another organization (if a business)? What if the student graduates? Drops out?

A variation on this is when the state suspends a person’s driver’s license. It’s no longer valid as proof of authority to drive but it’s still proof of identity. How to you make sure third parties have the most current information?

Tampering and Forgery

An ID should be immutable but it may still be possible to tamper with it. E.g., paste a picture of one person on top of the picture of a different person on a driver’s license. How easy will it be to detect that if you only look at the ID through a plastic sleeve?

This is a key point to remember – fake IDs don’t need to be perfect. They only need to be “good enough” for the intended purpose. That can be a shockingly lower barrier than you expect.

Lack of Due Diligence

This vulnerability is the nastiest – how can you trust the issuer to do a good job? In some cases this is sloppiness, but there’s also the structural questions of who pays the cost of investigating the subject and who pays the cost when the issuer is mistaken. An issuer who is expected to pay the costs for the investigation but will pay no penalty for mistakes isn’t likely to put much effort into the investigation. Make no mistake – they may not make intentional errors. They just won’t be zealous about doing an in-depth investigation.

On the other hand an issuer who faces a serious financial risk if they misidentify the subject will naturally make a much more serious effort to get it right.

Lessons

We can summarize this in two observations:

1. A third-party certificate authority will put its own interests above yours.

2. Your own certificate authority will still need to invest substantial resources to prevent impersonations, tampering, forgery, etc.

The bottom line is that Digital Certificates are a powerful tool but they are only a tool. They are not a silver bullet.

Danger, Danger, Will Robinson!

If you read nothing else in this series, read this!

Top 10 PKI Risks

Everything you Never Wanted to Know about PKI but were Forced to Find Out (Peter Gutmann)

This is the first entry in a series on the how, what and why of digital certificates. Especially the ‘what’ and ‘why’ since we developers tend to focus too much on the ‘how’.

The tentative topics include

• Introduction
• IDs
• X.509v3 Certificates
• Creating Certs with Bouncy Castle
• RA, CA and repository
• Policies and Practices
• Certificate Authority, Registration Authority and Registry

I’m also working on a set of related katana(*) projects. The current topics include

• writing a certificate builder
• writing test certificates into a KeyStore
• storing certs in a JPA database
• writing dao unit tests using Spring 3.1.1 @Configuration and @Profile beans
• using X509 certificates with container-provided authentication
• using X509 certificates with application-provided authentication
• writing a webapp using Google App Engine (GAE)
• writing a UI using Google Web Toolkit (GWT)
• more to follow…

Why GAE and GWT? Because this is a katana and I’ve never worked with GAE and only briefly with GWT. What better time to learn them?

(* A ‘katana’ (which may be the wrong word) in this context is a small programming problem to keep your skills sharp and learn new technologies. This effort is much bigger than a traditional katana but still a modest effort since it’s not intended for production use. Yet.)

Why do we care?

Why do we care about digital certificates? There are four common stories: securing a connection to a server, identifying a client, identifying a stranger, and storing public keys.

Securing a connection to a server

For most people the most common use of digital certificates is the ‘secure’ payment pages on websites. Behind the scenes the browser gets a digital certificate from the server, checks it, and only proceeds to establish an encrypted connection if it’s valid.

Developers can also use certificates to establish secure connections to other services, e.g., to a relational database or mail server.

In practice? Corners are often cut. In the worst case an ill-informed developer won’t perform any validation of the server’s certificate. More conscientious developers may perform additional checks but be forced to ignore the results because of ‘valid’ bad certs in the wild.

Identifying a client

How do you identify your clients? The traditional approach has been username and password but we all know that’s an extremely weak standard. In many environments clients are now required to provide their own digital certificate in order to establish a connection. The details are often hidden in the browser or a ‘smart card’ so the user may be unaware that this is happening.

Identifying a stranger

How do you know who a stranger is? Can you take them at their word? Rarely. Can you find somebody you both trust to vouch for them? Again, rarely. What we’re left with is a third party we both trust, e.g., the government agency that issued the passport or driver’s license. But this has its own limitations – do you know what a Freedonian passport looks like? Do you know how to verify its authenticity?

Public certificate authorities can act as trusted third parties to identify unknown parties. In fact that’s what we do when we use our browser – we shouldn’t trust the website claiming to be amazon.com to really be amazon.com, we want a third party (the certificate authority) to vouch for them.

In contrast we often know who the other party is. We might have been given the necessary certificates earlier via a separate trusted mechanism.

Storing public keys

Sometimes we need to manage our own keys for other reasons. A java “keystore”, or more generally a PKCS12 container, is a very good place to hold the private key. But where do we store the public key? How do we keep track of it if there are several other public keys? How do we provide it to others? How do they keep track of it?

These are all questions that lead to the initial digital certificates. Wrap the public key in a certificate and it’s easy to keep in a java KeyStore or PKCS12 container.

N.B., never store naked keys! Jasypt isn’t good enough! Proper storage of keys is a deep topic but a good start is to always keep your keys in a java or PKCS12 keystore. You then provide the password to the keystore via the appserver, e.g., via a JNDI property. The keystore itself should never be stored in the database. If you don’t have exclusive access to the appserver a good place for a read-only keystore is the webapp’s classpath. You can then load the keystore using the standard classloader methods. It’s more complicated if you need an updateable keystore, e.g., for working keys to minimize the exposure of the long-lived keys.

Sidenote: a recent major breach possibly involving millions of credit card purchases happened because the data was encrypted with a key that was itself kept in the database. Access to the database gave them access to everything they needed to decrypt the data!

What scale do we care about as developers?

On one extreme are very tightly controlled environments with only a few, rarely-changing, certificates. Developers at these sites can find everything they need in a quick google search and/or reading the OpenSSL documents.

One step up are what might be called departmental or even small enterprise environments. These can be large organizations, e.g., a university with tens of thousands of students, facility and staff, but there’s a straightforward hierarchy or well-defined set of hierachies. This is an environment where a small team of developers can do interesting work.

Then there’s the large enterprise and public certificate authority realms. Federated realms, unclear hierarchies, ambiguous legal environments. If you’re working in this environment my blog comments won’t be much help… but hopefully won’t be good for a quick laugh!

Danger, Danger, Will Robinson!

If you read nothing else in this series, read this!

Top 10 PKI Risks

Everything you Never Wanted to Know about PKI but were Forced to Find Out (Peter Gutmann)

Finally there was a recent uproar after it was learned that one CA, TrustWave, was selling a network firewall that used its trusted root certificate to create fake certificates that allowed all encrypted traffic to be intercepted. This is bad when employees check their bank balance at work, it’s far worse when employees are working with legally privileged information (e.g., personal medical or legal issues). Nobody realized that there was a problem since TrustWave was one of the standard root certificates accepted by all of the major browsers – the Firefox and Chrome browsers that people download immediately to replace the corporate-mandated MSIE didn’t give any warnings about untrusted certificates and nobody thought to check the actual certificates.

This drives home the fact that public digital certificates are only as trustworthy as the least trustworthy CA on your list. Check your browser – there’s now typically several hundred trusted CAs by default and all it takes is one of them to have a breach to be able to convince you to hand over your credit card information. Or worse.