Data Encryption

Data Encryption In Transit

JuiceFS encrypts data when transmitted across networks to protect against eavesdropping of network traffic by unauthorized users.

For metadata, JuiceFS client communicates with metadata server with TLS on top of TCP protocol.

For the data uploaded to object storage services, JuiceFS client will always use HTTPS except for the following scenarios:

• Uploading to AliCloud OSS using internal endpoint
• Uploading to UCloud UFile using internal endpoint
• Uploading to JDCloud JSS using internal endpoint

note

When group caching is enabled (mounted with option --cache-group), the data exchanged between clients is NOT encrypted. Please use this only in a secure environment.

Data Encryption At Rest

JuiceFS supports data encryption at rest, i.e. data is encrypted before uploading to object storage. In this case, the data stored in object storage will be encrypted which prevents data breach effectively when object storage itself is compromised.

Industry standard encryption (AES-GCM and RSA) is leveraged by JuiceFS in client side encryption. The encryption and decryption are carried out in JuiceFS client. The only thing users need to do is to provide a private key or passphrase during JuiceFS mount and use it like an ordinary file system. It is completedly transparent to the applications.

The data cached in the client side is NOT encrypted. Nevertheless, it is only accessible by root or the owner. If you want to encrypt the cached data as well, you can put the cache directory in an encrypted file system or block storage.

In addition, the metadata in JuiceFS currently does not support encrypted storage. Please do not save sensitive information (such as the user's email and other private information) in the metadata (file name, directory name, or extended attributes).

Encryption and Decryption Method

A global RSA key M must be created for each encrypted file system. Every object stored in the object storage will have its own random symmetric key S. The data is encrypted using AES-GCM with the symmetric key S, S is encrypted using the global RSA key M, and the RSA key is encrypted with the passphrase specified by the user.

The detailed procedure for data encryption is as following:

1. Data are split in 4MB pages compressed using Zstandard before writing to object storage.
2. A random 256-bit symmetric key S and a random seed N are generated for each page.
3. Each page is encrypted with S and N using AES-GCM.
4. The symmetric key S is encrypted with RSA key M as cipher K.
5. The encrypted data is combined with cypher K and random seed N into object. then written to object storage.

The steps for data decryption are as following:

1. Read the whole encrypted object (it could be a bit larger than 4MB).
2. Parse the cypher K of symmetric key K, random seed N and encrypted data.
3. Decrypt K with RSA key to get symmetric key S.
4. Decrypt data with S and N using AES-GCM into plain formats.
5. Uncompress the data Page and combine with other decrypted Page into required data block.

Key Management

The safety of RSA key is extremely important when encryption is enabled. If the key is leaked, it may result in data leakage. If the key is lost, then all encrypted data will be lost and it is unrecoverable.

JuiceFS supports two kinds of key managements: One is self-managed by user or any third-party system. The other is delegate it to JuiceFS.

Self Managed Key

No setting is required if you decide to manage the key by yourself. All you need to do is provide the same private RSA key (and optional passphrase) at each time you mount the file system.

Usage:

1. Generate RSA key

   openssl genrsa -out my-priv-key.pem -aes256 2048
   note

   Please store the key carefully in a safe place. The file system will become unreadable if the key gets lost.

2. Provide the key during mount:

   juicefs mount $VOL_NAME $JFS_MOUNTPOINT --rsa-key $JFS_PRIVATE_KEY

When RSA key is provided during mount, the client will ask for the passphrase. Click enter to ignore it if no passphrase is set.

You may set environment variable JFS_RSA_PASSPHRASE to mount it non-interactively. Set it to an empty string if no passphrase is set.

Delegated Key Management

JuiceFS also comes with a built-in key management service. To enable it, you need to turn on the storage encryption option in JuiceFS web console. A random 2048 bits RSA key will be generated and encrypted with passphrase provided by user. The encrypted keys will be kept safely. You may modify the passphrase at any time you want. The mounted file system will not be affected. The new passphrase is required for mount operation later on.

To reduce the risk of losing key, JuiceFS provides an extra protection. When encryption at-rest is enabled, the web console will generate a random recovery code which is used to encrypt the RSA key before saving. The random recovery code will be displayed (allow user to download) just once when encryption is turned on. Please save it in a safe place. In case you forget the passphrase someday, the recovery code can be used to reset the passphrase (decrypt the RSA key and re-encrypt it with new passphrase).

Usage:

1. Wipe the file system

   Encryption at-rest applies to all content in a file system so that you can only enable it for an empty file system. The files in the trash must also be deleted, otherwise they can not be read correctly once encryption is enabled.

2. Enable encryption at-rest in console

   Encryption at-rest can be enabled in setting tab of the file system. You can set the passphrase and save the recovery code to a safe place.

3. Mount file system with passphrase

   For a file system with encryption enabled, the client will ask for passphrase during mounting. If the passphrase is invalid, mounting will fail. For non-interactive mount, you may set the passphrase in environment variable JFS_RSA_PASSPHRASE. Encryption is supported in JuiceFS client newer than 4.3.0. Please upgrade it with juicefs version --upgrade.

Performance

TLS, HTTPS and AES-256 are implemented very efficiently in modern CPU. Therefore, enabling encryption has little influence to the performance of the file system. RSA algorithm is relatively slow, especially the decryption procedure. It is recommended to use 2048 bit RSA key in storage encryption. Using 4096 bit key may have significant affect in read performance.