parquet/encryption/kms_client.h

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017
0018 #pragma once
0019
0020 #include <memory>
0021 #include <string>
0022 #include <unordered_map>
0023
0024 #include "arrow/util/mutex.h"
0025 #include "arrow/util/secure_string.h"
0026
0027 #include "parquet/exception.h"
0028 #include "parquet/platform.h"
0029
0030 namespace parquet::encryption {
0031
0032 /// This class wraps the key access token of a KMS server. If your token changes over
0033 /// time, you should keep the reference to the KeyAccessToken object and call Refresh()
0034 /// method every time you have a new token.
0035 class PARQUET_EXPORT KeyAccessToken {
0036  public:
0037   KeyAccessToken() = default;
0038
0039   explicit KeyAccessToken(const std::string value) : value_(value) {}
0040
0041   void Refresh(const std::string& new_value) {
0042     auto lock = mutex_.Lock();
0043     value_ = new_value;
0044   }
0045
0046   const std::string& value() const {
0047     auto lock = mutex_.Lock();
0048     return value_;
0049   }
0050
0051  private:
0052   std::string value_;
0053   mutable ::arrow::util::Mutex mutex_;
0054 };
0055
0056 struct PARQUET_EXPORT KmsConnectionConfig {
0057   std::string kms_instance_id;
0058   std::string kms_instance_url;
0059   /// If the access token is changed in the future, you should keep a reference to
0060   /// this object and call Refresh() on it whenever there is a new access token.
0061   std::shared_ptr<KeyAccessToken> refreshable_key_access_token;
0062   std::unordered_map<std::string, std::string> custom_kms_conf;
0063
0064   KmsConnectionConfig();
0065
0066   const std::string& key_access_token() const {
0067     if (refreshable_key_access_token == NULLPTR ||
0068         refreshable_key_access_token->value().empty()) {
0069       throw ParquetException("key access token is not set!");
0070     }
0071     return refreshable_key_access_token->value();
0072   }
0073
0074   void SetDefaultIfEmpty();
0075 };
0076
0077 class PARQUET_EXPORT KmsClient {
0078  public:
0079   static constexpr const char kKmsInstanceIdDefault[] = "DEFAULT";
0080   static constexpr const char kKmsInstanceUrlDefault[] = "DEFAULT";
0081   static constexpr const char kKeyAccessTokenDefault[] = "DEFAULT";
0082
0083   /// \brief Wraps a key.
0084   ///
0085   /// Encrypts it with the master key, encodes the result
0086   /// and potentially adds a KMS-specific metadata.
0087   virtual std::string WrapKey(const ::arrow::util::SecureString& key_bytes,
0088                               const std::string& master_key_identifier) = 0;
0089
0090   /// \brief Decrypts (unwraps) a key with the master key.
0091   virtual ::arrow::util::SecureString UnwrapKey(
0092       const std::string& wrapped_key, const std::string& master_key_identifier) = 0;
0093
0094   virtual ~KmsClient() {}
0095 };
0096
0097 }  // namespace parquet::encryption