Skip to content

Commit

Permalink
Advanced Envelope Handlers - MVP (trisacrypto#84)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bbengfort
bbengfort authored Mar 31, 2022
1 parent 347f88d commit cbfff05
Show file tree
Hide file tree
Showing 28 changed files with 2,742 additions and 65 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/build.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ jobs:
go-version: 1.16

- name: Install Staticcheck
run: go install honnef.co/go/tools/cmd/staticcheck@latest
run: go install honnef.co/go/tools/cmd/staticcheck@v0.2.2

- name: Checkout Code
uses: actions/checkout@v2
Expand Down Expand Up @@ -47,7 +47,7 @@ jobs:
- name: Install Dependencies
run: |
go version
go get -u github.com/kevinburke/go-bindata/...
go install github.com/kevinburke/go-bindata/[email protected]
go install google.golang.org/protobuf/cmd/[email protected]
go install google.golang.org/grpc/cmd/[email protected]
Expand Down Expand Up @@ -77,7 +77,7 @@ jobs:
- name: Install Dependencies
run: |
go version
go get -u github.com/kevinburke/go-bindata/...
go install github.com/kevinburke/go-bindata/[email protected]
go install google.golang.org/protobuf/cmd/[email protected]
go install google.golang.org/grpc/cmd/[email protected]
Expand Down
35 changes: 33 additions & 2 deletions docs/content/reference/glossary.en.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,44 @@
---
title: Glossary
date: 2021-06-14T15:59:09-05:00
lastmod: 2021-06-14T15:59:09-05:00
lastmod: 2022-03-31T16:10:07-05:00
description: "TRISA Glossary and Terminology"
weight: 20
---

## General Terminology

- **Originator**: The initiator of a blockchain transaction and therefore also the initiator of a TRISA transfer. The "originator" can refer to the originating VASP, the originating customer of the VASP or both.

- **Beneficiary**: The recipient of a blockchain transaction and therefore also the recipient of a TRISA transfer. The "beneficiary" can refer to the beneficiary VASP, the beneficiary customer of the VASP or both.

- **Local vs Remote VASP**: A reference to the source of peer-to-peer traffic in an information exchange. The "local VASP" usually refers to the service you are running, while the "remote VASP" usually refers to some other VASP in the TRISA network. Local vs. Remote is often used to condition originator vs. beneficiary. If you are initiating the transaction then the local VASP is the originator and the remote VASP is the beneficiary. If you are receiving a transaction then the local VASP is the beneficiary and the remote VASP is the originator.
- **Local vs Remote VASP**: A reference to the source of peer-to-peer traffic in an information exchange. The "local VASP" usually refers to the service you are running, while the "remote VASP" usually refers to some other VASP in the TRISA network. Local vs. Remote is often used interchangeably with originator vs. beneficiary. If you are initiating the transaction then the local VASP is the originator and the remote VASP is the beneficiary. If you are receiving a transaction then the local VASP is the beneficiary and the remote VASP is the originator.

- **Travel Rule**: Record-keeping rules for transfers between financial institutions that allow law enforcement agencies to prevent illicit finance (e.g. money laundering or the financing of terrorism).

- **VASP**: Virtual Asset Service Provider. A legal entity (usually a business) that manages and transfers virtual assets and are required by the Travel Rule to conduct information exchanges. Compliance exchanges in the TRISA network are between VASPs.


## Cryptographic Terminology

- **mTLS**: Mutual Transport Layer Security is an encryption protocol that authenticates both the client and the server in a network connection and encrypts communications between the parties so that data cannot be read in flight. mTLS is an extention of TLS (formerly SSL) that requires both sides of a network connection to have a certificate that establishes their identity and which can be used to encrypt packets sent on the channel.

- **Symmetric Cryptography**: Both encryption and decryption of data are performed using a single secret key that must be shared by the sender and the recipient. Shared secrets introduce the problem of how to share the secret key, however symmetric cryptographic algorithms are usually faster and better for bulk encryption of larger amounts of data. Generally, secrets are shared by asymmetric-key encryption and data encrypted using symmetric encryption.

- **Secret Key Cryptography**: See _symmetric cryptography_.

- **Public Key Cryptography**: A cryptographic method that uses a pair of related keys. Each pair consists of a _public key_, which can be shared with others, and a _private key_, which must not be shared with anyone but the owner. In practice, data can be encrypted with a public key but only decrypted with the private key.

- **Asymmetric Cryptography**: See _public key cryptography_.

- **Digital Signature**: A mathematical method that produces a _signature_ of data, e.g. some other piece of data that summarizes or describes the original data, usually via a hashing method. If the original data changes, its digital signature will change, therefore digital signatures are generally used as proof that the original data has not been tampered with, particularly if the signature has been generated cryptographically. For example, if a certificate has a signature that is signed with the private key of the certificate authority, anyone with the CA's public key can verify the signature of the certificate, ensuring it was the certificate produced by the CA.

- **HMAC**: Hash Message Authentication Code. A secure method of producing a digital signature for data that uses a cryptographic hash function and a secret key. HMACs are used to verify that data has not been modified or changed, see also _digital signature_.

- **Certificate**: Usually a reference to an X.509 certificate, a standard format for public key infrastructure. An X.509 certificate is a digital document that securely associates cryptographic key pairs with identities. Certificates are signed by a certificate authority to guarantee their provenance and contain subject information and other metadata concerning , the keypair, and its usage. Generally a reference to a certificate refers to the public key -- the part of the certificate that is shared for authentication purposes. However when certificates are issued, they are issued as a public/private key pair.

- **Identity Certificate**: a TRISA specific term that refers to the certificate issued by the TRISA CA to a VASP entity that they should use to connect to other VASPs in the TRISA network via mTLS.

- **Sealing Certificate (or keys)**: a TRISA specific term that refers to a key pair that is used to seal secure envelopes in the TRISA protocol. Sealing keys may be certificates issued by the TRISA CA, or they may be keys generated by the VASP and exchanged during the TRISA protocol.

- **Certificate Authority**: an entity that issues and revokes certificates and whose public keys are used to establish trust in the identities its issued certificates provide. Certificate authorities usually control cryptographic hardware and the "root of trust" -- a digital key pair that is used to generate and sign intermediate and leaf certificates for public key infrastructure.
112 changes: 112 additions & 0 deletions docs/content/secure-envelopes/_index.en.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
title: Secure Envelopes
date: 2022-03-03T15:36:09-06:00
lastmod: 2022-03-03T15:36:09-06:00
description: "Working with Secure Envelopes and cryptography in the TRISA protocol."
weight: 21
---

![Secure Envelopes](/img/secure_envelopes.png)


The primary data structure for a TRISA exchange is the `SecureEnvelope` -- a wrapper for compliance payload data that facilitates peer-to-peer trust in compliance information exchanges. The design of TRISA secure envelopes had the following requirements:

1. **Privacy**: only the recipient of the secure envelope should be able to open the secure envelope, even outside of the context of an RPC that is secured by transport layer encryption.
2. **Non-repudiation**: the secure envelope should cryptographically guarantee that the compliance payload is valid and has not been modified or tampered with since the original exchange.
3. **Long-term data storage**: the secure envelope should be encrypted at rest and can be "erased" by deleting its associated private keys when the compliance statute is over (usually 5-7 years).
4. **Security**: secure envelopes should prevent statistical attacks on the encrypted payload data while using public-key cryptography for ease of key management.

These requirements are essential to understanding how to successfully engage with TRISA peers, therefore understanding the `SecureEnvelope` is the first step to being able to implement the TRISA protocol.

## Working with Secure Envelopes

There are two basic workflows for secure envelopes: creating and sealing an envelope to send to a counterparty, or unsealing and parsing a received secure envelope.

### Creating a Secure Envelope

**Prerequisites**:

1. You should have constructed an appropriate TRISA `Payload` that contains an `identity` (an IVMS 101 `IdentityPayload`), a `transaction` (a TRISA generic transaction) and a `sent_at` timestamp (RFC-3339 formatted).
2. You should have the _public sealing key_ of the receipient. You can obtain this key either via the `KeyExchange` RPC or by requesting the key from the [directory service]({{< ref "/gds" >}}).

**Steps**:

1. Create a new envelope with a uuid4 envelope ID and the current timestamp
2. Marshal the `Payload` protocol buffers into an array of bytes.
3. Generate an encryption key and encrypt the payload bytes.
4. Generate an hmac secret and sign the encrypted payload
5. Use the public sealing key of the recipient to encrypt the encryption key and hmac secret.
6. Mark the envelope as sealed and populate all required metadata.

### Opening a Secure Envelope

1. Use the `public_key_signature` to identify the private key required to decrypt the encryption key and hmac secret.
2. Use your _private sealing key_ to decrypt the encryption key and HMAC secret.
3. Use the hmac secret and hmac algorithm to verify the encrypted payload has not been tampered with by ensuring the hmac you generate is identical to the hmac on the envelope.
4. Use the encryption key and encryption algorithm to decrypt the payload.
5. Unmarshal the payload into a TRISA `Payload` object.
6. Unmarshal the `identity` and `transaction` payloads and verify that you can parse them into data structures you can use for your compliance workflow.

### Envelope States

As you can see from the above workflows, envelopes can be in one of three states:

1. **Sealed**: the encryption key and hmac secret on the envelope are encrypted with the public key of the recipient. Only the recipient can open the envelope in this state.
2. **Unsealed**: the encryption key and hmac secret are in the clear and can be used to decrypt the payload and verify the HMAC.
3. **Clear**: the payload has been decrypted and can be unmarshaled into a TRISA `Payload` protocol buffer.

Generally speaking, when working with secure envelopes, "sealing" an envelope moves it through the following states:

```
Payload --> Clear --> Unsealed --> Sealed
```

Conversely opening an envelope moves it through the following states:

```
Sealed --> Unsealed --> Clear --> Payload
```

Maintaining envelopes in these various states can be useful to different applications. For example, an unsealed or clear envelope can be used to move data inside of an application while maintaining associated TRISA metdata. A sealed envelope can be used for long-term storage and with proper key-management, ensure erasure of the envelope simply by deleting the keys.

## The Anatomy of a Secure Envelope

A `SecureEnvelope` contains envelope metadata, cryptographic metadata, and an encrypted payload and HMAC signature. There are two types of complete envelope:

1. An error envelope containing complete envelope metadata and a TRISA error. This envelope is sent as a rejection or transfer control message back to the sender from the recipient.
2. A payload envelope that has complete envelope and cryptographic metadata, as well as an encrypted payload and HMAC signature, but without an error. Payload envelopes can be either "sealed" or "unsealed" as described above.

### Envelope Metadata

| Field | Definition |
|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | also referred to as the "envelope id" - this is a unique ID generated by the originator and must be identical on all envelopes referring to the same virtual asset transaction. The originator usually generates this ID as a [UUID4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)). |
| `timestamp` | a nanosecond resolution RFC-3339 formatted timestamp (e.g. [`RFC3339Nano`](https://pkg.go.dev/time#RFC3339Nano)) that is used to order messages with the same ID. |
| `error` | a TRISA-specific error that is intended to help facilitate compliance exchanges. TRISA [error codes](https://github.com/trisacrypto/trisa/blob/main/proto/trisa/api/v1beta1/errors.proto) are used to reject compliance data or to request a fix and retry in a follow-on secure envelope. |

### Cryptographic Metadata

| Field | Definition |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `encryption_key` | the key used to encrypt the compliance payload. Keys are generated by the originator using a crypto random method. To prevent statistical attacks, a new key is generated for every transfer (e.g. at the same time as the envelope ID). If the envelope is sealed the `encryption_key` is encrypted using the public sealing key of the recipient. |
| `encryption_algorithm` | a string that describes the algorithm used to encrypt the compliance payload. This string should provide enough information for the recipient to be able to decrypt the payload. The default in the reference implementation is `"AES256-GCM"` which describes the use of [ AES Galois Counter Mode ]( https://datatracker.ietf.org/doc/html/rfc5288 ) with a 32 byte key. |
| `hmac_secret` | the secret used to calculate the HMAC signature. This secret is generated by the originator using a crypto random method, and is generated for every transfer. If the envelope is sealed then the `hmac_secret` is encrypted using the public sealing key of the recipient. |
| `hmac_algorithm` | a string that describes the algorithm used to compute the HMAC signature. The default in the reference implementation is `"HMAC-SHA256"` which describes the use of the [ HMAC ]( https://en.wikipedia.org/wiki/HMAC ) algorithm with a [ SHA-256 ]( https://en.wikipedia.org/wiki/SHA-2 ) secure hashing function. |
| `sealed` | a boolean that describes the state of the envelope. If true, this means that the `encryption_key` and `hmac_secret` have been encrypted using the public sealing key of the recipient. |
| `public_key_signature` | the signature of the public key used to seal the envelope, a helper for the recipient to identify the private key required to unseal the envelope. |

### Payload

| Field | Definition |
|-----------|-----------------------------------------------------------------------------------------------|
| `payload` | the ` Payload ` protocol buffer marshaled to bytes and encrypted using the ` encryption_key`. |
| `hmac` | the HMAC signature computed from the encrypted payload bytes and the ` hmac_secret`. |

The `Payload` protocol buffer has the following fields:

| Field | Definition |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `identity` | a protobuf [ any ]( https://developers.google.com/protocol-buffers/docs/proto3#any ) that contains the compliance identity information of the originator and the beneficiary. Although this can be any message type, it should be an [ IVMS101 Identity Payload ]( https://intervasp.org ). |
| `transaction` | a protobuf [ any ]( https://developers.google.com/protocol-buffers/docs/proto3#any ) that contains information used to identify the associated transaction on the blockchain or to send control flow messages and handling-specific instructions. Use one of the TRISA defined [generic transaction data structures](https://github.com/trisacrypto/trisa/blob/main/proto/trisa/data/generic/v1beta1/transaction.proto). |
| `sent_at` | The RFC-3339 formatted timestamp that the originator sent the first compliance message to the beneficiary. This timestamp is part of the compliance payload for non-repudiation purposes. |
| `received_at` | The RFC-3339 formatted timestamp when the beneficiary accepted the compliance message and returned the completed payload to the originator. This timestamp is part of the compliance payload for non-repudiation purposes. |
Binary file added docs/static/img/secure_envelopes.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit cbfff05

Please sign in to comment.