Skip to content

Latest commit

 

History

History
90 lines (61 loc) · 5.47 KB

index.md

File metadata and controls

90 lines (61 loc) · 5.47 KB
title category type source
Off-chain Messages
messages
reference

Off-chain Messages

Most request and responses are performed privately off-chain between the different parties to a flow.

JSON Web Token

Most off-chain messages consist of signed JWTs (JSON Web Tokens) as defined in RFC 7519.

Requirements

We currently only support signatures using the secp256k1 ECDSA curve, which is also used by both Bitcoin and Ethereum.

JOSE Header

The JOSE header indicates the signing algorithm used in the JWT. This MUST contain the following:

{"typ": "JWT", "alg": "ES256K"}

Attributes

The JWT spec calls these claims, but we use the term "claims" for identity-specific data. So in this document we will call these standard JWT "claims" "attributes" instead.

Name Description Required
iss The DID of the signing identity yes
sub The DID of the subject of the JWT no
aud The DID or URL of the audience of the JWT. Our libraries or app will not accept any JWT that has someone else as the audience no
iat The time of issuance yes
exp Expiration time of JWT no

Non Standard attributes:

Name Description Required
callback Callback URL for returning the response to a request no
type Type of Message no
vc Array of Verified Claims JWTs or IPFS hash of JSON encoded equivalent about the iss of this message. See Issuer Claims and Verified Claims no
boxPub 32 byte base64 encoded Curve25519 public key no

The following attributes can also be appended to the signed request as URL encoded query parameters outside of the signed payload.

Name Description Required
redirect_url The URL that control is returned to once a request is complete (mobile). Base url/domain must match callback in JWT. no
callback_type Valid values post or redirect. Determines if callback should be sent as a HTTP POST or open the link (redirect). If unspecified, the mobile app will attempt to pick the correct one no

These options allow you to tell the client how you want to receive the response. If a redirect_url is provided, the client will post the response to the callback in the JWT and then call the given redirect_url to return control to the original callee. You can also add any contextual data in the redirect_url query params or as a url fragment (i.e. you may want to map requests to responses). If a redirect_url is provided and a callback_type redirect is provided the response will be passed as url fragment with the redirect_url. If no redirect_url is provided, it will use the callback in JWT and will use the callback_type if provided or the client will attempt to choose the correct type.

Signature Verification

Each uPort compatible JWT must be signed using an secp256k1 curve. The public key is resolved for the iss using the uPort PKI.

Message Encryption

Some message transports are not secure and require messages to be encrypted. See our encryption specs for more detail.

Unsigned Requests (Deprecated)

Many apps that run 100% in the browser do not have a secure way of signing a request. Therefore we provide unsigned versions of certain requests.

Standard Unsigned Parameters

There are certain standardized parameters that are provided using HTTP query params in the request. Some of these are based on parameters in the OAuth 2.0 RFC 6749 Spec:

Name Description Required
client_id The DID of the requesting identity no
callback_url The URL that receives the response no
callback_type Valid values post or redirect. Determines if callback should be sent as a HTTP POST or open the link (redirect). If unspecified the mobile app will attempt to pick the correct one no
label Plain text name of client to be displayed to user no

Message types

There are several standard message types that the uPort mobile app knows how to handle or create: