lv.pasts.eme.security

## Class KeyStoreManager

- java.lang.Object
- - lv.pasts.eme.security.KeyStoreManager

- All Implemented Interfaces:
    KeyAccessor

      public class KeyStoreManager
      extends Object
      implements KeyAccessor

  `KeyStoreManager` class provides functionality to access cryptographic keys and certificates contained by various types of keystores.
  Since:
    1.3.3

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeyStoreManager(KeyStore keyStore, KeyStoreManagerCallback callback)` Creates a new `KeyStoreManager` instance for the given KeyStore.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `containsAlias(String alias)` Returns true if keystore contains the given alias.
    `X509Certificate` | `getCertificate(String alias)` Returns the `X509Certificate` associated with the given alias.
    `static CertificateEntry[]` | `getCertificates(KeyStore keyStore, String usageIdentifier)` Utility method for internal use.
    `CertificateEntry[]` | `getClientAuthenticationCertificateEntries()` Returns the `CertificateEntry` array containing available client authentication certificates.
    `CertificateEntry[]` | `getDocumentSigningCertificateEntries()` Returns the `CertificateEntry` array containing available signing certificates.
    `KeyStore.Builder` | `getKeyStoreBuilder(String alias)` Returns KeyStore.Builder instance for KeyStore containing the given alias.
    `PrivateKey` | `getPrivateKey(String alias)` Returns the `PrivateKey` associated with the given alias.
    `static KeyStore` | `loadWindowsTrustStore()` Returns KeyStore containg the native Windows ROOT and CA certificates.
    `static KeyStoreManager` | `manageJavaKeyStore(String file, char[] password, KeyStoreManagerCallback callback)` Returns an instance of `KeyStoreManager` providing access to the Java keystore.
    `static KeyStoreManager` | `managePKCS12KeyStore(String file, char[] password, KeyStoreManagerCallback callback)` Returns an instance of `KeyStoreManager` providing access to the PKCS12 format (.p12, .pfx) keystore.
    `static KeyStoreManager` | `manageWindowsMyKeyStore(KeyStoreManagerCallback callback)` Returns an instance of `KeyStoreManager` providing access to the native Microsoft Windows MY keystore.
    `static KeyStoreManager` | `manageWindowsRootKeyStore(KeyStoreManagerCallback callback)` Returns an instance of `KeyStoreManager` providing access to the native Microsoft Windows ROOT keystore.
    `String` | `selectClientAuthenticationCertificate()` Requests user to select the client authentication certificate and returns the alias name of the selected item, or `null` if action is cancelled.
    `String` | `selectDocumentSigningCertificate()` Requests user to select the signing certificate and returns the alias name of the selected item, or `null` if action is cancelled.
    `byte[]` | `signData(byte[] data, PrivateKey privateKey)` Returns the signature bytes of all the given data.
    `byte[]` | `signData(byte[] data, String alias)` Returns the signature bytes of all the given data.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### KeyStoreManager

          public KeyStoreManager(KeyStore keyStore,
                                 KeyStoreManagerCallback callback)

      Creates a new `KeyStoreManager` instance for the given KeyStore.
      Parameters:
        `keyStore` - an initialized keystore.
        `callback` - a callback used to interact with the user while accessing the keystore.

  - ### Method Detail

    - #### manageWindowsMyKeyStore

          public static KeyStoreManager manageWindowsMyKeyStore(KeyStoreManagerCallback callback)
                                                         throws KeyStoreException

      Returns an instance of `KeyStoreManager` providing access to the native Microsoft Windows MY keystore. The keystore contains the user's personal certificates and associated private keys.
      Parameters:
        `callback` - a callback used to interact with the user while accessing the keystore.
      Returns:
        a KeyStoreManager providing access to the native Microsoft Windows MY keystore.
      Throws:
        `KeyStoreException` - if the native Microsoft Windows MY keystore cannot be accessed.
      Since:
        1.3.4

    - #### manageWindowsRootKeyStore

          public static KeyStoreManager manageWindowsRootKeyStore(KeyStoreManagerCallback callback)
                                                           throws KeyStoreException

      Returns an instance of `KeyStoreManager` providing access to the native Microsoft Windows ROOT keystore. The keystore contains the certificates of Root certificate authorities and other self-signed trusted certificates.
      Parameters:
        `callback` - a callback used to interact with the user while accessing the keystore.
      Returns:
        a KeyStoreManager providing access to the native Microsoft Windows ROOT keystore.
      Throws:
        `KeyStoreException` - if the native Microsoft Windows ROOT keystore cannot be accessed.
      Since:
        1.3.4

    - #### loadWindowsTrustStore

          public static KeyStore loadWindowsTrustStore()
                                                throws KeyStoreException

      Returns KeyStore containg the native Windows ROOT and CA certificates.
      Returns:
        KeyStore containg Windows trusted certificates.
      Throws:
        `KeyStoreException` - if the native Microsoft Windows keystore cannot be accessed.
      Since:
        1.4.5

    - #### manageJavaKeyStore

          public static KeyStoreManager manageJavaKeyStore(String file,
                                                           char[] password,
                                                           KeyStoreManagerCallback callback)
                                                    throws KeyStoreException

      Returns an instance of `KeyStoreManager` providing access to the Java keystore.
      Parameters:
        `file` - the file from which the keystore is loaded.
        `password` - the password used to unlock the keystore.
        `callback` - callback a callback used to interact with the user while accessing the keystore.
      Returns:
        a KeyStoreManager providing access to the Java keystore.
      Throws:
        `KeyStoreException` - if the keystore cannot be accessed.

    - #### managePKCS12KeyStore

          public static KeyStoreManager managePKCS12KeyStore(String file,
                                                             char[] password,
                                                             KeyStoreManagerCallback callback)
                                                      throws KeyStoreException

      Returns an instance of `KeyStoreManager` providing access to the PKCS12 format (.p12, .pfx) keystore.
      Parameters:
        `file` - the file from which the keystore is loaded.
        `password` - the password used to unlock the keystore.
        `callback` - callback a callback used to interact with the user while accessing the keystore.
      Returns:
        a KeyStoreManager providing access to the PKCS12 format keystore.
      Throws:
        `KeyStoreException` - if the keystore cannot be accessed.

    - #### containsAlias

          public boolean containsAlias(String alias)
                                throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Returns true if keystore contains the given alias.
      Specified by:
        `containsAlias` in interface `KeyAccessor`
      Parameters:
        `alias` - the alias name.
      Returns:
        true if keystore contains the alias name.
      Throws:
        `KeyStoreException` - if keystore cannot be accessed.

    - #### getCertificate

          public X509Certificate getCertificate(String alias)
                                         throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Returns the `X509Certificate` associated with the given alias.

      An alias of the certificate can be obtained from the `CertificateEntry` object returned by either `KeyAccessor.getDocumentSigningCertificateEntries()` or `KeyAccessor.getClientAuthenticationCertificateEntries()` method.

      Specified by:
        `getCertificate` in interface `KeyAccessor`
      Parameters:
        `alias` - the alias name.
      Returns:
        the requested certificate, or null if the given alias does not exist.
      Throws:
        `KeyStoreException` - if certificate data cannot be accessed.

    - #### getPrivateKey

          public PrivateKey getPrivateKey(String alias)
                                   throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Returns the `PrivateKey` associated with the given alias.

      An alias of the key can be obtained from the `CertificateEntry` object returned by either `KeyAccessor.getDocumentSigningCertificateEntries()` or `KeyAccessor.getClientAuthenticationCertificateEntries()` method.

      Specified by:
        `getPrivateKey` in interface `KeyAccessor`
      Parameters:
        `alias` - the alias name.
      Returns:
        the requested key, or null if the given alias does not exist.
      Throws:
        `KeyStoreException` - if key data cannot be accessed.

    - #### getDocumentSigningCertificateEntries

          public CertificateEntry[] getDocumentSigningCertificateEntries()
                                                                  throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Returns the `CertificateEntry` array containing available signing certificates.

      Document signing certificates are resolved by the Extended Key Usage extension, containing the "Document signing" object identifier (OID 1.3.6.1.4.1.311.10.3.12).

      Specified by:
        `getDocumentSigningCertificateEntries` in interface `KeyAccessor`
      Returns:
        the `CertificateEntry` array containing signing certificates.
      Throws:
        `KeyStoreException` - if certificate data cannot be retrieved.

    - #### getClientAuthenticationCertificateEntries

          public CertificateEntry[] getClientAuthenticationCertificateEntries()
                                                                       throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Returns the `CertificateEntry` array containing available client authentication certificates.

      Client authentication certificates are resolved by the Extended Key Usage extension, containing the "Client Authentication" object identifier (OID 1.3.6.1.5.5.7.3.2).

      Specified by:
        `getClientAuthenticationCertificateEntries` in interface `KeyAccessor`
      Returns:
        the `CertificateEntry` array containing client authentication certificates.
      Throws:
        `KeyStoreException` - if certificate data cannot be retrieved.

    - #### selectDocumentSigningCertificate

          public String selectDocumentSigningCertificate()
                                                  throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Requests user to select the signing certificate and returns the alias name of the selected item, or `null` if action is cancelled.
      Specified by:
        `selectDocumentSigningCertificate` in interface `KeyAccessor`
      Returns:
        the alias name.
      Throws:
        `KeyStoreException` - if keystore cannot be accessed.

    - #### selectClientAuthenticationCertificate

          public String selectClientAuthenticationCertificate()
                                                       throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Requests user to select the client authentication certificate and returns the alias name of the selected item, or `null` if action is cancelled.
      Specified by:
        `selectClientAuthenticationCertificate` in interface `KeyAccessor`
      Returns:
        the alias name.
      Throws:
        `KeyStoreException` - if keystore cannot be accessed.

    - #### signData

          public byte[] signData(byte[] data,
                                 String alias)
                          throws KeyStoreException,
                                 SignatureException

      Description copied from interface: `KeyAccessor`
      Returns the signature bytes of all the given data. Signature is calculated using the 'SHA1withRSA' algorithm.
      Specified by:
        `signData` in interface `KeyAccessor`
      Parameters:
        `data` - the byte array to use for the signature calculation.
        `alias` - the alias name representing a private key of the identity whose signature is going to be generated.

        An alias of the key can be obtained from the `CertificateEntry` object returned by either `KeyAccessor.getDocumentSigningCertificateEntries()` or `KeyAccessor.getClientAuthenticationCertificateEntries()` method.

      Returns:
        the signature bytes of all the given data.
      Throws:
        `KeyStoreException` - if key data cannot be accessed.
        `SignatureException` - if the given data cannot be signed.

    - #### signData

          public byte[] signData(byte[] data,
                                 PrivateKey privateKey)
                          throws SignatureException

      Returns the signature bytes of all the given data. Signature is calculated using the 'SHA1withRSA' algorithm.
      Parameters:
        `data` - the byte array to use for the signature calculation.
        `privateKey` - the private key of the identity whose signature is going to be generated.

        The private can be obtained using the `KeyAccessor.getPrivateKey(String)` method.

      Returns:
        the signature bytes of all the given data.
      Throws:
        `SignatureException` - if the given data cannot be signed.

    - #### getKeyStoreBuilder

          public KeyStore.Builder getKeyStoreBuilder(String alias)
                                              throws KeyStoreException

      Description copied from interface: `KeyAccessor`
      Returns KeyStore.Builder instance for KeyStore containing the given alias.
      Specified by:
        `getKeyStoreBuilder` in interface `KeyAccessor`
      Parameters:
        `alias` - the alias name.
      Returns:
        KeyStore.Builder instance.
      Throws:
        `KeyStoreException` - if KeyStore cannot be accessed.

    - #### getCertificates

          public static CertificateEntry[] getCertificates(KeyStore keyStore,
                                                           String usageIdentifier)
                                                    throws KeyStoreException

      Utility method for internal use.
      Parameters:
        `keyStore` - keystore.
        `usageIdentifier` - certificate usage identifier.
      Returns:
        the `CertificateEntry` array containing requested certificates.
      Throws:
        `KeyStoreException` - if certificate data cannot be retrieved.

Copyright VAS Latvijas Valsts radio un televizijas centrs / Developed by SIA EUSO