org.cryptacular.util

Class CertUtil

java.lang.Object

org.cryptacular.util.CertUtil

public final class CertUtil
extends Object

Utility class providing convenience methods for common operations on X.509 certificates.

Author:

Middleware Services

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	CertUtil.EncodeType<T> Marker interface for encoding types.
static class	CertUtil.X500PrincipalFormat Describes the behavior of string formatting of X.500 distinguished names.

Method Summary

Modifier and Type	Method and Description
static boolean	allowsUsage(X509Certificate cert, org.bouncycastle.asn1.x509.KeyPurposeId... purposes) Determines whether the certificate allows the given extended key usages.
static boolean	allowsUsage(X509Certificate cert, KeyUsageBits... bits) Determines whether the certificate allows the given basic key usages.
static String	authorityKeyId(X509Certificate cert) Gets the authority key identifier of the given certificate in delimited hexadecimal format, e.g.
static X509Certificate	decodeCertificate(byte[] encoded) Creates an X.509 certificate from its ASN.1 encoded form.
static X509Certificate[]	decodeCertificateChain(byte[] encoded) Creates an X.509 certificate chain from its ASN.1 encoded form.
static <T> T	encodeCert(X509Certificate certificate, CertUtil.EncodeType<T> encodeType) PEM encodes the given certificate with the provided encoding type.
static X509Certificate	findEntityCertificate(PrivateKey key, Collection<X509Certificate> candidates) Finds a certificate whose public key is paired with the given private key.
static X509Certificate	findEntityCertificate(PrivateKey key, X509Certificate... candidates) Finds a certificate whose public key is paired with the given private key.
static X509Certificate	generateX509Certificate(KeyPair keyPair, String dn, Date notBefore, Date notAfter, String signatureAlgo) Generates a self-signed certificate.
static X509Certificate	generateX509Certificate(KeyPair keyPair, String dn, Duration duration, String signatureAlgo) Generates a self-signed certificate.
static boolean	hasPolicies(X509Certificate cert, String... policyOidsToCheck) Determines whether the certificate defines all the given certificate policies.
static X509Certificate	readCertificate(File file) Reads an X.509 certificate from ASN.1 encoded format from the given file.
static X509Certificate	readCertificate(InputStream in) Reads an X.509 certificate from ASN.1 encoded data in the given stream.
static X509Certificate	readCertificate(String path) Reads an X.509 certificate from ASN.1 encoded format in the file at the given location.
static X509Certificate[]	readCertificateChain(File file) Reads an X.509 certificate chain from ASN.1 encoded format from the given file.
static X509Certificate[]	readCertificateChain(InputStream in) Reads an X.509 certificate chain from ASN.1 encoded data in the given stream.
static X509Certificate[]	readCertificateChain(String path) Reads an X.509 certificate chain from ASN.1 encoded format in the file at the given location.
static org.bouncycastle.asn1.x509.GeneralNames	subjectAltNames(X509Certificate cert) Gets all subject alternative names defined on the given certificate.
static org.bouncycastle.asn1.x509.GeneralNames	subjectAltNames(X509Certificate cert, GeneralNameType... types) Gets all subject alternative names of the given type(s) on the given cert.
static String	subjectCN(X509Certificate cert) Gets the common name attribute (CN) of the certificate subject distinguished name.
static String	subjectDN(X509Certificate cert, CertUtil.X500PrincipalFormat format) Retrieves the subject distinguished name (DN) of the provided X.509 certificate.
static String	subjectKeyId(X509Certificate cert) Gets the subject key identifier of the given certificate in delimited hexadecimal format, e.g.
static List<String>	subjectNames(X509Certificate cert) Gets a list of all subject names defined for the given certificate.
static List<String>	subjectNames(X509Certificate cert, GeneralNameType... types) Gets a list of subject names defined for the given certificate.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

subjectCN

public static String subjectCN(X509Certificate cert)
                        throws EncodingException

Gets the common name attribute (CN) of the certificate subject distinguished name.

Parameters:

cert - Certificate to examine.

Returns:

Subject CN or null if no CN attribute is defined in the subject DN.

Throws:

EncodingException - on cert field extraction.

subjectAltNames

public static org.bouncycastle.asn1.x509.GeneralNames subjectAltNames(X509Certificate cert)
                                                               throws EncodingException

Gets all subject alternative names defined on the given certificate.

Parameters:

cert - X.509 certificate to examine.

Returns:

List of subject alternative names or null if no subject alt names are defined.

Throws:

EncodingException - on cert field extraction.

subjectAltNames

