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
```
 // One-time operations, should be done when the application is starting up.
 // Instead of repeatedly instantiating these crypto objects, instantiate them once and save for
 // later use.
 AndroidKeysetManager manager = AndroidKeysetManager.Builder()
    .withSharedPref(getApplicationContext(), "my_keyset_name", "my_pref_file_name")
    .withKeyTemplate(AesGcmHkfStreamingKeyManager.aes128GcmHkdf4KBTemplate())
    .build();
 StreamingAead streamingAead = manager.getKeysetHandle().getPrimitive(StreamingAead.class);
 
```
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 a keyset is found, but it is invalid, an IOException is thrown. The most common cause is when you decrypted a keyset with a wrong master key. In this case, an InvalidProtocolBufferException would be thrown. This is an irrecoverable error. You'd have to delete the keyset in Shared Preferences and all existing data encrypted with it.
- If a keyset is not found, and a KeyTemplate is set with AndroidKeysetManager.Builder.withKeyTemplate(com.google.crypto.tink.KeyTemplate), a fresh keyset is generated and is written to the my_keyset_name preference of the my_pref_file_name shared preferences file.
Key rotation

The resulting manager supports all operations supported by KeysetManager. For example to rotate the keyset, you can do:
```
 manager.rotate(AesGcmHkfStreamingKeyManager.aes128GcmHkdf1MBTemplate());
 
```
All operations that manipulate the keyset would automatically persist the new keyset to permanent storage.
Opportunistic keyset encryption with Android Keystore
Warning: because Android Keystore is unreliable, we strongly recommend disabling it by not setting any master key URI.
If a master key URI is set with AndroidKeysetManager.Builder.withMasterKeyUri(java.lang.String), the keyset may be encrypted with a key generated and stored in Android Keystore.
Android Keystore is only available on Android M or newer. Since it has been found that Android Keystore is unreliable on certain devices. Tink runs a self-test to detect such problems and disables Android Keystore accordingly, even if a master key URI is set. You can check whether Android Keystore is in use with isUsingKeystore().
When Android Keystore is disabled or otherwise unavailable, keysets will be stored in cleartext. This is not as bad as it sounds because keysets remain inaccessible to any other apps running on the same device. Moreover, as of July 2020, most active Android devices support either full-disk encryption or file-based encryption, which provide strong security protection against key theft even from attackers with physical access to the device. Android Keystore is only useful when you want to require user authentication for key use, which should be done if and only if you're absolutely sure that Android Keystore is working properly on your target devices.
The master key URI must start with android-keystore://. The remaining of the URI is used as a key ID when calling Android Keystore. If the master key doesn't exist, a fresh one is generated. If the master key already exists but is unusable, a KeyStoreException is thrown.
This class is thread-safe.
Since:

1.0.0

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class AndroidKeysetManager.Builder
A builder for AndroidKeysetManager.

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

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`AndroidKeysetManager`	`add(KeyTemplate keyTemplate)` Deprecated. This method takes a KeyTemplate proto, which is an internal implementation detail. Please use the add method that takes a `KeyTemplate` POJO.
`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()`
`boolean`	`isUsingKeystore()` Returns whether Android Keystore is being used to wrap Tink keysets.
`AndroidKeysetManager`	`promote(int keyId)` Deprecated. use `setPrimary`
`AndroidKeysetManager`	`rotate(KeyTemplate keyTemplate)` Deprecated. Please use `add(com.google.crypto.tink.proto.KeyTemplate)`. This method adds a new key and immediately promotes it to primary. However, when you do keyset rotation, you almost never want to make the new key primary, because old binaries don't know the new key yet.
`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
```
@CanIgnoreReturnValue
 @Deprecated
public AndroidKeysetManager rotate(KeyTemplate keyTemplate)
                                                               throws GeneralSecurityException
```
    Deprecated. Please use add(com.google.crypto.tink.proto.KeyTemplate). This method adds a new key and immediately promotes it to primary. However, when you do keyset rotation, you almost never want to make the new key primary, because old binaries don't know the new key yet.
    
    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
```
@CanIgnoreReturnValue
 @Deprecated
public AndroidKeysetManager add(KeyTemplate keyTemplate)
                                                            throws GeneralSecurityException
```
    Deprecated. This method takes a KeyTemplate proto, which is an internal implementation detail. Please use the add method that takes a KeyTemplate POJO.
    
    Generates and adds a fresh key generated using keyTemplate.
    
    Throws:
    
    GeneralSecurityException - if cannot find any KeyManager that can handle keyTemplate
  - add
```
@CanIgnoreReturnValue
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
```
@CanIgnoreReturnValue
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
```
@InlineMe(replacement="this.setPrimary(keyId)")
 @CanIgnoreReturnValue
 @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
```
@CanIgnoreReturnValue
public AndroidKeysetManager enable(int keyId)
                                                  throws GeneralSecurityException
```
    Enables the key with keyId.
    
    Throws:
    
    GeneralSecurityException - if the key is not found
  - disable
```
@CanIgnoreReturnValue
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
```
@CanIgnoreReturnValue
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
```
@CanIgnoreReturnValue
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
  - isUsingKeystore
```
public boolean isUsingKeystore()
```
    Returns whether Android Keystore is being used to wrap Tink keysets.

Class AndroidKeysetManager

Warning

Usage

Key rotation

Opportunistic keyset encryption with Android Keystore

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getKeysetHandle

rotate

add

add

setPrimary

promote

enable

disable

delete

destroy

isUsingKeystore