fpc-cc-invocation.puml

/'
    Copyright 2020 Intel Corporation
    Copyright IBM Corp. All Rights Reserved.

    SPDX-License-Identifier: Apache-2.0
'/

@startuml

'- force wrapping of longer text
'skinparam wrapWidth 400

!pragma teoz true

hide footbox
title Foot Box removed

title Fabric Private Chaincode - Chaincode invocation

actor "User" as User1 order 9

participant "Peer_CLI/\nClient SDK" as CLI order 10

participant "Ledger_enclave" as TLCC1 order 45 #99FF99

participant "Peer" as Peer order 25
participant "ERCC" as ERCC1 order 11

ref over User1, TLCC1
  see fpc-registration-new.puml
  |||
end ref
note over TLCC1
  "Full" FPC only (Post-MVP)
end note

|||

User1 -> CLI ++: invoke <CC_Id, args, ...>

group prepare FPC proposal

CLI -> ERCC1 ++: queryChaincodeEncryptionKey(CC_Id)
return Chaincode_EK

CLI -> CLI : ccreq_msg.rsp_key <- keyGen()
note right
    generate a symmetric key to
    encrypt the FPC chaincode result
end note

CLI -> CLI : ccreq_msg.encryped_request <- encrypt <args, r_key> with Chaincode_EK

end

group invoke
  CLI -> ERCC1 ++: queryListEnclaveCredentials(CC_Id)
  return list of Credentials
  note right
    HostParam in Credentials allows client to identify peers which host enclaves for this Chaincode
  end note

  CLI -> Peer ++: send proposal <- <chaincodeInvoke, CC_Id, ccreq_msg>

  alt FPC Chaincode is not running
      note right Peer
          handled implicitly by the peer which determines
          when to call run() from external builder.
      end note

      create participant "FPC_stub" as ECC1 order 26
      Peer -> ECC1 ++: call external builder run()
      note right
          NOTE: Any failure in ECC or FPC_Enclave will cause
          ecc (and docker) dieing so peer will notice it.
      end note


      ECC1 -> ECC1 ++: get sealed credentials
      note right ECC1
        FPC_stub has access to peer local
        storage through external builder.
      end note
      return

      create participant "FPC_stub_enclave" as Enclave1 order 30 #99FF99
      ECC1 -> Enclave1 ++ : spawn enclave with sealed credentials
      Enclave1 -> Enclave1 : unseal credentials and restore
      return
      return
  end

      Peer -> ECC1 ++: invoke (proposal, CTX)
      note right
        FPC_Stub is called through a normal Fabric invoke which
        uses the function <i>chaincodeInvoke</i> of the proposal
        to dispatch the invocation and call the enclave accordingly.

        Transaction context (CTX) used for all interactions
        with both, the untrusted ledger und trusted ledger (Ledger_enclave)
        within the invocation. It ensures that all state accesses
        are from the same state view (block height).
      end note
      ECC1 -> Enclave1 ++: ecall_chaincode_invoke (proposal, CTX)

      alt "full" FPC (Post-MVP)
        Enclave1 <-> TLCC1: establish secure channel based on local attestation
          note right Enclave1
             See interfaces.ecc-tlcc-channel.md for details on secure channel
          end note

        Enclave1 -> Enclave1 : verify proposal

        Enclave1 -> TLCC1 ++: verify (proposal.creator, CTX)
          note over TLCC1
            Ledger_enclave access is needed to check that the creator
            (client identity) passes MSP validation, that is,
            it comes with a certificate that is a proper root
            of trust.
          end note
        return
      end

      Enclave1 -> Enclave1 : <args, r_key> <- decrypt ccreq_msg.encryped_request with Chaincode_DK

      note right
        If proposal contains optional Req_ledger_enclave_inst_id parameter,
        make sure it matches own Ledger_enclave_inst_id, otherwise abort.
        This is necessary for CC2CC calls to make sure the two chaincodes
        interact with the same Ledger_enclave instance and hence have consistent
        views on ledger state.
      end note

      Enclave1 -> Enclave1: result <- invoke(args, CTX)
      ref over Enclave1
        Chaincode execution
        see fpc-chaincode-execution.puml
      end ref


      Enclave1 -> Enclave1 : ccrsp_msg.encrypted_response <- encrypt result with r_key
      note right
        The encryption is via authenticated symmetric cipher like aes-gcm
      end note
      Enclave1 -> Enclave1 : ccrsp_msg.signature <- sign <proposal, read/writeset, result_enc> with Enclave_SK
      Enclave1 -> Enclave1 : ccrsp_msg.enclave_id <- Enclave_Id
      return <ccrsp_msg>

     alt FPC Lite
       ECC1 -> ECC1 : ccrsp_msg.rw_set <- encrypted_rw_set
       note right ECC1
         with chaincode-hosted validation, the stub will keep track of the 
         R/W set (of cleartext keys but encrypted values) and pass it on to
         the validation transaction as part of the response message.
       end note
       ECC1 -> ECC1 : ccrsp_msg.proposal <- proposal
    end

    return <ccrsp_msg>

  alt  MVP
    Peer -> Peer : create proposal-response <proposal, read/writeset, result=ccrsp_msg, ...>
      note right Peer
          This is the standard Fabric response generation.
          Note that the result field of the proposal response contains
          a message that comprises the encrypted result produced by the
          enclave, the enclave signature, and the corresponding
          verification key.
      end note

  else Post-MVP: Validation
    Peer -> Peer : create proposal-response <proposal, read/writeset, result=ccrsp_msg.result_enc, ...>
    Peer -> Peer : Replace in proposal-response endorsement signature & cert of peer with ccrsp_msg.signature & CC_Params.Certificate
      note right Peer
          These steps are performed using an FPC-specific endorsement plugin.
      end note
  end

  return proposal-response

  loop for all/"enough" enclave endorsers
    note right CLI
      Invoke at enough endorsing peers to satisfy enclave endorsement policy 
      and collect { proposal-response }.

      NOTE: For MVP we support a (single) designated enclave only
    end note
    ref over CLI
      invoke
    end
  end

end

group complete transaction
    ref over CLI, ECC1
      continue with transaction submission/validation
      see fpc-validation.puml
      |||
    end ref
end

group result decryption
    CLI -> CLI : result_enc <- extract from proposal-response
    CLI -> CLI : result <- decrypt result_enc with r_key
end


return result

@enduml