From 10b67ce7cc0d201cc46db7f3e1ff4edffca94377 Mon Sep 17 00:00:00 2001 From: Pawel Jakubas Date: Wed, 17 Jul 2024 12:44:09 +0200 Subject: [PATCH] reformat metadata-encrypt.md more --- specifications/api/metadata-encrypt.md | 68 +++++++++++++------------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/specifications/api/metadata-encrypt.md b/specifications/api/metadata-encrypt.md index 30c4315e7ea..18056d54c9c 100644 --- a/specifications/api/metadata-encrypt.md +++ b/specifications/api/metadata-encrypt.md @@ -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. @@ -24,9 +27,9 @@ 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`: ``` { @@ -34,7 +37,7 @@ Specifically: "encrypt_metadata": { "passphrase": "my secret encryption password" }, - "metadata": + "metadata": { "674" : { "msg": "raw metadata ... " } @@ -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=" ] @@ -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 @@ -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 ... " } @@ -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.