The BSV Paymail standard in a nutshell Paymail, published previously as BSV Alias, is a collection of protocols for Bitcoin SV wallets that lets parties identify each other and exchange messages securely, confidentially and with mutual authentication. Instead of using complicated addresses like 17Dx2iAnGWPJCdqVvRFr45vL9YvT86TDsn, Paymail employs simple payment handles that are formatted like an email address. The existing solution originated in a Bitcoin Association Wallet Workshop and featured input from Centbee, Conify, CopPay, ElectrumSV, Handcash, MoneyButton, nChain, The Workshop and Tokenized. In its current format, the solution has already been adopted by several companies, most prominently Centbee, Handcash and MoneyButton, as well as the RelayX exchange. Read more

TS 2021.010-30

Paymail

Standard fact sheet

Attribute	Description
Version	0.1 (2022 specification)
Authors	Andy Mee, Miguel Duarte
Reviewers	Austin Rappaport, Curtis Ellis, Dan Dragon, Darren Kellenschwiler, Lorien Gamaroff, Rafa Jimenez Seibane, Will Devine, Xiaohui Liu
Tags and Categories	Client Services, SPV Client services
Publication Date	12 July 2022
Valid Until	n/a
Copyright	2022 Bitcoin Association for BSV
IP Generation	US Patent Application No. 16/384,696 filed on 15 April 2019 International and other national filings claiming priority from, and covering the same invention(s) as 16/384,696 The patent application(s) are currently owned by nChain. It is the intention of nChain to assign or licence the patent rights to the Bitcoin Association. Until such an event, nChain shall offer the patent rights under a patent pledge that is equivalent to pledge made in respect of the Merkle Proof Standardised Format specification. In the event that the patent rights are transferred to Bitcoin Association, Bitcoin Association will upheld the same pledge.
Known Implementations	TBC Record your implementation of the standard using the form on the menu bar.
Known Implementations (2019 specification)	Money Button, HandCash, CentBee, RelayX, Simply.cash, DotWallet, Bit.sv, myPaymail, Volt, BaeMail, SV Pay, BSV Alias (library), TonicPow, Paymail Inspector
Applies To	Wallets, exchanges, merchants, consumers
BRFC ID	TBC
Acknowledgements	The authors wish to acknowledge the significant contributions of the reviewers within the working group both for their feedback and their forward planning on extensions to help mitigate the risks identified in this document. Further, the authors acknowledge all participants of the March 2019 Wallet Workshop that led to the original 2019 BSV Alias/Paymail Specification: Ryan X Charles, Miguel Duarte, Maria Eugenia Lopez (Money Button) Jeppe Nejsum (Coinify) Lorien Gamaroff (CentBee) Ina Samovich (CopPay) Rafa Seibane, Alex Agut (HandCash) Roger Taylor (Electrum SV) Simon Ordish (Workshop) Steve Shadders, Andy Mee (nChain)
Status	Published
Visibility	Public

Background

There is a need for parties to be able to identify each other and exchange messages securely, confidentially, and with mutual authentication. A number of technologies work together to deliver this need, with Paymail at the core.

The Paymail protocol solves for service location and capability discovery based upon a human-friendly identifier, formatted similar to an email address. It defines a trust and security model, and provides guidance under which the above message exchange properties may be achieved. The protocol also defines an extension mechanism that allows for applications across a range of industries to benefit from the core Paymail features.

Problem Statement

A peer-to-peer payments model was first demonstrated in early versions of Bitcoin, where parties could exchange transactions by IP address. This early functionality was rightly deprecated as the implementation was insecure. There was no mutual party authentication, no confidentiality, and no message integrity, meaning it was susceptible to many well-known, well-understood and often unsophisticated failure modes, through both malicious and erroneous activity.

As a result, applications became dependent on scanning the blockchain for transactions of interest, detecting scripts containing hashes of public keys to which the interested party held the private key. This is an application and network scalability bottleneck, and is in direct contrast to the SPV model of light client applications that scale only with their own data and usage volumes, not in line with global usage of Bitcoin.

As well as the scalability issue, this dependence on scanning the blockchain left no room for applications to coordinate in the construction of a transaction. A partially constructed transaction, for example a transaction spending multisig funds that has not yet been signed by the required threshold of signatories, cannot be communicated on chain directly as it would not be valid until all signatures are collected. An unsophisticated means of communication could be to embed the incomplete transaction as data inside another carrier transaction, now that restrictions on standard transactions and data sizes were lifted. This approach however, still does not solve for scalability, as interested parties must again scan the blockchain to search for the needle in the haystack.

Wallets attempting anything more complicated than P2PKH transactions chose features over interoperability; for example several wallets supported multisig transactions of various forms, however the wallet vendors implemented application-specific flows to enable communication between signing parties, which meant that these features were only available within the walled garden of individual service providers.

Some flows, such as threshold signature setups, depend upon the confidentiality of messages exchanged between peers during the setup phase, and upon prior authentication of the counterpart to the message exchange; this is directly at odds with using Bitcoin as a message transport. Other flows, for example transaction negotiating via a payment channel, lose their purpose as their benefit is lost when messages are exchanged inside on-chain transactions.

With the 2019 Genesis protocol upgrade, Bitcoin SV deprecated P2SH addresses. Whilst both P2PKH and P2SH addressing schemes have weaknesses, specifically in privacy leaks through address re-use and the aforementioned scalability concerns, they were often used as a form of addressing, similar to a bank account number and sort code. Neither P2PKH nor P2SH were user-friendly, however, as they were long alphanumeric strings, frequently re-used, and difficult to communicate outside of copy/paste scenarios.

Objectives

