Api design

[mbrandenburger]

What this PR does / why we need it:

This PR proposes the FPC component API and state design based on the most recent UML diagrams. The goal is to stablize the APIs and internal state before current code base can be refactored to align with the FPC design as specified by the UML diagrams.

Which issue(s) this PR fixes:
Addresses #410 but excludes chaincode enclave / tlcc binding as this is covered by #434

Special notes for your reviewer:

Does this PR introduce a user-facing changes and/or breaks backward compatability?:

[mbrandenburger]

@bvavala @g2flyer Can you please have a quick look at this? It's still incomplete; happy for initial thoughts. Thanks

[g2flyer]

So much for a first round of comments. Sorry adding quite a few ...

[bvavala]

Definitely a step forward.
As mentioned, the document should however avoid taking final decision on implementations such as internal data structures.
Also, many things (most related to key distribution) could be marked as out of scope, with the intent of dealing with them after MVP.

[bvavala]

• Given the request routing, I am assuming that this is originally called by ecc_enclave, but I cannot figure out where this is needed. If this is meant to validate the mspid in cc_params, then it is not needed. The reason is that the parameter is checked by ERCC on registration.
• What is actually required is a mechanism to validate a transaction proposal (or perhaps just it creator).

[mbrandenburger]

I changed this function to validate_identity, which can be used to implement get_creator and check if the creator is a valid identity with respect to the consortium defined in this channel.

[mbrandenburger]

renamed it to validate_identity, which can be used to implement getCreator

[bvavala]

Ok, it should be enough for now.

However, this document (part 2) corroborates my second point: we need a mechanism for checking the proposal (including its creator, and thus this API).

[g2flyer]

