# Public Key Infrastructure

| brfc         | title                              | authors                                       | version |
| ------------ | ---------------------------------- | --------------------------------------------- | ------- |
| 0c4339ef99c2 | bsvalias Public Key Infrastructure | andy (nChain), Ryan X. Charles (Money Button) | 1       |

Each paymail handle `<alias>@<domain>.<tld>` *MUST* be issued a stable ECDSA public key that *SHOULD NOT* be used as part of any on-chain transaction. Clients must be able to locate the public key from information within the `.well-known/bsvalias` configuration file:

```json
{
  "bsvalias": "1.0",
  "capabilities": {
    "pki": "https://bsvalias.example.org/{alias}@{domain.tld}/id",
  }
}
```

The template values `{alias}` and `{domain.tld}` refer to the components of target paymail handle `<alias>@<domain>.<tld>` and must be substituted by the client before issuing a request.

## PKI Flow

<figure><img src="https://2147185133-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWtK4ab0ntyPZBmGoKq4t%2Fuploads%2Fgit-blob-c3c389db524a07209589426577afd5aab61ed6d6%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Client Request

The `capabilities.pki` path returns a URI template. Clients should replace the `{alias}` and `{domain.tld}` template parameters and then make an HTTP GET request against this URI.

Standard HTTP caching headers *SHOULD* be supported, and clients that have previously requested the public key *SHOULD NOT* re-request information within any server-advertised caching window.

## Server Responses

Below are the responses that have meaning to this protocol. A server may return other status codes, for example `5xx` indicating some sort of server failure. Clients should treat status codes not specified as part of this specification as some sort of transient error and may retry at their leisure.

### 200 OK

Returned when a valid request for a known paymail handle has been received. The return message *MUST* have a content type of `application/json`. The response body *MUST* conform to the following schema:

```json
{
  "bsvalias": "1.0",
  "handle": "<alias>@<domain>.<tld>",
  "pubkey": "..."
}
```

The public key *MUST* be a valid point on the secp256k1 curve, compressed, and hex-encoded. This means that the pubkey string length *MUST* be 66 bytes long (33 bytes binary, each byte encoded as two hex characters):

| Start | Length | Value                                             |
| ----- | ------ | ------------------------------------------------- |
| `00`  | `02`   | "Odd/even" indicator, must be either `02` or `03` |
| `02`  | `64`   | Elliptic curve point x-coordinate                 |

### 304 Not Modified

No public key rotation has taken place since the previous request, based on caching headers supplied.

### 404 Not Found

The paymail handle was not found by this service.