En pratique, Tink fournit des objets Key
pour représenter des clés et des objets Parameters
pour représenter Parameters
.
Par exemple, en Java, des objets AesGcmKey
représentent les clés AES GCM.
Dans cette section, nous expliquons comment ces objets sont conçus en Java et comment ils interagissent.
Objets Parameters
Prenons l’exemple d’AES GCM, un schéma de chiffrement AEAD très utilisé.
Tink fournit un objet AesGcmParameters
avec les informations nécessaires à la création d'un AesGcmKey
, comme expliqué ultérieurement.
La hiérarchie des paramètres en Java se présente comme suit:
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() {...}
}
Comme expliqué dans la section Ensembles de clés, ajout de tags aux textes chiffrés, l'ID de certaines clés est obligatoire lorsqu'elles se trouvent dans une collection de clés. Chaque objet Parameters
possède une méthode hasIdRequirement
qui spécifie si la clé créée par cet objet Parameters
possède ou non un tel identifiant.
L'objet AesGcmParameters
fournit ensuite les méthodes getKeySizeBytes()
, getIvSizeBytes()
et getTagSizeBytes()
. Celles-ci renvoient les longueurs de la clé utilisée, la longueur du vecteur d'initialisation utilisé et la longueur du tag produit, en octets. Bien que Tink fournisse certaines de ces fonctions par souci d'exhaustivité, il ne permet pas toujours de créer des Aead
pour chaque choix. Par exemple, actuellement, seuls les vecteurs d'initialisation de 12 octets sont pris en charge pour AES GCM.
L'objet AesGcmParameters
fournit également des forçages pour les méthodes définies précédemment (et les méthodes Java standards equals
et hashCode
, ce qui est considéré comme une bonne pratique).
Enfin, elle fournit des méthodes statiques pour créer des objets AeadParameters
.
Ils valident les entrées, c'est-à-dire que la taille correspond à l'une des tailles 16, 24 ou 32.
Objets clés
Tink dispose également d'une hiérarchie de clés. En reprenant notre exemple d'AES GCM, il se présente comme suit:
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);
}
La méthode getIdRequirementOrNull
renvoie l'ID que cette clé doit avoir, ou null
si cela n'est pas obligatoire.
(Une telle exigence liée à la clé réside dans le fait que Tink ajoute dans certains cas le préfixe du texte chiffré ou des signatures avec la chaîne 0x01<id>
. Consultez la section sur l'ajout de tags à du texte chiffré.)
Cela sera toujours cohérent avec le résultat de getParameters().hasIdRequirement()
, et les développeurs de nouvelles classes de clé doivent s'en assurer.
Les implémentations de Key
doivent également fournir une méthode equalsKey
pour comparer différentes clés. Une telle méthode est souvent utile. Par exemple, lors du test de la dérivation de clé, il faut s'assurer que l'application répétée de la dérivation génère le même objet de clé. En outre, un service de gestion des clés peut vouloir vérifier si certaines des clés qu'il fournit à différents utilisateurs sont identiques (ce qui se produit parfois si les utilisateurs partagent des clés et les importent plusieurs fois dans le même service de gestion des clés). Il est à noter que nous ne forçons pas la méthode Java equals
, car cela nous obligerait à remplacer hashCode
. De plus, il n'existe aucun moyen d'implémenter hashCode
de manière sécurisée et compatible avec equals
sans faire d'hypothèses non prouvées.
Nous avons ensuite besoin d'une méthode getParameters()
. Cela permet aux utilisateurs d'obtenir les informations d'origine sur les paramètres utilisés pour créer la clé.
Enfin, AesGcmKey
dispose d'une méthode getKeyBytes
qui renvoie le matériel brut de la clé.
Ces méthodes sont très courantes pour les classes de clé: elles sont spécifiques au type et donnent accès au matériel de clé sous-jacent. En principe, ces instances permettent aux utilisateurs d'implémenter la primitive représentée par la clé, ou de sérialiser la clé afin de la stocker sur le disque ou de l'envoyer sur le réseau. La clé elle-même est responsable de la protection du matériel de la clé contre les accès non autorisés. Par exemple, SecretBytes
nécessite un jeton d'accès pour fournir le contenu (voir Contrôle des accès).
Clés asymétriques
Pour les primitives asymétriques, Tink utilise deux classes Key, l'une pour les clés privées et l'autre pour les clés publiques. Pour les paramètres, il est plus pratique d'utiliser la même classe, car il n'existe qu'une seule classe pouvant être utilisée pour générer les clés.
Tink dispose également d'une interface PrivateKey
avec la fonction supplémentaire getPublicKey()
.