This standard addresses the problem of enabling secure, confidential, authenticated message exchange between Bitcoin applications, including user-friendly addressing, service discovery, feature negotiation, and a permissionless extension model for arbitrary application and business flows. These different flows are codified by extensions, and so this standard provides an extension mechanism for this purpose. Extensions inherit the trust and security model, and all other functionality, of the core Paymail standard.

Scope

In Scope

• Addressing
  • Hosts/service providers
  • Users of those hosts/service providers
  • Logical entities, for example company departments
• Service Discovery
  • Host discovery
  • Feature negotiation
    • AKA capability discovery
    • Extensions
• Secure message exchange
  • Mutual authentication
  • Confidentiality
  • Message integrity/tamper evidence
• Extension mechanism
• Federation model
• Flexible hosting/deployment model
  • Self-hosted
  • Managed services

Out of Scope

• Anything not related to interoperability between applications.
  The internal operation of a single application is not considered by Paymail. For example, wallets have to deal with all of the following, which are all out of scope as they do not affect cross-wallet interoperability flows:
  • UTXO set management
  • transaction construction
  • transaction submission
  • confirmation management
  • script and solution construction
  • key management, safety, backup, recovery
• Elements of the 2019 specification that are now deemed extensions (see below and decision log)
• Extensions that have been developed by industry since the launch of Paymail

Future work

As the standardisation of an existing specification with industry adoption, extensions defined by standards subsequent to this standard that support specific flows around peer-to-peer payments, public key infrastructure (key exchange) and more. Each of these extensions solves for a specific business need by leveraging the features and capabilities offered by this core Paymail standard.

A number of ideas and extensions of interest have been identified by this Working Group:

• Direct Payment Protocol (aka BIP27x)
• P2P/SPV payment flows (MAPI, Transaction Ancestors)
• Contact/Profile Cards
• Token support
• Proliferation of asynchronous message flows (202 Accepted + Callbacks)
• 2FA, OTP, YubiKey support
• Bulk payment destination resolution
• Blockchain credential pinning

Methods and Concepts

This standard draws together a number of well-understood and widely deployed technologies to define a protocol that solves for the concerns defined in the previous sections of this document within a trust, security and federation model that simultaneously allows for autonomy within organisations and entities whilst enables and encourages interoperability between them.

Paymail is a federated protocol, comprising of domains, hosts, and aliases. Domains are public DNS names, <domain.tld>, for example example.org. Alias addressing takes the form <local-part>@<domain.tld>, for example [email protected].

A Paymail host is a service that responds to queries on behalf of a domain owner. A host is identified by a public DNS name. For a given domain name, the responsible host may be a host identified by the same domain name, or the responsibility for the domain name may be delegated to another hostname, at the sole discretion of the domain owner.

A Paymail domain may have responsibility for multiple aliases. An alias represents a single logical entity, for example a user or company department. A logical entity may have multiple aliases, at the discretion of both the entity and the host service provider. A Paymail host may service one or many domains.

The authority and trust root of the Paymail protocol is the domain owner. This is very similar to email, where companies, organisations and individuals may each have their own domain name in the public DNS system. Federation is an important aspect of the Paymail trust model, as it allows a domain owner the flexibility to either provide their own infrastructure, or delegate to a service provider of their choosing. Service providers are incentivised to operate in a trustworthy manor, as the protocol provides domain owners with simple mechanisms for switching to new service providers, which leads to lost revenue for the losing provider. Further, a managed service provider would typically operate under a contract with the domain owner, under which both acceptable behaviours and liabilities may be expressed on both parties, with breaches ultimately arbitrated and resolved in the existing legal system.

Under this trust model, a domain owner is the ultimate authority for information served in the context of that domain. The domain owner nominates a responsible host to actually service the domain. The responsible host may be under the control of the domain order, or may be delegated to a third party service provider. On a case by case, flow by flow basis, information may be attested to by the host or the alias that is the subject in question. Thus, both <domain.tld> and the responsible host for <domain.tld> are considered identifiable entities similar to any <local-part>@<domain.tld> alias.

The local-part refers to an alias within the authority of the federated domain.tld host. The explicit local part _ (ASCII underscore, decimal 95, hex 0x5f) is reserved to refer to the Paymail host itself, and not a specific identity for which the host is responsible. The host alias, therefore, is _@<domain.tld>, for example [email protected].

Paymail clients message peers via JSON over HTTP APIs. Peers, identified by <local-part>@<domain.tld>, must ensure that they are communicating with the expected peer, and not an impostor or a malicious actor intercepting communications (via a man-in-the-middle attack or similar). Resolution via the Service Discovery protocol leverages the following technologies to provide this security:

• DNS
• DNSSEC
• TLS and the Root CA structure

Clients may authenticate services by leveraging this existing internet infrastructure when sending messages. As each Paymail alias is represented by a host service, host services may in turn authenticate clients by performing service discovery on the alias claimed in the client message. Message signing may be used to provide both client-to-server and server-to-client message integrity, with bidirectional alias resolution confirming with the respective authoritative Paymail host that the keys used in message signing do belong to the claimed alias.

In this base protocol, messages are confidential between peer users and their respective Paymail hosts. As the Paymail model nominates each federated domain as its own ultimate authority, and the responsible host may attest to messages on behalf of clients, this is considered sufficient for the Paymail confidentiality model. For some extension flows, host visibility of the messages is actually a feature; for example, payment message flows enacted via VASP-hosted Paymail hosts need to be able to inspect messages in order to satisfy FATF Travel Rule requirements. It is noted, however, that extensions are expected that introduce a Paymail-backed key exchange mechanism and SPV Channels to provide end-to-end encryption, and therefore client-to-client confidentiality, excluding the host from the conversation, for scenarios where this is desirable.

