---
tags: aries, connection, invitation, service
---

# OutOfBand Protocol

The OutOfBand protocol is used when you wish to engage with another agent and you are not aware of a DIDComm connection to use for the interaction. This could be because you are trying to establish a new connection, you might have a connection, but don't know which connection it is, or if you want to have a connection-less interaction.

## Points from Meeting - 20200214 - Sam, George, Andrew, Stephen

~~1. Protocol: OutOfBandMsg~~
2. Two message types "invitation" and "request" (is there a better name for this one?)
3. The response to this message should use the @id from an OutOfBandMsg message as the @pthid (parent thread id).
4. The "invitation" message should include a "protocol" array of the protocols that the inviter expects to receive back from the invitee (expected to be "connections" or "did-exchange" for now, but could be other things in the future).
~~5. We will remove the "initial" item from the message, but will allow the default "request" item in the "invitation" message.~~
6. The "request" item will become "~request-attachment" and so support the goodness of the attachment decorator, including the ability to sign the attachment (if that works in this context).
7. Only if a public DID is used in the invitation should the invitee check for an existing connection that was started from that public DID. A note will indicate that we are looking for a way to support the case of using a non-public DID.
> NOTE - this increases the number of public DIDs needed as now instead of just issuers, every enterprise app needs a public DID. Something to consider.
8. We will add both the "ack" message to the DID-Exchange protocol (to follow from the invitee to the inviter after the "response" message -- unrelated to OutOfBand) and the "continue" message, which is used to respond to an "invitation" message using an existing connection.
9. We should talk about QR codes in this RFC, and also talk about the existing RFC on URLs and QR codes (from Spaceman.io).
10. The "service" item will be an array, with a note that invitees will ignore the non-didcomm items and select from the didcomm items as they choose. The order of the entries will be in the inviters preference. Un-type entries are assumed to be "didcomm". This use of the array is done to mimick the handling of a the message containing the full "service" block from a DIDDoc. An agent can just drop their normal DIDDoc "service" block into this message.

> [name=Stephen Curran] I think the next step is to take the "invitation" section of the DID-Exchange protocol as the starting point and then add in the concepts below and in the list above.

## Required Properties

An invitation message has two required properties, `@type` and `service`.

### Invitation Type

