
=== Encryption choice

Data can be optionally encrypted with a symmetric key using AES before being stored in the blobStore. As many user relies
on third party for object storage, a compromised third party will not escalate to a data disclosure. Of course, a
performance price have to be paid, as encryption takes resources.

*encryption.aes.enable* : Optional boolean, defaults to false.

If AES encryption is enabled, then the following properties MUST be present:

 - *encryption.aes.password* : String
 - *encryption.aes.salt* : Hexadecimal string

The following properties CAN be supplied:

 - *encryption.aes.private.key.algorithm* : String, defaulting to PBKDF2WithHmacSHA512. Previously was
PBKDF2WithHmacSHA1.

WARNING: Once chosen this choice can not be reverted, all the data is either clear or encrypted. Mixed encryption
is not supported.

Here is an example of how you can generate the above values (be mindful to customize the byte lengths in order to add
enough entropy.

....
# Password generation
openssl rand -base64 64

# Salt generation
generate salt with : openssl rand -hex 16
....

AES blob store supports the following system properties that could be configured in `jvm.properties`:

....
# Threshold from which we should buffer the blob to a file upon encrypting
# Unit supported: K, M, G, default to no unit
james.blob.aes.file.threshold.encrypt=100K

# Threshold from which we should buffer the blob to a file upon decrypting
# Unit supported: K, M, G, default to no unit
james.blob.aes.file.threshold.decrypt=256K

# Maximum size of a blob. Larger blobs will be rejected.
# Unit supported: K, M, G, default to no unit
james.blob.aes.blob.max.size=100M
....

=== Object storage configuration

==== AWS S3 Configuration

.blobstore.properties S3 related properties
|===
| Property name | explanation

| objectstorage.s3.endPoint
| S3 service endpoint

| objectstorage.s3.region
| S3 region

| objectstorage.s3.accessKeyId
| https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[S3 access key id]

| objectstorage.s3.secretKey
| https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[S3 access key secret]

| objectstorage.s3.http.concurrency
| Allow setting the number of concurrent HTTP requests allowed by the Netty driver.

| objectstorage.s3.truststore.path
| optional: Verify the S3 server certificate against this trust store file.

| objectstorage.s3.truststore.type
| optional: Specify the type of the trust store, e.g. JKS, PKCS12

| objectstorage.s3.truststore.secret
| optional: Use this secret/password to access the trust store; default none

| objectstorage.s3.truststore.algorithm
| optional: Use this specific trust store algorithm; default SunX509

| objectstorage.s3.trustall
| optional: boolean. Defaults to false. Cannot be set to true with other trustore options. Wether James should validate
S3 endpoint SSL certificates.

| objectstorage.s3.read.timeout
| optional: HTTP read timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.

| objectstorage.s3.write.timeout
| optional: HTTP write timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.

| objectstorage.s3.connection.timeout
| optional: HTTP connection timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.

| objectstorage.s3.in.read.limit
| optional: Object read in memory will be rejected if they exceed the size limit exposed here. Size, exemple `100M`.
Supported units: K, M, G, defaults to B if no unit is specified. If unspecified, big object won't be prevented
from being loaded in memory. This settings complements protocol limits.

| objectstorage.s3.upload.retry.maxAttempts
| optional: Integer. Default is zero. This property specifies the maximum number of retry attempts allowed for failed upload operations.

| objectstorage.s3.upload.retry.backoffDurationMillis
| optional: Long (Milliseconds). Default is 10 (miliseconds).
Only takes effect when the "objectstorage.s3.upload.retry.maxAttempts" property is declared.
This property determines the duration (in milliseconds) to wait between retry attempts for failed upload operations.
This delay is known as backoff. The jitter factor is 0.5

|===

==== Buckets Configuration

.Bucket configuration
|===
| Property name | explanation

| objectstorage.bucketPrefix
| Bucket is a concept in James and similar to Containers in Swift or Buckets in AWS S3.
BucketPrefix is the prefix of bucket names in James BlobStore

| objectstorage.namespace
| BlobStore default bucket name. Most of blobs storing in BlobStore are inside the default bucket.
Unless a special case like storing blobs of deleted messages.

| objectstorage.namespace.read.fallback
| BlobStore fallback bucket name. Allows to fallback to a previous used bucket when blob is missing from the default one.
It can be useful when migrating blobs to a new bucket for example.
|===

==== SSE-C Configuration

.SSE-C configuration
|===
| Property name | explanation

| encryption.s3.sse.c.enable
| optional: Boolean. Default is false. Controls whether to use Server-Side Encryption with Customer-Provided Keys (SSE-C) for S3 blobs.

| encryption.s3.sse.c.master.key.algorithm
| String. Required if `encryption.s3.sse.c.enable` is true. The algorithm used to derive the master key from the provided password. Eg: AES256

| encryption.s3.sse.c.master.key.password
| String. Required if `encryption.s3.sse.c.enable` is true. The password used to generate the customer key.

| encryption.s3.sse.c.master.key.salt
| String. Required if `encryption.s3.sse.c.enable` is true. The salt used to generate the customer key.

|===

==== Improve listing support for MinIO

Due to blobs being stored in folder, adding `/` in blobs name emulates folder and avoids blobs to be all stored in a
same folder, thus improving listing.

Instead of `1_628_36825033-d835-4490-9f5a-eef120b1e85c` the following blob id will be used: `1/628/3/6/8/2/5033-d835-4490-9f5a-eef120b1e85c`

To enable blob hierarchy compatible with MinIO add in `jvm.properties`:

----
james.s3.minio.compatibility.mode=true
----


== Blob Export

Blob Exporting is the mechanism to help James to export a blob from an user to another user.
It is commonly used to export deleted messages (consult <a href="/server/config-vault">configuring deleted messages vault</a>).
The deleted messages are transformed into a blob and James will export that blob to the target user.

This configuration helps you choose the blob exporting mechanism fit with your James setup and it is only applicable with Guice products.

Consult {sample-configuration-prefix-url}/blob.properties[blob.properties]
in GIT to get some examples and hints.

Configuration for exporting blob content:

.blobstore.properties content
|===
| blob.export.implementation

| localFile: Local File Exporting Mechanism (explained below). Default: localFile

|===

=== Local File Blob Export Configuration

For each request, this mechanism retrieves the content of a blob and save it to a distinct local file, then send an email containing the absolute path of that file to the target mail address.

Note: that absolute file path is the file location on James server. Therefore, if there are two or more James servers connected, it should not be considered an option.

*blob.export.localFile.directory*: The directory URL to store exported blob data in files, and the URL following
http://james.apache.org/server/3/apidocs/org/apache/james/filesystem/api/FileSystem.html[James File System scheme].
Default: file://var/blobExporting