Specification

Entity Model

Paymail is a federated model of domains and hosts, with each host having a private and out-of-scope client-server API with its respective clients:

Domains are trust and authority roots within the federation model. They are represented by a host service.

Hosts are always-online services that expose both a public JSON-over-HTTPS Paymail API and a private and implementation-specific client API. It is expected that vendors and service providers supply both the host and the client, or at least client libraries, for a given host implementation. Hosts are identified by a public DNS name <domain.tld>.

Clients may be always-online or they may have partial connectivity, such as mobile or desktop computing devices. They are paired with a host, for whom the host service performs the role of authority and trust root.

Users, defined as individuals, organisational departments, or any other logically addressable entity, possess a client, either manage a Paymail service or hold an account with a service provider, and are addressable via an alias of the form <local-part>@<domain.tld>.

Both users and hosts may query the public Paymail API provided by peer hosts. The client-server API is a private interface between a single host and its clients, and is not specified here.

Domain Specification

A Paymail domain is an ordinary domain alias in the public DNS system. The DNS servers for a Paymail domain may be configured in one of two ways:

Authoritative Configuration

In this configuration, the authoritative DNS servers for a domain MUST contain either or both of an A (IPv4) or AAAA (IPv6) record, resolving to the IP address of the responsible Paymail host. In this configuration the authoritative domain name and the responsible host domain name are identical.

Delegated Configuration

In this configuration, the authoritative DNS servers for a domain MUST contain an SRV record indicating the DNS name of the responsible host to which domain authority has been delegated. When using delegated configuration, DNS records MUST be secured by DNSSEC.

The SRV record is composed of the following parameters:

Parameter	Value	Specification
Service	_bsvalias	Mandatory
Proto	_tcp	Mandatory
Name	<domain.tld>.	Mandatory
TTL	3600	Recommended, Domain Owner Specified
Class	IN	Mandatory
Priority	10	Domain Owner Specified
Weight	10	Domain Owner Specified
Port	443	Mandatory
Target	<delegated.host.tld>.	Domain Owner Specified

Host Specification

• Paymail hosts MUST provide a public HTTPS API conforming to this standard
• Hosts MUST NOT serve the API over insecure HTTP connections; TLS MUST be used
  • The TLS certificate CN (or any certified alternate/wildcard CN) MUST be valid and MUST match the public DNS name of the host
• A host SHOULD be configured with either Authoritative Configuration or with Delegated Configuration. A host SHOULD NOT advertise both Authoritative and Delegated configuration DNS records.
• A JSON Capabilities Document MUST be present on the API server
  • The URL MUST be /.well-known/bsvalias.json
  • The document SHOULD be served with the application/json content type
  • The structure of the document must contain, at a minimum, the following:

{
  "bsvalias": "1.0",
  "capabilities": {}
}

• Hosts SHOULD advertise supported extensions within the capabilities element, where each child key in the capabilities map is the BRFC ID of the extension defining the supported flow, and the value of that key is determined by the same BRFC document
  • Hosts MUST use the tokens {local-part} and {domain.tld} to identify the local part and domain name respectively when serving parameterised template strings inside the Capabilities Document
  • Hosts MAY choose to serve endpoints listed in the Capabilities Document from other hosts. In this case, the alternate hosts MUST serve those APIs via TLS, the TLS certificate MUST be valid, and the certificate CN MUST match the host declared in the Capabilities Document
• Further extension-specific endpoints MUST be made available at the locations described in the Capabilities Document

Client Specification

• Clients SHOULD be paired with an authoritative or delegated Paymail host service
• Clients SHOULD act on behalf of an addressable entity in the Paymail system
• Clients MUST support TLS and DNSSEC
• Clients MUST follow the procedures outlined in the following Service Discovery section

Service Discovery

A Paymail client may attempt to locate the responsible host service for a peer via the peer handle. Service discovery is performed in two phases, host discovery and capability discovery. Once these phases have completed, extension-specific messages may be exchanged between clients, their respective hosts, and their counterpart hosts.

A Paymail user Alice, with the alias [email protected], who wishes to exchange messages with Bob, who has alias [email protected], would perform the following steps:

Host Discovery

• Alice’s client performs a DNS lookup of the domain portion of Bob’s alias, example.com..
• If an SRV record is present, then example.com. is using Delegated Configuration:
  • If the DNS response was secured with a valid DNSSEC signature chain:
    • Perform another DNS query for the FQDN identified in the target field of the SRV record
    • If A/AAAA records are present, select any appropriate for the client network stack and proceed to Service Discovery with the target FQDN and resolved IP address
    • If neither an A nor AAAA record is found, the host is not configured correctly and Host Discovery has failed
  • If the DNS response was not secured with a valid DNSSEC signature chain, ignore the SRV record and attempt to proceed following Authoritative Configuration rules
• If no SRV record is present, or an insecure SRV record was served, then example.com. is using Authoritative Configuration:
  • If A/AAAA records are present, select any appropriate for the client network stack and proceed to Service Discovery with the example.com. FQDN and resolved IP address
  • If neither an A nor AAAA record is found, the host is not configured correctly and Host Discovery has failed

Capability Discovery

• Having resolved both a responsible host name and IP address by following the Host Discovery process, Alice’s client proceeds to query the host responsible for example.com.
• Alice’s client makes an HTTPS GET request to the responsible host for the Capabilities Document at https://<responsible-host.tld>/.well-known/bsvalias.json
• The client verifies that the connection is secured using a valid TLS certificate and that the CN (or any certified alternate/wildcard CN) match the expected responsible host FQDN
  • If there is a mismatch in expected versus actual FQDN, Capability Discovery has failed
  • Clients MAY follow HTTP 3xx redirects as long as the response from <responsible-host.tld> as long as they are served over HTTPS and the certificate used is valid and the CN matches
