Objets Key et Parameters

<ph type="x-smartling-placeholder">

En pratique, Tink fournit des objets Key pour représenter des objets keys et Parameters pour représenter Parameters. Par exemple, en Java, nous avons des objets AesGcmKey à qui représentent des clés AES GCM.

Dans cette section, nous expliquons comment ces objets sont conçus en Java et comment ils d'interagir.

Objets Parameters

Prenons l'exemple d'AES GCM, un schéma de chiffrement AEAD très utilisé. Tink fournit à un objet AesGcmParameters les informations nécessaires pour créez une AesGcmKey. Nous y reviendrons plus tard. 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 chiffrés au format chiffré certaines clés ont une exigence sur leur ID, lorsqu'elles se trouvent dans une collection de clés. Toutes les L'objet Parameters comporte une méthode hasIdRequirement qui spécifie si le la clé créée par cet objet Parameters aura ou non un ID obligatoire.

L'objet AesGcmParameters fournit ensuite les méthodes getKeySizeBytes(), getIvSizeBytes() et getTagSizeBytes(). Ils renvoient les longueurs la clé utilisée, la longueur du vecteur d'initialisation utilisé et la longueur du tag produit, en octets. Si Tink fournit certaines de ces fonctions pour des raisons d'exhaustivité, ne permet pas toujours de créer des Aead pour chaque choix. Par exemple, actuellement seuls les IV de 12 octets sont compatibles avec AES GCM.

L'objet AesGcmParameters fournit également des forçages pour le précédent définies par l'utilisateur (ainsi que les méthodes standards Java equals et hashCode ce qui est considéré comme une bonne pratique).

Enfin, il fournit des méthodes statiques pour créer des objets AeadParameters. Elles valident les entrées, c'est-à-dire que la taille est de 16, 24, ou 32.

Objets Key

Tink a également une hiérarchie de clés. En reprenant notre exemple d'AES GCM, il semble comme ceci:

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 dont cette clé doit avoir ou null si aucune exigence n'est requise. Une telle exigence sur la clé réside dans le fait que, dans certains cas, préfixe les textes chiffrés ou les signatures avec la chaîne 0x01<id>, consultez la section sur le taggage de texte chiffré).

Cela sera toujours cohérent avec le résultat de getParameters().hasIdRequirement() et les responsables de la mise en œuvre les classes de clés doivent s'en assurer.

Les implémentations de Key doivent également fournir une méthode equalsKey pour comparer différentes clés. Telles Une méthode est souvent utile. Par exemple, pour tester la dérivation d'une clé, de s'assurer que l'application répétée de la dérivation génère le même objet clé. De plus, un service de gestion des clés peut vérifier si l'une des clés qu'il fournies à différents utilisateurs sont égales (ce qui arrive parfois si les utilisateurs partagent et les importer plusieurs fois dans le même service de gestion des clés). Il convient de noter que nous ne remplacez pas la méthode Java equals, car cela nous obligerait à remplacer hashCode, et il n'existe aucun moyen d'implémenter hashCode de manière sécurisée parfaitement 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 des informations originales sur les paramètres utilisés pour créer la clé.

Enfin, AesGcmKey comporte 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és: elles sont spécifiques au type, et donnent accès au matériel de clé sous-jacent. Grâce à eux, les utilisateurs En principe, on peut, par exemple, implémenter la primitive représentée par la clé, ou sérialiser la clé pour la stocker sur le disque réseau. La clé elle-même est chargée de protéger le matériel de clé contre tout accès non autorisé. Par exemple, SecretBytes nécessite un jeton d'accès pour de fournir réellement le matériel (voir Contrôle des accès).

Clés asymétriques

Pour les primitives asymétriques, Tink utilise deux classes Key, l'une privée et l'autre. pour les clés publiques. Pour les paramètres, il est plus pratique d'utiliser (car une seule classe peut être utilisée pour générer les clés).

Tink dispose également d'une interface PrivateKey avec la commande la fonction getPublicKey().