Class SecureStorageDeviceProtection

java.lang.Object

com.codename1.security.vault.spi.DeviceProtection

com.codename1.security.vault.SecureStorageDeviceProtection

public class SecureStorageDeviceProtection
extends DeviceProtection

The DeviceProtection every port gets when it does not supply one of its own: a random wrapping key in SecureStorage, and AES-GCM performed in shared code.

This is the right implementation wherever SecureStorage is the operating system's secret store -- the iOS keychain, the Android keystore, the desktop credential store. The wrapping key is bytes, and it is bytes in the one place on the device that is built to hold bytes nobody else should reach.

It is the wrong implementation in a browser, where SecureStorage is ordinary origin-private storage: the wrapping key would sit beside the ciphertext it protects, which is no protection at all. The JavaScript port therefore overrides CodenameOneImplementation.getDeviceProtection() with one built on a non-extractable CryptoKey, and this class never runs there.

Racing callers

Key creation goes through SecureStorage.setIfAbsent(String, String), which returns what the store ended up holding rather than what this call wrote. Two processes that both find nothing therefore agree on one key instead of each overwriting the other -- which matters more here than almost anywhere, because the loser's key is what a device's remembered vault was wrapped under.

Field Summary

Fields inherited from class DeviceProtection

KEY_ABSENT, KEY_PRESENT, KEY_UNKNOWN

Constructor Summary

Constructors

Constructor	Description
SecureStorageDeviceProtection()

Method Summary

Modifier and Type	Method	Description
AsyncResource<Boolean>	deleteKey(String keyId)	Removes the device key, which is what "forget this device" does.
AsyncResource<Boolean>	ensureKey(String keyId)	Creates the device key if there is none, and converges when two callers race.
int	keyState(String keyId)	Whether a device key exists for this id.
ProtectionReport	protection()	What this device protection actually provides, as observed rather than as advertised.
protected SecureStorage	storage()	The store backing this.
AsyncResource<byte[]>	unwrap(String keyId, byte[] wrapped, byte[] aad)	Decrypts what DeviceProtection.wrap(String, byte[], byte[]) produced.
AsyncResource<byte[]>	wrap(String keyId, byte[] plaintext, byte[] aad)	Encrypts under the device key.

Methods inherited from class DeviceProtection

requiresUserVerification, setDeviceBoundRequired, userVerifying

Methods inherited from class Object

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

Constructor Details

SecureStorageDeviceProtection

public SecureStorageDeviceProtection()

Method Details

storage

protected SecureStorage storage()

The store backing this. Overridable so a port can supply a store other than the one SecureStorage.getInstance() returns, which the simulator's test harness uses.

protection

public ProtectionReport protection()

Description copied from class: DeviceProtection

What this device protection actually provides, as observed rather than as advertised.

A port that has not yet tried an operation may only report what it can verify; several answers are legitimately ProtectionReport.UNKNOWN -- no browser can say whether a key is hardware backed, and reporting NO there would understate an authenticator that uses a secure element.

Specified by:

protection in class DeviceProtection

keyState

public int keyState(String keyId)

Description copied from class: DeviceProtection

Whether a device key exists for this id.

Parameters

• keyId: the vault's device key id

Returns

DeviceProtection.KEY_PRESENT, DeviceProtection.KEY_ABSENT or DeviceProtection.KEY_UNKNOWN

Specified by:

keyState in class DeviceProtection

ensureKey

public AsyncResource<Boolean> ensureKey(String keyId)

Description copied from class: DeviceProtection

Creates the device key if there is none, and converges when two callers race.

Parameters

• keyId: the vault's device key id

Returns

a resource completing with true when a key is in place -- whether this call created it or found another one already there -- and erroring with a VaultException when no key could be established

Specified by:

ensureKey in class DeviceProtection

wrap

public AsyncResource<byte[]> wrap(String keyId,
 byte[] plaintext,
 byte[] aad)

Description copied from class: DeviceProtection

Encrypts under the device key.

Parameters

• keyId: the vault's device key id

• plaintext: what to protect, normally a vault's 32 byte data key

• aad: associated data the result is bound to; the same bytes must be supplied to DeviceProtection.unwrap(String, byte[], byte[])

Returns

a resource completing with the wrapped bytes. The format is the port's own and is never interpreted by shared code, but it must be authenticated

Specified by:

wrap in class DeviceProtection

unwrap

public AsyncResource<byte[]> unwrap(String keyId,
 byte[] wrapped,
 byte[] aad)

Description copied from class: DeviceProtection

Decrypts what DeviceProtection.wrap(String, byte[], byte[]) produced.

A failure to authenticate must arrive as VaultError.AUTHENTICATION_FAILED, a missing key as VaultError.KEY_MISSING, and a store that could not be read as VaultError.TEMPORARILY_UNREADABLE. Collapsing the last two is how a vault regenerates a key and orphans its data.

Specified by:

unwrap in class DeviceProtection

deleteKey

public AsyncResource<Boolean> deleteKey(String keyId)

Description copied from class: DeviceProtection

Removes the device key, which is what "forget this device" does.

Everything wrapped under it becomes unopenable on this device. That is the intent; it is not revocation, because a copy taken while the key existed is beyond reach.

Specified by:

deleteKey in class DeviceProtection