org.jivesoftware.openfire.keystore

Class IdentityStore

java.lang.Object

org.jivesoftware.openfire.keystore.CertificateStore

org.jivesoftware.openfire.keystore.IdentityStore

public class IdentityStore
extends CertificateStore

A wrapper class for a store of certificates, its metadata (password, location) and related functionality that is used to provide credentials (that represent this Openfire instance), an identity store An identity store should contain private keys, each associated with its certificate chain. Having the root certificate of the Certificate Authority that signed the certificates in this identity store should be in a corresponding trust store, although this is not strictly required. The reasoning here is that when you trust a Certificate Authority to verify your identity, you're likely to trust the same Certificate Authority to verify the identities of others. Note that in Java terminology, an identity store is commonly referred to as a 'key store', while the same name is also used to identify the generic certificate store. To have clear distinction between common denominator and each of the specific types, this implementation uses the terms "certificate store", "identity store" and "trust store".

Author:

Guus der Kinderen, guus.der.kinderen@gmail.com

Field Summary

Fields inherited from class org.jivesoftware.openfire.keystore.CertificateStore

configuration, PROVIDER, store

Constructor Summary

Constructors

Constructor and Description
IdentityStore(CertificateStoreConfiguration configuration, boolean createIfAbsent)

Method Summary

Methods

