# 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="/files/lZQxUTSwShNcIKUePYJo" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bsvblockchain.org/paymail/public-key-infrastructure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.