• Alice’s client confirms that the response type is one of 200 (OK) or, if passing an appropriate caching header, 304 (not modified)
• If any other HTTP response code is encountered, Capability Discovery has failed
• Alice’s client proceeds to inspect the Capabilities Document for extensions supported both by the local client and Bob’s responsible host

Protocol Flow

Having completed Host Discovery and Capability Discovery, Alice’s client and Bob’s responsible host continue to exchange application-specific message exchanges determined by extensions to this core standard.

Extension Mechanism

Any industry participant may build application or business specific flows on top of the Paymail base in order to leverage the inherent aliasing, service discovery, capability discovery, and authentication features of the standard. Extension authors should document their end-to-end message flows, design appropriate communications channels (for example, provision additional HTTP API endpoints), calculate their BRFC ID, and expose the extension through the Capabilities Document on their Paymail hosts. Extensions are declared by extending the capabilities element. For example, the 2019 Payment Destination (Payee Approvals) specification, with BRFC ID 3d7c2ca83a46, is declared through the following element:

{
  "bsvalias": "1.0",
  "capabilities": {
    "3d7c2ca83a46": {
      "callback": "https://example.org/{alias}@{domain.tld}/payment-destination-response"
    }
  }
}

The specific schema of the JSON element attached to the named BRFC ID key of the capabilities object is defined by the extension whose BRFC ID matches the key.

Values within the extension-defined JSON element may be templated; note the use of the {alias} and {domain.tld} tokens in the callback value in the above example. Clients reading the capabilities document must substitute these tokens for the correct local part and domain wherever they appear before issuing requests. Applied to the above example, when substituting the callback value for [email protected], the tokens alice and example.org should be substituted into the string, yielding https://bsvalias.example.org/[email protected]/payment-destination-response.

Server Authentication

Paymail clients establish the authenticity of hosts they communicate with by leveraging existing, well understood and widely deployed internet protocols.

The DNS system alone is not considered secure. DNSSEC, now widely supported, mirrors the Root CA structure used to verify TLS certificates. Each DNS server in a recursive chain from some.example.net., and its parents example.net., net., and . (the root servers), serves signed records where the signing keys are published by the DNS server responsible for the parent zone and verified by the DNSSEC client, with recursive verification all the way back to the root servers. Any attempt to tamper, intercept, or MITM a DNS response will invalidate the signatures over DNS records or break the recursive signature chain. For this reason, DNSSEC is required for domains using Delegated Configuration, as the SRV record would otherwise form an insecure point in the protocol. Note that DNSSEC SHOULD be used for Authoritative Configuration, however this is not mandatory. Under Authoritative Configuration, any attempt at tampering with A/ AAAA DNS responses to redirect clients to a third-party host would be detected by the subsequent TLS CN checks.

TLS/HTTPS provides similar authentication for host web services. A server attempting to impersonate a domain name like example.org. would not be in possession of a valid TLS certificate with accompanying certificate chain linking it back to one of the internet’s Root Certificate Authorities. Further, TLS provides confidential communication between clients and servers using authenticated message encryption.

This construction authenticates the Paymail host to the client. It does not, on its own, provide authentication of the client to the Paymail host. Mutual Party Authentication is required in order to authenticate the client to the Paymail host.

Mutual Party Authentication

Whilst the measures above allow a client to verify the authenticity of a Paymail host, they do not allow for hosts to verify the authenticity of a given client. In many scenarios it is desirable for clients to make requests in the context of a Paymail user, identified by an alias <local-part>@<domain.tld>, and further, that Paymail hosts may verify that such a request originates from the user identified by the supplied alias.

In order for a client to authenticate itself to a Paymail host, requests made by the client MUST include the client’s Paymail alias, the request MUST be signed, the public key and signature MUST be included in the request, and the client MUST be associated with a Paymail host that supports Mutual Party Authentication. Signature schemes and message enveloping are discussed later in this section.

Paymail hosts perform one of two roles during Mutual Party Authentication, depending upon their role in the specific request/response flow:

• The authenticating host is the Paymail host that has received a request from a client. In this role, the Paymail host first verifies that the client signature over the request message is valid for the supplied public key, and then verifies that the supplied public key belongs to the Paymail alias given in the request. The verifier temporarily acts as a Paymail client, and requests confirmation from the client’s responsible Paymail host (the confirmer) that the key belongs to the declared alias.
• The client-authoritative host is the Paymail host associated with the client making a request against the verifier host. In this role, the host provides an authoritative statement on the relationship between a Paymail alias for which it is responsible, and the association of a public key with that Paymail alias.

Paymail hosts MAY support either, both, or neither of the authenticating host and client-authoritative host roles.

⚠️ TODO: Generate actual BRFC IDs and substitute them into the Capabilities Document snippets that follow.

Hosts indicate their support for client authority, and requirements for authentication, through their Capabilities Document, by declaring an element with the capability ID ____TODO____:

{
  "bsvalias": "1.0",
  "capabilities": {
    "___TODO_1___": {
      "authority": {...}
      "requirements": {...}
    }
  }
}

Verifying Client Authentication

Context: Having verified the correctness of the request message signature, an authenticating host proceeds to verify the authenticity of the signing key used with respect to the Paymail alias claimed within the request.

A client-authoritative host’s Capabilities Document defines an endpoint that can be used to query the association between an alias and a public key:

