[SPARK-35658][DOCS] Document Parquet encryption feature in Spark SQL
### What changes were proposed in this pull request? Spark 3.2.0 will use parquet-mr.1.12.0 version (or higher), that contains the column encryption feature which can be called from Spark SQL. The aim of this PR is to document the use of Parquet encryption in Spark. ### Why are the changes needed? - To provide information on how to use Parquet column encryption ### Does this PR introduce _any_ user-facing change? Yes, documents a new feature. ### How was this patch tested? bundle exec jekyll build Closes #32895 from ggershinsky/parquet-encryption-doc. Authored-by: Gidon Gershinsky <ggershinsky@apple.com> Signed-off-by: Sean Owen <srowen@gmail.com>
This commit is contained in:
Gidon Gershinsky
Sean Owen
parent
1a8c6755a1
commit
7ceefcace9
|
|
@ -252,6 +252,71 @@ REFRESH TABLE my_table;
|
|||
|
||||
</div>
|
||||
|
||||
## Columnar Encryption
|
||||
|
||||
|
||||
Since Spark 3.2, columnar encryption is supported for Parquet tables with Apache Parquet 1.12+.
|
||||
|
||||
Parquet uses the envelope encryption practice, where file parts are encrypted with "data encryption keys" (DEKs), and the DEKs are encrypted with "master encryption keys" (MEKs). The DEKs are randomly generated by Parquet for each encrypted file/column. The MEKs are generated, stored and managed in a Key Management Service (KMS) of user’s choice. The Parquet Maven [repository](https://repo1.maven.org/maven2/org/apache/parquet/parquet-hadoop/1.12.0/) has a jar with a mock KMS implementation that allows to run column encryption and decryption using a spark-shell only, without deploying a KMS server (download the `parquet-hadoop-tests.jar` file and place it in the Spark `jars` folder):
|
||||
|
||||
<div data-lang="scala" markdown="1">
|
||||
{% highlight scala %}
|
||||
|
||||
sc.hadoopConfiguration.set("parquet.encryption.kms.client.class" ,
|
||||
"org.apache.parquet.crypto.keytools.mocks.InMemoryKMS")
|
||||
|
||||
// Explicit master keys (base64 encoded) - required only for mock InMemoryKMS
|
||||
sc.hadoopConfiguration.set("parquet.encryption.key.list" ,
|
||||
"keyA:AAECAwQFBgcICQoLDA0ODw== , keyB:AAECAAECAAECAAECAAECAA==")
|
||||
|
||||
// Activate Parquet encryption, driven by Hadoop properties
|
||||
sc.hadoopConfiguration.set("parquet.crypto.factory.class" ,
|
||||
"org.apache.parquet.crypto.keytools.PropertiesDrivenCryptoFactory")
|
||||
|
||||
// Write encrypted dataframe files.
|
||||
// Column "square" will be protected with master key "keyA".
|
||||
// Parquet file footers will be protected with master key "keyB"
|
||||
squaresDF.write.
|
||||
option("parquet.encryption.column.keys" , "keyA:square").
|
||||
option("parquet.encryption.footer.key" , "keyB").
|
||||
parquet("/path/to/table.parquet.encrypted")
|
||||
|
||||
// Read encrypted dataframe files
|
||||
val df2 = spark.read.parquet("/path/to/table.parquet.encrypted")
|
||||
|
||||
{% endhighlight %}
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
#### KMS Client
|
||||
|
||||
The InMemoryKMS class is provided only for illustration and simple demonstration of Parquet encryption functionality. **It should not be used in a real deployment**. The master encryption keys must be kept and managed in a production-grade KMS system, deployed in user's organization. Rollout of Spark with Parquet encryption requires implementation of a client class for the KMS server. Parquet provides a plug-in [interface](https://github.com/apache/parquet-mr/blob/apache-parquet-1.12.0/parquet-hadoop/src/main/java/org/apache/parquet/crypto/keytools/KmsClient.java) for development of such classes,
|
||||
|
||||
<div data-lang="java" markdown="1">
|
||||
{% highlight java %}
|
||||
|
||||
public interface KmsClient {
|
||||
// Wraps a key - encrypts it with the master key.
|
||||
public String wrapKey(byte[] keyBytes, String masterKeyIdentifier);
|
||||
|
||||
// Decrypts (unwraps) a key with the master key.
|
||||
public byte[] unwrapKey(String wrappedKey, String masterKeyIdentifier);
|
||||
|
||||
// Use of initialization parameters is optional.
|
||||
public void initialize(Configuration configuration, String kmsInstanceID,
|
||||
String kmsInstanceURL, String accessToken);
|
||||
}
|
||||
|
||||
{% endhighlight %}
|
||||
|
||||
</div>
|
||||
|
||||
An [example](https://github.com/apache/parquet-mr/blob/master/parquet-hadoop/src/test/java/org/apache/parquet/crypto/keytools/samples/VaultClient.java) of such class for an open source [KMS](https://www.vaultproject.io/api/secret/transit) can be found in the parquet-mr repository. The production KMS client should be designed in cooperation with organization's security administrators, and built by developers with an experience in access control management. Once such class is created, it can be passed to applications via the `parquet.encryption.kms.client.class` parameter and leveraged by general Spark users as shown in the encrypted dataframe write/read sample above.
|
||||
|
||||
Note: By default, Parquet implements a "double envelope encryption" mode, that minimizes the interaction of Spark executors with a KMS server. In this mode, the DEKs are encrypted with "key encryption keys" (KEKs, randomly generated by Parquet). The KEKs are encrypted with MEKs in KMS; the result and the KEK itself are cached in Spark executor memory. Users interested in regular envelope encryption, can switch to it by setting the `parquet.encryption.double.wrapping` parameter to `false`. For more details on Parquet encryption parameters, visit the parquet-hadoop configuration [page](https://github.com/apache/parquet-mr/blob/master/parquet-hadoop/README.md#class-propertiesdrivencryptofactory).
|
||||
|
||||
|
||||
## Data Source Option
|
||||
|
||||
Data source options of Parquet can be set via:
|
||||
|
|
|
|||
Loading…
Reference in a new issue