Package com.google.crypto.tink

Class KeysetHandle.Builder

java.lang.Object

com.google.crypto.tink.KeysetHandle.Builder

Enclosing class:

KeysetHandle

public static final class KeysetHandle.Builder
extends java.lang.Object

Used to create new KeysetHandle objects.

A builder can be used to create a new KeysetHandle object. To create a builder with an empty keyset, one calls KeysetHandle.newBuilder();. To create a builder from an existing keyset, one calls KeysetHandle.newBuilder(keyset);.

To add a new key to a Builder, one calls addEntry(com.google.crypto.tink.KeysetHandle.Builder.Entry) with a KeysetEntry object. Such objects can be created

• From a named Parameters with KeysetHandle.generateEntryFromParametersName(java.lang.String),
• From a Parameters object, with KeysetHandle.generateEntryFromParameters(com.google.crypto.tink.Parameters),
• By importing an existing key, with KeysetHandle.importKey(com.google.crypto.tink.Key)

All these functions return a KeysetBuilder.Entry. It is necessary to assign an ID to a new entry by calling one of KeysetHandle.Builder.Entry.withFixedId(int) or KeysetHandle.Builder.Entry.withRandomId(). The exception is when an existing key which has an id requirement is imported (in which case the required ID is used).

It is possible to set the status of an entry by calling KeysetHandle.Builder.Entry.setStatus(com.google.crypto.tink.KeyStatus). The Status defaults to ENABLED.

It is possible to set whether an entry is the primary by calling KeysetHandle.Builder.Entry.makePrimary(). The user must ensure that once build() is called, a primary has been set.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	KeysetHandle.Builder.Entry	One entry, representing a single key, in a Keyset.Builder.

Constructor Summary

Constructors

Constructor	Description
Builder()

Method Summary

Modifier and Type	Method	Description
<T extends Annotations> KeysetHandle.Builder	addAnnotations(java.lang.Class<T> clazz, T annotations)	Adds some annotations to the keyset.
KeysetHandle.Builder	addEntry(KeysetHandle.Builder.Entry entry)	Adds an entry to a keyset
KeysetHandle	build()	Creates a new KeysetHandle.
KeysetHandle.Builder	deleteAt(int i)	Deletes the entry at index i.
KeysetHandle.Builder.Entry	getAt(int i)	Returns the entry at index i, 0 <= i < size().
KeysetHandle.Builder.Entry	removeAt(int i)	Deprecated. Use deleteAt(int) or getAt(int) instead.
int	size()	Returns the number of entries in this builder.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder()

Method Detail

addEntry

@CanIgnoreReturnValue
public KeysetHandle.Builder addEntry(KeysetHandle.Builder.Entry entry)

Adds an entry to a keyset

addAnnotations

@CanIgnoreReturnValue
public <T extends Annotations> KeysetHandle.Builder addAnnotations(java.lang.Class<T> clazz,
                                                                   T annotations)

Adds some annotations to the keyset.

The annotations object needs to be a subclass of Annotations, and it can later be retrieved from the keyset by calling KeysetHandle.getAnnotationsOrNull(java.lang.Class<T>). These annotations are ignored when creating a KeysetHandle.Builder from a Keyset, when comparing two keyset using equalsKeyset, or any other situation.

size

public int size()

Returns the number of entries in this builder.

getAt

public KeysetHandle.Builder.Entry getAt(int i)

Returns the entry at index i, 0 <= i < size().

Throws:

java.lang.IndexOutOfBoundsException - if i < 0 or i >= size();

removeAt

@CanIgnoreReturnValue
@Deprecated
public KeysetHandle.Builder.Entry removeAt(int i)

Deprecated.

Use deleteAt(int) or getAt(int) instead.

Removes the entry at index i and returns that entry. Shifts any subsequent entries to the left (subtracts one from their indices).

deleteAt

@CanIgnoreReturnValue
public KeysetHandle.Builder deleteAt(int i)

Deletes the entry at index i. Shifts any subsequent entries to the left (subtracts one from their indices).

build

public KeysetHandle build()
                   throws java.security.GeneralSecurityException

Creates a new KeysetHandle.

Throws a GeneralSecurityException if one of the following holds

• No entry was marked as primary
• There is an entry in which the ID has not been set and which did not have a predefined ID (see KeysetHandle.Builder.Entry).
• There is a withRandomId-entry which is followed by a non withRandomId-entry
• There are two entries with the same withFixedId (including pre-existing keys and imported keys which have an id requirement).
• build() was previously called for withRandomId entries, and hence calling build() twice would result in a keyset with different key IDs.
• The primary key is not enabled

Throws:

java.security.GeneralSecurityException