Design common attestation / crypto API

[mbrandenburger]

Description

This work items defines a common attestation / crypto API that can be used in various components. The main goal of this task is to reduce redundant code and provide a single implementation usable from c/cc+ and go-based components.

The implementation is based on the PDO crypto library which we have already linked in the project with PR pdo-crypto-lib integration #337

The main focus lies on the c/c++ interface as exposed to the FPC components and implemented by the PDO crypto lib. Ideally, we have this abstraction in case we need to change the underlying implementation and remove the PDO crypto dependency. Additionally, a go interface is designed and its implementation uses cgo to call the corresponding c/c++ interface.

Required functionality:

• create and verify signatures
• encryption and decryption (symmetric/asymmetric)
• SGX attestation evidence verification (support for EPID and DCAP)

TODOs:

• Define Attestation API
• Define Crypto API
• Integrate PDO crypto Lib to implement the new interfaces
• Implement go-based API using cgo
• Create test cases
• Integrate new attestation / crypto API in TLCC
• Integrate attestation / crypto API in FPC_Enclave
• Integrate attestation / crypto API in ERCC

Some ground work has been done already:

• pdo-crypto-lib integration pdo-crypto-lib integration #337
• port pdo crypto tests port pdo crypto tests #367

Other related issues:

• Attestation mechanism: EPID Attestation mechanism: EPID #278
• Generalize attestation support Generalize attestation support #15
• Publicly verifiable attestation Reproducible build for Publicly verifiable attestation #114

[g2flyer]

a few thoughts on the APIs and for which language:

• do we really need a cgo interface for crypto? From what i can see we need crypto as part of processing of client request and response. However, i wonder whether for that case it wouldn't be better to have higher-level C APIs along the lines of WrapRequest(..), UnwrapRequest(...), WrapResponse(...), UnwrapResponse` which we then can wrap with Cgo (and potentially, with swig for Node SDK).

• In general, i think it would be a good idea to implement "sibling" functions like above WrapRequest(..) and UnwrapRequest(...) in the same language and same library as it makes it easiest to keep stuff consistent and re-using code.

• In light of above, i think we should also have both AttestationEvidence generation and verification in C and just a cgo shim for the verification in ercc. We should already have verification code in C from PDO (actually more complete than the one currently in FPC?) and for DCAP we will SGX (and hence C) code anyway on the verification front. So defining a clean attestationevidence API already right now in C should make transition to DCAP much smoother. (Apropos DCAP: @mbrandenburger @jrlinton did we here anything on the IBM Cloud/k8s front regarding needs for attestation tech?)

[bvavala]

A draft implementation of the attestation mechanism is here. The mechanism requires the spid as input to the enclave, and then uses the following ocalls:

void ocall_init_quote(
                [out, size=target_len] uint8_t *target, uint32_t target_len,
                [out, size=egid_len] uint8_t *egid, uint32_t egid_len);
void ocall_get_quote(
                [in, size=spid_len] uint8_t *spid, uint32_t spid_len,
                [in, size=report_len] uint8_t *report, uint32_t report_len,
                [out, size=max_quote_len] uint8_t *quote, uint32_t max_quote_len,
                [out] uint32_t *actual_quote_len);

[mbrandenburger]

// creates an attestation evidence; the evidence_request includes all the form of evidence (EPID/DCAP), the quote, and additional information required to complete the evidence request
void ocall_create_evidence(
        [in] evidence_request
        [out] evidence
);

[g2flyer]

uses the following ocalls:

assuming the quote is the sgx quote, presumably there will also be an additional ocall for the attestation report (as this is the evidence we need as output of this module)?

More importantly, though, the edls seem more the internals of the module/library, what would be the external api? Presumably something like

int get_attestation_evidence(AttestedData ad, bytearray* evidence)

and on verification side something like

int verify_attestation_evidence(AttestedData ad, bytearray evidence)

