Note: this document now refers to an out of date version of the APIs. Please see the version 2 document.
The Bouncy Castle APIs have support for creating two kinds of X.509 certificates - version 1 and version 3 - as well as PKCS10 certification requests. Version 1 certificates are generally only used to create root certificates, version 3 certificates are used elsewhere as the extension facility they support is used to help validate both the certificate and the use it is being put to. A fuller description of this and all it entails can be found in RFC 3280.
The classes for generating certificates are:
and the class for generating PKCS10 certification requests is:
Older versions of the X.509 certificate generator classes also appear in the org.bouncycastle.jce package. They are deprecated and should not be used.
DSA currently just supports SHA-1. The following value can be used in place of the variable signatureAlgorithm in the examples below:
ECDSA is support with both the SHA-1 and SHA-2 family of digest algorithms. The following values can be used in place of the variable signatureAlgorithm in the examples below:
Astute readers will probably realise at this point that given a 239 bit ECDSA key and a 512 bit hash, about 280 of the hash bits are going to be without a home in the signature as the hash can be no longer than the order N of the key. In this case the hash is truncated by losing the excess right most bits of it, so you can still use the larger hash algorithm, but it will be shortened.
The algorithms GOST3410-94 and GOST3410-2001 are supported for certificate signing. The following value can be used in place of signatureAlgorithm in the examples below:
A variety of digests can be used to sign certficates using the RSA algorithm. The following value can be used in place of the variable signatureAlgorithm in the examples below:
We use the X509V1CertificateGenerator to create the version 1 certificate. As version 1 certificates have no extensions creating them is fairly straight forward:
where the resulting certificate cert is a self-signed certificate that can be verified using the public key it contains and the algorithm defined in signatureAlgorithm.
Before looking at creation of version 3 certificates it is worth having a brief look at certificate extensions. This is a facility that was added in X.509 version 3 and a lot of the flexibility that Version 3 certificates provide derive from it.
Extensions have a variety of uses and are used for identifying both the certificate and the CA certificate it depends on as well as determining what usages the certificate is valid for. While there are a range of standard extensions, in some case people even make up their own if it suits their organisation.
The basic api support for extensions in the Bouncy Castle Package is provided by the org.bouncycastle.asn1.x509 package, most particulary the X509Extension and X509Extensions classes, the first acting as a carrier for individual extensions and the second which acts as a container for the ones found in a certificate. The X509Extensions class also provides definitions for the ASN.1 object identifiers associated with most common extensions.
The more common extensions are described below, they are all defined in RFC 3280.
The AuthorityKeyIdentifier extension provides a means for identifying the issuer of the certificate. You can think of it as the equivalent to a pointer to the parent certificate. It is covered in section 184.108.40.206 of RFC 3280.
The Bouncy Castle APIs include a helper class for creating or containing this extension. It can be found in the org.bouncycastle.x509.extension package and is called AuthorityKeyIdentifierStructure. The extension can be identified in a certificate by the object identifier given in X509Extensions.AuthorityKeyIdentifier.
Given a parent certificate, caCert, that you want to be referred to by the AuthorityKeyIdentifier extension, a standard version of the extension can be generated as follows:
This will create an AuthorityKeyIdentifier extension which is populated with the issuer name, serial number of the certificate, and the standard key identifier, based on the SubjectKeyIdentifier extension of caCert if caCert contains the extension. If the SubjectKeyIdentifier is not present the key identifier is calculated using the standard method, a SHA-1 hash of the public key data which is defined in RFC 3280.
The BasicConstraints identifies whether the certificate is that of a CA, and optionally it indicates how many certificates after the next one can follow it in the certificate path. It is covered in section 220.127.116.11 of RFC 3280 and is identified in a certificate by the object identifier given in X509Extensions.BasicConstraints.
The following fragment shows how to create one which indicates that the certificate containing it is a CA and that only one certificate can follow in the certificate path.
ExtendedKeyUsage is an extension which restricts a certificate to a specific usage, given by the object identifiers it contains which are KeyPurposeIds. It is covered in section 18.104.22.168 of RFC 3280. The extension can be identified in a certificate by the object identifier given in X509Extensions.ExtendedKeyUsage.
The example below shows the creation of one using the special KeyPurposeId anyExtendedKeyUsage.
You'll run into this extension in a few places, two of the most popular being TSP and OCSP, where the ExtendedKeyUsage extension is used to specifically mark the certificate for a single purpose.
This extension is also used to restrict the purposes that a certificate can be put to. The extension is discussed in section 22.214.171.124 of RFC 3280, but briefly it should always be marked critical if used and it must appear in Version 3 certificates used to validate digital signatures on other certificates and CRLs. The extension can be identified in a certificate by the object identifier given in X509Extensions.KeyUsage.
The following code fragment gives an example of how to create one for this purpose:
In the most common case the SubjectAlternativeName extension is used to associate other names, such as email addresses with the DN giving the subject of the certificate. The extension is discussed in section 126.96.36.199 of RFC 3280 and can be identified in a certificate by the object identifier given in X509Extensions.SubjectAlternativeName.
The SubjectKeyIdentifier provides another means of identifying that a certificate contains a particular public key. It is covered in section 188.8.131.52 of RFC 3280. The extension can be identified in a certificate by the object identifier given in X509Extensions.SubjectKeyIdentifier.
The Bouncy Castle APIs include a helper class for creating or containing this extension. It can be found in the org.bouncycastle.x509.extension package and is called SubjectKeyIdentifierStructure. Given a public key, publicKey, that needs to be identified as belonging to a particular certificate, a SubjectKeyIdentifier extension can be created as follows:
Construction of a version 3 certificate has a couple of difference from a version 1 certificate. Generally a version 3 certificate has a parent certificate so the issuer is not the same as the subject, and they normally also require extensions if you're planning to use them in conjunction with path validation APIs and storage mechanisms such as PKCS12.
The addExtension() method contains the code that was used in the previous examples to create an X509Extension object.
Certification Requests are simply made via a constructor using the org.bouncycastle.jce.PKCSCertificationRequest class. In the simplest case, a certification request which just includes a principal and a public key a request can be constructed as follows:
The null parameter is actually reserved for an ASN.1 SET that can be used to pass in attributes for the certification request. The most common one of these is the extensionRequest attribute defined in PKCS#9, which is used to include extensions that are to be added to the certificate generated by the CA that processes the request.
Creation of the extensionRequest attribute isn't exactly a high point in using the Bouncy Castle APIs, however while it is a bit fiddley to do, it does work! One simple case, that of including an email address in the SubjectAlternative name extension in the certificate generated from the request is done as follows:
On the upside, adding extra extensions to the certification request is just a matter of adding extra oids and extension objects to the oids and values Vector objects respectively.
The created attribute is then added to the construction of the PKCS10 certification request by wrapping it in an ASN.1 SET and passing it as an argument as follows:
A conforming CA will then return a certificate which incorporates the SubjectAlternativeName extension as well as whatever extensions are appropriate for the certificate it issues.