grpc 1.56.0 → 1.61.0

data/src/core/tsi/alts/crypt/gsec.h

@@ -25,9 +25,81 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+#include <memory>
+#include <vector>
+
+#include "absl/types/span.h"
+
 #include <grpc/event_engine/port.h>
 #include <grpc/grpc.h>
 
+namespace grpc_core {
+
+// Provides accessors to all information representing a gsec key. Owns all the
+// read-only or mutable buffers via the accessors. Mutable accessors such as
+// `aead_key()` or `kdf_buffer()` are NOT thread-safe.
+class GsecKeyInterface {
+ public:
+  virtual ~GsecKeyInterface() = default;
+
+  virtual bool IsRekey() = 0;
+  virtual absl::Span<const uint8_t> key() = 0;
+
+  // All the accessors below should only be called when IsRekey() is true.
+  virtual absl::Span<uint8_t> aead_key() = 0;
+  virtual absl::Span<const uint8_t> nonce_mask() = 0;
+  virtual absl::Span<uint8_t> kdf_counter() = 0;
+  virtual absl::Span<uint8_t> kdf_buffer() = 0;
+};
+
+// Interface for a GsecKey factory.
+class GsecKeyFactoryInterface {
+ public:
+  virtual ~GsecKeyFactoryInterface() = default;
+
+  // Creates identical and independent GsecKeyInterface objects.
+  virtual std::unique_ptr<GsecKeyInterface> Create() const = 0;
+};
+
+class GsecKeyFactory : public GsecKeyFactoryInterface {
+ public:
+  // The exact given parameters will be used to create GsecKey objects.
+  GsecKeyFactory(absl::Span<const uint8_t> key, bool is_rekey);
+  ~GsecKeyFactory() override = default;
+
+  std::unique_ptr<GsecKeyInterface> Create() const override;
+
+ private:
+  std::vector<uint8_t> key_;
+  bool is_rekey_;
+};
+
+class GsecKey : public GsecKeyInterface {
+ public:
+  // If `is_rekey` is false, the given key will be copied as the symmetric key.
+  // Otherwise, part of the given key is copied as the KDF key and another part
+  // is copied as the nonce mask.
+  GsecKey(absl::Span<const uint8_t> key, bool is_rekey);
+  ~GsecKey() override = default;
+
+  bool IsRekey() override;
+  absl::Span<const uint8_t> key() override;
+  absl::Span<uint8_t> aead_key() override;
+  absl::Span<const uint8_t> nonce_mask() override;
+  absl::Span<uint8_t> kdf_counter() override;
+  absl::Span<uint8_t> kdf_buffer() override;
+
+ private:
+  bool is_rekey_;
+  std::vector<uint8_t> key_;
+  std::vector<uint8_t> aead_key_;
+  std::vector<uint8_t> kdf_buffer_;
+  std::vector<uint8_t> nonce_mask_;
+  std::vector<uint8_t> kdf_counter_;
+};
+
+}  // namespace grpc_core
+
 #ifndef _STRUCT_IOVEC
 #if !defined(GRPC_EVENT_ENGINE_POSIX)
 struct iovec {
@@ -37,11 +109,11 @@ struct iovec {
 #endif  // GRPC_EVENT_ENGINE_POSIX
 #endif  // _STRUCT_IOVEC
 
-///
-/// A gsec interface for AEAD encryption schemes. The API is thread-compatible.
-/// Each implementation of this interface should specify supported values for
-/// key, nonce, and tag lengths.
-///
+//
+// A gsec interface for AEAD encryption schemes. The API is thread-compatible.
+// Each implementation of this interface should specify supported values for
+// key, nonce, and tag lengths.
+//
 
 // Key, nonce, and tag length in bytes
 const size_t kAesGcmNonceLength = 12;
@@ -55,92 +127,92 @@ const size_t kAes128GcmRekeyKeyLength = 44;
 
 typedef struct gsec_aead_crypter gsec_aead_crypter;
 
-///
-/// The gsec_aead_crypter is an API for different AEAD implementations such as
-/// AES_GCM. It encapsulates all AEAD-related operations in the format of
-/// V-table that stores pointers to functions implementing those operations.
-/// It also provides helper functions to wrap each of those function pointers.
-///
-/// A typical usage of this object would be:
-///
-///------------------------------------------------------------------------------
-///// Declare a gsec_aead_crypter object, and create and assign an instance
-///// of specific AEAD implementation e.g., AES_GCM to it. We assume both
-///// key and nonce contain cryptographically secure random bytes, and the key
-///// can be derived from an upper-layer application.
-/// gsec_aead_crypter* crypter;
-/// char* error_in_creation;
-///// User can populate the message with any 100 bytes data.
-/// uint8_t* message = gpr_malloc(100);
-/// grpc_status_code creation_status = gsec_aes_gcm_aead_crypter_create(key,
-///                                                     kAes128GcmKeyLength,
-///                                                     kAesGcmNonceLength,
-///                                                     kAesGcmTagLength,
-///                                                     &crypter,
-///                                                     false,
-///                                                     0
-///                                                     &error_in_creation);
-///
-/// if (creation_status == GRPC_STATUS_OK) {
-///   // Allocate a correct amount of memory to hold a ciphertext.
-///   size_t clength = 0;
-///   gsec_aead_crypter_max_ciphertext_and_tag_length(crypter, 100, &clength,
-///                                                   nullptr);
-///   uint8_t* ciphertext = gpr_malloc(clength);
-///
-///   // Perform encryption
-///   size_t num_encrypted_bytes = 0;
-///   char* error_in_encryption = nullptr;
-///   grpc_status_code status = gsec_aead_crypter_encrypt(crypter, nonce,
-///                                                       kAesGcmNonceLength,
-///                                                       nullptr, 0, message,
-///                                                       100, ciphertext,
-///                                                       clength,
-///                                                       &num_encrypted_bytes,
-///                                                       &error_in_encryption);
-/// if (status == GRPC_STATUS_OK) {
-///      // Allocate a correct amount of memory to hold a plaintext.
-///      size_t plength = 0;
-///      gsec_aead_crypter_max_plaintext_length(crypter, num_encrypted_bytes,
-///                                             &plength, nullptr);
-///      uint8_t* plaintext = gpr_malloc(plength);
-///
-///      // Perform decryption.
-///      size_t num_decrypted_bytes = 0;
-///      char* error_in_decryption = nullptr;
-///      status = gsec_aead_crypter_decrypt(crypter, nonce,
-///                                         kAesGcmNonceLength, nullptr, 0,
-///                                         ciphertext, num_encrypted_bytes,
-///                                         plaintext, plength,
-///                                         &num_decrypted_bytes,
-///                                         &error_in_decryption);
-///      if (status != GRPC_STATUS_OK) {
-///        fprintf(stderr, "AEAD decrypt operation failed with error code:"
-///                        "%d, message: %s\n", status, error_in_decryption);
-///      }
-///      ...
-///      gpr_free(plaintext);
-///      gpr_free(error_in_decryption);
-///   } else {
-///       fprintf(stderr, "AEAD encrypt operation failed with error code:"
-///                       "%d, message: %s\n", status, error_in_encryption);
-///   }
-///   ...
-///   gpr_free(ciphertext);
-///   gpr_free(error_in_encryption);
-///} else {
-///  fprintf(stderr, "Creation of AEAD crypter instance failed with error code:"
-///                  "%d, message: %s\n", creation_status, error_in_creation);
-///}
-///
-///// Destruct AEAD crypter instance.
-/// if (creation_status == GRPC_STATUS_OK) {
-///  gsec_aead_crypter_destroy(crypter);
-///}
-/// gpr_free(error_in_creation);
-/// gpr_free(message);
-///-----------------------------------------------------------------------------
-///
+//
+// The gsec_aead_crypter is an API for different AEAD implementations such as
+// AES_GCM. It encapsulates all AEAD-related operations in the format of
+// V-table that stores pointers to functions implementing those operations.
+// It also provides helper functions to wrap each of those function pointers.
+//
+// A typical usage of this object would be:
+//
+//------------------------------------------------------------------------------
+//// Declare a gsec_aead_crypter object, and create and assign an instance
+//// of specific AEAD implementation e.g., AES_GCM to it. We assume both
+//// key and nonce contain cryptographically secure random bytes, and the key
+//// can be derived from an upper-layer application.
+// gsec_aead_crypter* crypter;
+// char* error_in_creation;
+//// User can populate the message with any 100 bytes data.
+// uint8_t* message = gpr_malloc(100);
+// grpc_status_code creation_status = gsec_aes_gcm_aead_crypter_create(key,
+//                                                     kAes128GcmKeyLength,
+//                                                     kAesGcmNonceLength,
+//                                                     kAesGcmTagLength,
+//                                                     &crypter,
+//                                                     false,
+//                                                     0
+//                                                     &error_in_creation);
+//
+// if (creation_status == GRPC_STATUS_OK) {
+//   // Allocate a correct amount of memory to hold a ciphertext.
+//   size_t clength = 0;
+//   gsec_aead_crypter_max_ciphertext_and_tag_length(crypter, 100, &clength,
+//                                                   nullptr);
+//   uint8_t* ciphertext = gpr_malloc(clength);
+//
+//   // Perform encryption
+//   size_t num_encrypted_bytes = 0;
+//   char* error_in_encryption = nullptr;
+//   grpc_status_code status = gsec_aead_crypter_encrypt(crypter, nonce,
+//                                                       kAesGcmNonceLength,
+//                                                       nullptr, 0, message,
+//                                                       100, ciphertext,
+//                                                       clength,
+//                                                       &num_encrypted_bytes,
+//                                                       &error_in_encryption);
+// if (status == GRPC_STATUS_OK) {
+//      // Allocate a correct amount of memory to hold a plaintext.
+//      size_t plength = 0;
+//      gsec_aead_crypter_max_plaintext_length(crypter, num_encrypted_bytes,
+//                                             &plength, nullptr);
+//      uint8_t* plaintext = gpr_malloc(plength);
+//
+//      // Perform decryption.
+//      size_t num_decrypted_bytes = 0;
+//      char* error_in_decryption = nullptr;
+//      status = gsec_aead_crypter_decrypt(crypter, nonce,
+//                                         kAesGcmNonceLength, nullptr, 0,
+//                                         ciphertext, num_encrypted_bytes,
+//                                         plaintext, plength,
+//                                         &num_decrypted_bytes,
+//                                         &error_in_decryption);
+//      if (status != GRPC_STATUS_OK) {
+//        fprintf(stderr, "AEAD decrypt operation failed with error code:"
+//                        "%d, message: %s\n", status, error_in_decryption);
+//      }
+//      ...
+//      gpr_free(plaintext);
+//      gpr_free(error_in_decryption);
+//   } else {
+//       fprintf(stderr, "AEAD encrypt operation failed with error code:"
+//                       "%d, message: %s\n", status, error_in_encryption);
+//   }
+//   ...
+//   gpr_free(ciphertext);
+//   gpr_free(error_in_encryption);
+//} else {
+//  fprintf(stderr, "Creation of AEAD crypter instance failed with error code:"
+//                  "%d, message: %s\n", creation_status, error_in_creation);
+//}
+//
+//// Destruct AEAD crypter instance.
+// if (creation_status == GRPC_STATUS_OK) {
+//  gsec_aead_crypter_destroy(crypter);
+//}
+// gpr_free(error_in_creation);
+// gpr_free(message);
+//-----------------------------------------------------------------------------
+//
 
 // V-table for gsec AEAD operations
 typedef struct gsec_aead_crypter_vtable {
@@ -179,39 +251,39 @@ struct gsec_aead_crypter {
   const struct gsec_aead_crypter_vtable* vtable;
 };
 
-///
-/// This method performs an AEAD encrypt operation.
-///
-///- crypter: AEAD crypter instance.
-///- nonce: buffer containing a nonce with its size equal to nonce_length.
-///- nonce_length: size of nonce buffer, and must be equal to the value returned
-///  from method gsec_aead_crypter_nonce_length.
-///- aad: buffer containing data that needs to be authenticated but not
-///  encrypted with its size equal to aad_length.
-///- aad_length: size of aad buffer, which should be zero if the buffer is
-///  nullptr.
-///- plaintext: buffer containing data that needs to be both encrypted and
-///  authenticated with its size equal to plaintext_length.
-///- plaintext_length: size of plaintext buffer, which should be zero if
-///  plaintext is nullptr.
-///- ciphertext_and_tag: buffer that will contain ciphertext and tags the method
-///  produced. The buffer should not overlap the plaintext buffer, and pointers
-///  to those buffers should not be equal. Also if the ciphertext+tag buffer is
-///  nullptr, the plaintext_length should be zero.
-///- ciphertext_and_tag_length: size of ciphertext+tag buffer, which should be
-///  at least as long as the one returned from method
-///  gsec_aead_crypter_max_ciphertext_and_tag_length.
-///- bytes_written: the actual number of bytes written to the ciphertext+tag
-///  buffer. If bytes_written is nullptr, the plaintext_length should be zero.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of encryption, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
-///
+//
+// This method performs an AEAD encrypt operation.
+//
+//- crypter: AEAD crypter instance.
+//- nonce: buffer containing a nonce with its size equal to nonce_length.
+//- nonce_length: size of nonce buffer, and must be equal to the value returned
+//  from method gsec_aead_crypter_nonce_length.
+//- aad: buffer containing data that needs to be authenticated but not
+//  encrypted with its size equal to aad_length.
+//- aad_length: size of aad buffer, which should be zero if the buffer is
+//  nullptr.
+//- plaintext: buffer containing data that needs to be both encrypted and
+//  authenticated with its size equal to plaintext_length.
+//- plaintext_length: size of plaintext buffer, which should be zero if
+//  plaintext is nullptr.
+//- ciphertext_and_tag: buffer that will contain ciphertext and tags the method
+//  produced. The buffer should not overlap the plaintext buffer, and pointers
+//  to those buffers should not be equal. Also if the ciphertext+tag buffer is
+//  nullptr, the plaintext_length should be zero.
+//- ciphertext_and_tag_length: size of ciphertext+tag buffer, which should be
+//  at least as long as the one returned from method
+//  gsec_aead_crypter_max_ciphertext_and_tag_length.
+//- bytes_written: the actual number of bytes written to the ciphertext+tag
+//  buffer. If bytes_written is nullptr, the plaintext_length should be zero.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of encryption, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
+//
 grpc_status_code gsec_aead_crypter_encrypt(
     gsec_aead_crypter* crypter, const uint8_t* nonce, size_t nonce_length,
     const uint8_t* aad, size_t aad_length, const uint8_t* plaintext,
@@ -219,32 +291,32 @@ grpc_status_code gsec_aead_crypter_encrypt(
     size_t ciphertext_and_tag_length, size_t* bytes_written,
     char** error_details);
 
-///
-/// This method performs an AEAD encrypt operation.
-///
-///- crypter: AEAD crypter instance.
-///- nonce: buffer containing a nonce with its size equal to nonce_length.
-///- nonce_length: size of nonce buffer, and must be equal to the value returned
-///  from method gsec_aead_crypter_nonce_length.
-///- aad_vec: an iovec array containing data that needs to be authenticated but
-///  not encrypted.
-///- aad_vec_length: the array length of aad_vec.
-///- plaintext_vec: an iovec array containing data that needs to be both
-///  encrypted and authenticated.
-///- plaintext_vec_length: the array length of plaintext_vec.
-///- ciphertext_vec: an iovec containing a ciphertext buffer. The buffer should
-///  not overlap the plaintext buffer.
-///- ciphertext_bytes_written: the actual number of bytes written to
-///  ciphertext_vec.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of encryption, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
-///
+//
+// This method performs an AEAD encrypt operation.
+//
+//- crypter: AEAD crypter instance.
+//- nonce: buffer containing a nonce with its size equal to nonce_length.
+//- nonce_length: size of nonce buffer, and must be equal to the value returned
+//  from method gsec_aead_crypter_nonce_length.
+//- aad_vec: an iovec array containing data that needs to be authenticated but
+//  not encrypted.
+//- aad_vec_length: the array length of aad_vec.
+//- plaintext_vec: an iovec array containing data that needs to be both
+//  encrypted and authenticated.
+//- plaintext_vec_length: the array length of plaintext_vec.
+//- ciphertext_vec: an iovec containing a ciphertext buffer. The buffer should
+//  not overlap the plaintext buffer.
+//- ciphertext_bytes_written: the actual number of bytes written to
+//  ciphertext_vec.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of encryption, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
+//
 grpc_status_code gsec_aead_crypter_encrypt_iovec(
     gsec_aead_crypter* crypter, const uint8_t* nonce, size_t nonce_length,
     const struct iovec* aad_vec, size_t aad_vec_length,
@@ -252,67 +324,67 @@ grpc_status_code gsec_aead_crypter_encrypt_iovec(
     struct iovec ciphertext_vec, size_t* ciphertext_bytes_written,
     char** error_details);
 
-///
-/// This method performs an AEAD decrypt operation.
-///
-///- crypter: AEAD crypter instance.
-///- nonce: buffer containing a nonce with its size equal to nonce_length.
-///- nonce_length: size of nonce buffer, and must be equal to the value returned
-///  from method gsec_aead_crypter_nonce_length.
-///- aad: buffer containing data that needs to be authenticated only.
-///- aad_length: size of aad buffer, which should be zero if the buffer is
-///  nullptr.
-///- ciphertext_and_tag: buffer containing ciphertext and tag.
-///- ciphertext_and_tag_length: length of ciphertext and tag. It should be zero
-///  if any of plaintext, ciphertext_and_tag, or bytes_written is nullptr. Also,
-///  ciphertext_and_tag_length should be at least as large as the tag length set
-///  at AEAD crypter instance construction time.
-///- plaintext: buffer containing decrypted and authenticated data the method
-///  produced. The buffer should not overlap with the ciphertext+tag buffer, and
-///  pointers to those buffers should not be equal.
-///- plaintext_length: size of plaintext buffer, which should be at least as
-///  long as the one returned from gsec_aead_crypter_max_plaintext_length
-///  method.
-///- bytes_written: the actual number of bytes written to the plaintext
-///  buffer.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of decryption, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method performs an AEAD decrypt operation.
+//
+//- crypter: AEAD crypter instance.
+//- nonce: buffer containing a nonce with its size equal to nonce_length.
+//- nonce_length: size of nonce buffer, and must be equal to the value returned
+//  from method gsec_aead_crypter_nonce_length.
+//- aad: buffer containing data that needs to be authenticated only.
+//- aad_length: size of aad buffer, which should be zero if the buffer is
+//  nullptr.
+//- ciphertext_and_tag: buffer containing ciphertext and tag.
+//- ciphertext_and_tag_length: length of ciphertext and tag. It should be zero
+//  if any of plaintext, ciphertext_and_tag, or bytes_written is nullptr. Also,
+//  ciphertext_and_tag_length should be at least as large as the tag length set
+//  at AEAD crypter instance construction time.
+//- plaintext: buffer containing decrypted and authenticated data the method
+//  produced. The buffer should not overlap with the ciphertext+tag buffer, and
+//  pointers to those buffers should not be equal.
+//- plaintext_length: size of plaintext buffer, which should be at least as
+//  long as the one returned from gsec_aead_crypter_max_plaintext_length
+//  method.
+//- bytes_written: the actual number of bytes written to the plaintext
+//  buffer.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of decryption, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_decrypt(
     gsec_aead_crypter* crypter, const uint8_t* nonce, size_t nonce_length,
     const uint8_t* aad, size_t aad_length, const uint8_t* ciphertext_and_tag,
     size_t ciphertext_and_tag_length, uint8_t* plaintext,
     size_t plaintext_length, size_t* bytes_written, char** error_details);
 
-///
-/// This method performs an AEAD decrypt operation.
-///
-///- crypter: AEAD crypter instance.
-///- nonce: buffer containing a nonce with its size equal to nonce_length.
-///- nonce_length: size of nonce buffer, and must be equal to the value returned
-///  from method gsec_aead_crypter_nonce_length.
-///- aad_vec: an iovec array containing data that needs to be authenticated but
-///  not encrypted.
-///- aad_vec_length: the array length of aad_vec.
-///- ciphertext_vec: an iovec array containing the ciphertext and tag.
-///- ciphertext_vec_length: the array length of ciphertext_vec.
-///- plaintext_vec: an iovec containing a plaintext buffer. The buffer should
-///  not overlap the ciphertext buffer.
-///- plaintext_bytes_written: the actual number of bytes written to
-///  plaintext_vec.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of decryption, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method performs an AEAD decrypt operation.
+//
+//- crypter: AEAD crypter instance.
+//- nonce: buffer containing a nonce with its size equal to nonce_length.
+//- nonce_length: size of nonce buffer, and must be equal to the value returned
+//  from method gsec_aead_crypter_nonce_length.
+//- aad_vec: an iovec array containing data that needs to be authenticated but
+//  not encrypted.
+//- aad_vec_length: the array length of aad_vec.
+//- ciphertext_vec: an iovec array containing the ciphertext and tag.
+//- ciphertext_vec_length: the array length of ciphertext_vec.
+//- plaintext_vec: an iovec containing a plaintext buffer. The buffer should
+//  not overlap the ciphertext buffer.
+//- plaintext_bytes_written: the actual number of bytes written to
+//  plaintext_vec.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of decryption, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_decrypt_iovec(
     gsec_aead_crypter* crypter, const uint8_t* nonce, size_t nonce_length,
     const struct iovec* aad_vec, size_t aad_vec_length,
@@ -320,140 +392,136 @@ grpc_status_code gsec_aead_crypter_decrypt_iovec(
     struct iovec plaintext_vec, size_t* plaintext_bytes_written,
     char** error_details);
 
-///
-/// This method computes the size of ciphertext+tag buffer that must be passed
-/// to gsec_aead_crypter_encrypt function to ensure correct encryption of a
-/// plaintext. The actual size of ciphertext+tag written to the buffer could be
-/// smaller.
-///
-///- crypter: AEAD crypter instance.
-///- plaintext_length: length of plaintext.
-///- max_ciphertext_and_tag_length_to_return: the size of ciphertext+tag buffer
-///  the method returns.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method computes the size of ciphertext+tag buffer that must be passed
+// to gsec_aead_crypter_encrypt function to ensure correct encryption of a
+// plaintext. The actual size of ciphertext+tag written to the buffer could be
+// smaller.
+//
+//- crypter: AEAD crypter instance.
+//- plaintext_length: length of plaintext.
+//- max_ciphertext_and_tag_length_to_return: the size of ciphertext+tag buffer
+//  the method returns.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_max_ciphertext_and_tag_length(
     const gsec_aead_crypter* crypter, size_t plaintext_length,
     size_t* max_ciphertext_and_tag_length_to_return, char** error_details);
 
-///
-/// This method computes the size of plaintext buffer that must be passed to
-/// gsec_aead_crypter_decrypt function to ensure correct decryption of a
-/// ciphertext. The actual size of plaintext written to the buffer could be
-/// smaller.
-///
-///- crypter: AEAD crypter instance.
-///- ciphertext_and_tag_length: length of ciphertext and tag.
-///- max_plaintext_length_to_return: the size of plaintext buffer the method
-///  returns.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method computes the size of plaintext buffer that must be passed to
+// gsec_aead_crypter_decrypt function to ensure correct decryption of a
+// ciphertext. The actual size of plaintext written to the buffer could be
+// smaller.
+//
+//- crypter: AEAD crypter instance.
+//- ciphertext_and_tag_length: length of ciphertext and tag.
+//- max_plaintext_length_to_return: the size of plaintext buffer the method
+//  returns.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_max_plaintext_length(
     const gsec_aead_crypter* crypter, size_t ciphertext_and_tag_length,
     size_t* max_plaintext_length_to_return, char** error_details);
 
-///
-/// This method returns a valid size of nonce array used at the construction of
-/// AEAD crypter instance. It is also the size that should be passed to encrypt
-/// and decrypt methods executed on the instance.
-///
-///- crypter: AEAD crypter instance.
-///- nonce_length_to_return: the length of nonce array the method returns.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method returns a valid size of nonce array used at the construction of
+// AEAD crypter instance. It is also the size that should be passed to encrypt
+// and decrypt methods executed on the instance.
+//
+//- crypter: AEAD crypter instance.
+//- nonce_length_to_return: the length of nonce array the method returns.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_nonce_length(
     const gsec_aead_crypter* crypter, size_t* nonce_length_to_return,
     char** error_details);
 
-///
-/// This method returns a valid size of key array used at the construction of
-/// AEAD crypter instance. It is also the size that should be passed to encrypt
-/// and decrypt methods executed on the instance.
-///
-///- crypter: AEAD crypter instance.
-///- key_length_to_return: the length of key array the method returns.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method returns a valid size of key array used at the construction of
+// AEAD crypter instance. It is also the size that should be passed to encrypt
+// and decrypt methods executed on the instance.
+//
+//- crypter: AEAD crypter instance.
+//- key_length_to_return: the length of key array the method returns.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_key_length(const gsec_aead_crypter* crypter,
                                               size_t* key_length_to_return,
                                               char** error_details);
