Objetos de chave e parâmetros

Na prática, a Tink fornece objetos Key para representar chaves e objetos Parameters para representar Parameters. Por exemplo, em Java, temos objetos AesGcmKey para representar chaves GCM do AES.

Nesta seção, explicamos como esses objetos são projetados em Java e como eles interagem.

Parameters objetos

Considere o AES GCM, um esquema de criptografia AEAD amplamente utilizado. A Tink fornece um objeto AesGcmParameters com as informações necessárias para criar uma AesGcmKey, que explicaremos mais tarde. A hierarquia de parâmetros em Java tem a seguinte aparência:

public abstract class Parameters {
  public abstract boolean hasIdRequirement();
}

public abstract class AeadParameters extends Parameters {}

public final class AesGcmParameters extends AeadParameters {
  /**
   * The Variant specified how ciphertexts are [tagged](/tink/design/keysets#tagging_ciphertexts).
   */
  public static final class Variant {...}
  /** A helper object to create new AesGcmParameters. */
  public static final class Builder {...}

  public int getKeySizeBytes() {...}
  public int getIvSizeBytes() {...}
  public int getTagSizeBytes() {...}

  public Variant getVariant() {...}

  public OutputPrefixType getOutputPrefixType() {...}
  public boolean equals(Object object) {...}
  public int hashCode() {...}
}

Conforme explicado na seção Conjuntos de chaves, marcação de textos criptografados, algumas chaves têm um requisito no código quando estão em um conjunto de chaves. Cada objeto Parameters tem um método hasIdRequirement que especifica se a chave criada por esse objeto Parameters terá ou não um ID obrigatório.

Em seguida, o objeto AesGcmParameters fornece os métodos getKeySizeBytes(), getIvSizeBytes() e getTagSizeBytes(). Eles retornam o comprimento da chave usada, o comprimento do IV usado e o comprimento da tag produzida, em bytes. Embora a Tink forneça algumas dessas funções para garantir a integridade, ela nem sempre permite a criação de Aeads para todas as opções. Por exemplo, atualmente, apenas IVs de 12 bytes são compatíveis com o GCM do AES.

O objeto AesGcmParameters também fornece substituições para os métodos definidos anteriormente, além dos métodos padrão do Java equals e hashCode, que são considerados uma prática recomendada.

Por fim, ela fornece métodos estáticos para criar novos objetos AeadParameters. Eles validam as entradas, ou seja, verificam se o tamanho é 16, 24 ou 32.

Objetos principais

A Tink também tem uma hierarquia de chaves. Ainda usando o exemplo do AES GCM, o exemplo fica assim:

public abstract class Key {
  public abstract Parameters getParameters();
  public abstract @Nullable Integer getIdRequirementOrNull();
  public abstract boolean equalsKey(Key other);
}

public abstract class AeadKey extends Key {
  public abstract AeadParameters getParameters();
  public abstract Bytes getOutputPrefix();
}

public final class AesGcmKey implements AeadKey {
  public SecretBytes getKeyBytes();
  public abstract Bytes getOutputPrefix();
  public AesGcmParameters getParameters();
  public @Nullable Integer getIdRequirementOrNull();
  public boolean equalsKey(Key object);
}

O método getIdRequirementOrNull retorna o ID que essa chave precisa ter, ou null se não houver um requisito. Esse requisito na chave vem do fato de que, em alguns casos, o Tink, em alguns casos, prefixa textos criptografados ou assinaturas com a string 0x01<id>. Consulte a seção sobre inclusão de tags de texto criptografado.

Isso sempre vai ser consistente com o resultado de getParameters().hasIdRequirement(), e os implementadores de novas classes de chave precisam garantir isso

As implementações de Key também precisam fornecer um método equalsKey para comparar chaves diferentes. Esse método geralmente é útil. Por exemplo, ao testar a derivação de chave, é importante garantir que a aplicação repetida da derivação gere o mesmo objeto chave. Além disso, talvez o KMS queira verificar se alguma das chaves que ele fornece para usuários diferentes é igual (o que acontece às vezes quando os usuários compartilham chaves e fazem upload delas para o mesmo KMS várias vezes). Não substituimos o método Java equals, porque isso exigiria a substituição de hashCode, e não há como implementar hashCode de uma forma segura compatível com equals sem fazer suposições não comprovadas.

Em seguida, exigimos um método getParameters(). Assim, os usuários recebem as informações originais sobre os parâmetros usados para criar a chave.

Por fim, AesGcmKey tem um método getKeyBytes que retorna o material bruto da chave. Esses métodos são muito comuns para classes de chaves: eles são específicos do tipo e fornecem acesso ao material da chave subjacente. Com eles, os usuários podem, por exemplo, implementar o primitivo representado pela chave ou serializar a chave para armazená-la em disco ou enviá-la pela rede. A chave é responsável por proteger o material dela contra acesso não autorizado. Por exemplo, SecretBytes requer um token de acesso para realmente fornecer o material (consulte Controle de acesso).

Chaves assimétricas

Para primitivas assimétricas, o Tink usa duas classes Key, uma para chaves privadas e outra para chaves públicas. Para os parâmetros, é mais conveniente usar a mesma classe, já que há apenas uma classe que pode ser usada para gerar as chaves.

O Tink também tem uma interface PrivateKey com a função extra getPublicKey().