Skip to content

Latest commit

 

History

History
187 lines (134 loc) · 8.56 KB

4.5-attesteer.md

File metadata and controls

187 lines (134 loc) · 8.56 KB
Raw

4.5 Attesteer

The Integritee Attesteer is an API service to interface with the decentralized DCAP attestation on the Integritee Network.

Advantages of using the Attesteer:

  • No need for a license with Intel
  • Your end-users can verify remote attestation themselves and authenticate your enclave (client side) thanks to our public Integritee Network.
  • Unstoppable: remote attestation on Integritee Network doesn't rely on the consent or availability of Intel or data centers hosting your SGX machine.
  • Hassle-free remote attestation

Three Ways to do Remote Attestation on Integritee Network

  1. If you build your enclave based on our SDK, you don't need the Attesteer because your enclave will be sovereign; it can interact with the Integritee Network to do DCAP attestation independently.
  2. If you build your enclave with Gramine and deploy it with securitee.tech, you need not worry. The attestation on the Integritee Network will happen automatically, managed by marblerun as a part of the Securitee service.
  3. In case you build a custom enclave yourself from scratch, the Attesteer JSON-RPC is your easy-to-use gateway API to the Integritee Network. See instructions below on how to do that.

How to use the Attesteer

The Attesteer acts as a proxy for remote attestation for enclaves that are not sovereign (i.e. can't send RA transaction to the Integritee Network by themselves). For Intel SGX enclaves, this is really just a proxy forwarding service, which would not even need to run in an enclave.

For enclaves not built with our SDK and not managed by MarbleRun on securitee.tech, the Attesteer exposes an API, which will forward attestation quotes for you.

obtain a quote

We will show here step by step how this works with Intel's sample enclave.

In the following, we assume that you

  1. have the Intel SGX SDK installed
  2. have a working build environment
  3. are working on a real Intel SGX enabled machine with correct BIOS settings and recent security patches applied

{% code overflow="wrap" lineNumbers="true" %}

git clone git@github.com:intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives
git checkout DCAP_1.16
cd SampleCode/QuoteGenerationSample
make
./app
xxd -plain quote.dat | tr -d '[[:blank:][:space:]]' > quote_single_line.hex

{% endcode %}

The output quote_single_line.hex can now be sent to the attesteer by two different methods:

Method 1 - JSON API for Attesteer Kusama

To utilize the Integritee JSON API, you will need obtain a personal bearer token in the future. For now, the token can be any word of your choosing, for instance: YOURTOKEN.

Check API availability: Retrieving Methods

To retrieve a list of available methods, use the following cURL command:

{% code overflow="wrap" lineNumbers="true" %}

curl -X 'GET' \
https://services.integritee.network/v1/attesteer/get_methods \
-H 'accept: */*' \
-H 'Authorization: Bearer YOURTOKEN'

{% endcode %}

The response should be similar to

{% code overflow="wrap" lineNumbers="true" %}

{ 
"data": "{\"jsonrpc\":\"2.0\",\"result\":\"methods: [attesteer_forwardDcapQuote, attesteer_forwardIasAttestationReport, author_getShieldingKey, author_getUntrustedUrl, author_pendingExtrinsics, author_pendingTrustedCallsFor, author_submitAndWatchExtrinsic, author_submitExtrinsic, system_health, system_name, system_version]\",\"id\":1}", 
"error_code": 0, 
"error_message": "null" 
}

{% endcode %}

Forwarding a DCAP Quote

To forward your DCAP quote, use the following cURL command:

{% code overflow="wrap" lineNumbers="true" %}

curl -X 'POST' \
'https://services.integritee.network/v1/attesteer/forward_dcap_quote' \
-H 'accept: */*' \
-H 'Authorization: Bearer YOURTOKEN' \
-H 'Content-Type: application/json' \
-d "{ \"quote\": \"$(<quote_single_line.hex)\", \"url\": \"yourdomain.com\" }"

{% endcode %}

Response:

{% code overflow="wrap" lineNumbers="true" %}

{ 
"data": "{\"jsonrpc\":\"2.0\",\"result\":\"0x.....\",\"id\":1}", 
"error_code": 0, 
"error_message": "null" 
}

{% endcode %}

Method 2 - Websocat Directly into Enclave

for advanced users only. The direct enclave API may be discontinued in the future

The API endpoints of the attesteer enclaves are (json-rpc over secure websocket):

  • Mainnet: attesteer-kusama.integritee.network:2000
  • Testnet on Paseo: attesteer-paseo.integritee.network:3000

Check API availability: Retrieving Methods

For test purposes, you could send this request with websocat (replace the JSON request with your own. The one below just fetches the available methods):

You will need to setup a Rust build environment for this

{% code overflow="wrap" lineNumbers="true" %}

cargo install websocat
echo '{"jsonrpc":"2.0","method":"rpc_methods","params":[],"id":1}' > request.json 
echo "$(cat request.json | tr -d '\n' )" | websocat wss://attesteer-paseo.integritee.network:3000 --insecure

{% endcode %}

Submitting a DCAP Quote directly to Attesteer Enclave

From the output quote_single_line.hex you generated above, you can build your JSON-RPC request like this:

{% code overflow="wrap" lineNumbers="true" %}

quote=$(<quote_single_line.hex)
echo '{
    "jsonrpc":"2.0",
    "method":"attesteer_forwardDcapQuote",
    "params":[
        "QUOTE",
        "myenclave.com"
    ],
    "id": 1
}' | sed "s/\"QUOTE\"/\"$quote\"/g" > request.json
echo "$(cat request.json | tr -d '\n' )" | websocat wss://attesteer-paseo.integritee.network:3000 --insecure

