cc/key.h

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////

#ifndef TINK_KEY_H_
#define TINK_KEY_H_

#include "absl/types/optional.h"
#include "tink/parameters.h"

namespace crypto {
namespace tink {

// Represents a cryptographic function.
//
// In Tink, `Key` objects represent cryptographic functions. For example, a
// `MacKey` represents the two functions: `computeMac()` and `verifyMac()`.
// The function `computeMac()` maps a byte sequence (possibly with additional
// randomness) to another byte sequence, called the tag. The function
// `verifyMac()` verifies the tag. A subclass `HmacKey` would contain all the
// information needed to properly compute an HMAC (e.g., including the hash
// function and tag length used).
//
// `Key` objects are lightweight, meaning they should have almost no
// dependencies except what is needed to represent the function. This allows
// `Key` objects to be used in contexts where dependencies need to be kept to a
// minimum.
class Key {
 public:
  // Returns a `Parameters` object containing all the information about the key
  // that is not randomly chosen.
  //
  // Implementations should ensure that 'GetParameters().HasIdRequirement()`
  // returns true if and only if `GetIdRequirement()` has a non-empty value.
  virtual const Parameters& GetParameters() const = 0;

  // Returns the required id if this key has an id requirement.  Otherwise,
  // returns an empty value if the key can have an arbitrary id.
  //
  // Some keys within a keyset are required to have a specific id to work
  // properly. This comes from the fact that Tink in some cases prefixes
  // ciphertexts or signatures with the string '0x01<id>', where the key id is
  // encoded in big endian format (see the documentation of the key type for
  // details). The key id provides a hint for which specific key was used to
  // generate the ciphertext or signature.
  virtual absl::optional<int> GetIdRequirement() const = 0;

  // Returns true if all `Key` object fields have identical values, including
  // the bytes for the raw key material.  Otherwise, returns false.
  //
  // NOTE: Implementations must perform equality checks in constant time.
  virtual bool operator==(const Key& other) const = 0;
  bool operator!=(const Key& other) const { return !(*this == other); }

  virtual ~Key() = default;
};

}  // namespace tink
}  // namespace crypto

#endif  // TINK_KEY_H_