| Internet-Draft | SATP-vLEI | September 2025 |
| Smith | Expires 8 March 2026 | [Page] |
The verifiable Legal Entity Identifier (vLEI) is a cryptographically verifiable extension of the LEI standard, designed to automate trust in organizational identity. Governed by the Global Legal Entity Identifier Foundation (GLEIF), the vLEI system uses W3C Verifiable Credentials, Decentralized Identifiers (DIDs), and Key Event Receipt Infrastructure (KERI) to issue and verify credentials for legal entities and their authorized representatives. It enables secure, machine-readable identity assertions across financial, regulatory, and supply chain ecosystems, supporting role-based delegation and interoperability with decentralized trust frameworks.¶
This specification defines vLEI for verifiable gateway operator identities and cryptographically links the gateway operator identity to the gateway identity. Thus SATP core lock assertions are cryptographically linked to gateway operator identities.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://nedmsmith.github.io/draft-smith-satp-vlei-binding/draft-smith-satp-vlei-binding.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-smith-satp-vlei-binding/.¶
Discussion of this document takes place on the Secure Asset Transfer Protocol Working Group mailing list (mailto:sat@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/sat/. Subscribe at https://www.ietf.org/mailman/listinfo/sat/.¶
Source for this draft and an issue tracker can be found at https://github.com/nedmsmith/draft-smith-satp-vlei-binding.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 8 March 2026.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The SATP architecute [I-D.ietf-satp-architecture] defines an interoperability architecture for interconnection between networks or systems that anticipates a secure asset transfer protocol that satisfies security, privacy, atomicity and liveliness requirements in the transfer of assets. The SATP core protocol [I-D.ietf-satp-core] is a protocol for exchanging digital assets that ensures the state of the asset is preserved across inter-domain transfers. It is an extensible protocol where fields containing identity and payload values that are not defined by SATP core may be defined by companion specifications. This specification defines a SATP core protocol binding for Verifiable Legal Entity Identifiers (vLEI) [ISO17442-3] used to identify SATP gateways and the organizations that operate them. In some use cases, the assets being transferred have legal considerations such that officers of the organization are expected to authorize digital asset transfers. This specification details the various vLEI credentials needed and how to integrate them with SATP core messages. SATP core message binding anticipates use of a message wrapper that uses media type [STD91] and content format [RFC7252] identifiers to facilitate interoperability with vLEI and other credential types.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The SATP core protocol [I-D.ietf-satp-core] defines several extensible protocol fields that contain identity and other values not defined by SATP core. To facilitate interoperability these fields SHOULD contain a media type [STD91] or content format [RFC7252] wrapper. This specation requests IANA assignment of media type and content format identifiers for vLEIs which are serialized as Composable Event Streaming Representation (CESR) [CESR-Spec] objects in JSON format. See Section 7.¶
The following SATP messages are extended to contain vLEI credentials:¶
| # | SATP Message | Credential Type |
|---|---|---|
| 1 | verifiedOriginatorEntityId, verifiedBeneficiaryEntityId, senderGatewayOwnerId, receiverGatewayOwnerId | LegalEntityvLEICredential |
| 2 | senderGatewayId, recipientGatewayId, senderGatewayNetworkId, recipientGatewayNetworkId | LegalEntityEngagementContextRolevLEICredential |
| 3 | assetControllerCredential, lockEvidenceIssuerCredential, commitAuthorizingCredential | LegalEntityvLEICredential, OfficialOrganizationalRolevLEICredential, LegalEntityEngagementContextRolevLEICredential |
| 4 | originatorPubkey, beneficiaryPubkey, senderGatewaySignaturePublicKey, receiverGatewaySignaturePublicKey, senderGatewayDeviceIdentityPubkey, receiverGatewayDeviceIdentityPubkey, lockEvidenceVerificationKey, commitVerificationKey, postCommitSecureChannelKey | JOSE or COSE Key |
The SATP Messages in row 4 of Table 1 SHALL be a JSON Web Key as defined by [RFC7517] or a COSE Key as defined by [STD96].¶
The SATP Messages in row 1 of Table 1 SHALL be a LegalEntityvLEICredential as defined by the LEvLEIC schema.¶
These messages are realized using a Legal Entity vLEI Credential (LEvLEIC) because these message identify legal entities. Gateway owner identities area form of legal entity as they identify the owner of a gateway rather than the gateway itself.¶
The SATP Messages in row 2 of Table 1 SHALL be a LegalEntityEngagementContextRolevLEICredential as defined by the LEECRvLEIC schema.¶
These messages are realized using a Legal Entity Engagement Context Role vLEI Credential (LEECRvLEIC) because these message identify the gateways and hosts within the respective networks involved in transferring digital assets.¶
The SATP Messages in row 3 of Table 1 SHALL be one of a LegalEntityvLEICredential, LegalEntityEngagementContextRolevLEICredential, or OfficialOrganizationalRolevLEICredential as defined by the LEvLEIC, LEECRvLEIC, and LEOORvLEIC schemas.¶
These messages are realized using various vLEI credentials depending on use case context.¶
Examples:¶
LEvLEIC is used if an asset controller, lock evidence issuer, or commit authority are legal entities.¶
LEECRvLEIC is used if an asset controller, lock evidence issuer, or commit authority are machine hosts facilitating SATP gateways or network hosts.¶
Official Organizational Role vLEI Credential (OORvLEIC) is used if an asset controller, lock evidence issuer, or commit authority are organizational roles.¶
Keys embedded in hardware or firmware may not easily be converted to an interoperablel format, hence support for multiple key formats ensures the SATP protocols can be implemented by a wide variety of systems.¶
The SATP messages in row 4 of Table 1 SHALL be encoded using JSON Web Key (JWK) [RFC7517] or COSE key [STD96] formats.¶
The key structure SHOULD be extensible to support additional key formats.¶
The following CDDL [RFC8610] defines the wrapper and application to SATP fields.¶
; =====================================================================
; --- SATP Message (Entry Point) ---
; =====================================================================
satp-message = {
; --- Stage 1 ---
? verifiedOriginatorEntityId: wrapped-vlei ; always "leid"
? verifiedBeneficiaryEntityId: wrapped-vlei ; always "leid"
? senderGatewayOwnerId: wrapped-vlei ; always "leid"
? receiverGatewayOwnerId: wrapped-vlei ; always "leid"
? senderGatewayId: wrapped-vlei ; always "ecr"
? recipientGatewayId: wrapped-vlei ; always "ecr"
? senderGatewayNetworkId: wrapped-vlei ; always "ecr"
? recipientGatewayNetworkId: wrapped-vlei ; always "ecr"
? originatorPubkey: wrapped-key
? beneficiaryPubkey: wrapped-key
? senderGatewaySignaturePublicKey: wrapped-key
? receiverGatewaySignaturePublicKey: wrapped-key
? senderGatewayDeviceIdentityPubkey: wrapped-key
? receiverGatewayDeviceIdentityPubkey: wrapped-key
; --- Stage 2 ---
? assetControllerCredential: wrapped-vlei ; can be "leid", "ecr" or "oor"
? lockEvidenceIssuerCredential: wrapped-vlei ; can be "leid", "ecr" or "oor"
? lockEvidenceVerificationKey: wrapped-key
; --- Stage 3 ---
? commitAuthorizingCredential: wrapped-vlei ; can be "leid", "ecr" or "oor"
? commitVerificationKey: wrapped-key
? postCommitSecureChannelKey: wrapped-key
}
; =====================================================================
; --- Wrapped vLEI Payloads ---
; =====================================================================
wrapped-vlei = {
vleitype: tstr
content: content-ref
payload: bstr / tstr
}
content-ref = {
? mt: tstr ; TBA e.g., "application/acdc+json"
? cf: uint ; TBA content format id
? cbt: bool ; payload contains CBOR tagged content in the TN() range if true
? oid: tstr ; generated from content-format-id e.g., "1.3.6.1.4.1.37476.2.1.5"
}
; =====================================================================
; --- Wrapped Key Definitions ---
; =====================================================================
wrapped-key = $key-type
$key-type /= cose-key
$key-type /= jwk-key
$key-type /= pkix-key
$wrapped-key-content /= "application/cose;cose-type=cose-key"
$wrapped-key-content /= "application/jwk+json"
$wrapped-key-content /= "application/pkix-cert"
$wrapped-key-content /= uint
cose-key = {
content: "application/cose;cose-type=cose-key" / uint,
encoding: "cbor" / "base64",
payload: bstr / tstr
}
jwk-key = {
content: "application/jwk+json" / uint,
payload: tstr
}
pkix-key = {
content: "application/pkix-cert" / uint,
encoding: "PEM" / "DER",
payload: tstr / bstr
}
¶
vLEI credentials are expressed as Authentic Chained Data Containers (ACDC) [ACDC-Spec]. Section Section 7 request IANA assignment of ACDC media types [STD91].¶
SATP messages as JSON can contain JSON wrapped ACDCs, but other ACDC formats are possible. The follwing media types MAY be used when supplying ACDC credential payloads:¶
| Media Types |
|---|
| application/acdc+json |
| application/acdc+cbor |
| application/acdc+msgpk |
| application/acdc+cesr |
| application/said+cesr |
| Profile name | Profile ID |
|---|---|
| Legal Entity Identity (LEI‑ID) | ;profile="urn:vlei:lei-id" |
| Engagement Context Role (ECR) | ;profile="urn:vlei:ecr" |
| Official Organizational Role (OOR) | ;profile="urn:vlei:oor" |
| Legal Entity Authorizing Role (LAR) | ;profile="urn:vlei:lar" |
| Qualified vLEI Issuer (QVI) | ;profile="urn:vlei:qvi" |
| vLEI Root Authority (vRA) | ;profile="urn:vlei:vra" |
The various vLEI credential types can be specified in a media type using the profile option. Table 3 summarizes the profile identifiers for the various vLEI credential types. A comprehensive listing of vLEI profiles is provided even though some of the vLEI credential types are not anticipated by the vLEI binding to SATP at this time.¶
The following SATP wrapper examples show synthetic vLEI data:¶
{
"verifiedOriginatorEntityId": {
"vleitype": "verified-originator-entity-id",
"content": {
"mt": "application/acdc+json;profile=urn:vlei:leid"
// JSON serialization of an ACDC credential (LEID profile)
// CESR framing in plain text, not CBOR
},
"payload": "ACDC10JSON...SAID...i:did:keri:..."
// literal CESR/ACDC JSON text, not base64
}
}
¶
{
"verifiedBeneficiaryEntityId": {
"vleitype": "verified-beneficiary-entity-id",
"content": {
"mt": "application/said+cbor;profile=urn:vlei:leid;base64=true",
"cbt": false // no TN() CBOR tag; payload is base64 of raw CBOR
},
"payload": "QUNEQzEwQ0JPUkJhc2U2NEVuY29kZWQvLi4u"
// base64 of binary CBOR serialization of SAID credential (LEID profile)
}
}
¶
{
"senderGatewayOwnerId": {
"vleitype": "sender-gateway-owner-id",
"content": {
"mt": "application/acdc+msgpk;profile=urn:vlei:leid"
// cf, cbt, oid omitted here — optional in schema
},
"payload": "ACDC10MSGP...SAID...i:did:keri:..."
// MessagePack serialization of an ACDC credential (LEID profile)
}
}
¶
{
"receiverGatewayOwnerId": {
"vleitype": "leid", // always "leid" for this field
"content": {
"mt": "application/said+cesr;profile=urn:vlei:leid;base64=true"
// could also include cf, cbt, oid if known
},
"payload": "QUNEQzEwQ0VTUkJhc2U2NEVuY29kZWQvLi4u"
// ⟶ Base64 of binary CESR stream encoding of SAID credential
}
}
¶
{
"senderGatewayId": {
"vleitype": "sender-gateway-id",
"content": {
"mt": "application/acdc+cesr;profile=urn:vlei:ecr"
// cf, cbt, oid omitted — optional in schema
},
"payload": "ACDC10CESR...SAID...i:did:keri:..."
// CESR-encoded ACDC credential (ECR profile) as plain text
}
}
¶
{
"recipientGatewayId": {
"vleitype": "recipient-gateway-id",
"content": {
"mt": "application/acdc+cbor;profile=urn:vlei:ecr", // from vlei-media-type enum
"cf": 0,
"oid": "1.2.3.4.6" // actual OID for this credential type
},
"payload": "ACDC10CBORTESTSAIDi:did:keri:EXAMPLERGWNETID"
// raw CBOR bytes or base64/base64url string, but not CBOR-tagged
}
}
¶
{
"senderGatewayNetworkId": {
"vleitype": "sender-gateway-network-id",
"content": {
"mt": "application/acdc+cbor;profile=urn:vlei:ecr;base64=true",
"cbt": false // no TN() CBOR tag; just base64 of raw CBOR
},
"payload": "oWJ0ZXN0LWVjci1jcmVkZW50aWFs..."
// base64 of the CBOR-encoded ACDC (ECR profile)
}
}
¶
{
"senderGatewayNetworkId": {
"vleitype": "sender-gateway-network-id",
"content": {
"mt": "application/acdc+cbor;profile=urn:vlei:ecr;base64=true",
"cbt": false
},
"payload": "gEEBAQ..."
// base64 of CBOR-encoded ACDC (ECR profile)
}
}
¶
The following SATP wrapper examples show synthetic key data:¶
{
"originatorPubkey": {
"content": "application/jwk+json",
"payload": "{ \"kty\": \"EC\", \"crv\": \"P-256\", \"x\": \"...\", \"y\": \"...\" }"
},
"beneficiaryPubkey": {
"content": "application/cose;cose-type=cose-key",
"encoding": "base64", // explicitly flagging representation
"payload": "aEtNQnBRLi4u" // base64 of CBOR COSE_Key bytes
},
"senderGatewaySignaturePublicKey": {
"content": "application/jwk+json",
"payload": "{ \"kty\": \"RSA\", \"n\": \"...\", \"e\": \"AQAB\" }"
},
"receiverGatewaySignaturePublicKey": {
"content": "application/cose;cose-type=cose-key",
"encoding": "base64",
"payload": "aEtNQ3BBLi4u"
},
"senderGatewayDeviceIdentityPubkey": {
"content": "application/pkix-cert",
"encoding": "PEM",
"payload": "-----BEGIN CERTIFICATE-----\nMIIB...==\n-----END CERTIFICATE-----"
},
"receiverGatewayDeviceIdentityPubkey": {
"content": "application/pkix-cert",
"encoding": "DER",
"payload": "MIIB..." // base64 DER
},
"lockEvidenceVerificationKey": {
"content": "application/jwk+json",
"payload": "{ \"kty\": \"OKP\", \"crv\": \"Ed25519\", \"x\": \"...\" }"
},
"commitVerificationKey": {
"content": "application/cose;cose-type=cose-key",
"encoding": "base64",
"payload": "aEtNQ3BBLi4u"
},
"postCommitSecureChannelKey": {
"content": "application/jwk+json",
"payload": "{ \"kty\": \"EC\", \"crv\": \"P-384\", \"x\": \"...\", \"y\": \"...\" }"
}
}
¶
TODO Security¶
application¶
acdc+json¶
None¶
profile — Indicates the credential conforms to a specific schema registry (e.g., "vlei")¶
base64 — Indicates the CESR stream is base64-encoded for transport in JSON wrappers¶
charset — Optional; default is UTF-8¶
8bit; CESR text encoding is UTF-8 compatible and self-framing.¶
When base64=true, the CESR stream is base64-encoded for safe embedding in JSON.¶
CESR payloads are cryptographically signed and self-framing.¶
Signature verification is required to ensure authenticity and integrity.¶
Schema SAIDs must be validated against the GLEIF vLEI Credential Schema Registry.¶
Credential provenance must be anchored to the GLEIF Root AID via ACDC edges.¶
CESR supports dual text-binary encoding; this media type assumes CESR text encoding.¶
When base64=true, payloads are safely embeddable in JSON-based SATP wrappers.¶
Compatible with SATP, ACDC, and KERI protocols.¶
Composable Event Streaming Representation (CESR) — draft-ssmith-cesr-03¶
GLEIF vLEI Credential Schema Registry — GLEIF Registry PDF¶
GLEIF vLEI issuance and verification systems¶
SATP-compliant credential exchange platforms¶
Forensic credential chaining and audit systems¶
None¶
Magic number(s): None¶
File extension(s): .cesrj¶
Macintosh file type code(s): None¶
N. Smith spec-author@example.org¶
GLEIF IT Team vlei-support@gleif.org¶
COMMON¶
TBD, GLEIF IT Team¶
IETF / GLEIF¶
TODO acknowledge.¶