{
  "bsvalias": "1.0",
  "capabilities": {
    "___TODO_1___": {
      "authority": {
        "keyAlias": "https://example.org/paymail/mpa/key?scheme={scheme}&alias={alias}@{domain.tld}&key={key}"
      }
    }
  }
}

To verify the relationship between a signing key and a Paymail alias, an authenticating host MUST:

• Perform Host Discovery and Capability Discovery for the Paymail alias supplied by the client request
• Inspect the Capability Document for an endpoint URL contained in the capabilities.___TODO_1___.authority.keyAlias string element of the Capabilities Document supplied by the client-authoritative host
• Issue an HTTP GET request to the endpoint defined in the previous step. An authenticating host MUST substitute {scheme}, {alias}, {domain.tld}, and {key} tokens for the values supplied by the client.

A client-authoritative host must respond with either a 204 No Content, confirming that the key is associated with the alias, or a 404 Not Found, refuting the relationship. Upon receipt of a 404, an authenticating host must not proceed with servicing the client request, instead returning 401 Unauthorized to the client.

This standard does not mandate any mechanism for client-authoritative hosts to become aware of the public signing keys used by clients; it is both envisaged for and typical of Paymail hosts to be supplied by the same vendor as Paymail clients, and so any integration between the two is beyond the scope of this standard. There are many possible solutions, from shared-bag-of-keys to root key with derivation to single static signing key. This standard RECOMMENDS that Paymail hosts do not ever have access to client private key materials, as this presents an increased surface area for unauthorised access to – and use of – client private keys.

Specifying Authentication Requirements

Paymail hosts that require clients to participate in Mutual Party Authentication indicate this requirement via the capabilities.___TODO_1___.requirements element. The requirements element contains an entry for each capability for which Mutual Party Authentication is required. For each capability, the BRFC ID of the supported signature scheme/message envelope pairing (described in the next section) is declared. Clients SHOULD inspect this element during Capability Discovery in order to determine the Mutual Party Authentication requirements of the host, and SHOULD conform to the requirements or not proceed with requests. Note that the decision made by the client can be either because the server indicates requirements that can not be fulfilled, or that the server does not indicate requirements where the client believes such a requirement should be in place.

The requirements element’s child elements describe which capabilities described by the authenticating host’s Capabilities Document require Mutual Party Authentication. Requirements apply to all sub-sections of a capability identified by a single BRFC ID in full.

{
  "bsvalias": "1.0",
  "capabilities": {
    "010101010101": {...}
    "020202020202": {...}
    "030303030303": {...}
    "040404040404": {...}
    "___TODO_1___": {
      "requirements": {
        "010101010101": "aabbccddeeff",
        "020202020202": "aabbccddeeff"
      }
    }
  }
}

In the above example, the authenticating host’s Capabilities Document declares support for four capabilities, with BRFC IDs 010101010101, 020202020202, 030303030303, 040404040404, and ___TODO_1___ (the Mutual Party Authentication capability). The capabilities.___TODO_1___.requirements child elements indicate to clients that the capabilities required by 010101010101 and 020202020202, will only be served to clients who authenticate themselves using the scheme defined by BRFC ID aabbccddeeff. The capabilities defined by BRFC IDs 030303030303 and 040404040404 are not listed as requiring Mutual Party Authentication.

In addition to responses defined by the capabilities for which authentication is a requirement, the authenticating host may return 401 Unauthorized in the cases that the client either did not supply required authentication information, or that information was invalid. The authenticating host may include a WWW-Authenticate header with the <auth-scheme> set to the BRFC ID of the supported authentication scheme.

Further, clients should expect a 401 Unauthorized response and an optional WWW-Authenticate header for endpoints not listed as requiring Mutual Party Authentication in the Capabilities Document. Authenticating hosts SHOULD ensure that the requirement is declared in the capabilities document, however, the requirement MAY be communicated solely at the point an unauthenticated client request is received. This allows for authenticating hosts to be compliant with this standard in the event of a misconfiguration of the Capabilities Document, and allows for clients to recover and continue in the event of encountering such a misconfigured host.

Specifying Signature Schemes and Message Enveloping

This standard recognises that there is no one-size-fits-all decision that can be made for either signature schemes or message enveloping. The Paymail standard therefore defines neither, instead deferring specific pairings of signature scheme and message enveloping to Paymail extensions.

The choice to defer this to extensions was taken for the following reasons:

• Different capabilities will have different needs and requirements. For example, a web-based Paymail wallet client may prefer to use the same message signing scheme as Bitcoin itself in order to keep the code size -and therefore initial application download overhead – as small as possible. Other wallets may prefer to use an entirely different signing scheme in order to clearly enforce the separation of keys between message signing and the security of on-chain funds.
• The security of any given scheme may be degraded by research without warning. Deferring the choice of signature schemes to extensions allows for extensions to have their own lifecycle and deprecation timelines without affecting this core standard.
• New or alternative signature schemes that best fit a given application flow may be used without amending this core Paymail standard.
• This standard is not required to mandate – and therefore restrict – request/response message formats, allowing capability authors and designers flexibility in choosing an appropriate solution for their use case, such as carrying message authentication data in HTTP headers, packing signed messages into HTTP body envelopes, query string parameters, or any other mechanism for carrying Mutual Party Authentication fields.

In order to provide a complete solution, the authors of this standard present the following extensions alongside this base Paymail standard, with the caveat that these are separate standards and may follow a different lifecycle to this base standard:

⚠️Replace these with the actual BRFC IDs once generated

• 001122334455 ECDSA + JSON Envelope
• 6677889900aa ECDSA + HTTP Headers

Confidentiality

