1 // Copyright 2022 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 //////////////////////////////////////////////////////////////////////////////// 16 17 package com.google.crypto.tink; 18 19 import com.google.errorprone.annotations.Immutable; 20 import javax.annotation.Nullable; 21 22 /** 23 * Represents a cryptographic object. 24 * 25 * <p>In Tink, {@code Key} objects are objects which represent some cryptographic functions. For 26 * example, a {@code MacKey} represents the two functions {@code computeMac} and {@code verifyMac}. 27 * The function {@code computeMac} maps a byte sequence (possibly with additional randomness) to 28 * another byte sequence, called the tag. The function {@code verifyMac} verifies the tag. A 29 * subclass {@code HmacKey} then contains all the information one needs to properly compute an HMAC 30 * (including e.g. the hash function and tag length used). 31 * 32 * <p>Key objects are light weight, i.e., they should have almost no dependencies, except what is 33 * needed to <em>represent</em> the function. This allows key objects to be used in contexts where 34 * dependencies need to be kept at a minimum. 35 */ 36 @Immutable 37 public abstract class Key { 38 /** 39 * Returns a {@link Parameters} object containing all the information about the key which is not 40 * randomly chosen. 41 * 42 * <p>Implementations need to ensure that {@code getParameters().hasIdRequirement()} returns true 43 * if and only if {@code getIdRequirementOrNull} is non-null. 44 */ getParameters()45 public abstract Parameters getParameters(); 46 47 /** 48 * Returns null if this key has no id requirement, otherwise the required id. 49 * 50 * <p>Some keys, when they are in a keyset, are required to have a certain ID to work properly. 51 * This comes from the fact that Tink in some cases prefixes ciphertexts or signatures with the 52 * string {@code 0x01<id>}, where the ID is encoded in big endian (see the documentation of the 53 * key type for details), in which case the key requires a certain ID. 54 */ 55 @Nullable getIdRequirementOrNull()56 public abstract Integer getIdRequirementOrNull(); 57 58 /** 59 * Returns true if the key is guaranteed to be equal to {@code other}. 60 * 61 * <p>Implementations are required to do this in constant time. 62 * 63 * <p>Note: this is allowed to return false even if two keys are guaranteed to represent the same 64 * function, but are represented differently. For example, a key is allowed to internally store 65 * the number of zero-bytes used as padding when a large number is represented as a byte array, 66 * and use this in the comparison. 67 * 68 * <p>Note: Tink {@code Key} objects should typically not override {@code hashCode} (because it 69 * could risk leaking key material). Hence, they typically also should not override {@code 70 * equals}. 71 */ equalsKey(Key other)72 public abstract boolean equalsKey(Key other); 73 } 74