Skip to content

Commit

Permalink
reformat metadata-encrypt.md
Browse files Browse the repository at this point in the history 
more
  • Loading branch information
@paweljakubas
paweljakubas committed Jul 17, 2024
1 parent 5ff526f commit 10b67ce
Showing 1 changed file with 35 additions and 33 deletions.
68 changes: 35 additions & 33 deletions specifications/api/metadata-encrypt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,19 @@ In addition "Transactions New > Decode" HTTP endpoint is described in the contex
## Metadata encryption

Encryption of metadata is optional and when chosen the metadata in transaction is to be encrypted
via AES256CBC according to [CIP-0020][ref1] and [CIP-0083][ref2].
via AES256CBC according to [CIP-0020][cip0020] and [CIP-0083][cip0083].
A PKCS#7 padding of payload is used before encryption as the required
input length must be a multiple of block size, ie., 16 bytes.
PBKDF2 password stretching is used to get a 32-byte symmetric key
that is required for the adopted encryption algorithm. In detail,
PBKDF2 encryption uses HMAC with the hash algorithm SHA512.

As a consequence the encrypted metadata, not its raw version, is going to be stored in blockchain.

[ref1]: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0020
[ref2]: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0083
However, in line with [CIP-0020][cip0020] and [CIP-0083][cip0083], only the field `674` of the `metadata` field of the transaction will be affected.

[cip0020]: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0020
[cip0083]: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0083

The "Transactions New > Construct" HTTP endpoint allows the encryption of metadata.
The "Transactions New > Decode" HTTP endpoint allows for decrypting of the encrypted metadata.
Expand All @@ -24,17 +27,17 @@ Specifically:

1. Creation of a transaction output that contains a metadata with encryption enabled.

In the `encrypt_metadata` field, passphrase used in encryption is established. `metadata` field to be encrypted is required.
In the `encrypt_metadata` field, passphrase used in encryption is established. `metadata` field to be encrypted is required.

Example `POST` data for the endpoint, ie., /wallets/{walletId}/transactions-construct`:
Example `POST` data for the endpoint, ie., /wallets/{walletId}/transactions-construct`:

```
{
...
"encrypt_metadata":
{ "passphrase": "my secret encryption password"
},
"metadata":
"metadata":
{ "674" : {
"msg": "raw metadata ... "
}
Expand All @@ -43,50 +46,49 @@ Specifically:
}
```

As a result we get transaction with metadata encrypted:
As a result we get transaction with metadata encrypted:
```
{
...
"metadata":
"metadata":
{ "674":
{
{
"enc": "basic",
"msg":
[
"msg":
[
"base64-string 1", "base64-string 2", "base64-string 3" ...
]
}
}
}
...
}
```
The same is the case for `GET` transaction. `encrypt_metadata` is an object as we might want to introduce
optional choice of encryption method in the future. In that case the new enhancement to api will be introduced in
non-intrusive way.
The same is the case for `GET` transaction. `encrypt_metadata` is an object as we might want to introduce
optional choice of encryption method in the future. In that case the new enhancement to api will be introduced in
non-intrusive way.

Metadata encryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-construct` endpoint with the same `POST` payload.
Metadata encryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-construct` endpoint with the same `POST` payload.

Example:
Example:
```
{
...
"encrypt_metadata":
{ "passphrase": "metadata-secret"
},
"metadata":
"metadata":
{ "674" : {
"msg":"world"
}
}
...
}
```
will return (for salt "yoDCYXKaVhA=")
will return (for the example salt "yoDCYXKaVhA=")
```
{
...
"metadata":
"metadata":
{ "674" : {
"enc": "basic",
"msg": [ "U2FsdGVkX1/KgMJhcppWEG6t0aUcMqdEJmnSHVOCgpw=" ]
Expand All @@ -96,44 +98,44 @@ Specifically:
}
```

Example:
Example:
```
{
...
"encrypt_metadata":
{ "passphrase": "metadata-secret"
},
"metadata":
"metadata":
{ "674" : {
"msg":
[ "Hard times create strong men."
, "Strong men create good times."
, "Good times create weak men."
, "And, weak men create hard times."
]
]
}
}
}
...
}
```
will return (for salt "XG1cgIw56q8=")
will return (for the example salt "XG1cgIw56q8=")
```
{
...
{ "674" : {
"enc": "basic",
"enc": "basic",
"msg":
[ "U2FsdGVkX19cbVyAjDnqr5eksQ9gnxJDz6dWhAaXvZGQl31HdEtTpBa91osBavdQ"
, "xvOJpGuA8vQGJUgn9RVuqFbVxpggHGCspU6Z5BV5j1LlSqnp6GfHFvrTL3sZcZMq"
, "MtOMZSx+d6nPRJL6453wC3rh0cny6SnrEUt9awwxx4PDZk7pDT85h3ygQf1I8fow"
, "tYtj3GY0cBwIHfkRLrsxbg=="
]
]
}
}
}
...
}
```
as metadata values have 64-byte limit. In that case the encrypted metadata is encoded in the successive bytes.
as metadata values have 64-byte limit. In that case the encrypted metadata is encoded in the successive bytes.


## Metadata decryption
Expand All @@ -149,11 +151,11 @@ Specifically:
}
```

As a result we get decoded transaction with metadata decrypted:
As a result we get decoded transaction with metadata decrypted:
```
{
...
"metadata":
"metadata":
{ "674" : {
"msg": "raw metadata ... "
}
Expand All @@ -162,4 +164,4 @@ Specifically:
}
```

Metadata decryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-decode` endpoint with the same `POST` payload.
Metadata decryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-decode` endpoint with the same `POST` payload.

0 comments on commit 10b67ce

Please sign in to comment.