ExternalPublicKey

Public key of a remote recipient used by the encryption gateway, entered manually, kept up to date from a discovery method or learned from received mail.

This object can be configured from the WebUI under Settings › Encryption › External Public Keys, Settings › Encryption › Pending Key Changes

Fields

`emailAddress`

Type: EmailAddress · required

Address the key is used for

`key`

Type: Text?

OpenPGP key or S/MIME certificate, armored, PEM, or binary encoded as base64; an S/MIME certificate may be followed by its intermediate certificates

`description`

Type: String?

Description of the key

`status`

Type: ExternalPublicKeyStatus · default: "active"

Whether the key is used

`pinned`

Type: Boolean · default: false

Never replace this key automatically

`authenticatedEncryption`

Type: Boolean · default: false

All mail clients holding the private key can read AES-GCM with RSA-OAEP. Applies to S/MIME RSA and elliptic-curve keys. Apple Mail and Thunderbird ESR cannot read it.

`source`

Type: KeySource · default: {"@type":"Manual"}

Where the key comes from; it cannot be changed once the key is created

`trust`

Type: KeyTrust · server-set

Trust level derived from the source and certificate validation

`kind`

Type: PublicKeyKind? · server-set

Type of key, taken from the key itself

`keyType`

Type: String? · server-set

Type of key and its encryption algorithms, taken from the key itself

`fingerprint`

Type: String? · server-set

Fingerprint of the key or certificate used for encryption

`capabilities`

Type: Set<PublicKeyCapability> · server-set

Encryption features supported by the key

`smimeCiphers`

Type: Set<SmimeCipher> · server-set

Content encryption algorithms advertised by the recipient in signed S/MIME messages

`smimeOaep`

Type: Boolean · server-set · default: false

Whether the recipient advertised support for RSA-OAEP in signed S/MIME messages

`smimeSignedAt`

Type: UTCDateTime? · server-set

Signing time of the message the S/MIME capabilities were learned from

`firstSeen`

Type: UTCDateTime · server-set

When the key was first stored

`lastSeen`

Type: UTCDateTime · server-set

When the key was last seen in a discovery result or received message

`lastChecked`

Type: UTCDateTime? · server-set

When the key was last confirmed by its discovery method or certificate check

`nextCheckAt`

Type: UTCDateTime? · server-set

When the key is next fetched or checked

`expiresAt`

Type: UTCDateTime? · server-set

When the key stops being used: its own expiration date or, for keys from DNSSEC, the end of the DNS TTL

`nextKey`

Type: Text? · server-set

Replacement key waiting for approval, or for the current key to expire

`nextKeyType`

Type: String? · server-set

Type of the replacement key and its encryption algorithms

`nextFingerprint`

Type: String? · server-set

Fingerprint of the replacement key

`nextCapabilities`

Type: Set<PublicKeyCapability> · server-set

Encryption features supported by the replacement key

`nextExpiresAt`

Type: UTCDateTime? · server-set

Expiration date of the replacement key

`blockedFingerprints`

Type: Set<String> · server-set

Fingerprints of keys that were revoked or rejected and are not accepted again

JMAP API

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

`x:ExternalPublicKey/get`

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

This method requires the sysExternalPublicKeyGet permission.

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

`x:ExternalPublicKey/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 sysExternalPublicKeyCreate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:ExternalPublicKey/set",
          {
            "create": {
              "new1": {
                "emailAddress": "[email protected]",
                "source": {
                  "@type": "Manual"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysExternalPublicKeyUpdate permission.

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

Destroy

This operation requires the sysExternalPublicKeyDestroy permission.

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

`x:ExternalPublicKey/query`

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

This method requires the sysExternalPublicKeyQuery permission.

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

The x:ExternalPublicKey/query filter argument accepts the following conditions (combinable with AnyOf / AllOf / Not per RFC 8620):

Condition	Kind
`emailAddress`	text

CLI

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

Fetch

stalwart-cli get ExternalPublicKey id1

Create

stalwart-cli create ExternalPublicKey \
  --field [email protected] \
  --field 'source={"@type":"Manual"}'

Query

stalwart-cli query ExternalPublicKey
stalwart-cli query ExternalPublicKey --where emailAddress=example

Update

stalwart-cli update ExternalPublicKey id1 --field key='updated value'

Delete

stalwart-cli delete ExternalPublicKey --ids id1

Nested types

KeySource

Where an external public key comes from.

Manual: Enter the key manually. No additional fields.
Automatic: Keep the key up to date from a discovery method. Carries the fields of KeySourceAutomatic.
HarvestedSmime: Learned from an S/MIME signature. No additional fields.
HarvestedPgp: Learned from an OpenPGP signature. No additional fields.
Autocrypt: Learned from an Autocrypt header. No additional fields.

KeySourceAutomatic

Discovery method that keeps an external public key up to date.

`method`

Type: KeyDiscoverySource · required

Where the key is fetched from

Enums

ExternalPublicKeyStatus

Value	Label
`active`	Active
`disabled`	Disabled
`pendingApproval`	Pending approval (the current key stays in use)
`rejected`	Reject the replacement key

KeyDiscoverySource

Value	Label
`dnssec`	DNS (OPENPGPKEY and SMIMEA, DNSSEC required)
`wkd`	Web Key Directory
`vks`	keys.openpgp.org
`hkp`	Keyservers (HKP)

KeyTrust

Value	Label
`manual`	Manual
`verified`	Verified (CA chain or DNSSEC)
`discovered`	Fetched from WKD or keys.openpgp.org
`harvested`	Harvested from authenticated mail without a CA chain
`unverified`	Unverified

PublicKeyKind

Value	Label
`openPgp`	OpenPGP
`smime`	S/MIME

PublicKeyCapability

Value	Label
`aead`	Authenticated encryption
`postQuantum`	Post-quantum

SmimeCipher

Value	Label
`aes128Cbc`	AES-128-CBC
`aes192Cbc`	AES-192-CBC
`aes256Cbc`	AES-256-CBC
`aes128Gcm`	AES-128-GCM
`aes192Gcm`	AES-192-GCM
`aes256Gcm`	AES-256-GCM
`chaCha20Poly1305`	ChaCha20-Poly1305