Attribute-based access control

[informartin]

As part of the signing process, we have to ensure that only document signatures of authorized employees are processed by partner organizations. To achieve this, we have agreed on using attribute-based access control. Each organization's CA issues certificates for employees including an attribute attesting the employee's authorization to sign a document. As the validity of document signature cannot be validated on-chain, due to the absence of the document that was shared off-chain beforehand, the validation has to take place off-chain on the partner organization's side. As the Blockchain-adapter subscribes to the storage key of received documents, the validation should be initiated by the Blockchain-adapter as soon as a new signature arrives. The local status of the document, e.g. the amount of valid signatures, should then be updated in the local DB as well. In case the validation fails, proper error handling including standardized error codes need to be implemented. In order to provide a standardized method for validating signatures, the validation should be triggered by the Blockchain-adapter, but implemented in a chaincode function that is called as a local query. Therefore, no transaction is logged on the ledger.

To implement attribute-based access control, the following is required:

• The BC-adapter listens for updates of a storage key from the local HLF Peer
• The BC-adapter initiates the validation performed locally by the chaincode as a query
• The chaincode validates the signature, handles errors and calls the DB-adpter to update the document status if successful
• The DB-adapter needs to be prepared to update the document accordingly

The tasks that needs to be completed

• [x] Add a validation method in the chaincode
• [x] Add respective unit tests
• [ ] When a signature arrives call the is_valid_signature method

Further feedback and comments are welcome!

[Horizon-Developer]

I added the tasks to the first issue for tracking

If I am correct the other parts like saving the signature when they arrive and response to the webhook are already there. Maybe @sgerhardt-trilobyte can confirm this.

@informartin in this validation function do we only check the attribute or also for instance the CA?

[informartin]

From my point of view, the validation function should also check if the certificate was issued by the respective organization's CA. For the MVP, I think it is safe to assume that the CA issuing user certificates is equivalent to the organization's Hyperledger CA. However, that may change in future implementations.

[sgerhardt-trilobyte]

The name of the attribute (ABAC) to check in chaincode is "CanSignDocument". If this attribute is set the user/identity has the permission to sign documents

Example cert:

X509v3 extensions: 1.2.3.4.5.6.7.8.1: {"attrs":{"CanSignDocument":"yes","hf.Affiliation":"","hf.EnrollmentID":"bob","hf.Type":"client"}}

[Horizon-Developer]

@informartin You propose to do the validation async ea triggered after the signature is uploaded. This leaves the validation always to the client.

We could also validate the signature and certificates when/before they are put on the ledger this way only checked sigs are put on the chain. (It also means a bit less moving parts because the check is done in chaincode).

[informartin]

I agree that it would be beneficial to check the signature's validity before it gets uploaded. How would the chaincode perform the validation though? As the document is not available, only the certificate's attribute could be validated, right? In that case a second validation in the client would be necessary.

[dhruvagarwal86]

@sgerhardt-trilobyte : Can you provide reference to the code where you are saving the signature when they arrive and response to the webhook? And, is the OID of the attribute extension fixed and also the value format of the attribute or it can be changed in future?

[sgerhardt-trilobyte]

@dhruvagarwal86 Signatures are stored on the ledger (blockchain). Webapp creates the signatures and forwards them to the blockchain-adapter (BWRP-blockchain-adapter)

see webapp code:

https://github.com/GSMA-CPAS/BWRP-UI/blob/master/webapp/app-core/backend/services/signatures/v1/SignatureService.js

https://github.com/GSMA-CPAS/BWRP-UI/blob/master/webapp/app-core/backend/adapter/blockchain/v1/BlockchainAdapter.js

Documentation of BWRP-blockchain-adapter api can be found here:

https://github.com/GSMA-CPAS/BWRP-blockchain-adapter/blob/master/api/doc/README.md

OID is set by fabric-ca. Documentation regarding HLF-CA ABAC can be found here:

https://github.com/hyperledger/fabric/blob/release-1.4/core/chaincode/lib/cid/README.md https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/users-guide.html#attribute-based-access-control

[dhruvagarwal86]

func (s *RoamingSmartContract) IsValidSignature(ctx contractapi.TransactionContextInterface, document string, signature string, certPEM string) (int, error) {

"IsValidSignature" function receives 3 arguments as below 1 - Document Hash string 2 - Signature String 3 - Certificate array string in JSON format. For example - ["", "<Intermediate Certificate 1 PEM", "<Intermediate Certificate 2 PEM>", ..., ""] Make sure Certificate JSON array string is URL safe.

Tasks performed by the function

1. Extracting the attribute "CanSignDocument" from user certificate and if it's value is yes, proceed further else return false (Signature is Invalid)
2. Validating the Certificate chain till root certificate, if valid proceed further, else return false
3. Validate the document and signature using x509's "CheckSignature" function, if true Signature is valid else invalid

Error Codes

0 = Valid Signature Invalid Signature Scenarios with Error Codes -1 = Failed to parse Certificate JSON string which is passed as 3rd argument to "IsValidSignature" function -2 = Failed to Decode User Certificate PEM from Certificate JSON string which is passed as 3rd argument to "IsValidSignature" function -3 = Failed to parse User Certificate from User Certificate PEM block bytes -4 = Custom Attibute Extension with Oid "1.2.3.4.5.6.7.8.1" not present in User Certificate -5 = Failed to parse Custom Attribute Extension JSON"" -6 = Custom Attribute Extension JSON string doesn't have "attrs" key -7 = "attrs" JSON key value doesn't have "CanSignDocument" key -8 = "CanSignDocument" key value is not yes -9 = Failed to append Root Certificate PEM (from Certificate JSON string passed as 3rd argument to "IsValidSignature" function) to Certificate Pool Object -10 = Failed to append any Intermediate certificate PEM (from certificate JSON string passed as 3rd argument to "IsValidSignature" function) to certificate Pool Object -11 = User Certificate verification failed -12 = Signature validation failed over signed hashed data document from cert's public key

[Horizon-Developer]

@dhruvagarwal86 Thank you for the code in the branch, can you begin a PR to main so that we can review / comment on your code?

[informartin]

Basic functionality is merged.