Openenclave: Crypto Library Modularity in Enclaves

[johnkord]

Note: This design document is currently being revised.

Crypto Library Modularity in Enclaves

Author: John Kordich
Current Revision: 3
Latest Revision Date: 2018-12-10
First Revision Date: 2018-11-15

Abstract

This document proposes to add a new library named “oecrypto” to be linked together with enclaves, which will function as a layer of abstraction for cryptographic function implementations. Developers will be able to implement this library to define the functions that the OE enclave libraries will invoke. This allows developers to use a cryptographic suite other than mbedtls in an enclave by writing their own wrapper functions to wrap a developer-chosen cryptographic suite. If a developer does not want to use their own crypto library, mbedtls will be used by default.

Current Behavior

Currently, enclaves reference crypto wrapper functions that are prefixed with “oe_”, which then directly call mbedtls functions. For example, in the file “openenclave/enclave/sha.c”, you can find the function "oe_sha256_update", which is invoked by the enclave core libraries during report verification. Here is the definition of that function:

oe_result_t oe_sha256_update(
    oe_sha256_context_t* context,
    const void* data,
    size_t size)
{
    oe_result_t result = OE_INVALID_PARAMETER;
    oe_sha256_context_impl_t* impl = (oe_sha256_context_impl_t*)context;

    if (!context || !data)
        OE_RAISE(OE_INVALID_PARAMETER);

    mbedtls_sha256_update_ret(&impl->ctx, data, size);

    result = OE_OK;

done:
    return result;
}

This function can be seen above to call “mbedtls_sha256_update_ret”, which is a crypto function defined by the mbedtls libraries and is coupled to the mbedtls API. Currently, if a developer wants to use a different cryptography library besides mbedtls to perform SHA256 hashes, they would need to modify the Open Enclave source significantly to replace all interfaces to mbedtls.

Proposed Behavior

There will be an alternative implementation of the oe_-prefixed crypto functions for enclaves that will invoke a subset of OpenSSL 1.1 API functions. Developers can then implement this OpenSSL 1.1 API subset to wrap around cryptography libraries of their own choosing. Creating an implementation of this subset of the OpenSSL 1.1 API can be referred to as an implementation of the oecrypto library. Developers will then link their enclaves against their newly implemented oecrypto library and the actual cryptography libraries that their implementation of oecrypto wraps.

For example, in the code snippet above that references oe_sha256_update, that function will have an alternative implementation that invokes OpenSSL that an enclave can link with:

oe_result_t oe_sha256_update(
    oe_sha256_context_t* context,
    const void* data,
    size_t size)
{
    oe_result_t result = OE_UNEXPECTED;
    oe_sha256_context_impl_t* impl = (oe_sha256_context_impl_t*)context;

    if (!context)
        OE_RAISE(OE_INVALID_PARAMETER);

    if (!SHA256_Update(&impl->ctx, data, size))
        OE_RAISE(OE_FAILURE);

    result = OE_OK;

done:
    return result;
}

That "SHA256_Update" OpenSSL function can then be defined in any way a developer wishes to define it. The intention of this design is to allow a developer to define this function (and define a subset of the whole OpenSSL 1.1 API) to wrap around a crypto library of their choosing. OpenSSL was chosen as the base API because many crypto libraries already provide wrapper APIs to interface with OpenSSL.

Visualized, this is how linking will be possible with this proposal:

Note that both the "Current" and "Proposed" items in the above graph will be possible when this feature is implemented.

If developers wish to have a similar experience as they currently have (i.e. they are satisfied using the mbedtls crypto libraries), then they will be able to continue to do so.

If developers wish to provide/use an oecrypto library, they will get specific link flags passed to them when invoking pkg-config.

oecrypto API (Work in Progress)

• This API will be what developers need to implement in order to provide Open Enclave the crypto functionality it needs.
• A subset of the OpenSSL 1.1 API
• This will be specified as soon as prototyping work completes.

Testing and Verification

• There will be a test suite that a developer can use to verify that a custom implementation of the oecrypto library is satisfactory.

Questions for Consideration

• Should there also be support for oecrypto libraries for host crypto use? Currently host executables interface with the same oecrypto API that enclaves use, so the cost to do this would be relatively low.
• Should there be support for more crypto functions in our API than what’s currently available? The secure filesystem work will likely need symmetric encryption functions. There is also some work to enable X509 certificate generation in enclaves. It is likely that the API will expand to support these operations in enclaves.
• The Intel SGX SSL library will hopefully be a satisfactory implementation of an oecrypto library, but how many new functions will we need to add to it? (Especially with the new requirements for the X509 cert gen and the symmetric encryption functions). To be determined.

Acknowledgements

Thanks to @CodeMonkeyLeet and @gupta-ak for originally proposing this idea and their great notes in the issues referenced below[1][2].

References

[1] #401
[2] #1003
[3] #852 -

[anitagov]

Looks good. Minor comments:
Consider rephrasing and perhaps shortening this sentence. "which can seen above to then call" can be replaced with "which then invokes mdedtls.... as shown in the code snippet/function"
From within an enclave, a user would invoke “oe_sha256_update”, which can be seen above to then call “mbedtls_sha256_update_ret”, which is a crypto function defined by the mbedcrypto library (one of the mbedtls libraries).

[soccerGB]

Could multiple crypto libraries co-exist in the same system at the same time? Or this oecrypto library can only lock to one single chosen library?

[johnkord]

Thanks @anitagov!

And @soccerGB : the answer to your first question is yes, multiple crypto libraries could (and usually do) exist on the same system at once! They're just libraries (.a/.lib and .so/.dll). It's very common to have both NSS and OpenSSL installed on the same system for many Linux distributions!

Also, as for your second question: the oecrypto library implementation is left up to the developer, they just need to implement the oecrypto API. That implementation can be as simple or complex as a developer wants. For example, it could be entirely possible for a user to want to use an OpenSSL implementation of a crypto function in most circumstances, but in some circumstances use an mbedtls implementation of that same crypto function, and they could write their oecrypto wrapper library to delegate which version gets invoked based on whatever circumstances they wish. Of course, they would need to deem that to be important to develop such delegation (perhaps some governmental or business reasons).

[anakrish]

There needs to be a crypto testsuite that accompanies the crypto API.
That would help developers test any crypto library that they are wrapping to make sure it behaves as OE expects.

[anakrish]

It would be good for OE to provide by a shim layer over popular crypto interfaces:

1. Open SSL. That would make any enclave compatible implementations of Open SSL usable.
2. SGX Crypto abstraction layer: https://github.com/intel/linux-sgx/blob/master/common/inc/sgx_tcrypto.h

[anakrish]

It would be good to coordinate with @mikbras 's filesystem implementation where the user can provide custom file-system implementations. A nice to have would be to have users use a similar model for extending OE.

[johnkord]

Version 3 was just posted, updating for some discussions we had on Friday about how mbedtls will fit into this plan.

[johnkord]

Closing this because the design is being reconsidered.