fpc-registration.puml

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

    SPDX-License-Identifier: Apache-2.0
'/

@startuml

!pragma teoz true

title FPC Enclave Registration

actor "Admin" as Admin order 10
participant "Peer_CLI" as Peer_CLI order 15
participant "FPC_stub" as ECC1 order 20
participant "Ledger Enclave" as TLCC1 order 36 #99FF99
participant "ERCC" as ERCC1 order 40

entity CA order 90

entity IAS order 100
participant Orderer as Orderer order 100

note over TLCC1
  "Full" FPC (Post-MVP)
end note

note right Admin
Types are shown in the fpc-components diagram.
end note

note right Admin
  It is assumed that:
    - Channel has already been created;
    - ERCC has been installed -- approved by the participating organizations;
    - ERCC contains hard-coded the IAS Root Certificate and, for the 
      "full" FPC version (post-MVP), the TLCC_MRenclave.
    - ERCC should have an Endorsement Policy which subsumes the organizational trust
      assumptions for any FPC chaincode executed on this channel. Hence, a suitable
      choice might be to keep it the same as the the Lifecycle Policy, e.g., the 
      majority of Organizations.
      Note: While ERCC transactions are essentially extensions to the chaincode 
      lifecycle and ERCC-managed data is paramount for the overall security of FPC 
      chaincode, ERCC performs strict test on crucial data "baked" into the ERCC
      chaincode definition and such data is already automatically protected by the 
      lifecycle policy.  
end note

Admin -> Admin: Attestation_Params <- <.e.g, SPID, sig-rl, ....>

Admin -> Peer_CLI ++: lifecycle chaincode\n initEnclave (CC_Id, Attestation_Params, Peer_Endpoint)