-///
-/// This method returns a valid size of tag array used at the construction of
-/// AEAD crypter instance. It is also the size that should be passed to encrypt
-/// and decrypt methods executed on the instance.
-///
-///- crypter: AEAD crypter instance.
-///- tag_length_to_return: the length of tag array the method returns.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
-/// it returns an error status code along with its details specified in
-/// error_details (if error_details is not nullptr).
-///
+//
+// This method returns a valid size of tag array used at the construction of
+// AEAD crypter instance. It is also the size that should be passed to encrypt
+// and decrypt methods executed on the instance.
+//
+//- crypter: AEAD crypter instance.
+//- tag_length_to_return: the length of tag array the method returns.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On the success of execution, the method returns GRPC_STATUS_OK. Otherwise,
+// it returns an error status code along with its details specified in
+// error_details (if error_details is not nullptr).
+//
 grpc_status_code gsec_aead_crypter_tag_length(const gsec_aead_crypter* crypter,
                                               size_t* tag_length_to_return,
                                               char** error_details);
 
-///
-/// This method destroys an AEAD crypter instance by de-allocating all of its
-/// occupied memory.
-///
-///- crypter: AEAD crypter instance that needs to be destroyed.
-///
+//
+// This method destroys an AEAD crypter instance by de-allocating all of its
+// occupied memory.
+//
+//- crypter: AEAD crypter instance that needs to be destroyed.
+//
 void gsec_aead_crypter_destroy(gsec_aead_crypter* crypter);
 