public static org.bouncycastle.asn1.x509.GeneralNames subjectAltNames(X509Certificate cert,
                                                                      GeneralNameType... types)
                                                               throws EncodingException

Gets all subject alternative names of the given type(s) on the given cert.

Parameters:

cert - X.509 certificate to examine.

types - One or more subject alternative name types to fetch.

Returns:

List of subject alternative names of the matching type(s) or null if none found.

Throws:

EncodingException - on cert field extraction.

subjectNames

public static List<String> subjectNames(X509Certificate cert)
                                 throws EncodingException

Gets a list of all subject names defined for the given certificate. The list includes the first common name (CN) specified in the subject distinguished name (if defined) and all subject alternative names.

Parameters:

cert - X.509 certificate to examine.

Returns:

List of subject names.

Throws:

EncodingException - on cert field extraction.

subjectNames

public static List<String> subjectNames(X509Certificate cert,
                                        GeneralNameType... types)
                                 throws EncodingException

Gets a list of subject names defined for the given certificate. The list includes the first common name (CN) specified in the subject distinguished name (if defined) and all subject alternative names of the given type.

Parameters:

cert - X.509 certificate to examine.

types - One or more subject alternative name types to fetch.

Returns:

List of subject names.

Throws:

EncodingException - on cert field extraction.

findEntityCertificate

public static X509Certificate findEntityCertificate(PrivateKey key,
                                                    X509Certificate... candidates)
                                             throws EncodingException

Finds a certificate whose public key is paired with the given private key.

Parameters:

key - Private key used to find matching public key.

candidates - Array of candidate certificates.

Returns:

Certificate whose public key forms a keypair with the private key or null if no match is found.

Throws:

EncodingException - on cert field extraction.

findEntityCertificate

public static X509Certificate findEntityCertificate(PrivateKey key,
                                                    Collection<X509Certificate> candidates)
                                             throws EncodingException

Finds a certificate whose public key is paired with the given private key.

Parameters:

key - Private key used to find matching public key.

candidates - Collection of candidate certificates.

Returns:

Certificate whose public key forms a keypair with the private key or null if no match is found.

Throws:

EncodingException - on cert field extraction.

readCertificate

public static X509Certificate readCertificate(String path)
                                       throws EncodingException,
                                              StreamException

Reads an X.509 certificate from ASN.1 encoded format in the file at the given location.

Parameters:

path - Path to file containing an DER or PEM encoded X.509 certificate.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

StreamException - on IO errors.

readCertificate

public static X509Certificate readCertificate(File file)
                                       throws EncodingException,
                                              StreamException

Reads an X.509 certificate from ASN.1 encoded format from the given file.

Parameters:

file - File containing an DER or PEM encoded X.509 certificate.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

StreamException - on IO errors.

readCertificate

public static X509Certificate readCertificate(InputStream in)
                                       throws EncodingException,
                                              StreamException

Reads an X.509 certificate from ASN.1 encoded data in the given stream.

Parameters:

in - Input stream containing PEM or DER encoded X.509 certificate.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

StreamException - on IO errors.

decodeCertificate

public static X509Certificate decodeCertificate(byte[] encoded)
                                         throws EncodingException

Creates an X.509 certificate from its ASN.1 encoded form.

Parameters:

encoded - PEM or DER encoded ASN.1 data.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

readCertificateChain

public static X509Certificate[] readCertificateChain(String path)
                                              throws EncodingException,
                                                     StreamException

Reads an X.509 certificate chain from ASN.1 encoded format in the file at the given location.

Parameters:

path - Path to file containing a sequence of PEM or DER encoded certificates or PKCS#7 certificate chain.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

StreamException - on IO errors.

readCertificateChain

public static X509Certificate[] readCertificateChain(File file)
                                              throws EncodingException,
                                                     StreamException

Reads an X.509 certificate chain from ASN.1 encoded format from the given file.

Parameters:

file - File containing a sequence of PEM or DER encoded certificates or PKCS#7 certificate chain.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

StreamException - on IO errors.

readCertificateChain

public static X509Certificate[] readCertificateChain(InputStream in)
                                              throws EncodingException,
                                                     StreamException

Reads an X.509 certificate chain from ASN.1 encoded data in the given stream.

Parameters:

in - Input stream containing a sequence of PEM or DER encoded certificates or PKCS#7 certificate chain.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

StreamException - on IO errors.

decodeCertificateChain

public static X509Certificate[] decodeCertificateChain(byte[] encoded)
                                                throws EncodingException

Creates an X.509 certificate chain from its ASN.1 encoded form.

Parameters:

encoded - Sequence of PEM or DER encoded certificates or PKCS#7 certificate chain.