we definitely need to validate the signed proposal. Using the proposed validate_identity we should be able to conclude that the creator -- as expressed by serializedIdentity which contains the msp-id and the x509 cert with pk, name and role [might help, though, explicitly mention that in the comment around validate_identity -- is a valid party grounded in the specified MSP-id root-of-trust and the rest of the signature verification of the proposal we can do locally to ecc based on the resulted validated public key? Is there any other step in verifying the signedproposal in the enclave we need tlcc assistance?

[bvavala]

(see the link I have attached)
The endorsing peer verifies also that (i) the proposal has not been submitted in the past, (ii) the submitter respects the channel policy. In theory, TLCC should do this. In practice, we can rely on the validators for (i), and delegate (ii, or more precisely, any authentication/authorization) to the enclave.

[g2flyer]

ok, i see now what you mean (didn't initially get what you meant by "part 2"). Good points.

Regarding the replay protection, at first sight it certainly seems mainly a waste of resource you save by checking, as during submission of a replayed transaction it should fail due to rw-set conflicts? This assumes, though, it is state-changing, maybe there could be issues of transactions which might be non-state-changing dependent on state and somebody could try to replay such a transaction at a later time when it would be state-changing? So integrity-wise there might or might not be issue? For FPC maybe confidentiality could add additional twists: As an original tx/query submitter can always recreate a new query, so from overt channel (results to querier) perspective a replay shouldn't help? If there would be covert channel, then a resubmit could potentially help in throttling attacks but that seems rather esoteric? So i would somewhat agree that we can punt on replay protection to validators/rw-conflict (although i have not a good feeling yet how much this this-tx-does-not-change-state-now-but-could-potentially-later scenario is an issue or not.)

regarding authorization, though, it becomes a bit more sensitive as we are talk also about confidentiality (for queries), not only integrity. So maybe the validated_identity should maybe return which permissions the client has and ecc should immediately abort if client doesn't have read privs and abort on first write-attempt if it doesn't have write permissions? Of course, we could also punt on that but would have to document that reader/writer polices could not be trusted to provide confidentiality of information protected fpc cc?

[bvavala]

during submission of a replayed transaction it should fail due to rw-set conflicts?

Probably yes, in a concurrent execution: send proposal P1 and replay it immediately; you get two separate endorsements/transactions where the updated keys likely conflict with each other.
Maybe not, in a serialized execution: send proposal P1 (e.g., incrementCounter), commit transaction; replay P1, commit transaction; here the counter will be incremented by two with a single proposal.

The check that Fabric does should be here. It's based a transaction id value computed over the proposal and stored (at some point) on the ledger.

So maybe the validated_identity should maybe return which permissions the client has and ecc should immediately abort if client doesn't have read privs and abort on first write-attempt if it doesn't have write permissions?

In theory, yes.
However, this is all Fabric logic that TLCC should implement. Following Yacov's recommendation, we can simplify.

Of course, we could also punt on that but would have to document that reader/writer polices could not be trusted to provide confidentiality of information protected fpc cc?

In practice, this is (part of) the solution. The other part (in my answer above) is to tell a developer how to leverage the fpc chaincode to implement an equivalent mechanism.

[g2flyer]

during submission of a replayed transaction it should fail due to rw-set conflicts?
[..]
Maybe not, in a serialized execution: send proposal P1 (e.g., incrementCounter), commit transaction; replay P1, commit transaction; here the counter will be incremented by two with a single proposal.

Oops, of course, this is a much simpler examples where replay works (badly) than my contrieved sometimes-state-changes example. (Not sure what i was thinking in the morning, i guess i was still have up in the mountains ... :-)

The check that Fabric does should be here. It's based a transaction id value computed over the proposal and stored (at some point) on the ledger.

This code seems to be executed by the endorsers. You mentioned above also "rely on the validators for (i)": Do the validators automatically also cross-check this? If so, i think we can punt on them as good peers would ignore replays from a integrity perspective and from a confidentiality perspective there seems only esoteric direct leakage (and not indirect via integrity corruption, which would be caught by validators?) If standard validators would not do it, this (contrary to authorizaton) seems a bit a tough to say we do not support replay protetion and punt it to the app developer? If we can live with some false-positives for replays, we could handle replay protection with a bloom-filter. Actually, for channel & ercc transactions we cannot punt to app developers at all? So we more or less have something inside tlcc? We currently have these three opaque kvs_t files as part of tlcc internal state but seems we might want to be more explicitl. And of course this ties now this to (some) resolutions of #402 ... :-(

So maybe the validated_identity should maybe return which permissions the client has and ecc should immediately abort if client doesn't have read privs and abort on first write-attempt if it doesn't have write permissions?

In theory, yes.
However, this is all Fabric logic that TLCC should implement. Following Yacov's recommendation, we can simplify.

That's what i meant with punt below. But i agree that besides explicit telling you cannot rely on ledger-specified authorization rules (which we would have to do at a minimum) ...

Of course, we could also punt on that but would have to document that reader/writer polices could not be trusted to provide confidentiality of information protected fpc cc?

In practice, this is (part of) the solution. The other part (in my answer above) is to tell a developer how to leverage the fpc chaincode to implement an equivalent mechanism.

... pointing out how to do it themselves is even better. Certainly, per-app authorization policies should be easy to handle via get_creator_name ...

[mbrandenburger]

@bvavala @g2flyer Thanks for your new feedback! I tried to address everything where I can and commented you your feedback. Please have a look and click the resolve conversation btn where ever possible! THanks

[g2flyer]

A few comments: most, though, are responses to ongoing discussions, so you will have to look in the history (and potentially unfolded "hidden conversation") to get them all. All my old comments which are addressed, i've resolved, so only somewhat-open should show up (but as mentioned, potentially buried behind hidden conversations ...)

[g2flyer]

arrgh, wrong radio box again: this was not supposed to be approved. Not all of my comments are crucial but a number of them should hopefully, when addressed,help clarity, and i think the channel_id vs channel_hash it might be good to have some quick discussion on a call?

[g2flyer]

Below a dump regarding the tlcc-ecc session. Sorry, nothing integrated into text from this PR. Hopefully, it is at least parseable .. :-)

Table of Contents

1. ECC - TLCC Tunnel Design Outline
   1. public API
   2. control flow of implementation
   3. sgx_dh_* background

ECC - TLCC Tunnel Design Outline

public API

- ecc_enclave
  - session_setup(channel_id) -> {ctx, channel_hash, tlcc_mrenclave, rc}
  - session_request(ctx, protobuf SessionRequest{TransactionCtx ctx, req anyof ...} req) -> {protobuf SessionResponse{ anyof ...} response, rc}
- tlcc_enclave
  - register_request_handlers(function(SessionRequest)->SessionResponse f)
  - rest should be "under the cover", driven by ecalls

control flow of implementation

- session_setup
  - ecc_enclave (#include <sgx_dh.h>)
    - ectx = EccTlccSessionCtx{sgx_dh_session_t dh, channel_id cid = cid, channel_hash ch, sgx_dh_session_enclave_identity_t tlcc_identity, sgx_key_128bit_t aek}
    - sgx_dh_init_session(initiator, ectx.dh)
    - init_req = protobuf SessionSetupInitMsg{channel_id cid = ectx.cid, enclave_id eid = eid}
    - ecc_enclave-tlcc_enclave ocall+ecall(init_req)
      - in tlcc_enclave (#include <sgx_dh.h>)
	- tctx = TlccEccSessionCtx{sgx_dh_session_t dh, channel_id cid = init_req.cid, enclave_id eid = init_req.eid, sgx_dh_session_enclave_identity_t ecc_identity, sgx_key_128bit_t aek}
	- sgx_dh_init_session(responder, tctx.dh)
	- init_rsp = protobuf SessionSetupInitResponseMsg{sgx_dh_msg1_t msg1}
	- sgx_dh_responder_gen_msg1(init_rsp.msg1, tctx.dh)
	- return(init_rsp}
    - compl_req = protobuf SessionSetupCompleteMsg{sgx_dh_msg2_t msg2}
    - sgx_dh_initiator_proc_msg1(init_rsp.msg1, compl_req.msg2, ectx.dh)
    - ecc_enclave-tlcc_enclave ocall+ecall(compl_req)
      - in tlcc_enclave
	- compl_rsp = protobuf SessionSetupCompleteResponseMsg{sgx_dh_msg3_t msg3, channel_id cid = tctx.cid, channel_hash ch = channel_hash_for(tctx.cid), enclave_id eid = tctx.eid, mac}
	- sgx_dh_responder_proc_msg2(compl_req.msg2, compl.rsp.msg3, tctx.dh, tctx.aek, tctx.ecc_identity)
	- compl_rsp.mac = GMAC(tctx.aek, <compl_req.cid, compl_req.ch, compl_req.eid>) ~= tag of (AES-GCM-Enc(tctx.aek, aad=<compl_req.cid, compl_req.ch, compl_req.eid>, msg={})
	- return(compl_resp}
    - sgx_dh_initiator_proc_msg3(compl_rsp.msg3, ectx, ectx.aek, ectx.tlcc_identity)
    - GMAC_Verify(ectx.aek, <ectx.cid, compl_rsp.ch, eid>)
    - ectx.ch = compl_rsp.ch
    - return success

- session_request(ectx, request)
  - ecc_enclave
    - req_msg = protobuf SessionRequestMsg{Bytes enc_req, nonce n=random()}
    - req_msg.enc_req = AES-GCM-Enc(ectx.aek, aad={req_msg.n}, msg={request})
    - ecc_enclave
      - ecc_enclave-tlcc_enclave ocall+ecall(req_msg)
	- in tlcc_enclave
	  - request = AES-GCM-Dec(tctx.aek, aad={req_msg.n}, msg={req_msg.enc_req})
	  - rsp_msg = protobuf SessionRequestMsg{Bytes enc_rsp}
	  - process(request) -> response
	  - req_msg.enc_rsp = AES-GCM-Enc(tctx.aek, aad={req_msg.n}, msg={response})
	  - return(req_resp}
    - response = AES-GCM-Dec(ectx, ectx.aek, aad={req_msg.n}, msg={rsp_msg.enc_rsp})
    - return response

sgx_dh_* background

- functions
  - [[https://download.01.org/intel-sgx/latest/linux-latest/docs/Intel_SGX_Developer_Reference_Linux_2.10_Open_Source.pdf][Developer Reference Guide v2.10]]
    - overview/flows: page 97-102
    - function list summary with pointers: 121ff
    - function reference: page 305ff
      - trusted (#include <[[https://github.com/intel/linux-sgx/blob/master/common/inc/sgx_dh.h][sgx_dh.h]]>) [[[/home/msteiner/src/projects/intel/sgx/sdk/public/src/linux-sgx.git/common/inc/sgx_dh.h][local]]]
	- sgx_dh_init_session (role=initiator, ctx) -> status
	- (app: session_request_ocall -> session_request_ecall)
	- sgx_dh_init_session (role=responder, ctx) -> status
	- sgx_dh_responder_gen_msg1(*msg1, ctx) -> status
	- (app: session_X_ocall -> session_X_ecall; [missing from
	  flow diagram, but essentially is return flow from above ocall/ecall!])
	- sgx_dh_initiator_proc_msg1(msg1, *msg2, ctx) -> status
	- (app: session_exchange_ocall -> session_exchange_ecall)
	- sgx_dh_responder_proc_msg2(msg2, *msg3, ctx, *eak, *initiator_identity) -> status
	- (app: session_X_ocall -> session_X_ecall; [missing from flow diagram?!])
	  (      note: this flow can also piggyback first payload ..)
	- sgx_dh_initiator_proc_msg3(msg3, ctx, *aek, *responder_identity) -> status
      - key-types
	typedef struct _sgx_dh_session_enclave_identity_t {
	    sgx_cpu_svn_t     cpu_svn;
	    sgx_misc_select_t misc_select;
	    uint8_t           reserved_1[28];
	    sgx_attributes_t  attributes;
	    sgx_measurement_t mr_enclave;
	    uint8_t           reserved_2[32];
	    sgx_measurement_t mr_signer;
	    uint8_t           reserved_3[96];
	    sgx_prod_id_t     isv_prod_id;
	    sgx_isv_svn_t     isv_svn;
	} sgx_dh_session_enclave_identity_t;

      - notes
	- no way to bind explicit session context into the
	  hand-shake, so this will need additional messages
	- we also need a msg0 from initiator to responder, but it
	  is not secured!
	- above also means that _responder_ is first to be able to
	  add payload, not _initiator_, i.e., you need 2 round-trip
	  instead of only 1 to start :-(
	  - you can, though, send public insecured content in msg0
	    and just confirm in msg3
	- two protocol versions (page 98-99 & 99-100, with v2
	  version sligthly more context, all internal to impl of
	  api & presumably more secure)
	  - selected by #define SGX_USE_LAv2_INITIATOR
	    - in below sample, done in Makefile!
	       Enclave_C_Flags += -DSGX_USE_LAv2_INITIATOR
	       Enclave_Cpp_Flags += -DSGX_USE_LAv2_INITIATOR
	    - both versions exist, though, in library, so could be
	      used concurrently
	      #ifdef SGX_USE_LAv2_INITIATOR
	      #define sgx_dh_initiator_proc_msg1 sgx_LAv2_initiator_proc_msg1
	      #define sgx_dh_initiator_proc_msg3 sgx_LAv2_initiator_proc_msg3
	      #else
	      #define sgx_dh_initiator_proc_msg1 sgx_LAv1_initiator_proc_msg1
	      #define sgx_dh_initiator_proc_msg3 sgx_LAv1_initiator_proc_msg3
	      #endif

• samples
  • LocalAttestation/
    • EnclaveInitiator/EnclaveMessageExchange.cpp (sourcegraph)
    • for verification (including debug flags, but not others, say 64-bit)
      • verify_{peerenclavetrust}

[g2flyer]

FYI: to make sure we do not forget updating the UML diagrams as mentioned in comments here, i've created a corresponding issue #432

[g2flyer]

Looks good. As discussed, the changes regarding session i will do as part of #434 and the (minor) reconcilation regarding attestation api is probably best done in #433