From 2c8638e4425fae98334b09a0024854f1e3e45f31 Mon Sep 17 00:00:00 2001 From: Nathaniel Maile Date: Tue, 7 Feb 2023 16:13:09 -0500 Subject: [PATCH 1/3] add backend general spec --- .../card-interface-specification/README.md | 3 +- developing-with-phonon/known-issues.md | 7 - .../secure-backend-specification/README.md | 211 ++++++++++++++++++ 3 files changed, 212 insertions(+), 9 deletions(-) delete mode 100644 developing-with-phonon/known-issues.md create mode 100644 developing-with-phonon/secure-backend-specification/README.md diff --git a/developing-with-phonon/card-interface-specification/README.md b/developing-with-phonon/card-interface-specification/README.md index d0cd954..54603dc 100644 --- a/developing-with-phonon/card-interface-specification/README.md +++ b/developing-with-phonon/card-interface-specification/README.md @@ -1,3 +1,2 @@ # Card Interface Specification - -TODO +This section details available interfaces with which, phonon can be utilized. diff --git a/developing-with-phonon/known-issues.md b/developing-with-phonon/known-issues.md deleted file mode 100644 index 76282ee..0000000 --- a/developing-with-phonon/known-issues.md +++ /dev/null @@ -1,7 +0,0 @@ -# Known Issues - -These are the known issues with the Phonon Protocol. - -| Issue | Date Discovered | Issue Tracker | -| ----- | --------------- | ------------- | -| | | | diff --git a/developing-with-phonon/secure-backend-specification/README.md b/developing-with-phonon/secure-backend-specification/README.md new file mode 100644 index 0000000..ed9d8e4 --- /dev/null +++ b/developing-with-phonon/secure-backend-specification/README.md @@ -0,0 +1,211 @@ +# Phonon Secure Backend Specification +This document specifies interactions required by the phonon secure backend from a high level. This is primarily meant for developers seeking to implement the phonon protocol on secure hardware devices and curious technical people. + +## General + +### Terminology +**phonon sce** Stands for phonon Secure Compute Environment. A device implementing the phonon secure backend, meant to be used in conjunction with the phonon terminal + +**terminal** A device used to communicate with the phonon sce as well as allow the user a simple interface to do transactions and asset management + +**phonon** For the purposes of defining interactions, a phonon is defined as a data structure containing the private key generated within the phonon sce, and the descriptor + +**descriptor** A portion of the phonon describing the asset/assets associated to the private key that it shares a phonon with + +**bob** A fictional phonon user generally wishing to send phonons to alice + +**alice** A fictional phonon user generally wishing to receive phonons from bob + +**phonon transfer packet** the encrypted data containing a number of phonons while in transit between phonon sce units + + +### General Constraints +all phonon interactions must adhere to the following Constraints +1. A phonon's private key may not be accessible by more than a single entity at one time +1. A phonon's private key MUST remain secret unless the phonon is destroyed at or before the time of the phonon being viewable by an outside system or entity +1. A phonon private key may not be transferred to a phonon sce that has not been verified by the sending phonon sce +1. A phonon private key may not be received by a phonon sce that has not verified the sender + +### Encoding +For the purposes of this document, any data being described will be in JSON format. +Data sent between the terminal and the phonon sce will be implementation dependent. +Data sent between the phonon sce and another phonon sce will be in CBOR format. + +## Interaction descriptions +### Certificate Authority loading +The manufacturer of the phonon sce, to indicate that the phonon sce is legitimate, will instruct the phonon sce to store a certificate. The purpose of this certificate is to verify with other phonon sces that they are also legitimate. + +1. Manufacturer runs LOAD_CA command +#### Constraints +1. Once set, this may not be changed. + +### Certificate signing +1. GET_PUB_KEY command is run +1. Public key of phonon sce is signed by the manufacturer with the certificate authority private key, and a certificate is generated +1. LOAD_CERT command is run with the newly generated certificate + +### Personal security setup +The phonon sce SHOULD be secured against unauthroized access by some sort of identification. For personal use, a pin is likely sufficient, though for corporate use, Key authentication may be used or other forms of protection +1. ESTABLISH_SECURITY command is run +1. user verifies log in to the system with a login challenge + +#### Constraints +1. The owner MUST set this up before phonon creation and transfers can occur + +### Phonon Creation +Phonon creation connsists of the generation of a public/private keypair within the phonon sce, the expression of the public key to the client application, A likely transaction on a blockchain to encumber assets to the phonon's associated wallet, and a call back into the phonon sce to set the descriptor of the phonon +1. GENERATE_PHONON command is run +1. The private key and relevant addressing id is returned to the client +1. the client handles generating relevant crypto wallet address and encumbering assets to it +1. SET_DESCRIPTOR command is run + +### Phonon Listing +There must be a way to obtain a list of existing phonons for further use by the user +1. LIST_PHONONS command is run + +### Remote Connection (depricated) +A connection on the client level must be established in order for the secure connection to be established between phonon sce units. There are many ways this can be done, and will be ommitted from this document + +### Secure Connection (depricated) +this is complicated enough that it's not worth the effort to get it right in this document due to it's depricated status. +### Phonon Transfer (depricated) +A transfer of phonons between bob and alice assumes the secure connction between both bob and alice's phonon sces are engaged in a secure connection +1. bob initiates SEND_PHONONS command through the clint +2. the resulting phonon transfer packet is sent over the remote connection to alice's client +3. Alice's client runs the RECEIVE_PHONONS command with the phonon transfer packet payload against her phonon sce + +### Phonon Transfer +A transfer of phonons from Bob to Alice +1. Bob retrieves Alice's Phonon sce certificate +2. Bob initiates SEND_PHONONS command through the client +3. The resulting transfer packet is sent to Alice's client +4. Alice's client rust the RECEIVE_PHONONS command with the phonon transfer payload against her phonon sce + +### Phonon Redemption +a user retrieves the private key of a phonon and utilizes it to do transactions on a blockchain +1. Bob initiates the DESTROY_PHONON command +2. The resulting private key is used in an asset dependent way to move the asset previously encumbered in the phonon to a permanent wallet + +# Command Glossary +## LOAD_CA +This is to load the phonon certificate authority Public Key. Phonon sce devices to be transferred to will have their certificate signatures checked against this key to verify the authenticity of the phonon device. +### Inputs + ```json + {"Certificate":[binary data]} + ``` + +### Outputs + ```json + {} + ``` + +## INFORMATION +the phonon sce will return certificate information. Only the identity public key will be returned upon first run, and all the specified information will be returned after LOAD_CA has been run +### Inputs + ``` + none + ``` +### Outputs (after certificate loading) + ```json + { + "pubkey": "binary", + "cert": "binary", + "name": "string", + "nonce": "binary", + "counter", "integer or binary?", + } +### Outputs (pre certificate loading) + ```json + { + "pubkey": "binary", + } +## LOAD_CERT +The phonon sce will store its identity certificate. the identity certificate will be stored to be returned in the INFORMATION command +### Inputs + ```json + { + "pub": "public key point as byte string", + "iat": "uint32", + "exp": "uint32", + "ver": "int, device firmware version" + } + ``` +### Outputs + ``` + none + ``` + +## ESTABLSIH_SECURITY +This command is to setup the security mechanism on the phonon sce. This is implementation dependent but SHOULD appropriately lock out unauthorized users from utilizing the phonon sce it is set to. +### Inputs + ```json + [implementation dependent] + ``` + +### Outputs: + ```json + [implementation dependent] + ``` +## UNLOCK +This comand is to unlock the phonon sce for use. Before this command is successfully run the phonon sce should not respond to calls to other commands +### Inputs + ```json + [implementation dependent] + ``` + +### Outputs + ```json + [implementation dependent] + ``` +## GENERATE_PHONON +A phonon keypair will be generated on the phonon sce, and it's public portion will be returned +### Inputs + ```json + {"type":[curve type]) + ``` +note: curve type is a string and currently the only option is "secp256k1" +### Outputs + ```json + {"pubkey":"binary data"} + ``` +## SET_DESCRIPTOR +### Inputs + ```json + { + "arbitrary keys":"arbitrary values" + } + ``` + +### Outputs + ```json + ``` +## LIST_PHONONS +### Inputs + ```json + [optional] + ```json +### Outputs + + ```json + [ + { + "header": { + "curve": "secp256k1", + "pub": "public key bytes" + }, + "metadata":{ + "xyz": "abc", + "something else":"another value", + } + ] + ``` +note: some implemntations will allow for filter queries to be input to cut down on the amount of phonons returned in a single request +## DESTROY_PHONON +### Inputs + ```json + todo + ``` + +### Outputs + ```json + ``` From 37cc040ee2aaa16c426ec1895555a5fa94b43cfa Mon Sep 17 00:00:00 2001 From: Nathaniel Maile Date: Wed, 8 Feb 2023 00:47:08 -0500 Subject: [PATCH 2/3] add latest changes --- .../secure-backend-specification/README.md | 162 +++++++++++++----- 1 file changed, 115 insertions(+), 47 deletions(-) diff --git a/developing-with-phonon/secure-backend-specification/README.md b/developing-with-phonon/secure-backend-specification/README.md index ed9d8e4..0f6e141 100644 --- a/developing-with-phonon/secure-backend-specification/README.md +++ b/developing-with-phonon/secure-backend-specification/README.md @@ -29,7 +29,7 @@ all phonon interactions must adhere to the following Constraints ### Encoding For the purposes of this document, any data being described will be in JSON format. Data sent between the terminal and the phonon sce will be implementation dependent. -Data sent between the phonon sce and another phonon sce will be in CBOR format. +Phonon transfer packets must be encoded in [CBOR](https://www.rfc-editor.org/rfc/rfc8949.html) format ## Interaction descriptions ### Certificate Authority loading @@ -63,17 +63,6 @@ Phonon creation connsists of the generation of a public/private keypair within t There must be a way to obtain a list of existing phonons for further use by the user 1. LIST_PHONONS command is run -### Remote Connection (depricated) -A connection on the client level must be established in order for the secure connection to be established between phonon sce units. There are many ways this can be done, and will be ommitted from this document - -### Secure Connection (depricated) -this is complicated enough that it's not worth the effort to get it right in this document due to it's depricated status. -### Phonon Transfer (depricated) -A transfer of phonons between bob and alice assumes the secure connction between both bob and alice's phonon sces are engaged in a secure connection -1. bob initiates SEND_PHONONS command through the clint -2. the resulting phonon transfer packet is sent over the remote connection to alice's client -3. Alice's client runs the RECEIVE_PHONONS command with the phonon transfer packet payload against her phonon sce - ### Phonon Transfer A transfer of phonons from Bob to Alice 1. Bob retrieves Alice's Phonon sce certificate @@ -90,23 +79,23 @@ a user retrieves the private key of a phonon and utilizes it to do transactions ## LOAD_CA This is to load the phonon certificate authority Public Key. Phonon sce devices to be transferred to will have their certificate signatures checked against this key to verify the authenticity of the phonon device. ### Inputs - ```json +```json {"Certificate":[binary data]} - ``` +``` ### Outputs - ```json +```json {} - ``` +``` ## INFORMATION the phonon sce will return certificate information. Only the identity public key will be returned upon first run, and all the specified information will be returned after LOAD_CA has been run ### Inputs - ``` +``` none - ``` +``` ### Outputs (after certificate loading) - ```json +```json { "pubkey": "binary", "cert": "binary", @@ -114,67 +103,75 @@ the phonon sce will return certificate information. Only the identity public key "nonce": "binary", "counter", "integer or binary?", } +``` ### Outputs (pre certificate loading) - ```json +```json { "pubkey": "binary", } +``` ## LOAD_CERT The phonon sce will store its identity certificate. the identity certificate will be stored to be returned in the INFORMATION command ### Inputs - ```json +```json { "pub": "public key point as byte string", "iat": "uint32", "exp": "uint32", "ver": "int, device firmware version" } - ``` +``` ### Outputs - ``` +``` none - ``` +``` -## ESTABLSIH_SECURITY +## ESTABLISH_SECURITY This command is to setup the security mechanism on the phonon sce. This is implementation dependent but SHOULD appropriately lock out unauthorized users from utilizing the phonon sce it is set to. ### Inputs - ```json +```json [implementation dependent] - ``` +``` ### Outputs: - ```json +```json [implementation dependent] - ``` +``` ## UNLOCK This comand is to unlock the phonon sce for use. Before this command is successfully run the phonon sce should not respond to calls to other commands ### Inputs - ```json +```json [implementation dependent] - ``` +``` ### Outputs - ```json +```json [implementation dependent] - ``` +``` ## GENERATE_PHONON A phonon keypair will be generated on the phonon sce, and it's public portion will be returned ### Inputs - ```json +```json {"type":[curve type]) - ``` +``` note: curve type is a string and currently the only option is "secp256k1" ### Outputs - ```json +```json {"pubkey":"binary data"} - ``` +``` ## SET_DESCRIPTOR +the descriptor of a phonon contains arbitrary key value pairs and is to be attached to phonons when this command is run. the identifier of the phonon is implementation dependent and may be a representation of the pubkey or an index or other identifier stored on the sce. ### Inputs - ```json +```json { - "arbitrary keys":"arbitrary values" + { + phonon:4 + } + "data":{ + "arbitrary keys":"arbitrary values" + } } - ``` +``` ### Outputs ```json @@ -185,8 +182,7 @@ note: curve type is a string and currently the only option is "secp256k1" [optional] ```json ### Outputs - - ```json +```json [ { "header": { @@ -198,14 +194,86 @@ note: curve type is a string and currently the only option is "secp256k1" "something else":"another value", } ] - ``` +``` note: some implemntations will allow for filter queries to be input to cut down on the amount of phonons returned in a single request +## SEND_PHONONS +The sce is given the receiver identity certificate, validates it with the certificate authority, and generates a phonon transfer packet. It is imperative that the phonon is deleted from the sce when this packet is returned to the client. If the receiver certificate cannot be validated, the packet cannot be created. +### Encryption +the output of this command includes encrypted private keys. +$ENCRYPTION_SCHEME_DEFINITION (todo) +### Inputs +```json + { + "receiver":"[bytes of full identity certificate of receiver]", + "receiver_nonce":56383927, + "phonons":[1,3,26] + + } +``` +### Outputs +```json + { + { + "signature":"[signature of the remaining packet signed with identity certificate]", + "certificate":"[bytes of full identity certificate of sender]", + "counter":56383927, + "phonons":[ + { + "header":{ + "privKey":"[private key bytes encrypted]" + "curve": "secp256k1", + }, + "metadata":{ + "abc":"xyz", + "def":"uvw" + } + } + ] + } + } +``` +## RECEIVE_PHONONS +receive phonons is run with input of a transfer packet that was output from a sending card's SEND_PHONONS command, When this command is run, the receiving card must verify the legitimacy of the sender card's certificate prior to storage of the phonon. If the verification fails, the packet must not be ingested. The phonon receive counter is then increased to the value specified in the packet. +### Counter +the counter is a security measure to prevent a single sce from receiving the same phonon more than once. Upon initialization of the program, the counter must be set to 0, and increases to the value of the most recently received phonon upon ingestion. If a transfer packet comes in with the same or lower counter, the packet must be ignored by the sce. +todo: add documentation on active/passive counter and a way to differentiate between the two. +### Encryption +todo +### Inputs +```json + { + { + "signature":"[signature of the remaining packet signed with identity certificate]", + "certificate":"[bytes of full identity certificate of sender]", + "counter":56383927, + "phonons":[ + { + "header":{ + "privKey":"[private key bytes encrypted]" + "curve": "secp256k1", + }, + "metadata":{ + "abc":"xyz", + "def":"uvw" + } + } + ] + } + } + ``` + +### Outputs +```json + [none] + +``` ## DESTROY_PHONON +todo ### Inputs - ```json +```json todo - ``` +``` ### Outputs - ```json - ``` +```json +``` From b102d8da4b6e130a7bcc6ff68ae9aa7b70e03322 Mon Sep 17 00:00:00 2001 From: Nathaniel Maile Date: Mon, 13 Feb 2023 20:35:50 -0500 Subject: [PATCH 3/3] update based on pr suggestions --- .../secure-backend-specification/README.md | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/developing-with-phonon/secure-backend-specification/README.md b/developing-with-phonon/secure-backend-specification/README.md index 0f6e141..3cb2303 100644 --- a/developing-with-phonon/secure-backend-specification/README.md +++ b/developing-with-phonon/secure-backend-specification/README.md @@ -12,9 +12,9 @@ This document specifies interactions required by the phonon secure backend from **descriptor** A portion of the phonon describing the asset/assets associated to the private key that it shares a phonon with -**bob** A fictional phonon user generally wishing to send phonons to alice +**alice** A fictional phonon user generally wishing to send phonons to bob -**alice** A fictional phonon user generally wishing to receive phonons from bob +**bob** A fictional phonon user generally wishing to receive phonons from alice **phonon transfer packet** the encrypted data containing a number of phonons while in transit between phonon sce units @@ -23,8 +23,7 @@ This document specifies interactions required by the phonon secure backend from all phonon interactions must adhere to the following Constraints 1. A phonon's private key may not be accessible by more than a single entity at one time 1. A phonon's private key MUST remain secret unless the phonon is destroyed at or before the time of the phonon being viewable by an outside system or entity -1. A phonon private key may not be transferred to a phonon sce that has not been verified by the sending phonon sce -1. A phonon private key may not be received by a phonon sce that has not verified the sender +1. A phonon private key MUST NOT be received by a phonon sce that has not verified the sender ### Encoding For the purposes of this document, any data being described will be in JSON format. @@ -57,7 +56,7 @@ Phonon creation connsists of the generation of a public/private keypair within t 1. GENERATE_PHONON command is run 1. The private key and relevant addressing id is returned to the client 1. the client handles generating relevant crypto wallet address and encumbering assets to it -1. SET_DESCRIPTOR command is run +1. SET_METADATA command is run ### Phonon Listing There must be a way to obtain a list of existing phonons for further use by the user @@ -68,7 +67,7 @@ A transfer of phonons from Bob to Alice 1. Bob retrieves Alice's Phonon sce certificate 2. Bob initiates SEND_PHONONS command through the client 3. The resulting transfer packet is sent to Alice's client -4. Alice's client rust the RECEIVE_PHONONS command with the phonon transfer payload against her phonon sce +4. Alice's client runs the RECEIVE_PHONONS command with the phonon transfer payload against her phonon sce ### Phonon Redemption a user retrieves the private key of a phonon and utilizes it to do transactions on a blockchain @@ -98,7 +97,7 @@ the phonon sce will return certificate information. Only the identity public key ```json { "pubkey": "binary", - "cert": "binary", + "certificate": "binary", "name": "string", "nonce": "binary", "counter", "integer or binary?", @@ -159,7 +158,7 @@ note: curve type is a string and currently the only option is "secp256k1" ```json {"pubkey":"binary data"} ``` -## SET_DESCRIPTOR +## SET_METADATA the descriptor of a phonon contains arbitrary key value pairs and is to be attached to phonons when this command is run. the identifier of the phonon is implementation dependent and may be a representation of the pubkey or an index or other identifier stored on the sce. ### Inputs ```json @@ -195,7 +194,6 @@ the descriptor of a phonon contains arbitrary key value pairs and is to be attac } ] ``` -note: some implemntations will allow for filter queries to be input to cut down on the amount of phonons returned in a single request ## SEND_PHONONS The sce is given the receiver identity certificate, validates it with the certificate authority, and generates a phonon transfer packet. It is imperative that the phonon is deleted from the sce when this packet is returned to the client. If the receiver certificate cannot be validated, the packet cannot be created. ### Encryption @@ -205,7 +203,7 @@ $ENCRYPTION_SCHEME_DEFINITION (todo) ```json { "receiver":"[bytes of full identity certificate of receiver]", - "receiver_nonce":56383927, + "receiver_counter":56383927, "phonons":[1,3,26] } @@ -235,7 +233,7 @@ $ENCRYPTION_SCHEME_DEFINITION (todo) ## RECEIVE_PHONONS receive phonons is run with input of a transfer packet that was output from a sending card's SEND_PHONONS command, When this command is run, the receiving card must verify the legitimacy of the sender card's certificate prior to storage of the phonon. If the verification fails, the packet must not be ingested. The phonon receive counter is then increased to the value specified in the packet. ### Counter -the counter is a security measure to prevent a single sce from receiving the same phonon more than once. Upon initialization of the program, the counter must be set to 0, and increases to the value of the most recently received phonon upon ingestion. If a transfer packet comes in with the same or lower counter, the packet must be ignored by the sce. +the counter is a security measure to prevent a single sce from receiving the same phonon transfer packet more than once. Upon initialization of the program, the counter must be set to 0, and increases to the value of the most recently received phonon upon ingestion. If a transfer packet comes in with the same or lower counter, the packet must be ignored by the sce. todo: add documentation on active/passive counter and a way to differentiate between the two. ### Encryption todo