Overview

The identity proof document library (/mufl/mufl_stdlib/identity_proof_document.mm) enables programmatically attesting ADAPT packets with each other. This attestation process validates that the counterpart packet was created from trusted MUFL code and is running in a secure environment.

We can trust counterpart MUFL code only if it is known to us. We must either know and trust the code itself or know and trust its maintainer. In both cases, it’s reasonable to assume that we should know the hash of that code, as the code can’t be trusted otherwise.

However, simply receiving the hash from the counterpart isn’t enough to declare the code as trusted. A malicious packet can pretend to be a trusted one and send us its hash. So, environment attestation becomes crucial.

We can trust the data signed by a trusted environment. Therefore, if the environment signs the hash of the counterpart packet’s code, we can trust that the packet code is indeed what we expect, knowing the hash of the code.

ADAPT’s identity proof document has two fields – Node Description and Attestation Document. The Node Description field contains data identifying the packet, namely, an address document, a packet ID, and the hash of the code. Additionally, when running in certain environments (for example, AWS Nitro Enclave), the field includes the packet ID of a so-called control packet.

The attestation document’s implementation depends on the host environment. For instance, in the secure AWS Nitro Enclave environment, attestation functionality is built-in. As stated earlier, we can’t directly trust the node description obtained from the counterpart packet. Therefore, we need a signature of that data from the host environment. The signature is provided in a special user data field in the host attestation document. The hash of the node description is passed as user data while creating the environment attestation document. Because the hash is included in the final document, the document is signed by the environment.

For comprehensive information about the identity proof document structure, refer to the source code.

While environment attestation is a built-in feature in ADAPT, developers must decide which MUFL code should be classified as trusted and implement the logic in MUFL. You can extract he identity proof document from the transaction envelope. Then, knowing the document’s structure, you can validate which code the counterpart packet is based on, and whether or not you want to trust this code.

This example extracts the identity proof document from the transaction envelope:

application identity_proof_document_example loads library current_transaction_info uses transactions
{
    trn my_trn _
    {
        external_envelope = current_transaction_info::get_external_envelope_or_abort ().
        ip_document = external_envelope $ip_document.

        // Add your logic here
    
        return ::transaction::success [].
    }
}