Class KeyStoreCredential

All Implemented Interfaces:
DisposableBean, InitializingBean, PkiCredential, ReloadablePkiCredential

public class KeyStoreCredential extends AbstractReloadablePkiCredential
A KeyStore backed implementation of the PkiCredential and ReloadablePkiCredential interfaces.

A KeyStoreCredential can be initialized in a number of ways:

  1. By loading a KeyStore from a Resource and then getting the certificate and private key. This is done either by using any of the constructors KeyStoreCredential(Resource, char[], String, char[]), KeyStoreCredential(Resource, String, char[], String, char[]) or KeyStoreCredential(Resource, String, String, char[], String, char[]) or by assigning all required properties using setter-methods.
  2. By providing an already loaded KeyStore instance and giving the entry alias and key password. This is done either by using the constructor KeyStoreCredential(KeyStore, String, char[]) or by assigning all required properties using setter-methods.

This class also supports handling of PKCS#11 credentials. This requires using a security provider that supports creating a KeyStore based on an underlying PKCS#11 implementation (for example the SunPKCS11 provider). There are three ways of creating a KeyStoreCredential for use with PKCS#11:

Supplying an already existing PKCS#11 KeyStore
In some cases you may already have loaded a KeyStore using a security provider configured for PKCS#11. In these cases the initialization of the KeyStoreCredential is identical with option number 2 above. You simply create your KeyStoreCredential instance by giving the KeyStore instance, the entry alias and key password either via the KeyStoreCredential(KeyStore, String, char[]) or by assigning all required properties using setter-methods.

Supplying the provider name of a Security provider configured for your PKCS#11 device
Another possibility is to supply the provider name of a security provider configured for PKCS#11. This could typically look something like:

 // Create a SunPKCS11 provider instance using our PKCS#11 configuration ...
 Provider provider = Security.getProvider("SunPKCS11");
 provider = provider.configure(pkcs11CfgFile);
 Security.addProvider(provider);

 // Create a credential ...
 KeyStoreCredential credential = new KeyStoreCredential(null, "PKCS11", provider.getName(), tokenPw, alias, null);
 credential.init();
 

Supplying the PKCS#11 configuration file
In the above example we created the SunPKCS11 provider instance manually. It is also to create a KeyStoreCredential instance by supplying the PKCS#11 configuration file.

 KeyStoreCredential credential = new KeyStoreCredential(null, "PKCS11", "SunPKCS11", tokenPw, alias, null);
 credential.setPkcs11Configuration(pkcs11CfgFile);
 credential.init();
 

Note: As an alternative of using KeyStoreCredential for PKCS#11 credentials see the Pkcs11Credential class.

