SymmetricKey

Defines a symmetric key used to encrypt blobs at rest. Blobs encrypted with a key cannot be read without it, so keys can only be deleted by the recovery administrator.

This object can be configured from the WebUI under Settings › Encryption › Symmetric Keys

Fields

description

Type: String · required

Description of the key

cipher

Type: SymmetricCipher · read-only · default: "aes256Gcm"

Encryption algorithm, which cannot be changed after the key is created

key

Type: SecretKey · read-only

Base64-encoded 256-bit key (for example, generated with openssl rand -base64 32), which cannot be changed after the key is created

fingerprint

Type: String · server-set

Fingerprint of the key, used to detect a changed key file or environment variable

JMAP API

The SymmetricKey object is available via the urn:stalwart:jmap capability.

x:SymmetricKey/get

This is a standard Foo/get method as defined in RFC 8620, Section 5.1.

This method requires the sysSymmetricKeyGet permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:SymmetricKey/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

x:SymmetricKey/set

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

Supports the following operations in a single call: create, update, destroy.

Create

This operation requires the sysSymmetricKeyCreate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:SymmetricKey/set",
          {
            "create": {
              "new1": {
                "description": "Example"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysSymmetricKeyUpdate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:SymmetricKey/set",
          {
            "update": {
              "id1": {
                "description": "updated value"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Destroy

This operation requires the sysSymmetricKeyDestroy permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:SymmetricKey/set",
          {
            "destroy": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

x:SymmetricKey/query

This is a standard Foo/query method as defined in RFC 8620, Section 5.5.

This method requires the sysSymmetricKeyQuery permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:SymmetricKey/query",
          {
            "filter": {}
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

CLI

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Fetch

stalwart-cli get SymmetricKey id1

Create

stalwart-cli create SymmetricKey \
  --field description=Example

Query

stalwart-cli query SymmetricKey

Update

stalwart-cli update SymmetricKey id1 --field description='updated value'

Delete

stalwart-cli delete SymmetricKey --ids id1

Nested types

SecretKey

A secret value provided directly, from an environment variable, or from a file.

• Value: Secret value. Carries the fields of SecretKeyValue.
• EnvironmentVariable: Secret read from environment variable. Carries the fields of SecretKeyEnvironmentVariable.
• File: Secret read from file. Carries the fields of SecretKeyFile.

SecretKeyValue

A secret value provided directly.

secret

Type: String · required · secret

Password or secret value

SecretKeyEnvironmentVariable

A secret value read from an environment variable.

variableName

Type: String · required

Environment variable name to read the secret from

SecretKeyFile

A secret value read from a file.

filePath

Type: String · required

File path to read the secret from

Enums

SymmetricCipher

Value	Label
aes256Gcm	AES-256-GCM
chacha20Poly1305	ChaCha20-Poly1305