group enclave creation
  note right Peer_CLI
    This operation can only be performed after the chaincode definition ---
    which defines the root of trust (MRENCLAVE) for the FPC Chaincode ---
    is committed on the channel. More specifically, this commitment must have
    completed before below 'registerEnclave' starts  in order to complete the
    enclave registration step.

    PS: In the future (post-MVP) when we support chaincode upgrades, the
    interleaving of below with normal lifecycle commands will have to be revisited;
    chaincode upgrades will require consistent and atomic updates of both the
    chaincode definition on the channel as well as in ERCC.
  end note

  Peer_CLI -> Peer_CLI : init_enclave_msg.attestation_params <- Attestation_Params
  Peer_CLI -> Peer_CLI : init_enclave_msg.peer_endpoint <- Peer_Endpoint

  Peer_CLI -> ECC1 ++: initEnclave (init_encalve_msg)
  ref over ECC1
    This might trigger [FPC Chaincode is not running] from fpc-cc-invocation.puml
  end ref

  ECC1 -> ECC1: fetch CC_Params and Host_Params objects
  note right ECC1
    The CC_Params help binding the enclave to a specific FPC chaincode,
    as it is registered in Fabric.

    The requirement of CC_Params can be met in practice as follows:
    CC_Id, version, and channel id can be retrieved through Fabric
    shim functions

    The Host_Params has two purposes: enable endpoint discovery for enclaves
    and capture the endorsement of the organization hosting the enclave.
    The stub creates it based on 'getCreator' to retrieve the MSP ID 
    (for Host_Params.Peer_MSP_ID) and from the endpoint address passed in initEnclave. 

    Note that the validation of these parameters is performed by ERCC.
    If necessary, a pre-validation can be performed through the Ledger Enclave.
  end note

  create "FPC_stub_enclave" as Enclave1 order 30 #99FF99
  ECC1 -> Enclave1 ++: ecall_init(CC_Params, Host_Params, Attestation_Params)

  Enclave1 -> Enclave1 : <Public_Keys, Private_Keys>  <- generate keys
  note right Enclave1
    This step generates the enclave's public and private keys used by
    the FPC chaincode to sign transactions and decrypt transaction arguments.
    See fpc-components.uml diagram for more details
  end note

  Enclave1 -> Enclave1 : Enclave_Id <- Hash(Enclave_VK)
  note right Enclave1
    A sha256 hash of the enclave signature verification key (Enclave_VK)
    is used as unique enclave identifier
  end note

  group attestation preparation
    alt FPC Lite
      Enclave1 -> Enclave1 : AttestedData <- <CC_Params, Host_Params, Enclave_VK, Channel_hash, onCreation=true>
      note right Enclave1
      In the future an admin might want to request re-attestations: For EPID this would be
      the only way to check for revocations (In DCAP, checking CRLs would enable this as well).
      For security reasoning, it is crucial that the TCB level (CPUSVN) of the seal operation is
      reflected in the attestation (and, hence, ERCC registration).
      We ensure that performing the initial attestation before sealing the state and distinguish
      the intial from subsequent attestations  based on the onCreation field in AttestedData.
      end note
    else "full" FPC (Post-MVP)
      group establish secure channel based on local attestation to retrieve MRENCLAVE of TLCC and cryptographic channel identifier (channel_hash)
        Enclave1 -> TLCC1 ++: tl_session_setup(Channel_Id, CC_Id, Enclave_Id)
        return

        Enclave1 -> TLCC1 ++: tl_session_get_tlcc_mrenclave()
        return tlcc_mrenclave

        Enclave1 -> TLCC1 ++: tl_session_get_channel_hash()
        return channel_hash
      end group

      Enclave1 -> Enclave1 : AttestedData <- <CC_Params, Host_Params, Enclave_VK, Channel_hash, tlcc_mrenclave, onCreation=true>
    end
  end group

  group enclave attestation
  Enclave1 -> Enclave1 : init_attestation(Attestation_Params)
  Enclave1 -> Enclave1 : get_attestation(AttestedData)
  note right Enclave1
    The GetAttestation method abstracts/generalizes the attestation protocol used here.
    Currently, Intel SGX supports two different attestation schemes, namely,
    EPID-based attestation and DCAP. For more details see Intel SGX docu.

    In this diagram we illustrate the flow of the EPID-based attestation, which
    involves Intel Attestation Service (IAS). As the EPID attestation requires
    the SPID to generate a quote, the peer provides it through FPC_stub.
  end note

  Enclave1 -> Enclave1 : Attestation <- create quote using Attestation_Params.SPID over Hash(AttestedData)

  end group

  ' sealing and storing state will eventually performed by a separate secure storage module, that is, details below may change in the future
  Enclave1 -> Enclave1 : Sealed_State <- seal <CC_Params, Host_Params, Private_Keys, Public_Keys>
    note right Enclave1
        The enclave keeps CC_Paramenters, Host_Params, Public_Keys, and Private_Keys as local state
        in memory during it's lifetime.  Once an enclave restarts, this state is
        deleted and must be restored. For this reason, the enclave state is sealed
        so it can be stored outside the enclave for recovery. 
        Also, a new secure connection with the Ledger Enclave must be established.
    end note

  Enclave1 -> ECC1 ++: store Sealed_State
  return
  note right ECC1
    FPC_stub stores sealed chaincode state with the help of
    the external builder on the peer local storage.
  end note

  Enclave1 -> Enclave1 : Credentials <- <AttestedData, Attestation>
  return Credentials

group Org-Enclave binding/certification [Post-MVP: Validation]
  note right ECC1
     In MVP, the attestation will be carried in the fabric transaction response payload in addition to the normal peer endorsement signature.
     To enable cleaner integration into Fabric and, in particular, support multi-enclave endorsement, post-MVP we will provide the enclave
     with a peer-certificate on Private_keys.Enclave_VK rooted in the organizations MSP -- more cleanly expressing that the Org take
     "ownership" of this enclave -- and replace the normal peer endorsement signature with the enclave signature.
     The corresponding changes will be marked with '[Post-MVP: Validation]'.
  end note

  ECC1 -> Enclave1 ++: getCSR
  Enclave1 -> Enclave1 : csr <- generate_csr(Private_Keys.Enclave_SK, CC_Params)
  return csr /' ECC1 -> Enclave1 '/
  ECC1 -> CA ++: issueCertificate(csr)
  return  cert /' ECC1 -> CA '/
  ECC1 -> ECC1: Credentials.Certificate <- cert
