---
tags: aries
---

# DIDcomm Envelope Structure notes

## Outer Envelope

{
    "protected": { // Encoded a base64-url string
        "typ": "prs.hyperledger.aries-envelope",
        "cty": "msgpack",
        "alg": "ECDH-ES+XC20PKW",
        "enc": "XC20P"
    },
    "recipients": [
        // CEK encrypted to each recipient
        // Includes ephemeral (anoncrypt) or sender key (authcrypt)
    ],
    "aad": "", // AEAD authenticated data (possibly implicit)
    "ciphertext": "", // Encrypted layer as base64-url string
    "iv": "", // AEAD nonce as base64-url string
    "tag": "" // AEAD tag as base64-url string
}

## Encrypted Layer (Inner Envelope)

Encoded in `msgpack`, allowing for binary strings without additional base64-encoding.

JSON could be supported equally well by indicating `json` for the `cty` in public header and base64-encoding the binary string properties, but at the expense of increasing the message size by a third.

**Repudiable payload:**

{
    "typ": "json | msgpack", // Encoding of the payload
    "payload": "", // Message as a binary string
    "meta": {
        // Transport properties, described below
    }
}

**Non-repudiable payload:**

{
    "sig": { // JWS
        "protected": {
            "alg": "EdDSA", // Signing algorithm
            "kid": "", // Sender VK
            "typ": "json | msgpack", // Encoding of the payload
        },
        "payload": "", // Message as a binary string
        "signature": "", // Signature as a binary string
    },
    "meta": {
        // Transport properties - not signed, described below
    }
}

Note that in the case of a forwarded message (and possibly other cases), the payload may be another Outer Envelope, either JSON or msgpack encoded as indicated by `typ`. Otherwise the payload must be an Aries agent message with `@type` indicating the protocol, in JSON format.

If support for multiple signatures is desired, the `payload` property could remain at the top level, with `sig` containing a list of JWS blocks sans-`payload` (to avoid repetition of the message body).

The signing key of the signature is not required to match the sender described in the recipients block.

## Transport Properties (`meta`)

This information is assembled after the message payload is produced, as it is being packed into the encrypted envelope.

{
    "info": {
        // Optional block for any open-vocabulary information to be
        // handled at the transport layer, for example the number of
        // queued messages held for the recipient by the sender.
    },
    "pad": "", // Optional random binary message padding
    "return": {
        // Optional instructions for return routing of responses.
        // Replaces the ~transport decorator.
        // Exclusive of `deliver`.
        "scope": "all | thread | none", // as in ~transport decorator
        "route": {
            // optionally define a return route
            // based on `service` block in a DID Doc
            // and similar to the ~service decorator
        }
    },
    "deliver": {
        // Optional instructions for forwarding agents.
        // Describes where to deliver the payload, which must be
        // a message envelope.
        // Exclusive of `return` and `forwarded`.
        // (format not yet specified)
    },
    "forwarded": {
        // Optional block to indicate that this message payload was
        // forwarded, and by whom. Can be used to contextualize any
        // transport instructions provided in the protected payload
        // message (which the forwarding agent can't see).
        // Exclusive of `deliver`.
        // (format not yet specified, could provide a DID, key, endpoint..)
    },
    "timing": {
        // Optional block equivalent to the ~timing decorator
    }
}

Other possibilities are a `trace` section equivalent to the `~trace` decorator, and a `payment` section equivalent to the `~payment` decorator.

## References

- [Message timing decorator](https://github.com/hyperledger/aries-rfcs/tree/master/features/0032-message-timing)
- [Message tracing decorator](https://github.com/hyperledger/aries-rfcs/tree/master/features/0034-message-tracing)
- [Service decorator](https://github.com/hyperledger/aries-rfcs/tree/master/features/0056-service-decorator)
- [Payment decorator](https://github.com/hyperledger/aries-rfcs/tree/master/features/0075-payment-decorators)
- [Transport decorator](https://github.com/hyperledger/aries-rfcs/tree/master/features/0092-transport-return-route)