Paymail achieves confidentiality between trust roots as defined by the trust model; confidentiality is provided by TLS between clients and counterpart hosts. This is achieved by using internet standards to protect traffic from eavesdropping, interception, man-in-the-middle attacks, and similar.

The core Paymail standard does not provide end-to-end confidentiality between two users of the system. It is, however, possible to layer end-to-end confidentiality over the top of Paymail. Those who wish to achieve true end-to-end confidentiality could extend Paymail with capabilities that provide:

• Key exchange endpoints. For situations where the Paymail host is under the control of the end user, such as users who own their own domain and host infrastructure (and are therefore not using a shared/managed/third-party host), the host could be provisioned with either a bag of single-use keys, or a derivation mechanism from a root public key, in order to provide both ephemeral and static keys to be used for key exchange to derive a symmetric key for encrypting messages.
• SPV Channels integration. The SPV Channels project provides a system whereby assuming secure key exchange, end-to-end message confidentiality is provided. This integration would leverage Paymail to provide endpoint the address of an SPV Channels host to which the user has sufficient permissions to exchange messages with peers.

Note that this is not a comprehensive guide and should not be considered a complete set of steps required to achieve end to end message confidentiality.

Glossary

Term	Definition
Alias	Identifier for a logical entity in the Paymail protocol Takes the form <local-part>@<domain.tld>
BRFC	Bitcoin SV Request-for-Comments A way of uniquely identifying a specification document without a central numbering authority
BSV Alias	Paymail (synonym) The working title for the 2019 specification deprecated by this standard
CA	Certificate Authority
Capability Discovery	Feature Negotiation (synonym) This term was used by the 2019 specification; see Feature Negotiation
DNS	Domain Name System The naming system underpinning the public internet
DNSSEC	DNS Security Extensions Specifications for securing the public internet DNS
ECDSA	Elliptic Curve Digital Signature Algorithm The digital signature algorithm used by Bitcoin and the 2019 BSV Alias specification
Feature Negotiation	Referred to as Capability Discovery in the 2019 specification A process through which two computer systems may determine a set of mutually supported features
FQDN	Fully-Qualified Domain Name An absolute domain name, in the form some.example.org., including trailing .. Opposite of relative domain names, whose suffix may be inferred by a client.
IANA	Internet Assigned Numbers Authority Standards organisation governing several aspects of the public internet
IETF	Internet Engineering Task Force A standards organisation that produces open standards for internet protocols
Local Part	An identifier provided within the scope of a single Paymail service, expressed in the form of a human-readable alias [email protected]
MITM	Man-In-The-Middle A form of attack in which the attacker positions themselves between two corresponding parties and intercepts, drops, snoops, modifies or otherwise maliciously handles messages between those to parties
P2PKH	Pay-to-Public-Key-Hash A type of script used to protect on-chain funds where the funds may be spend by producing a signature that validates against the identified public key
P2SH	Pay-to-Script-Hash A complex type of script used to protect on-chain funds (deprecated 2019)
RFC	Request For Comments Standards documents produced by IETF working groups
SRV	Service Record A type of DNS record that allows domain owners to specify the location (host and port) of arbitrary TCP and UDP services
TLS	Transport Layer Security A cryptographic protocol for secure communications over a computer network
UTXO	Unspent Transaction Output Bitcoin that may be spent subject to satisfying the spending conditions set by the originator
UTXO Set	The complete set of all Bitcoin that may be spent by future transactions
XMPP	Extensible Messaging and Presence Protocol A federated instant messaging protocol

Limitations

This protocol does not offer a security model that attempts to protect against nation-state threats. As a protocol that builds upon DNS, DNSSEC and TLS, infrastructure serving these technologies, from root servers to certificate authorities, are subject to the laws and enforcement orders of their host nations. Tampering, interception, subversion and adversarial behaviour from these sources are outside of the protections offered by this protocol.

Presently this protocol offers no provision for identifiers outside of the [email protected] format. The rise of mobile computing has led to some markets treating telephone number as the primary identifier, with notable examples such as WhatsApp and WeChat demonstrating the consumer appetite for these schemes. It is not straightforward to integrate telephone numbers with the federated identifiers featured in this standard, however this is an area already identified for future research and development.

Despite being listed as a goal, Mutual Party Authentication is not formally specified in this document. The specific choice of scheme and construction used to achieve Mutual Party Authentication, and any Confidentiality requirements, will differ from scenario to scenario, and from extension to extension. Guidance has been provided to implementation and extension authors for achieving both of these properties.

Risks

A number of risks have been identified. These are documented below.

NOTE: Mitigation strategies and guidance are required before publication of this standard.

Centralisation and Fragmentation

It is expected that in the long term, market forces will lead to consolidation amongst service providers, similar to those experienced by email service providers over the last few decades.

It is the authors’ belief that this will reach equilibrium with a few major providers, offering economic efficiencies from their scale. The model is not compromised as the federated nature of Paymail, coupled with an appropriate mutual party authentication scheme, will not collapse the system to a state where a few large providers with mutual peering agreements refuse interoperability with independent providers as has happened with email; this mutual party authentication may be leveraged to prevent the kind of spam that has plagued email and led to this fragmentation. It is anticipated that the option to move custom between service providers will always remain, as will the option to self-host a Paymail service, should no service provider satisfy a given customer’s requirements.

Nonetheless, sufficiently large service providers may attempt to form some sort of customer lock-in via a walled garden approach, in which the service provider abandons the Paymail protocol – and all forms of interoperability – once a certain market size has been reached; this has plagued other federated systems, notably those supporting XMPP, in the recent past.

