com.google.crypto.tink.integration.android

Class AndroidKeysetManager

java.lang.Object

com.google.crypto.tink.integration.android.AndroidKeysetManager

public final class AndroidKeysetManager
extends Object

A wrapper of KeysetManager that supports reading/writing Keyset to/from private shared preferences on Android.

Warning

This class reads and writes to shared preferences, thus is best not to run on the UI thread.

Usage

 String masterKeyUri = "android-keystore://my_master_key_id";
 AndroidKeysetManager manager = AndroidKeysetManager.Builder()
    .withSharedPref(getApplicationContext(), "my_keyset_name", "my_pref_file_name")
    .withKeyTemplate(SignatureKeyTemplates.ECDSA_P256)
    .withMasterKeyUri(masterKeyUri)
    .build();
 PublicKeySign signer = PublicKeySignFactory.getPrimitive(manager.getKeysetHandle());
 

This will read a keyset stored in the my_keyset_name preference of the my_pref_file_name preferences file. If the preference file name is null, it uses the default preferences file.

If the keyset is not found or invalid, and a valid KeyTemplate is set with AndroidKeysetManager.Builder.withKeyTemplate(com.google.crypto.tink.proto.KeyTemplate), a fresh keyset is generated and is written to the my_keyset_name preference of the my_pref_file_name shared preferences file.

On Android M or newer and if a master key URI is set with AndroidKeysetManager.Builder.withMasterKeyUri(java.lang.String), the keyset is encrypted with a master key generated and stored in Android Keystore. When Tink cannot decrypt the keyset it would assume that it is not encrypted.

The master key URI must start with android-keystore://. If the master key doesn't exist, a fresh one is generated. Usage of Android Keystore can be disabled with AndroidKeysetManager.Builder.doNotUseKeystore().

On Android L or older, or when the master key URI is not set, the keyset will be stored in cleartext in private preferences which, thanks to the security of the Android framework, no other apps can read or write.

The resulting manager supports all operations supported by KeysetManager. For example to rotate the keyset, one can do:

 manager.rotate(SignatureKeyTemplates.ECDSA_P256);
 

All operations that manipulate the keyset would automatically persist the new keyset to permanent storage.

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AndroidKeysetManager.Builder A builder for AndroidKeysetManager.

Method Summary

Modifier and Type	Method and Description
AndroidKeysetManager	add(KeyTemplate keyTemplate) Generates and adds a fresh key generated using keyTemplate.
AndroidKeysetManager	delete(int keyId) Deletes the key with keyId.
AndroidKeysetManager	destroy(int keyId) Destroys the key material associated with the keyId.
AndroidKeysetManager	disable(int keyId) Disables the key with keyId.
AndroidKeysetManager	enable(int keyId) Enables the key with keyId.
KeysetHandle	getKeysetHandle()
AndroidKeysetManager	promote(int keyId) Deprecated. use setPrimary
AndroidKeysetManager	rotate(KeyTemplate keyTemplate) Generates and adds a fresh key generated using keyTemplate, and sets the new key as the primary key.
AndroidKeysetManager	setPrimary(int keyId) Sets the key with keyId as primary.

Methods inherited from class java.lang.Object

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

Method Detail

getKeysetHandle

public KeysetHandle getKeysetHandle()
                             throws GeneralSecurityException

Returns:

a KeysetHandle of the managed keyset

Throws:

GeneralSecurityException

rotate

public AndroidKeysetManager rotate(KeyTemplate keyTemplate)
                            throws GeneralSecurityException

Generates and adds a fresh key generated using keyTemplate, and sets the new key as the primary key.

Throws:

GeneralSecurityException - if cannot find any KeyManager that can handle keyTemplate

add

public AndroidKeysetManager add(KeyTemplate keyTemplate)
                         throws GeneralSecurityException

Generates and adds a fresh key generated using keyTemplate.

Throws:

GeneralSecurityException - if cannot find any KeyManager that can handle keyTemplate

setPrimary

public AndroidKeysetManager setPrimary(int keyId)
                                throws GeneralSecurityException

Sets the key with keyId as primary.

Throws:

GeneralSecurityException - if the key is not found or not enabled

promote

@Deprecated
public AndroidKeysetManager promote(int keyId)
                                         throws GeneralSecurityException

Deprecated. use setPrimary

Sets the key with keyId as primary.

Throws:

GeneralSecurityException - if the key is not found or not enabled

enable

public AndroidKeysetManager enable(int keyId)
                            throws GeneralSecurityException

Enables the key with keyId.

Throws:

GeneralSecurityException - if the key is not found

disable

public AndroidKeysetManager disable(int keyId)
                             throws GeneralSecurityException

Disables the key with keyId.

Throws:

GeneralSecurityException - if the key is not found or it is the primary key

delete

public AndroidKeysetManager delete(int keyId)
                            throws GeneralSecurityException

Deletes the key with keyId.

Throws:

GeneralSecurityException - if the key is not found or it is the primary key

destroy

public AndroidKeysetManager destroy(int keyId)
                             throws GeneralSecurityException

Destroys the key material associated with the keyId.

Throws:

GeneralSecurityException - if the key is not found or it is the primary key