lv.pasts.eme.smartcard

## Class CardAccessor

- java.lang.Object
- - lv.pasts.eme.smartcard.CardAccessor

- All Implemented Interfaces:
    KeyAccessor

      public abstract class CardAccessor
      extends Object
      implements KeyAccessor

  `CardAccessor` class provides access to the SmartCard. An instance of this class can be obtained from the `getInstance(CardAccessorCallback)` method.

  As of the version 1.3.3, this class was adjusted to implement the `KeyAccessor` interface.

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `containsAlias(String alias)` Returns true if keystore contains the given alias.
    `CardAccessorCallback` | `getCardAccessorCallback()` Returns the current `CardAccessorCallback` object.
    `X509Certificate` | `getCertificate(String alias)` Returns the `X509Certificate` associated with the given alias.
    `CertificateEntry[]` | `getClientAuthenticationCertificateEntries()` Returns the `CertificateEntry` array containing available client authentication certificates.
    `CertificateEntry[]` | `getDocumentSigningCertificateEntries()` Returns the `CertificateEntry` array containing available signing certificates.
    `static CardAccessor` | `getInstance(CardAccessorCallback cardAccessorCallback)` Creates a `CardAccessor` object using the given CardAccessorCallback handler.
    `KeyStore.Builder` | `getKeyStoreBuilder()` Returns KeyStore builder instance for KeyStore representing the smart card's content.
    `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.
    `abstract void` | `refreshKeyStore()` Attempts to reload the smart card's content.
    `void` | `reset()` Resets any resources used by this `CardAccessor`.
    `String` | `selectClientAuthenticationCertificate()` Requests user to select the client authentication certificate retrieved from the smart card and returns the alias name of the selected item, or `null` if action is cancelled.
    `String` | `selectDocumentSigningCertificate()` Requests user to select the signing certificate retrieved from the smart card and returns the alias name of the selected item, or `null` if action is cancelled.
    `void` | `setCardAccessorCallback(CardAccessorCallback cardAccessorCallback)` Sets the current `CardAccessorCallback` object.
    `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`

- - ### Method Detail

    - #### getInstance

          public static CardAccessor getInstance(CardAccessorCallback cardAccessorCallback)

      Creates a `CardAccessor` object using the given CardAccessorCallback handler.

      In some cases `CardAccessor` must communicate with the user to obtain PIN code or get some other input, therefore to create a `CardAccessor`, you must specify an instance of `CardAccessorCallback` object which implements the required callback methods.

      Parameters:
        `cardAccessorCallback` - callback object used to retrieve smart card's information.

    - #### getDocumentSigningCertificateEntries

          public CertificateEntry[] getDocumentSigningCertificateEntries()
                                                                  throws KeyStoreException

      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.
      Since:
        1.3.3

    - #### getClientAuthenticationCertificateEntries

          public CertificateEntry[] getClientAuthenticationCertificateEntries()
                                                                       throws KeyStoreException

      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.
      Since:
        1.3.3

    - #### containsAlias

          public boolean containsAlias(String alias)
                                throws KeyStoreException

      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 smartcard cannot be accessed.

    - #### getCertificate

          public X509Certificate getCertificate(String alias)
                                         throws KeyStoreException

      Returns the `X509Certificate` associated with the given alias.

      An alias of the certificate can be obtained from the `CertificateEntry` object returned by either `getDocumentSigningCertificateEntries()` or `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 smart card cannot be accessed.

    - #### getPrivateKey

          public PrivateKey getPrivateKey(String alias)
                                   throws KeyStoreException

      Returns the `PrivateKey` associated with the given alias.

      An alias of the key can be obtained from the `CertificateEntry` object returned by either `getDocumentSigningCertificateEntries()` or `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 smart card cannot be accessed.

    - #### 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' digest 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 `getPrivateKey(String)` method.

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

    - #### signData

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

      Returns the signature bytes of all the given data. Signature is calculated using the 'SHA1withRSA' digest 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 `getDocumentSigningCertificateEntries()` or `getClientAuthenticationCertificateEntries()` method.

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

    - #### getKeyStoreBuilder

          public KeyStore.Builder getKeyStoreBuilder()
                                              throws KeyStoreException

      Returns KeyStore builder instance for KeyStore representing the smart card's content.
      Returns:
        KeyStore builder instance.
      Throws:
        `KeyStoreException` - if smart card cannot be accessed.

    - #### getKeyStoreBuilder

          public KeyStore.Builder getKeyStoreBuilder(String alias)
                                              throws KeyStoreException

      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.
      Since:
        1.3.3

    - #### reset

          public void reset()

      Resets any resources used by this `CardAccessor`.

    - #### refreshKeyStore

          public abstract void refreshKeyStore()
                                        throws KeyStoreException

      Attempts to reload the smart card's content.
      Throws:
        `KeyStoreException` - if KeyStore cannot be accessed.

    - #### selectDocumentSigningCertificate

          public String selectDocumentSigningCertificate()
                                                  throws KeyStoreException

      Requests user to select the signing certificate retrieved from the smart card 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 smart card cannot be accessed.

    - #### selectClientAuthenticationCertificate

          public String selectClientAuthenticationCertificate()
                                                       throws KeyStoreException

      Requests user to select the client authentication certificate retrieved from the smart card 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 smart card cannot be accessed.

    - #### getCardAccessorCallback

          public CardAccessorCallback getCardAccessorCallback()

      Returns the current `CardAccessorCallback` object.
      Returns:
        current CardAccessorCallback object.

    - #### setCardAccessorCallback

          public void setCardAccessorCallback(CardAccessorCallback cardAccessorCallback)

      Sets the current `CardAccessorCallback` object.
      Parameters:
        `cardAccessorCallback` - callback object used to retrieve smart card's information.
      Since:
        1.3.3

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