Fragmentation may occur if implementations do not achieve compatibility and interoperability, reducing the value of the protocol. Mitigation of this risk include the availability of conformance testing frameworks and an optional trademark-enforced certification strategy. Examples of technologies whose mark is protected and whose use is restricted only to certified parties include Wi-Fi and Bluetooth.

Mitigation:

Currently there is no specific mitigation for this risk.

However, there are three possible solutions that over time might become viable mitigations.

 (1) Open Source Software & High Adoption

If the Paymail specification is commonly used in open source software, similar to WordPress or OpenSSL, it will become adopted and increasingly harder for Centralization & Fragmentation (“CF”) to occur. In order to mitigate CF using open source software, the following needs to occur:

• Popular “all-in-one” software solutions for the “end-user” or “novice” developer (IE: WordPress)
  • Out of the box – it just works – easy to install and great documentation & videos
• Really robust and flexible libraries in all the top software languages (JavaScript, Java, C, Go, PHP, etc)
• Deep integrations for both the libraries and “all-in-one” software into all big providers (Data Analytics, Cloud Providers, Logging & Metrics, Etc)
• MetaMask for Paymail (front-end & back-end self hosted solution using SPV)

 (2) Large Public Enterprise Adoption

Large enterprise businesses adopting the Paymail specification and using the libraries that are TSC approved will help mitigate CF. Enterprise adoption should be seen as in conjunction with the open source initiative, as the enterprise companies would be using a lot of the open source libraries and contributing as needed, thus growing the overall Paymail adoption.

 (3) Rewarding Paymail Implementations & Usage

Using the flexible nature of Paymail extensions, a Operator Fee Configurator (OFC) could be used to help incentivize the Paymail operator for hosting and running a Paymail service with many different ways to earn or charge for using the service. In conjunction with that extension, a different extension Public Service Provider Broadcast (PSPB) could be reaching out to the TSC or Bitcoin Association and notifying them about the new Paymail service that is running. The provider might be rewarded from the Bitcoin Association or at minimum listed publicly in different Paymail directories.

Regulatory Concern for Wallets

The provision and operation of a Paymail host with payments-related extensions by a wallet provider may be seen as an indicator that the wallet provider is acting as a money services provider and may therefore fall under certain financial services regulations. Implementations should seek their own advice on regulation and their responsibilities within their operating jurisdiction.

Mitigation:

⚠️ You should seek you own legal advice at all times when running a public Paymail service.

After seeking legal advice, there are additional safeguards that could be used to help mitigate Regulatory Concerns for Wallets (RCW).

 (1) Strict Paymail Rules

Only allow transactions from accepted and trusted domains that have been previously researched, reviewed and safe to transact with. Using this strict rule will ensure that you are working with honest, reputable and legally focused providers which in turn should lower your risk exposure.

 (2) Using the “PCAD” Extension

This extension would allow the operator to set thresholds and requirements from different providers. As an example, you could require that the provider has AML or KYC enabled, thus rejecting any other providers or transactions.

Malicious Service Providers

Whilst the domain owner is the ultimate authority within the Paymail system, it is believed that many domain owners will delegate to a smaller number of service providers. The service provider in this role has the opportunity to act maliciously within the Paymail protocol to the detriment of the domain owner and all identities represented by managed aliases. Domain owners should consider carefully which service providers they delegate their domains to and should be aware of the risks of doing so.

Mitigation: 

⚠️ Research the provider, their security disclosures, certifications and other clients. Trust no one.

Anytime you are using a 3rd-party provider you are exposing yourself to certain risks.

As an example, hosting in the cloud using AWS is a risk (AWS employees or a hacker in AWS could compromise your system). However, there are industry standard approaches to mitigate a lot of these risks when using Cloud providers.

Using a 3rd-party Paymail provider comes with certain “known” risks but also some inherent benefits. If you’re using a well established provider, it should be more secure then running your own Paymail implementation. The 3rd-party provider is responsible for all the overhead, growth pains, security and other hurdles involved with scaling a reputable Paymail service.

Here are some “known” attacks that a 3rd-party provider or Hacker could do:

 (1) Attack: Response Hijacking or Redirection (server access only)

The MSP or Hacker is attempting to alter the response body from the Paymail requests.

(a) You delegated your DNS to the MSP

If you delegated your DNS, then you would need signatures both in DNS and on-chain to verify all the DNS records. You could have a private key that you use to write those DNS records that match a signature but you could put it on-chain where it could be verified for authenticity.

(b) You did NOT delegate your DNS

If you did NOT delegate your DNS then the response body would not match the signature (if you are using the MPA extension – TBD). Both the DNS & server would need to be comprised in order to change the response & signature (however, the signature key being changed might raise alarms if Paymail providers were caching that signature key using the MPA extension – TBD)

 (2) Attack: Alias Reassignment (server & database access)

The MSP or Hacker is changing an Alias in the database to point to a compromised Alias.

(a) Attacker changes an Alias in the database (no private keys)

Using the PAI extension, the new transactions should get alerted as it would detect changes in the PKI to Alias relationship. On every transaction the PKI and the output should be compared and validated.

(b) Attacker changes data in the response body

Using the MPA extension (TBD), the response should still match the known public signature key (which it would NOT match since the DNS is not compromised)

(c) Attacker has access to the private keys

The attacker could create a transaction and steal all associated funds using a basic bitcoin transaction. Follow the industry best practices for storing sensitive API tokens, auth tokens and use Multi-Sig or Threshold signatures if possible.

 (3) Attack: DNS Records Altered (dns access)

If the Paymail operator delegated their DNS or Domain settings to the MSP then the MSP could change your DNS records to alter signature keys or different entry points for the domain. The only way to mitigate this attack would be to use a 2FA or Bitcoin key in the configuration of the Paymail service that would detect a DNS change not being signed by the Paymail owner. All DNS records could have corresponding signatures showing that it was signed by a certain signature key.

