Objets Key et Parameters

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