1 // Copyright 2023 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_MAC_HMAC_PARAMETERS_H_ 18 #define TINK_MAC_HMAC_PARAMETERS_H_ 19 20 #include <memory> 21 22 #include "tink/mac/mac_parameters.h" 23 #include "tink/util/statusor.h" 24 25 namespace crypto { 26 namespace tink { 27 28 // Describes the parameters of an `HmacKey`. 29 class HmacParameters : public MacParameters { 30 public: 31 // Describes the details of a MAC computation. 32 // 33 // The usual HMAC key is used for variant `NO_PREFIX`. Other variants 34 // slightly change how the MAC is computed, or add a prefix to every 35 // computation depending on the key id. 36 enum class Variant : int { 37 // Prepends '0x01<big endian key id>' to tag. 38 kTink = 1, 39 // Prepends '0x00<big endian key id>' to tag. 40 kCrunchy = 2, 41 // Appends a 0-byte to input message BEFORE computing the tag, then 42 // prepends '0x00<big endian key id>' to tag. 43 kLegacy = 3, 44 // Does not prepend any prefix (i.e., keys must have no ID requirement). 45 kNoPrefix = 4, 46 // Added to guard from failures that may be caused by future expansions. 47 kDoNotUseInsteadUseDefaultWhenWritingSwitchStatements = 20, 48 }; 49 50 // Describes the hash algorithm used. 51 enum class HashType : int { 52 kSha1 = 1, 53 kSha224 = 2, 54 kSha256 = 3, 55 kSha384 = 4, 56 kSha512 = 5, 57 kDoNotUseInsteadUseDefaultWhenWritingSwitchStatements = 20, 58 }; 59 60 // Copyable and movable. 61 HmacParameters(const HmacParameters& other) = default; 62 HmacParameters& operator=(const HmacParameters& other) = default; 63 HmacParameters(HmacParameters&& other) = default; 64 HmacParameters& operator=(HmacParameters&& other) = default; 65 66 // Creates a new HMAC parameters object unless an error occurs. An error 67 // occurs under one of the following conditions: 68 // 1. `key_size_in_bytes` is a value smaller than 16 bytes 69 // 2. `cryptographic_tag_size_in_bytes` is either less than 10 bytes or 70 // greater than the maximum value accepted by the corresponding hash algorithm 71 static util::StatusOr<HmacParameters> Create( 72 int key_size_in_bytes, int cryptographic_tag_size_in_bytes, 73 HashType hash_type, Variant variant); 74 GetVariant()75 Variant GetVariant() const { return variant_; } 76 GetHashType()77 HashType GetHashType() const { return hash_type_; } 78 KeySizeInBytes()79 int KeySizeInBytes() const { return key_size_in_bytes_; } 80 81 // Returns the size of the tag, which is computed cryptographically from the 82 // message. Note that this may differ from the total size of the tag, as for 83 // some keys, Tink prefixes the tag with a key dependent output prefix. CryptographicTagSizeInBytes()84 int CryptographicTagSizeInBytes() const { 85 return cryptographic_tag_size_in_bytes_; 86 } 87 88 // Returns the size of the cryptographic tag plus the size of the prefix with 89 // which this key prefixes every cryptographic tag. 90 int TotalTagSizeInBytes() const; 91 HasIdRequirement()92 bool HasIdRequirement() const override { 93 return variant_ != Variant::kNoPrefix; 94 } 95 96 bool operator==(const Parameters& other) const override; 97 98 private: HmacParameters(int key_size_in_bytes,int cryptographic_tag_size_in_bytes,HashType hash_type,Variant variant)99 HmacParameters(int key_size_in_bytes, int cryptographic_tag_size_in_bytes, 100 HashType hash_type, Variant variant) 101 : key_size_in_bytes_(key_size_in_bytes), 102 cryptographic_tag_size_in_bytes_(cryptographic_tag_size_in_bytes), 103 hash_type_(hash_type), 104 variant_(variant) {} 105 106 int key_size_in_bytes_; 107 int cryptographic_tag_size_in_bytes_; 108 HashType hash_type_; 109 Variant variant_; 110 }; 111 112 } // namespace tink 113 } // namespace crypto 114 115 #endif // TINK_MAC_HMAC_PARAMETERS_H_ 116