Modifier and Type	Method and Description
void	addSelfSignedDomainCertificate(String algorithm) Populates the key store with a self-signed certificate for the domain of this XMPP service.
boolean	containsDomainCertificate(String algorithm) Checks if the store contains a certificate of a particular algorithm that matches the domain of this XMPP service.
protected boolean	corresponds(String alias, List<X509Certificate> certificates)
void	ensureDomainCertificates(String... algorithms) Adds a self-signed certificate for the domain of this XMPP service when no certificate for the domain (of the provided algorithm) was found.
String	generateCSR(String alias) Creates a Certificate Signing Request based on the private key and certificate identified by the provided alias.
protected static KeyPair	generateKeyPair(String algorithm, int keySize) Returns a new public & private key with the specified algorithm (e.g.
String	installCertificate(String pemCertificates, String pemPrivateKey, String passPhrase) Imports a certificate and the private key that was used to generate the certificate.
void	installCertificate(String alias, String pemCertificates, String pemPrivateKey, String passPhrase) Imports a certificate and the private key that was used to generate the certificate.
void	installCSRReply(String alias, String pemCertificates) Imports a certificate (and its chain) in this store.
static boolean	isForThisDomain(X509Certificate certificate) Verifies that the subject of the certificate matches the domain of this XMPP service.

Methods inherited from class org.jivesoftware.openfire.keystore.CertificateStore

delete, getAllCertificates, getConfiguration, getStore, persist, reload

Methods inherited from class java.lang.Object

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

Constructor Detail

IdentityStore

public IdentityStore(CertificateStoreConfiguration configuration,
             boolean createIfAbsent)
              throws CertificateStoreConfigException

Throws:

CertificateStoreConfigException

Method Detail

generateCSR

public String generateCSR(String alias)
                   throws CertificateStoreConfigException

Creates a Certificate Signing Request based on the private key and certificate identified by the provided alias. When the alias does not identify a private key and/or certificate, this method will throw an exception. The certificate that is identified by the provided alias can be an unsigned certificate, but also a certificate that is already signed. The latter implies that the generated request is a request for certificate renewal. An invocation of this method does not change the state of the underlying store.

Parameters:

alias - An identifier for a private key / certificate in this store (cannot be null).

Returns:

A PEM-encoded Certificate Signing Request (never null).

Throws:

CertificateStoreConfigException

installCSRReply

public void installCSRReply(String alias,
                   String pemCertificates)
                     throws CertificateStoreConfigException

Imports a certificate (and its chain) in this store. This method will fail when the provided certificate chain:

• does not match the domain of this XMPP service.
• is not a proper chain

This method will also fail when a corresponding private key is not already in this store (it is assumed that the CA reply follows a signing request based on a private key that was added to the store earlier).

Parameters:

pemCertificates - a PEM representation of the certificate or certificate chain (cannot be null or empty).

Throws:

CertificateStoreConfigException

corresponds

protected boolean corresponds(String alias,
                  List<X509Certificate> certificates)
                       throws KeyStoreException,
                              UnrecoverableKeyException,
                              NoSuchAlgorithmException

Throws:

KeyStoreException

UnrecoverableKeyException

NoSuchAlgorithmException

installCertificate

public String installCertificate(String pemCertificates,
                        String pemPrivateKey,
                        String passPhrase)
                          throws CertificateStoreConfigException

Imports a certificate and the private key that was used to generate the certificate. This method will import the certificate and key in the store using a unique alias. This alias is returned. This method will fail when the provided certificate does not match the domain of this XMPP service.

Parameters:

pemCertificates - a PEM representation of the certificate or certificate chain (cannot be null or empty).

pemPrivateKey - a PEM representation of the private key (cannot be null or empty).

passPhrase - optional pass phrase (must be present if the private key is encrypted).

Returns:

The alias that was used (never null).

Throws:

CertificateStoreConfigException

installCertificate

public void installCertificate(String alias,
                      String pemCertificates,
                      String pemPrivateKey,
                      String passPhrase)
                        throws CertificateStoreConfigException

Imports a certificate and the private key that was used to generate the certificate. This method will fail when the provided certificate does not match the domain of this XMPP service, or when the provided alias refers to an existing entry.

Parameters:

alias - the name (key) under which the certificate is to be stored in the store (cannot be null or empty).

pemCertificates - a PEM representation of the certificate or certificate chain (cannot be null or empty).

pemPrivateKey - a PEM representation of the private key (cannot be null or empty).

passPhrase - optional pass phrase (must be present if the private key is encrypted).

Throws:

CertificateStoreConfigException

ensureDomainCertificates

public void ensureDomainCertificates(String... algorithms)
                              throws CertificateStoreConfigException

Adds a self-signed certificate for the domain of this XMPP service when no certificate for the domain (of the provided algorithm) was found. This method is a thread-safe equivalent of:

   for ( String algorithm : algorithms ) {
     if ( !containsDomainCertificate( algorithm ) ) {
        addSelfSignedDomainCertificate( algorithm );
     }
   }
 

Parameters:

algorithms - The algorithms for which to verify / add a domain certificate.

Throws:

CertificateStoreConfigException

containsDomainCertificate

public boolean containsDomainCertificate(String algorithm)
                                  throws CertificateStoreConfigException

Checks if the store contains a certificate of a particular algorithm that matches the domain of this XMPP service. This method will not distinguish between self-signed and non-self-signed certificates.

Throws:

CertificateStoreConfigException

addSelfSignedDomainCertificate

public void addSelfSignedDomainCertificate(String algorithm)
                                    throws CertificateStoreConfigException

Populates the key store with a self-signed certificate for the domain of this XMPP service.

Throws:

CertificateStoreConfigException

generateKeyPair

protected static KeyPair generateKeyPair(String algorithm,
                      int keySize)
                                  throws GeneralSecurityException

Returns a new public & private key with the specified algorithm (e.g. DSA, RSA, etc.).

Parameters:

algorithm - DSA, RSA, etc.

keySize - the desired key size. This is an algorithm-specific metric, such as modulus length, specified in number of bits.

Returns:

a new public & private key with the specified algorithm (e.g. DSA, RSA, etc.).

Throws:

GeneralSecurityException

isForThisDomain

public static boolean isForThisDomain(X509Certificate certificate)

Verifies that the subject of the certificate matches the domain of this XMPP service.

Parameters:

certificate - The certificate to verify (cannot be null)

Returns:

true when the certificate subject is this domain, otherwise false.