end group

return Credentials

end

group Attestation-to-Evidence Conversion
  Peer_CLI -> Peer_CLI +: AttestationToEvidence(Credentials.Attestation)
  Peer_CLI -> IAS ++: send Credentials.Attestation for verification
  note left IAS
    IAS verifies the quote produced by the enclave and returns
    a signed verification report that is used as evidence that
    the enclave runs a certain FPC enclave in certain security context.
  end note
  return Verification_Report
  return Credentials.Evidence <- Verification_Report
end

  loop for all/"enough" endorsers to satisfy ercc endorsement policy
    Peer_CLI -> ERCC1 ++: registerEnclave (Credentials)
    note right ERCC1
        Note that ERCC aborts if a single check failed.
    end note

    group enclave attestation - evidence validation
      ERCC1 -> ERCC1 : verify_evidence(Credentials.Evidence)
      note right ERCC1
        The evidence check ensures that the evidence is correct (e.g. in
        case of EPID-based attestation the evidence must be signed by IAS)
        and covers Hash(Credentials.AttestedData).

        Note that the IAS verification key is hardcoded in ERCC. This
        verification key does not change frequently. In the case the verification
        key changes, the ERCC must be updated and upgraded through the normal
        chaincode lifecycle upgrade operation.
      end note
      ERCC1 -> ERCC1 : check Credentials.AttestedData
      note right ERCC1
        - check that CC_Params match chaincode definition
        - Channel_Id should correspond to ERCC's own view
        - Channel_hash should corresponds to peers view of the channel id
        - MSPID should correspond to the tx sender
        - TLCC_MRENCLAVE matches the version baked into ERCC ("full" FPC only, Post-MVP)
        - CC_Version matches MRENCLAVE from (validated) Credentials.Evidence
      end note
   end group

  alt Org-Enclave binding verification [MVP: Validation]
    ERCC1 -> ERCC1 : check Credentials.Host_Params.Peer_MSP_ID
      note right ERCC1
        must match msp ID from getCreator of this request
      end note
  else Org-Enclave binding verification [Post-MVP: Validation]
    ERCC1 -> ERCC1 : check Org-Enclave binding certificate
      note right ERCC1
        - Credentials.AttestedData.CC_Params == Credentials.Certificate.CC_Params
        - Credentials.Certificate should be issued by CA owned by Credentials.Host_Params.Peer_MSP_ID
        - Credentials.Certificate.role == 'peer'
      end note
  end

  group check consistency of Credentials
    create Lifecycle order 55
    ERCC1 -> Lifecycle +: queryChaincodeDefinition (Credentials.AttestedData.CC_Params.CC_Id)
    return chaincode definition

    ERCC1 -> ERCC1    : check Credentials.AttestedData.CC_Params against chaincode definition
    note right ERCC1
        This check ensures that:
        1) the chaincode version (i.e., the MREnclave) matches the
            version of the approved chaincode.
        2) the chaincode is registered

        Note that (1) is security-critical and saves the client from
        verifying the chaincode version/MREnclave.

        Note that (2) merely prevents spurious chaincode enclaves from
        being registered.
    end note
  end group

  group Deployment validation  [Post-MVP: Risk-management]
    ERCC1 -> ERCC1 : validate FPC deployment (restriction) policy
    note right ERCC1
      This might cover policies like anti-collocation, risk-budgets for collocated chaincodes or alike.
    end note
  end group

  ERCC1 -> ERCC1 : putState(namespaces/credentials/$CC_Id/$Enclave_Id, Credentials)
  note over ERCC1
  end note

  return  proposal response
  end loop



  Peer_CLI -> Peer_CLI : form transaction
  Peer_CLI -> Orderer: submit registerEnclave transaction

  return

@enduml