{% endcode %}

You can see in the above snippet that there is an optional parameter for the public URL myenclave.com of your enclave. In the next section, we will explain why this is important for public auditability.

Onchain Teerex Registry

If the request is correct, the Attesteer will send the quote to the Integritee Network for verification and your enclave will be recorded in the teerex registry, where everyone can look up your enclave's attributes:

  • the MRENCLAVE
  • the signing key (if you provide it as SGX_REPORT_DATA when you build your enclave)
  • the URL where your enclave is reachable (optional)

The full information in the teerex registry is:

  • the MRENCLAVE in the case of Intel SGX fingerprint: 0x8a2faa318ac37bd3895979188d86a1514bd66ce024a169f20f92640ec4f158f9
  • the attesteer's account: registrar: 2JqMzr1BanEZQ4xG3mGCWcmXdoiEPWMkiuf2XqVn1qmuQy4w
  • the public key for users to do enclave authentication with signer: { Opaque: 0x3792475ef5e50be41e68a2b48c85d92c4245e97f17b21b6d2d9000ee8c4bfc5a00000000000000000000000000000000000000000000000000000000000000000000 }
  • timestamp of quote verification: timestamp: 1,691,754,696,185
  • the public url of your enclave: url: my.enclave.com
  • SGX-specific stuff
    • the MRSIGNER who signed the enclave build (vendor): mrSigner: 0x43361affedeb75affee9baec7e054a5e14883213e5a121b67d74a0e12e9d2b7a
    • SGX_MODE: buildMode: Production
    • Attestation SGX_STATUS: status: Ok

Dashboard

For convenience, we provide a dashboard where you can browse the contents of the teerex registry and verify your enclave has been attested successfully.

Enclave Authentication

The Integritee Network's promise of public auditability is only meaningful if end users can look up your enclave on the Integritee Network and find the enclave's authentication public key together with the URL to initiate communication with your enclave.

In the best case, the enclave's key should be generated within the enclave itself as an initialization step and then provided as SGX_REPORT_DATA when generating the quote. In the sample code we used above, you could introduce the public key on this line.

We make no assumptions whatsoever about the cryptography you use for this, nor the protocol you use to talk to your enclave. It is up to you to communicate to your users how they should authenticate your enclaves.