(AttestedData is the protobuf from our uml spec, with some small changes from #420; bytearray is a placeholder for whatever byte array type is best in c++; ad could be input or output in verify_attestation_evidence.)

[g2flyer]

a few thoughts on the APIs and for which language:

• do we really need a cgo interface for crypto? From what i can see we need crypto as part of processing of client request and response.

In above comment, i've actually overlooked one case and that is verifying "our" endorsement signature which we also have to do in the validation plugins: Given our custom encoding of the parameters, i think though the same argument holds as for tx/query request/response encryption/decryption and a higher level api SignEnclaveEndorsement/VerifyEnclaveEndorsement which gets the parameters as separat params and does the encoding/serialization inside would seem a better place to surface to (c)go as it keeps encoding/serialization at a single place and probably might it even easier in future to change the encoding to adapt to the fabric format (which we will need whenever we go to MSP/X509 endorsements discussed for post-MVP ...)

[g2flyer]

btw: currently fpc currently uses CMAC which doesn't exist in pdo crypto. That said, pdo has HMAC ( ComputeMessageHMAC), i guess there is no fundamental reason to stick with CMAC? (HMAC should actually have more concrete security but is (quite a bit) slower compared to CMAC with AESNI). But neither of it should matter to us?

[bvavala]

// creates an attestation evidence; the evidence_request includes all the form of evidence (EPID/DCAP), the quote, and additional information required to complete the evidence request
void ocall_create_evidence(
        [in] evidence_request
        [out] evidence
);

For this to work with SGX EPID, we would need to pre-load the output of the init_quote -- so the create evidence will be equivalent to get quote.
However, in this case, the create_evidence abstraction does not fully hide the underlying details.

[bvavala]

assuming the quote is the sgx quote, presumably there will also be an additional ocall for the attestation report (as this is the evidence we need as output of this module)?

The attestation report (i.e., the output of get_quote) is returned by ocall_get_quote, inside the enclave.
Also, it is not meant to be communicated outside of the enclave through an ocall, but rather as an chaincode invocation response.

More importantly, though, the edls seem more the internals of the module/library, what would be the external api? Presumably something like

int get_attestation_evidence(AttestedData ad, bytearray* evidence)

The attached code has an attestation object with a constructor that looks like

attestation(keys, cc_parameters)
    create attestedData protobuf
    create report data

and another method that looks like:

to_public_proto
    b64_quote
        ocall_init_quote
        create_report
        ocall_get_quote
    return quote protobuf

and on verification side something like

int verify_attestation_evidence(AttestedData ad, bytearray evidence)

Not done yet.

[g2flyer]

assuming the quote is the sgx quote, presumably there will also be an additional ocall for the attestation report (as this is the evidence we need as output of this module)?

The attestation report (i.e., the output of get_quote) is returned by ocall_get_quote, inside the enclave.

What i meant by "attestation report" is the report returned from IAS. This is the attestation evidence we need in our protocol, not the (epid) quote? Or is the IAS attestation report what you mean when you refer to "quote"? (This would seem terminology-wise a bit confusing but would work with the ocalls you mentioned above.) If not, then it's 100% not clear to me how you see where/how the IAS interaction is handled below to retrieve the IAS report (which should be part of the attestation evidence API?) An easy way of course is to add a third ocall after the one init and get_quote you have which does IAS interaction and returns back the report protobuf instead of the quote protobuf below?

Also, it is not meant to be communicated outside of the enclave through an ocall, but rather as an chaincode invocation response.

More importantly, though, the edls seem more the internals of the module/library, what would be the external api? Presumably something like

int get_attestation_evidence(AttestedData ad, bytearray* evidence)

The attached code has an attestation object with a constructor that looks like

attestation(keys, cc_parameters)
    create attestedData protobuf
    create report data

and another method that looks like:

to_public_proto
    b64_quote
        ocall_init_quote
        create_report
        ocall_get_quote
    return quote protobuf

and on verification side something like

int verify_attestation_evidence(AttestedData ad, bytearray evidence)

Not done yet.