parquet/encryption/file_key_unwrapper.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 "arrow/util/concurrent_map.h"
0021 #include "arrow/util/secure_string.h"
0022
0023 #include "parquet/encryption/encryption.h"
0024 #include "parquet/encryption/file_system_key_material_store.h"
0025 #include "parquet/encryption/key_material.h"
0026 #include "parquet/encryption/key_toolkit.h"
0027 #include "parquet/encryption/key_toolkit_internal.h"
0028 #include "parquet/encryption/kms_client.h"
0029 #include "parquet/platform.h"
0030
0031 namespace parquet::encryption {
0032
0033 // This class will retrieve the key from "key metadata", following these steps:
0034 // 1. Parse "key metadata" (see structure in KeyMetadata class).
0035 // 2. Retrieve "key material" which can be stored inside or outside "key metadata".
0036 // 3. Unwrap the "data encryption key" from "key material". There are 2 modes:
0037 // 3.1. single wrapping: decrypt the wrapped "data encryption key" directly with "master
0038 // encryption key" 3.2. double wrapping: 2 steps: 3.2.1. "key encryption key" is decrypted
0039 // with "master encryption key" 3.2.2. "data encryption key" is decrypted with the above
0040 // "key encryption key"
0041 class PARQUET_EXPORT FileKeyUnwrapper : public DecryptionKeyRetriever {
0042  public:
0043   /// key_toolkit and kms_connection_config is to get KmsClient from cache or create
0044   /// KmsClient if it's not in the cache yet. cache_entry_lifetime_seconds is life time of
0045   /// KmsClient in the cache.
0046   /// If the file uses external key material then the Parquet file path and file
0047   /// system must be specified.
0048   FileKeyUnwrapper(std::shared_ptr<KeyToolkit> key_toolkit,
0049                    const KmsConnectionConfig& kms_connection_config,
0050                    double cache_lifetime_seconds, const std::string& file_path = "",
0051                    const std::shared_ptr<::arrow::fs::FileSystem>& file_system = NULLPTR);
0052
0053   /// Constructor overload that takes a raw pointer to the KeyToolkit
0054   FileKeyUnwrapper(KeyToolkit* key_toolkit,
0055                    const KmsConnectionConfig& kms_connection_config,
0056                    double cache_lifetime_seconds, const std::string& file_path = "",
0057                    const std::shared_ptr<::arrow::fs::FileSystem>& file_system = NULLPTR);
0058
0059   /// Constructor overload that takes a raw pointer to the KeyToolkit and
0060   /// accepts an existing key_material_store rather than using
0061   /// the file path and file system to create one when needed.
0062   FileKeyUnwrapper(KeyToolkit* key_toolkit,
0063                    const KmsConnectionConfig& kms_connection_config,
0064                    double cache_lifetime_seconds,
0065                    std::shared_ptr<FileKeyMaterialStore> key_material_store);
0066
0067   /// Get the data key from key metadata
0068   ::arrow::util::SecureString GetKey(const std::string& key_metadata_bytes) override;
0069
0070   /// Get the data key along with the master key id from key material
0071   KeyWithMasterId GetDataEncryptionKey(const KeyMaterial& key_material);
0072
0073  private:
0074   FileKeyUnwrapper(std::shared_ptr<KeyToolkit> key_toolkit_owner, KeyToolkit* key_toolkit,
0075                    const KmsConnectionConfig& kms_connection_config,
0076                    double cache_lifetime_seconds,
0077                    std::shared_ptr<FileKeyMaterialStore> key_material_store,
0078                    const std::string& file_path,
0079                    const std::shared_ptr<::arrow::fs::FileSystem>& file_system);
0080
0081   std::shared_ptr<KmsClient> GetKmsClientFromConfigOrKeyMaterial(
0082       const KeyMaterial& key_material);
0083
0084   /// A map of Key Encryption Key (KEK) ID -> KEK bytes, for the current token
0085   std::shared_ptr<::arrow::util::ConcurrentMap<std::string, ::arrow::util::SecureString>>
0086       kek_per_kek_id_;
0087   std::shared_ptr<KeyToolkit> key_toolkit_owner_;
0088   KeyToolkit* key_toolkit_;
0089   KmsConnectionConfig kms_connection_config_;
0090   const double cache_entry_lifetime_seconds_;
0091   std::shared_ptr<FileKeyMaterialStore> key_material_store_;
0092   const std::string file_path_;
0093   std::shared_ptr<::arrow::fs::FileSystem> file_system_;
0094 };
0095
0096 }  // namespace parquet::encryption