Step 7. Manage Your Keys

Each member uses cryptographic keys to endorse or sign a token. A key store handles saving and loading these keys using a crypto engine to implement the following methods:

  • Store a member's key pair
  • Look up a key by memberId and level
  • Look up a key by memberId and keyId
  • Return the list of member's keys
  • (optional) Keep track of the ID of the most recently active member
  • (optional) Retrieve the ID of the most recently active member (get)

When you add a member using the createMember method (Step 2), three key pairs are automatically created:

  1. low-level
  2. standard
  3. privileged

Each pair is comprised of a private and a public key. The three public keys are uploaded to the Token.io cloud; the private keys are placed into secure local storage.

Private keys are used to sign all requests made through the Member object, such as initiating requests for account access or payments, or changing a member profile. Token.io verifies each request using the public keys. Requests made directly from the Token.io client, such as to resolve an alias or retrieve a list of connected banks, are not signed and are therefore accessible by anyone.

Keys in the Token.io Cloud

The following methods control keys in the Token.io cloud only:

  • Adding keys
    • single key – call Member.approveKey
    • multiple keys – call Member.approveKeys
  • Removing Keys
    • single key – call Member.removeKey
    • multiple keys – call Member.removeKeys

Caution: Removed keys are no longer valid and cannot be used to sign requests.

Here's how to generate, approve, and remove keys:

Key lowKey = crypto.generateKey(LOW);

member.approveKeyBlocking(lowKey);

 

Key standardKey = crypto.generateKey(STANDARD);

Key privilegedKey = crypto.generateKey(PRIVILEGED);

member.approveKeysBlocking(Arrays.asList(standardKey, privilegedKey));

 

member.removeKeyBlocking(lowKey.getId());

Call the member approveKey or approveKeys method to add one or multiple keys, respectively. Similarly, call the member removeKey or member removeKeys to remove previously uploaded keys. Just remember that removed keys can longer be used to sign requests.

Here are the relevant API references:

Keys Stored Locally

Use the IKeyStore class to configure where the client stores its member's private keys and pass it as a parameter to TokenClient.Builder.WithKeyStore().

The TokenClient class supports these basic built-in IKeyStore classes:

  • InMemoryKeysStore – keeps keys in memory; forgets on restart. Useful for units tests but not for persistent members.
  • UnsecuredFileSystemKeyStore – stores keys in a local file directory you specify as a constructor parameter.

You can define your own IKeyStore class if you don't want to use the one listed above.

Here are the relevant API references: