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

Modifier and Type	Method and Description
void	addSelfSignedDomainCertificate() Populates the key store with a self-signed certificate for the domain of this XMPP service.
void	addSelfSignedDomainCertificate(String algorithm) Deprecated. Unused as of Openfire 4.3.0. Use 'addSelfSignedDomainCertificate' instead. See OF-1599.
boolean	containsAllIdentityCertificate() Checks if the store contains a certificate of a particular algorithm that contains at least all of the identities of this server (which includes the XMPP domain name, but also its hostname, and XMPP addresses of components that are currently being hosted).
boolean	containsAllIdentityCertificate(String algorithm) Deprecated. Unused as of Openfire 4.3.0. Use 'containsAllIdentityCertificate' instead. See OF-1599.
boolean	containsDomainCertificate() Checks if the store contains a certificate of a particular algorithm that matches the domain of this XMPP service.
boolean	containsDomainCertificate(String algorithm) Deprecated. Unused as of Openfire 4.3.0. Use 'containsDomainCertificate' instead. See OF-1599.
protected boolean	corresponds(String alias, List<X509Certificate> certificates)
void	ensureDomainCertificate() Adds a self-signed certificate for the domain of this XMPP service when no certificate for the domain was found.
void	ensureDomainCertificates(String... algorithms) Deprecated. Unused as of Openfire 4.3.0. Use 'ensureDomainCertificate' instead. See OF-1599.
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.
protected String	generateUniqueAlias() Generates an alias that is currently unused in this store.
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.
protected void	removeAllDomainEntries() Removes all entries that reflect the local domain.
String	replaceCertificate(String pemCertificates, String pemPrivateKey, String passPhrase) Imports a certificate and the private key that was used to generate the certificate, replacing any previously installed entries for the same domain.

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

backup, 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 - if there was a problem generating the CSR

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:

alias - the certificate alias

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

Throws:

CertificateStoreConfigException - if there was a problem installing the certificate

corresponds

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

Throws:

KeyStoreException

UnrecoverableKeyException

NoSuchAlgorithmException

replaceCertificate

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

Imports a certificate and the private key that was used to generate the certificate, replacing any previously installed entries for the same domain. 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 - if there was a problem replacing the certificate

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 - if there was a problem installing the certificate

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 - if there was a problem installing the certificate

ensureDomainCertificate

public void ensureDomainCertificate()
                             throws CertificateStoreConfigException

Adds a self-signed certificate for the domain of this XMPP service when no certificate for the domain was found.

Throws:

CertificateStoreConfigException - if there was a problem creating the certificate

ensureDomainCertificates

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

Deprecated. Unused as of Openfire 4.3.0. Use 'ensureDomainCertificate' instead. See OF-1599.

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 - if there was a problem creating the certificate

containsDomainCertificate

public boolean containsDomainCertificate()
                                  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.

Returns:

true if the store contains a certificate of a particular algorithm that matches the domain of this XMPP service, otherwise false

Throws:

CertificateStoreConfigException - if there was a problem creating the certificate

containsDomainCertificate

@Deprecated
public boolean containsDomainCertificate(String algorithm)
                                              throws CertificateStoreConfigException

Deprecated. Unused as of Openfire 4.3.0. Use 'containsDomainCertificate' instead. See OF-1599.

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. If the 'algorithm' parameter is used, then this method will evaluate only certificates that match that certificate.

Parameters:

algorithm - An optional algorithm constraint (eg: "RSA"). Can be null, cannot be empty.

Returns:

true if the store contains a certificate of a particular algorithm that matches the domain of this XMPP service, otherwise false

Throws:

CertificateStoreConfigException - if there was a problem creating the certificate

containsAllIdentityCertificate

public boolean containsAllIdentityCertificate()
                                       throws CertificateStoreConfigException

Checks if the store contains a certificate of a particular algorithm that contains at least all of the identities of this server (which includes the XMPP domain name, but also its hostname, and XMPP addresses of components that are currently being hosted). This method will not distinguish between self-signed and non-self-signed certificates.

Returns:

true if the store contains a certificate of a particular algorithm that contains at least all of the identities of this server, otherwise false

Throws:

CertificateStoreConfigException - if there was a problem accessing the certificates

containsAllIdentityCertificate

@Deprecated
public boolean containsAllIdentityCertificate(String algorithm)
                                                   throws CertificateStoreConfigException

Deprecated. Unused as of Openfire 4.3.0. Use 'containsAllIdentityCertificate' instead. See OF-1599.

Checks if the store contains a certificate of a particular algorithm that contains at least all of the identities of this server (which includes the XMPP domain name, but also its hostname, and XMPP addresses of components that are currently being hosted). This method will not distinguish between self-signed and non-self-signed certificates. If the 'algorithm' parameter is used, then this method will evaluate only certificates that match that certificate.

Parameters:

algorithm - An optional algorithm constraint (eg: "RSA"). Can be null, cannot be empty.

Returns:

{true if a certiicate contains all identities for this server, otherwise false}

Throws:

CertificateStoreConfigException - if a self-signed certificate could not be created

addSelfSignedDomainCertificate

public void addSelfSignedDomainCertificate()
                                    throws CertificateStoreConfigException

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

Throws:

CertificateStoreConfigException - if a self-signed certificate could not be created

addSelfSignedDomainCertificate

@Deprecated
public void addSelfSignedDomainCertificate(String algorithm)
                                                throws CertificateStoreConfigException

Deprecated. Unused as of Openfire 4.3.0. Use 'addSelfSignedDomainCertificate' instead. See OF-1599.

Populates the key store with a self-signed certificate for the domain of this XMPP service. If the 'algorithm' parameter is used, then this method will evaluate only certificates that match that certificate.

Parameters:

algorithm - An optional algorithm constraint (eg: "RSA"). Can be null, cannot be empty.

Throws:

CertificateStoreConfigException - if a self-signed certificate could not be created

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 - if the supplied algorithm does not have a key-pair generator

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.

generateUniqueAlias

protected String generateUniqueAlias()
                              throws CertificateStoreConfigException

Generates an alias that is currently unused in this store.

Returns:

An alias (never null).

Throws:

CertificateStoreConfigException - if a unique alias could not be generated

removeAllDomainEntries

protected void removeAllDomainEntries()
                               throws KeyStoreException

Removes all entries that reflect the local domain. This method iterates over all entries, and removes those that match the domain of this server. Note that the changes are not persisted by this method (as it is expected to be used in tandem with an insert.

Throws:

KeyStoreException - if the key store could not be updated