hwsecurity / de.cotech.hw

Package de.cotech.hw

Types

Name Summary
SecurityKey

abstract class SecurityKey

An abstract connected Security Key. Concrete instances of this class, such as FidoSecurityKey, PivSecurityKey, or OpenPgpSecurityKey, offer methods to interact with the connected Security Key and applet.

SecurityKeyAuthenticator

interface SecurityKeyAuthenticator

This use case class performs an “authenticate” operation on a challenge.

Instances of this class can be obtained from SecurityKey objects for Security Key types that support it. For Security Keys that contain more than possible key for authentication operations, each instance of this class is already associated with a specific key.

Example:

byte[] challenge = { (byte) 1, (byte) 2, (byte) 3, (byte) 4 };
  PinProvider pinProvider = StaticPinProvider.getInstance(ByteSecret.unsafeFromString("123456"));
 
  SecurityKeyAuthenticator securityKeyAuthenticator = securityKey.createSecurityKeyAuthenticator(pinProvider)
  byte[] signatureBytes = authenticator.authenticateWithDigest(challenge, "SHA-1");
 
  Signature signature = Signature.getInstance("SHA1withRSA");
  signature.initVerify(securityKeyAuthenticator.retrievePublicKey());
  signature.update(challenge);
  boolean isVerified = signature.verify(signatureBytes);
  assert isVerified;
SecurityKeyCallback

interface SecurityKeyCallback<T :SecurityKey>

A callback interface when a security key is discovered. This interface is parametrized with a type of SecurityKey, and is typically passed to [SecurityKeyManager#registerCallback]() with a matching SecurityKeyConnectionMode.

SecurityKeyConnectionMode abstract class SecurityKeyConnectionMode<T :SecurityKey>
SecurityKeyManager

open class SecurityKeyManager

The SecurityKeyManager is a singleton class for high-level management operations of security keys.

To use security keys in your App, you must first initialize it using #init(Application). This is usually done in Application#onCreate.

Once initialized, this class will dispatch newly connected security keys to all currently registered listeners. Listeners can be registered with [#registerCallback]().

public void onCreate() {
      super.onCreate();
      SecurityKeyManager securityKeyManager = SecurityKeyManager.getInstance();
      securityKeyManager.init(this);
  }

A callback is registered together with a SecurityKeyConnectionMode, which establishes a connection to a particular type of Security Token, such as FIDO, PIV, or OpenPGP. Implementations for different SecurityKeyConnectionModes are shipped as modules, such as :de.cotech:hwsecurity-fido:, :de.cotech:hwsecurity-piv:, and :de.cotech:hwsecurity-openpgp:. Apps will typically use only a single type of Security Key.

To receive callbacks in an Activity, register for a callback bound to the Activity’s lifecycle:

public void onCreate() {
      super.onResume();
      FidoSecurityKeyConnectionMode connectionMode = new FidoSecurityKeyConnectionMode();
      SecurityKeyManager.getInstance().registerCallback(connectionMode, this, this);
  }
  public void onSecurityKeyDiscovered(FidoSecurityKey securityKey) {
      // perform operations on FidoSecurityKey
  }

Advanced applications that want to work with different applets on the same connected Security Key can do so using de.cotech.hw.raw.RawSecurityKeyConnectionMode.

SecurityKeyManagerConfig

abstract class SecurityKeyManagerConfig

This class holds configuration options for SecurityKeyManager.

SecurityKeyTlsClientCertificateAuthenticator open class SecurityKeyTlsClientCertificateAuthenticator

Exceptions

Name Summary
SecurityKeyException

open class SecurityKeyException :IOException

Base exception of the Hardware Security SDK.