⚠️ There are possibly other attacks or risks that we are unaware of today. If you find any attacks or vulnerabilities, please follow the appropriate security policies in disclosing that information.

Domain Transfers

Domains are leased. Over time, domain ownership can change. A peer in the Paymail system must be aware that this can lead to stale aliases, and that the owner may change between communication rounds over an elongated period of time. Security mechanisms that pin both the domain and all aliases should be developed as extensions to this Standard to highlight a change in ownership and operation of a domain.

Mitigation:

Currently there is no specific mitigation for this risk.

However, there is a Paymail extension being planned that would help:

Provider Verification Service (PVS)

• Detects various changes like: DNS, domain WHOIS, SSL certification changes and more
• Alerts administrators on various thresholds of changes detected
• Allows transactions to stop if certain changes occur (requiring administrative review)
• Read more about this extension (TBC)

Reuse, Reallocation and Resale of Aliases

Even within the context of a single domain owner, local parts may be reused, reallocated, reissued or sold on to other users. As with domain transfers, security mechanisms that pin both the domain and all aliases should be developed as extensions to this Standard to highlight a change in ownership of an alias.

Mitigation:

Currently there is no specific mitigation for this risk.

However, there is a Paymail extension being planned that would help:

Paymail Alias Index (PAI)

• Reads on-chain attestations for Alias/Domain/PKI records
• Detects changes to Aliases & PKI
• Detects change of ownership (using identity keys related to Paymail aliases)

Hijacks, Hacks and Compromised Services

Malicious actors may attempt to compromise Paymail hosts. A malicious actor controlling a Paymail host has the opportunity to provide their own responses to any query, for any extension, offered by the compromised host. In payments-related extensions, this may mean that funds are diverted away from the intended recipient and instead toward the attacker.

Mitigation:

Currently there is no specific mitigation for this risk.

History

Artefact	Description
Errata	N/A
Change Log	N/A
Decision Log	TS 2021.010 | Paymail WG Space: Amending the 2019 Specification TS 2021.010 | Paymail: BRFC IDs as element names in Capabilities Document TS 2021.010 | Paymail: Mutual Party Authentication

Relationships

Relationship	Description
IP licences and dependencies	nChain Patent Pledge for Paymail Specification
Copyright	© 2022 Bitcoin Association for BSV. All rights reserved. Unless otherwise specified, or required in the context of its implementation on BSV Blockchain, no part of this standard may be reproduced or utilised otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission of Bitcoin Association.
Extends	None
Modifies	2019 Specification message signing process Sections of the 2019 Specification now considered extensions: 0c4339ef99c2 bsvalias Public Key Infrastructure a9f510c16bde bsvalias Verify Public Key Owner 759684b1a19a bsvalias Basic Address Resolution 6745385c3fc0 bsvalias Payer Validation 3d7c2ca83a46 bsvalias Payee Approvals 7bd25e5a1fc6 bsvalias PayTo Protocol Prefix
Deprecates	2019 Specification as a whole is withdrawn
Depends On	JSON Envelope (to be standardised) BRFC Numbering (to be standardised)
Prior Art	HandCash handles
Existing Solution	None known
References	DNS RFCs 1034, 1035, 1123, 2181, 4343 SRV RFC 2782 DNSSEC RFCs 2535, 3225, others (full list) TLS RFC 8446 IANA Well-Known Resources RFC 8615 JSON Envelope Specification Email (federation model and addressing) ECDSA Bitcoin Signed Messages StackOverflow explanation HTTP WWW-Authenticate Header

Extensions

The Paymail Working Group plans to deliver the following extensions after the core standard publication:

Operator Fee Configuration (OFC)

This extension’s purpose is to make it easy to add fee requirements for using the Paymail services being offered. As an example, each transaction could require an output and specific amount in order to be seen as valid by this Paymail provider. There could be a per transaction fee, or per Paymail address fee, or even a monthly subscription that needs to be paid.

Public Service Provider Broadcast ( PSPB )

Activating this extension would do the following:

• Notify the TSC with your domain, operator contact information, and list of capabilities, signatures etc
• Notify the Bitcoin Association (BA)
• Notify any other public Paymail directories or listings

The TSC or BA could now take advantage of this information and do (any) of the following:

• Promote and acknowledge the new Paymail provider (website, publications, etc)
• Ensure, validate and give certificates to providers following the specifications
• Reward new providers with different incentives (users, transactions, etc)

Public Compliance Attestation Discovery (PCAD)

This extension is aimed to publicly show the different levels of compliance that has been reached and verified. It should be easy for a Paymail operator to know if the other service provider is following certain compliance rules. Ideally, the verification attestation provider (VAP) would attest on-chain that the Paymail provider has met all the required criteria for the compliance rules. This extension would easily read on-chain for these attestations and verify their authenticity.

Provider Verification Service (PVS)

Domains are leased and change over time. It’s hard currently as a Paymail provider to ensure that the domain owner is the same and that the domain has not been compromised. This extension aims to help detect domain, dns, ssl and other changes that might be considered malicious and needs further review.

Paymail Alias Index (PAI)

Currently there is no way to tell who owns a Paymail alias or if a PKI changes for an alias. This extension is geared towards keeping a local version of PKI->Alias and using an on-chain service to also verify (once a service exists).

Supplementary Material

TS 2021.010 | Paymail WG Space: Amending the 2019 Specification
TS 2021.010 | Paymail: BRFC IDs as element names in Capabilities Document
TS 2021.010 | Paymail: Mutual Party Authentication