The `@type` property must use the DIDComm message type format `"https://didcomm.org/invitation/1.0/<messagetype>"` (TBD: exact message types - ideas `connect` a nd `request`, with perhaps another about `discovery`. The `service` property is described below. Unless otherwise indicated, the invitation represents an opportunity to create a pairwise connection.

### Service Descriptor

The `service` property of an invitation represents a locator and method for responding to the inviter. The property supports multiple formats, based on the `service` property of DID Documents as defined by the [Decentralized Identifiers working draft](https://w3c.github.io/did-core/).

The property may be an object representing a single service entry:

"service": {
      "recipientKeys": ["8HH5gYEeNc3z7PYXmd54d4x6qAfCNrqQqEB3nS7Zfu7K"],
      "routingKeys": ["8HH5gYEeNc3z7PYXmd54d4x6qAfCNrqQqEB3nS7Zfu7K"],
      "serviceEndpoint": "https://example.com:5000"
    }

When the service entry contains only a `serviceEndpoint` property, it may be shortened to a string:

"service": "did:sov:LjgpST2rjsoxYegQDRm7EL"

Finally, the `service` property may contain an array of service entries, the same way a DIDDoc can have multiple services:

"service": [
      {
        "id": "did:sov:LjgpST2rjsoxYegQDRm7EL#vcr",
        "type": "didcomm",
        "recipientKeys": ["8HH5gYEeNc3z7PYXmd54d4x6qAfCNrqQqEB3nS7Zfu7K"],
        "routingKeys": ["8HH5gYEeNc3z7PYXmd54d4x6qAfCNrqQqEB3nS7Zfu7K"],
        "serviceEndpoint": "https://example.com:5000"
      },
      "did:sov:LjgpST2rjsoxYegQDRm7EL"
  ]

the type is assumed to be didcomm if not specified.
the invitee is expected to ignore service entries with a different type.

## Invitation Use Cases

The invitation message may convey more than the ability to create a pairwise connection.

### Supported Protocols

The inviter may advertise the supported Aries protocols the invitee can use by using the `protocol` property at the message level or within a specific service entry. Protocol entries are additive between the two when connecting to a specific service. The `protocol` entry may be either a string or an array of strings and should be listed in order of decreasing preference when protocols fulfill roughly the same purpose (such as the `connection` and `did-exchange` protocols).

{
  "@type": "https://didcomm.org/invitation/1.0/connect",
  "@id": "<id used for context as pthread>",
  // ...
  "protocol": ["https://didcomm.org/did-exchange/1.0"],
  "service": ["did:sov:LjgpST2rjsoxYegQDRm7EL"],
  "request~attach" {} //optional
}

### Providing a DIDComm Request

An invitation may contain a `request` property with a complete agent message. The message is to be interpreted by the client application as if it were received over DIDComm without any encryption. A common use case is to attach a presentation request for the client to fulfill using proof of their own issued credentials. The response to this agent message should be sent to the service described by the invitation, and must be implied by the protocol referenced in the message's `@type` property. A pairwise connection may optionally be created before sending the response, but is not required.

_Maybe add a property to indicate whether anon-crypted messages can or should be sent? Add to the service entry?_

{
  "@type": "https://didcomm.org/invitation/1.0/request",
  "@id": "<uuid-invitation>",
  "label": "Authenticate with Service",
  "request": { //needs to be an attachment
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/request-presentation",
    "@id": "<uuid-request>",
    "request_presentations~attach": [
      {
        "@id": "libindy-request-presentation-0",
        "mime-type": "application/json",
        "data": {
          "base64": "<bytes for base64>"
        }
      }
    ]
  },
  "service": "did:sov:LjgpST2rjsoxYegQDRm7EL"
}

### Providing an Initial DIDComm Message

If provided, the `initial` property of an invitation represents an agent message to be sent by the invitee **after** forming a pairwise connection. The message may contain an identifier or other properties used to tie the request to the invitation message. The `initial` message should only be sent if the invitee application supports the given protocol; otherwise the response is unlikely to be understood. For example, an `initial` message may be used to suggest that the invitee application request an action menu:

_Maybe provide a list of initial entries for the client to select from depending which protocols are supported?_

{
  "@type": "https://didcomm.org/invitation/1.0/connect",
  "@id": "<uuid-invitation>",
  "label": "Request a Quote",
  "initial": {
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/action-menu/1.0/menu-request",
    "@id": "<uuid-initial>"
  },
  "service": "did:sov:LjgpST2rjsoxYegQDRm7EL"
}

## Additional Properties

The following properties are optional additions to an invitation.

### Invitation ID

The `@id` property, if present, should be used as the `~thread` `thid` for any resulting messages sent by the client application, unless superseded by the `@id` for a `request` or `initial` payload.

### Invitation Label

The `label` property defines a default label for the client's agent application to use for this request or connection target. It is self-asserted and should not be presented as authoritative. A `label` property may also be added to individual `service` entries as a descriptor for that service. This is recommended when the invitation represents a specific request beyond a connection.

_Add image URL? Maybe a common property for identifying information?_

## Reusing a Pairwise Connection

A client application may be able to identify an existing pairwise connection to use when responding to an invitation. To perform the comparison to existing connections, the `service` entry used to form the connection can be compared to the currently selected `service` entry.

In the case of an agent which issues new recipient keys for each invitation (normally an agent without a public DID), the agent may wish to relax the requirements for comparison. The `unique` property may be added to a `service` entry in order to specify which properties are to be considered canonical.

The `serviceEndpoint` property must always be considered canonical, whether listed in `unique` or not. Unless listed in the `unique` property, the `id`, `label`, `priority` and `type` properties may be ignored during comparison. The `unique` property itself should not be directly compared between entries.

{
  "id": "#my-service",
  "recipientKeys": ["8HH5gYEeNc3z7PYXmd54d4x6qAfCNrqQqEB3nS7Zfu7K"],
  "routingKeys": ["8HH5gYEeNc3z7PYXmd54d4x6qAfCNrqQqEB3nS7Zfu7K"],
  "serviceEndpoint": "https://example.com:5000",
  "unique": "routingKeys,serviceEndpoint"
}

If the invitation provides a `request` or `initial` block then the response may simply be sent along the existing connection. Otherwise, the a connection continuation message may be used to indicate that the invitation has been accepted, with the message referencing the `@id` of the invitation in its `~thread` decorator. The `protocol` property may also suggest an appropriate initial message.