|
| 1 | +--- |
| 2 | +name: Issue 3752 |
| 3 | +about: The goal is to detect inconsistencies between SATP code and draft. In particular, Stage 0 and Stage 1 inconsistencies. |
| 4 | +title: 'Inconsistencies between SATP code and draft' |
| 5 | +labels: feature |
| 6 | +assignees: 'Rodolfo Carapau' |
| 7 | +--- |
| 8 | + |
| 9 | +**What is the issue?** |
| 10 | + |
| 11 | +[Issue 3752](https://github.com/hyperledger-cacti/cacti/issues/3752): Given that SATP is a work in progress, new versions of the specification are being published concurrently with SATP's implementation. New versions of specification contain new information regarding SATP, which can lead to semanti and syntactic inconsistencies between the specification and the implementation. |
| 12 | +The goals of this report are to: |
| 13 | +- Identify inconsistencies, regarding SATP's Stage 0 and Stage 1; |
| 14 | +- Create action points, in the form of sub-issues, to solve each inconsistency. |
| 15 | + |
| 16 | +**How can the issue be solved?** |
| 17 | + |
| 18 | +1. Map SATP Stage 0 and Stage 1 [specification draft version 08](https://datatracker.ietf.org/doc/html/draft-ietf-satp-core#autoid-38) requirements; |
| 19 | +2. Understand cactus-plugin-satp-hermes implementation; |
| 20 | +3. Detect and propose corrections to incoherences; |
| 21 | + |
| 22 | +**Requirements - Stage 0:** |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +**Requirements - Stage 1:** |
| 27 | + |
| 28 | + |
| 29 | + |
| 30 | +**Inconsistencies - Stage 0:** |
| 31 | + |
| 32 | +- Access to tokenized asset records: |
| 33 | + - State: |
| 34 | + - Inconsistent |
| 35 | + - Description: |
| 36 | + - According to the specification, stage 0 starts with a request transfer context, from the client application to the source gateway. This requests provides a Tokenized Asset Record (TAR) to the gateway, which is used to generate a Transfer Context ID (TCID), that is returned to the Client application, and used throughout the session. The current implementation does not handle TARs, instead it returns an Asset Profile object that contains the TCID. |
| 37 | + - TODO: |
| 38 | + - [Sub-issue 3795](https://github.com/hyperledger-cacti/cacti/issues/3795) - Implement an Asset handling mechanism that passes a TAR to a client SATP gateway. The gateway's response must include the Transfer Context ID used for the session. |
| 39 | + |
| 40 | +- Gateway owner verification: |
| 41 | + - State: |
| 42 | + - Inconsistent |
| 43 | + - Description: |
| 44 | + - This is the verification of the identity of the owners of the gateways. The type considers the existence of a pubkey (has an optional parameter). However, the e2e integration test does not perform the verification of a pubkey, in the gateway instantiation. I did not find an explicit verification method for the gateway’s identity, in the implementation. |
| 45 | + - TODO: |
| 46 | + - [Sub-issue 3796](https://github.com/hyperledger-cacti/cacti/issues/3796) - Implement a mechanism that allows for the identification of the owners of the gateway. |
| 47 | + |
| 48 | +- Verification of the gateway signature public key |
| 49 | + - State: |
| 50 | + - Inconsistent |
| 51 | + - Description: |
| 52 | + - The sender gateway and receiver gateway must validate their respective signature public keys that will later be used to sign assertions and claims. This may include validating the X509 certificates of these keys. Probably should implemented at the transact-handler-service.ts. |
| 53 | + - TODO: |
| 54 | + - [Sub-issue 3796](https://github.com/hyperledger-cacti/cacti/issues/3796) - Implement a mechanism that allows for the identification of the owners of the gateway. |
| 55 | + |
| 56 | +- Gateway device and state validation |
| 57 | + - State: |
| 58 | + - Inconsistent |
| 59 | + - Description: |
| 60 | + - This is the device attestation evidence [RFC9334](https://datatracker.ietf.org/doc/html/rfc9334) that a gateway must collect and convey to each other, where a verifier is assumed to be available to decode, parse and appraise the evidence. In the implementation, it is not explicitly defined in the transfer method or in the stage0-handler.ts. It should maybe be implemented in the NewSessionRequest. The process should comply with the Remote ATtestation procedureS (RATS) Architecture. |
| 61 | + - TODO: |
| 62 | + - [Sub-issue 3797](https://github.com/hyperledger-cacti/cacti/issues/3797) - Implement a mechanism that complies with [RFC9334](https://datatracker.ietf.org/doc/html/rfc9334) for gateway state evidence collection and conveyance. |
| 63 | + |
| 64 | +- Originator and beneficiary state validation |
| 65 | + - State: |
| 66 | + - Inconsistent |
| 67 | + - Description: |
| 68 | + - This is the identity and public-key of the entity (originator) in the origin network seeking to transfer the asset to another entity (beneficiary) in the destination network. The public keys are included in the messages of the implementation; But there is no validation mechanism implemented (e.g. Certificate Authorities - Public Key Infrastructure). |
| 69 | + - TODO: |
| 70 | + - [Sub-issue 3798](https://github.com/orgs/hyperledger-cacti/projects/1/views/1?pane=issue&itemId=100462882&issue=hyperledger-cacti%7Ccacti%7C3798) - Implement a mechanism to validate the identity and public-key of the entity (originator) in the origin network seeking to transfer the asset to another entity (beneficiary) in the destination network. |
| 71 | + |
| 72 | +**Inconsistencies - Stage 1:** |
| 73 | + |
| 74 | +- Transfer initiation claim |
| 75 | + - State: |
| 76 | + - Small Inconsistencies |
| 77 | + - Description: |
| 78 | + - The inconsistencies are raised by |
| 79 | + - missing message fields: |
| 80 | + ```JSON |
| 81 | + senderGatewayID, recipientGatewayId, senderGatewayDeviceIdentityPubkey, receiverGatewayDeviceIdentityPubkey |
| 82 | + ``` |
| 83 | + - message fields with different names than the specification: |
| 84 | + ```JSON |
| 85 | + clientGatewaySignaturePubkey (in specification is senderGatewaySignaturePublicKey), serverGatewayPubkey (in specification is receiverGatewaySignaturePublicKey) |
| 86 | + ``` |
| 87 | + - additional fields not defined in the specification: |
| 88 | + ```JSON |
| 89 | + maxRetries, maxTimeout, amountFromOriginator, amountToBeneficiary, processPolicies, mergePolicies |
| 90 | + ``` |
| 91 | + - TODO: |
| 92 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 93 | + |
| 94 | +- Conveyance of gateway and network capabilities |
| 95 | + - State: |
| 96 | + - Small Inconsistencies |
| 97 | + - Description: |
| 98 | + - The inconsistencies are raised by |
| 99 | + - message fields with different names than the specification: |
| 100 | + ```JSON |
| 101 | + signatureAlgorithm (gatewayDefaultSignatureAlgorithm), supportedSignatureAlgorithms (gatewaySupportedSignatureAlgorithms), locktype (networkLockType), lockExpirationTime (networkLockExpirationTime), credentialProfile (gatewayCredentialProfile), loggingProfile (gatewayLoggingProfile), accessControlProfile (gatewayAccessControlProfile) |
| 102 | + ``` |
| 103 | + - additional fields not defined in the specification: |
| 104 | + ```JSON |
| 105 | + senderGatewayNetworkId, permissions?, developerUrn, applicationProfile, subsequentCalls, history |
| 106 | + ``` |
| 107 | + - TODO: |
| 108 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 109 | + |
| 110 | +- Transfer proposal message |
| 111 | + - State: |
| 112 | + - Small Inconsistencies |
| 113 | + - Description: |
| 114 | + - The inconsistencies are raised by |
| 115 | + - message fields with different names than the specification: |
| 116 | + ```JSON |
| 117 | + networkCapabilities(gatewayAndNetworkCapabilities) |
| 118 | + ``` |
| 119 | + - additional fields not defined in the specification: |
| 120 | + ```JSON |
| 121 | + multipleClaimsAllowed, multipleCancelsAllowed, sequenceNumber, resourceUrl, actionResponse |
| 122 | + ``` |
| 123 | + - TODO: |
| 124 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 125 | + |
| 126 | +- Transfer proposal receipt message |
| 127 | + - State: |
| 128 | + - Small Inconsistency |
| 129 | + - Description: |
| 130 | + - additional fields not defined in the specification: |
| 131 | + ```JSON |
| 132 | + transferCounterClaims |
| 133 | + ``` |
| 134 | + - TODO: |
| 135 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 136 | + |
| 137 | +- Reject message |
| 138 | + - State: |
| 139 | + - Inconsistent |
| 140 | + - Description: |
| 141 | + - No Reject message object defined in the implementation. The most similar to this message are the error and errorCode fields defined in the CommonSatp message object. |
| 142 | + - TODO: |
| 143 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 144 | + |
| 145 | +- Transfer commence message |
| 146 | + - State: |
| 147 | + - Small Inconsistency |
| 148 | + - Description: |
| 149 | + - additional fields not defined in the specification: |
| 150 | + ```JSON |
| 151 | + clientTransferNumber |
| 152 | + ``` |
| 153 | + - TODO: |
| 154 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 155 | + |
| 156 | +- Commence response message |
| 157 | + - State: |
| 158 | + - Small Inconsistency |
| 159 | + - Description: |
| 160 | + - additional fields not defined in the specification: |
| 161 | + ```JSON |
| 162 | + serverTransferNumber |
| 163 | + ``` |
| 164 | + - TODO: |
| 165 | + - Decide if wether the specification should be updated to match the implementation, or the other way around. |
| 166 | + |
| 167 | +**Future work:** |
| 168 | + |
| 169 | +Solving the resulting sub-issues in order to reduce inconsistency between the specification and implementation. |
| 170 | + |
| 171 | +**Published in:** |
| 172 | + |
| 173 | +18th of March 2025 by Rodolfo Carapau |
0 commit comments