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 Aead
s 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()
.