Author:
Martin Lindström (martin@idsec.se), Stefan Santesson (stefan@idsec.se)
  • Constructor Details

    • KeyStoreCredential

      public KeyStoreCredential()
      Default constructor.
    • KeyStoreCredential

      public KeyStoreCredential(KeyStore keyStore, String alias, char[] keyPassword)
      Constructor accepting an already loaded KeyStore.
      Parameters:
      keyStore - the keystore to read the key pair from
      alias - the alias to the entry holding the key pair
      keyPassword - the password to unlock the key pair
    • KeyStoreCredential

      public KeyStoreCredential(Resource resource, char[] password, String alias, char[] keyPassword)
      A constructor that creates and loads a KeyStore from the given resource. The default KeyStore type is used and the first security provider that can create such a KeyStore is used.
      Parameters:
      resource - the resource to load the KeyStore from
      password - the password needed to load the KeyStore
      alias - the entry alias for the certificate and private key
      keyPassword - the password needed to unlock the certificate and private key (if null, the same value as given for password is used)
    • KeyStoreCredential

      public KeyStoreCredential(Resource resource, String type, char[] password, String alias, char[] keyPassword)
      A constructor that creates and loads a KeyStore of the given type from the given resource. The first security provider that can create such a KeyStore is used.
      Parameters:
      resource - the resource to load the KeyStore from
      type - the KeyStore type
      password - the password needed to load the KeyStore
      alias - the entry alias for the certificate and private key
      keyPassword - the password needed to unlock the certificate and private key (if null, the same value as given for password is used)
    • KeyStoreCredential

      public KeyStoreCredential(Resource resource, String type, String provider, char[] password, String alias, char[] keyPassword)
      A constructor that creates and loads a KeyStore of the given type from the given resource using the given provider.
      Parameters:
      resource - the resource to load the KeyStore from
      type - the KeyStore type
      provider - the security provider to use when creating the KeyStore
      password - the password needed to load the KeyStore
      alias - the entry alias for the certificate and private key
      keyPassword - the password needed to unlock the certificate and private key (if null, the same value as given for password is used)
  • Method Details

    • afterPropertiesSet

      public void afterPropertiesSet() throws Exception
      The default implementation verfies that the public key and the private key is available. Implementations that needs to be initialized (for example by loading the keys) should override this method.
      Specified by:
      afterPropertiesSet in interface InitializingBean
      Overrides:
      afterPropertiesSet in class AbstractPkiCredential
      Throws:
      Exception
    • destroy

      public void destroy()
      Implementations that need to perform clean-up actions should override this method. The default implementation does nothing.
      Specified by:
      destroy in interface DisposableBean
      Overrides:
      destroy in class AbstractPkiCredential
    • isHardwareCredential

      public boolean isHardwareCredential()
      Predicate that tells whether this credential resides in a hardware module.
      Returns:
      true if the credential resides in a hardware module and false otherwise
    • setResource

      public void setResource(Resource resource)
      Assigns the resource holding the KeyStore to load.
      Parameters:
      resource - KeyStore resource
    • setType

      public void setType(String type)
      Assigns the KeyStore type to use, ("JKS", "PKCS12", "PKCS11", ...). If no type is configured KeyStore.getDefaultType() is assumed.
      Parameters:
      type - the KeyStore type
    • setProvider

      public void setProvider(String provider)
      Assigns the name of the security provider to use when loading the KeyStore. If no provider is assigned, the first provider that can create a KeyStore according to the given type is used.
      Parameters:
      provider - the provider name to use
    • setPkcs11Configuration

      public void setPkcs11Configuration(String pkcs11Configuration)
      Assigns the PKCS#11 configuration file to use.

      The type (setType(String)) must be "PKCS11" and the provider name must be set to the base signature provider to use (e.g. "SunPKCS11").

      Parameters:
      pkcs11Configuration - the complete path to the PKCS#11 configuration file
    • setPassword

      public void setPassword(char[] password)
      Assigns the password needed to load the KeyStore.
      Parameters:
      password - the password
    • setKeyStore

      public void setKeyStore(KeyStore keyStore)
      Assigns the keystore to read the key pair from.
      Parameters:
      keyStore - the keystore
    • setAlias

      public void setAlias(String alias)
      Assigns the alias of the KeyStore entry.
      Parameters:
      alias - the KeyStore alias
    • setKeyPassword

      public void setKeyPassword(char[] keyPassword)
      Assigns the key password needed to unlock the key entry.
      Parameters:
      keyPassword - the key password
    • getPublicKey

      public PublicKey getPublicKey()
      Gets the public key.
      Specified by:
      getPublicKey in interface PkiCredential
      Overrides:
      getPublicKey in class AbstractPkiCredential
      Returns:
      the public key
    • setPublicKey

      public void setPublicKey(PublicKey publicKey)
      Will throw an IllegalArgumentException since the public key will be read from the keystore.
      Overrides:
      setPublicKey in class AbstractPkiCredential
      Parameters:
      publicKey - the public key.
    • getCertificate

      public X509Certificate getCertificate()
      Gets the certificate holding the public key of the key pair. May be null depending on whether certificates are handled by the implementing class.
      Specified by:
      getCertificate in interface PkiCredential
      Overrides:
      getCertificate in class AbstractPkiCredential
      Returns:
      the certificate, or null if no certificate is configured for the credential
    • getCertificateChain

      public List<X509Certificate> getCertificateChain()
      Gets a certificate chain for the credential, where the first element is the entity certificate (PkiCredential.getCertificate()). If no certificate is configured for the credential an empty list is returned.
      Specified by:
      getCertificateChain in interface PkiCredential
      Overrides:
      getCertificateChain in class AbstractPkiCredential
      Returns:
      a list of certificates, or an empty list
    • getPrivateKey

      public PrivateKey getPrivateKey()
      Gets the private key.
      Specified by:
      getPrivateKey in interface PkiCredential
      Overrides:
      getPrivateKey in class AbstractPkiCredential
      Returns:
      the private key
    • setPrivateKey

      public void setPrivateKey(PrivateKey privateKey)
      Will throw an IllegalArgumentException since the private key will be read from the keystore.
      Overrides:
      setPrivateKey in class AbstractPkiCredential
      Parameters:
      privateKey - the private key
    • reload

      public void reload() throws Exception
      If the KeyStoreCredential is of PKCS#11 type, the method will reload the private key.
      Throws:
      Exception - for reloading errors
    • getDefaultName

      protected String getDefaultName()
      If the credential name property is not explicitly assigned using AbstractPkiCredential.setName(String) a name is calculated based on a credential's properties.

      Implementations must not assume that the object has been correctly initialized.

      Specified by:
      getDefaultName in class AbstractPkiCredential
      Returns:
      the credential name