-///
-/// This method creates an AEAD crypter instance of AES-GCM encryption scheme
-/// which supports 16 and 32 bytes long keys, 12 and 16 bytes long nonces, and
-/// 16 bytes long tags. It should be noted that once the lengths of key, nonce,
-/// and tag are determined at construction time, they cannot be modified later.
-///
-///- key: buffer containing a key which is binded with AEAD crypter instance.
-///- key_length: length of a key in bytes, which should be 44 if rekeying is
-///  enabled and 16 or 32 otherwise.
-///- nonce_length: length of a nonce in bytes, which should be either 12 or 16.
-///- tag_length: length of a tag in bytes, which should be always 16.
-///- rekey: enable nonce-based rekeying and nonce-masking.
-///- crypter: address of AES_GCM crypter instance returned from the method.
-///- error_details: a buffer containing an error message if the method does not
-///  function correctly. It is legal to pass nullptr into error_details, and
-///  otherwise, the parameter should be freed with gpr_free.
-///
-/// On success of instance creation, it stores the address of instance at
-/// crypter. Otherwise, it returns an error status code together with its
-/// details specified in error_details.
-///
-grpc_status_code gsec_aes_gcm_aead_crypter_create(const uint8_t* key,
-                                                  size_t key_length,
-                                                  size_t nonce_length,
-                                                  size_t tag_length, bool rekey,
-                                                  gsec_aead_crypter** crypter,
-                                                  char** error_details);
+//
+// This method creates an AEAD crypter instance of AES-GCM encryption scheme
+// which supports 16 and 32 bytes long keys, 12 and 16 bytes long nonces, and
+// 16 bytes long tags. It should be noted that once the lengths of key, nonce,
+// and tag are determined at construction time, they cannot be modified later.
+//
+//- key: an instance of GsecKeyInterface, which will provide accessors to the
+//  key, aead_key, kdf_counter, nonce_mask as well as the buffer for aead_key
+//  derivation. It also tells whether rekey is supported.
+//- nonce_length: length of a nonce in bytes, which should be either 12 or 16.
+//- tag_length: length of a tag in bytes, which should be always 16.
+//- crypter: address of AES_GCM crypter instance returned from the method.
+//- error_details: a buffer containing an error message if the method does not
+//  function correctly. It is legal to pass nullptr into error_details, and
+//  otherwise, the parameter should be freed with gpr_free.
+//
+// On success of instance creation, it stores the address of instance at
+// crypter. Otherwise, it returns an error status code together with its
+// details specified in error_details.
+//
+grpc_status_code gsec_aes_gcm_aead_crypter_create(
+    std::unique_ptr<grpc_core::GsecKeyInterface> key, size_t nonce_length,
+    size_t tag_length, gsec_aead_crypter** crypter, char** error_details);
 
 #endif  // GRPC_SRC_CORE_TSI_ALTS_CRYPT_GSEC_H