github.com/adnan-c/fabric_e2e_couchdb@v0.6.1-preview.0.20170228180935-21ce6b23cf91/docs/tech/application-ACL.md (about)

     1  # Hyperledger Fabric - Application Access Control Lists
     2  
     3  ## Overview
     4  
     5  We consider the following entities:
     6  
     7  1. *HelloWorld*: is a chaincode that contains a single function called *hello*;
     8  2. *Alice*: is the *HelloWorld* deployer;
     9  3. *Bob*: is the *HelloWorld*'s functions invoker.
    10  
    11  Alice wants to ensure that only Bob can invoke the function *hello*.
    12  
    13  ## Fabric Support
    14  
    15  To allow Alice to specify her own access control lists and Bob to gain access, the fabric layer gives access to following capabilities:
    16  
    17  1. Alice and Bob can sign and verify any message with specific transaction certificates or enrollment certificate they own;
    18  2. The fabric allows to *name* each transaction by means of a unique *binding* to be used to bind application data
    19  to the underlying transaction transporting it;
    20  3. Extended transaction format.
    21  
    22  The fabric layer exposes the following interfaces and functions to allow the application layer to define its own ACLS.
    23  
    24  ### Certificate Handler
    25  
    26  The following interface allows to sign and verify any message using signing key-pair underlying the associated certificate.
    27  The certificate can be a TCert or an ECert.
    28  
    29  ```
    30  // CertificateHandler exposes methods to deal with an ECert/TCert
    31  type CertificateHandler interface {
    32  
    33      // GetCertificate returns the certificate's DER
    34      GetCertificate() []byte
    35  
    36      // Sign signs msg using the signing key corresponding to the certificate
    37      Sign(msg []byte) ([]byte, error)
    38  
    39      // Verify verifies msg using the verifying key corresponding to the certificate
    40      Verify(signature []byte, msg []byte) error
    41  
    42      // GetTransactionHandler returns a new transaction handler relative to this certificate
    43      GetTransactionHandler() (TransactionHandler, error)
    44  }
    45  ```
    46  
    47  
    48  ### Transaction Handler
    49  
    50  The following interface allows to create transactions and give access to the underlying *binding* that can be leveraged to link
    51  application data to the underlying transaction.
    52  
    53  
    54  ```
    55  // TransactionHandler represents a single transaction that can be named by the output of the GetBinding method.
    56  // This transaction is linked to a single Certificate (TCert or ECert).
    57  type TransactionHandler interface {
    58  
    59      // GetCertificateHandler returns the certificate handler relative to the certificate mapped to this transaction
    60      GetCertificateHandler() (CertificateHandler, error)
    61  
    62      // GetBinding returns a binding to the underlying transaction
    63      GetBinding() ([]byte, error)
    64  
    65      // NewChaincodeDeployTransaction is used to deploy chaincode
    66      NewChaincodeDeployTransaction(chaincodeDeploymentSpec *obc.ChaincodeDeploymentSpec, uuid string) (*obc.Transaction, error)
    67  
    68      // NewChaincodeExecute is used to execute chaincode's functions
    69      NewChaincodeExecute(chaincodeInvocation *obc.ChaincodeInvocationSpec, uuid string) (*obc.Transaction, error)
    70  
    71      // NewChaincodeQuery is used to query chaincode's functions
    72      NewChaincodeQuery(chaincodeInvocation *obc.ChaincodeInvocationSpec, uuid string) (*obc.Transaction, error)
    73  }
    74  ```
    75  
    76  ### Client
    77  
    78  The following interface offers a mean to get instances of the previous interfaces.
    79  
    80  ```
    81  type Client interface {
    82  
    83      ...
    84  
    85      // GetEnrollmentCertHandler returns a CertificateHandler whose certificate is the enrollment certificate
    86      GetEnrollmentCertificateHandler() (CertificateHandler, error)
    87  
    88      // GetTCertHandlerNext returns a CertificateHandler whose certificate is the next available TCert
    89      GetTCertificateHandlerNext() (CertificateHandler, error)
    90  
    91      // GetTCertHandlerFromDER returns a CertificateHandler whose certificate is the one passed
    92      GetTCertificateHandlerFromDER(der []byte) (CertificateHandler, error)
    93  
    94  }
    95  ```
    96  
    97  ### Transaction Format
    98  
    99  To support application-level ACLs, the fabric's transaction and chaincode specification format have an additional field to store application-specific metadata.
   100  The content of this field is decided by the application. The fabric layer treats it as an unstructured stream of bytes.
   101  
   102  
   103  ```
   104  
   105  message ChaincodeSpec {
   106  
   107      ...
   108  
   109      ConfidentialityLevel confidentialityLevel;
   110      bytes metadata;
   111  
   112      ...
   113  }
   114  
   115  
   116  message Transaction {
   117      ...
   118  
   119      bytes payload;
   120      bytes metadata;
   121  
   122      ...
   123  }
   124  ```
   125  
   126  Another way to achieve this is to have the payload contain the metadata itself.
   127  
   128  ### Validators
   129  
   130  To assist chaincode execution, the validators provide the chaincode additional information, such as the metadata and the binding.
   131  
   132  ## Application-level access control
   133  
   134  ### Deploy Transaction
   135  
   136  Alice has full control over the deployment transaction's metadata.
   137  In particular, the metadata can be used to store a list of ACLs (one per function), or a list of roles.
   138  To define each of these lists/roles, Alice can use any TCerts/ECerts of the users who have been
   139  granted that (access control) privilege or have been assigned that role. The latter is done offline.
   140  
   141  Now, Alice requires that in order to invoke the *hello* function, a certain message *M* has to be authenticated by an authorized invoker (Bob, in our case).
   142  We distinguish the following two cases:
   143  
   144  1. *M* is one of the chaincode's function arguments;
   145  2. *M* is the invocation message itself, i.e., function-name, arguments.
   146  
   147  ### Execute Transaction
   148  
   149  To invoke *hello*, Bob needs to sign *M* using the TCert/ECert Alice has used to name him in the deployment transaction's metadata.
   150  Let's call this certificate CertBob. At this point Bob does the following:   
   151  
   152  1. Bob obtains a *CertificateHandler* for CertBob, *cHandlerBob*;
   153  2. Bob obtains a new *TransactionHandler* to issue the execute transaction, *txHandler* relative to his next available TCert or his ECert;
   154  3. Bob obtains *txHandler*'s *binding* by invoking *txHandler.getBinding()*;
   155  4. Bob signs *'M || txBinding'* by invoking *cHandlerBob.Sign('M || txBinding')*, let *signature* be the output of the signing function;
   156  5. Bob issues a new execute transaction by invoking, *txHandler.NewChaincodeExecute(...)*. Now, *signature* can be included
   157    in the transaction as one of the argument to be passed to the function or as transaction metadata.
   158  
   159  ### Chaincode Execution
   160  
   161  The validators, who receive the execute transaction issued by Bob, will provide to *hello* the following information:
   162  
   163  1. The *binding* of the execute transaction;
   164  2. The *metadata* of the execute transaction;
   165  3. The *metadata* of the deploy transaction.
   166  
   167  Then, *hello* is responsible for checking that *signature* is indeed a valid signature issued by Bob.