Returns:

Certificate.

Throws:

EncodingException - on cert parsing errors.

allowsUsage

public static boolean allowsUsage(X509Certificate cert,
                                  KeyUsageBits... bits)
                           throws EncodingException

Determines whether the certificate allows the given basic key usages.

Parameters:

cert - Certificate to check.

bits - One or more basic key usage types to check.

Returns:

True if certificate allows all given usage types, false otherwise.

Throws:

EncodingException - on cert field extraction.

allowsUsage

public static boolean allowsUsage(X509Certificate cert,
                                  org.bouncycastle.asn1.x509.KeyPurposeId... purposes)
                           throws EncodingException

Determines whether the certificate allows the given extended key usages.

Parameters:

cert - Certificate to check.

purposes - One or more extended key usage purposes to check.

Returns:

True if certificate allows all given purposes, false otherwise.

Throws:

EncodingException - on cert field extraction.

hasPolicies

public static boolean hasPolicies(X509Certificate cert,
                                  String... policyOidsToCheck)
                           throws EncodingException

Determines whether the certificate defines all the given certificate policies.

Parameters:

cert - Certificate to check.

policyOidsToCheck - One or more certificate policy OIDs to check.

Returns:

True if certificate defines all given policy OIDs, false otherwise.

Throws:

EncodingException - on cert field extraction.

subjectKeyId

public static String subjectKeyId(X509Certificate cert)
                           throws EncodingException

Gets the subject key identifier of the given certificate in delimited hexadecimal format, e.g. 25:48:2f:28:ec:5d:19:bb:1d:25:ae:94:93:b1:7b:b5:35:96:24:66.

Parameters:

cert - Certificate to process.

Returns:

Subject key identifier in colon-delimited hex format.

Throws:

EncodingException - on cert field extraction.

authorityKeyId

public static String authorityKeyId(X509Certificate cert)
                             throws EncodingException

Gets the authority key identifier of the given certificate in delimited hexadecimal format, e.g. 25:48:2f:28:ec:5d:19:bb:1d:25:ae:94:93:b1:7b:b5:35:96:24:66.

Parameters:

cert - Certificate to process.

Returns:

Authority key identifier in colon-delimited hex format.

Throws:

EncodingException - on cert field extraction.

encodeCert

public static <T> T encodeCert(X509Certificate certificate,
                               CertUtil.EncodeType<T> encodeType)

PEM encodes the given certificate with the provided encoding type.

Type Parameters:

T - type of encoding

Parameters:

certificate - X.509 certificate.

encodeType - Type of encoding. CertUtil.EncodeType.X509 or CertUtil.EncodeType.PKCS7

Returns:

either DER encoded certificate or PEM-encoded certificate header and footer defined by CertUtil.EncodeType and data wrapped at 64 characters per line.

Throws:

RuntimeException - if a certificate encoding error occurs

subjectDN

public static String subjectDN(X509Certificate cert,
                               CertUtil.X500PrincipalFormat format)

Retrieves the subject distinguished name (DN) of the provided X.509 certificate. The subject DN represents the identity of the certificate holder and typically includes information such as the common name (CN), organizational unit (OU), organization (O), locality (L), state (ST), country (C), and other attributes.

Parameters:

cert - The X.509 certificate from which to extract the subject DN.

format - Controls whether the output contains spaces between attributes in the DN. Use CertUtil.X500PrincipalFormat.READABLE to generate a DN with spaces after the commas separating attribute-value pairs, CertUtil.X500PrincipalFormat.RFC2253 for no spaces.

Returns:

The subject DN string of the X.509 certificate.

Throws:

NullPointerException - If the provided certificate is null.

generateX509Certificate

public static X509Certificate generateX509Certificate(KeyPair keyPair,
                                                      String dn,
                                                      Duration duration,
                                                      String signatureAlgo)

Generates a self-signed certificate.

Parameters:

keyPair - used for signing the certificate

dn - Subject dn

duration - Validity period of the certificate. The notAfter field is set to now plus this value.

signatureAlgo - the signature algorithm identifier to use

Returns:

a self-signed X509Certificate

generateX509Certificate

public static X509Certificate generateX509Certificate(KeyPair keyPair,
                                                      String dn,
                                                      Date notBefore,
                                                      Date notAfter,
                                                      String signatureAlgo)

Generates a self-signed certificate.

Parameters:

keyPair - used for signing the certificate

dn - Subject dn

notBefore - the date and time when the certificate validity period starts

notAfter - the date and time when the certificate validity period ends

signatureAlgo - the signature algorithm identifier to use

Returns:

a self-signed X509Certificate