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 #ifndef TINK_KEY_H_ 18 #define TINK_KEY_H_ 19 20 #include "absl/types/optional.h" 21 #include "tink/parameters.h" 22 23 namespace crypto { 24 namespace tink { 25 26 // Represents a cryptographic function. 27 // 28 // In Tink, `Key` objects represent cryptographic functions. For example, a 29 // `MacKey` represents the two functions: `computeMac()` and `verifyMac()`. 30 // The function `computeMac()` maps a byte sequence (possibly with additional 31 // randomness) to another byte sequence, called the tag. The function 32 // `verifyMac()` verifies the tag. A subclass `HmacKey` would contain all the 33 // information needed to properly compute an HMAC (e.g., including the hash 34 // function and tag length used). 35 // 36 // `Key` objects are lightweight, meaning they should have almost no 37 // dependencies except what is needed to represent the function. This allows 38 // `Key` objects to be used in contexts where dependencies need to be kept to a 39 // minimum. 40 class Key { 41 public: 42 // Returns a `Parameters` object containing all the information about the key 43 // that is not randomly chosen. 44 // 45 // Implementations should ensure that 'GetParameters().HasIdRequirement()` 46 // returns true if and only if `GetIdRequirement()` has a non-empty value. 47 virtual const Parameters& GetParameters() const = 0; 48 49 // Returns the required id if this key has an id requirement. Otherwise, 50 // returns an empty value if the key can have an arbitrary id. 51 // 52 // Some keys within a keyset are required to have a specific id to work 53 // properly. This comes from the fact that Tink in some cases prefixes 54 // ciphertexts or signatures with the string '0x01<id>', where the key id is 55 // encoded in big endian format (see the documentation of the key type for 56 // details). The key id provides a hint for which specific key was used to 57 // generate the ciphertext or signature. 58 virtual absl::optional<int> GetIdRequirement() const = 0; 59 60 // Returns true if all `Key` object fields have identical values, including 61 // the bytes for the raw key material. Otherwise, returns false. 62 // 63 // NOTE: Implementations must perform equality checks in constant time. 64 virtual bool operator==(const Key& other) const = 0; 65 bool operator!=(const Key& other) const { return !(*this == other); } 66 67 virtual ~Key() = default; 68 }; 69 70 } // namespace tink 71 } // namespace crypto 72 73 #endif // TINK_KEY_H_ 74