Merge pull request keystone-enclave#175 from keystone-enclave/dev-sec…

…ure-storage

Sealing Key Derivation Similar to Intel SGX

docs/source/Keystone-Applications/Data-Sealing.rst

@@ -0,0 +1,92 @@
+Data-Sealing
+============
+
+The data-sealing feature allows an enclave to derive a key for data encryption,
+to be able to save data in untrusted, non-volatile memory outside the enclave.
+This key is bound to the identity of the processor, the security monitor and the
+enclave. Therefore only the same enclave running on the same security monitor
+and the same processor is able to derive the same key. This key can be used to
+encrypt data and store them to unprotected, non-volatile memory. After an
+enclave restart, the enclave can derive the same key again, fetch the encrypted
+data from the untrusted storage and decrypt them using the derived key.
+
+
+Keystone Key-Hierarchy
+######################
+
+The following figure shows the key hierarchy of Keystone:
+
+.. figure:: /_static/images/keystone_key_hierarchy.png
+
+The root of the key hierarchy is the asymmetric processor key pair (SK_D /
+PK_D). The asymmetric security monitor key pair (SK_SK / PK_SM) is derived from
+the measurement of the security monitor (H_SM) and the private processor key
+SK_D.
+
+The resulting security monitor key pair is therefore bound to the processor and
+to the identity of the security monitor itself.
+
+
+Sealing-Key Derivation
+######################
+
+The following figure shows, how the sealing-key is derived in Keystone:
+
+.. figure:: /_static/images/sealing_key_deriv.png
+
+The key is derived using three main inputs:
+
+* The private security monitor key (SK_SM)
+* The hash of the enclave (H_SM)
+* A key identifier
+
+The private security monitor key (SK_SM) ensures that the resulting sealing-key
+is bound to the identity of the processor and the identity of the security
+monitor. Whenever one of the two components change, the resulting sealing-key is
+different.
+
+The enclave hash ensures that the sealing-key is bound to the enclave's
+identity. Therefore, no enclave can derive the key from another enclave.
+
+The key identifier is an additional input to the key derivation function, which
+can be chosen by the enclave. By choosing different values for the key
+identifier, a single enclave is able to derive multiple keys.
+
+
+Usage
+#####
+
+The enclave application library contains the function:
+
+.. code-block:: c
+
+    /* Returns 0 on success */
+    int get_sealing_key(void *sealing_key_struct,
+                        size_t sealing_key_struct_size,
+                        void *key_ident, size_t key_ident_size)
+
+The ``get_sealing_key`` function takes a pointer to the ``sealing_key_struct`` as
+first parameter followed by the length of the struct. The third parameter is a
+pointer to the buffer containing the key identifier and the last parameter
+specifies the length of the key identifier.
+
+The ``sealing_key_struct`` is defined in ``sdk/lib/app/include/sealing.h`` as
+follows:
+
+.. code-block:: c
+
+    struct sealing_key {
+        uint8_t key[SEALING_KEY_LENGTH];
+        uint8_t signature[SIGNATURE_SIZE];
+    };
+
+A generic sealing-key derivation example can be found at
+``sdk/examples/data-sealing`` and looks as follows:
+
+.. code-block:: c
+
+    struct sealing_key key_buffer;
+    char *key_identifier = "identifier";
+
+    int ret = get_sealing_key((void *)&key_buffer, sizeof(key_buffer),
+                              (void *)key_identifier, strlen(key_identifier));

docs/source/index.rst

@@ -28,6 +28,7 @@ Welcome to Keystone Enclave's documentation!
    Keystone-Applications/Compiling-Applications
    Keystone-Applications/Edge-Calls
    Keystone-Applications/Attestation
+   Keystone-Applications/Data-Sealing
 
 .. toctree::
    :maxdepth: 1

tests/test-qemu.expected.log

@@ -16,4 +16,6 @@ Enclave said value: 13
 Enclave said value: 20
 testing attestation
 Attestation report SIGNATURE is valid
+testing data-sealing
+Enclave said: Sealing key derivation successful!
 # 

tests/tests/Makefile

@@ -17,7 +17,7 @@ RUNNER := test-runner.riscv
 CCFLAGS := -I$(SDK_INCLUDE_HOST_DIR) -I$(SDK_INCLUDE_EDGE_DIR) -I$(SDK_INCLUDE_VERIFIER_DIR) -std=c++11
 LDFLAGS := -L$(SDK_LIB_DIR)
 
-TESTS=stack fibonacci long-nop loop malloc fib-bench untrusted attestation
+TESTS=stack fibonacci long-nop loop malloc fib-bench untrusted attestation data-sealing
 
 OBJS := $(patsubst %.riscv, %.o,$(RUNNER)) $(KEYSTONE_OBJ) edge_wrapper.o
 SRCS := $(patsubst %.o, %.cpp, $(OBJS))

tests/tests/data-sealing/Makefile

@@ -0,0 +1,3 @@
+APP = data-sealing
+APP_C_SRCS = data-sealing.c
+include ../app.mk

tests/tests/data-sealing/data-sealing.c

@@ -0,0 +1,59 @@
+/*
+ *  Copyright (c) 2018, The Regents of the University of California (Regents).
+ *
+ *  Copyright (C) 2020 Fraunhofer AISEC
+ *  Authors: Benedikt Kopf <benedikt.kopf@aisec.fraunhofer.de>
+ *           Lukas Auer <lukas.auer@aisec.fraunhofer.de>
+ *           Mathias Morbitzer <mathias.morbitzer@aisec.fraunhofer.de>
+ *
+ *  data-sealing.c
+ *
+ *  Shows how to use the sealing key feature of Keystone
+ *
+ *  All Rights Reserved. See LICENSE for license details.
+ */
+
+#include "eapp_utils.h"
+#include "string.h"
+#include <syscall.h>
+#include "data-sealing.h"
+
+/*
+ *  Function main:
+ *
+ *  Description:
+ *     Derives the sealing key
+ */
+int main()
+{
+  char *key_identifier = "identifier";
+  struct sealing_key key_buffer;
+  int ret = 0;
+
+  /* Derive the sealing key */
+  ret = get_sealing_key(&key_buffer, sizeof(key_buffer),
+                        (void *)key_identifier, strlen(key_identifier));
+
+  if (ret) {
+    ocall_print_buffer("Sealing key derivation failed!\n", 32);
+    EAPP_RETURN(-1);
+  } else {
+    ocall_print_buffer("Sealing key derivation successful!\n", 36);
+    EAPP_RETURN(0);
+  }
+}
+
+/*
+ *  Function ocall_print_buffer:
+ *
+ *  Description:
+ *     Prints the buffer to the console
+ */
+unsigned long ocall_print_buffer(char *data, size_t data_len)
+{
+  unsigned long retval;
+
+  ocall(OCALL_PRINT_BUFFER, data, data_len, &retval ,sizeof(unsigned long));
+
+  return retval;
+}

tests/tests/data-sealing/data-sealing.h

@@ -0,0 +1,16 @@
+/*
+ *  Copyright (C) 2020 Fraunhofer AISEC
+ *  Authors: Benedikt Kopf <benedikt.kopf@aisec.fraunhofer.de>
+ *           Lukas Auer <lukas.auer@aisec.fraunhofer.de>
+ *           Mathias Morbitzer <mathias.morbitzer@aisec.fraunhofer.de>
+ *
+ *  data-sealing.h
+ *
+ *  All Rights Reserved. See LICENSE for license details.
+ */
+
+#include "sealing.h"
+
+#define OCALL_PRINT_BUFFER 1
+
+unsigned long ocall_print_buffer(char *data, size_t data_len);

tests/tests/data-sealing/data-sealing_with_output.c

@@ -0,0 +1,123 @@
+/*
+ *  Copyright (c) 2018, The Regents of the University of California (Regents).
+ *
+ *  Copyright (C) 2020 Fraunhofer AISEC
+ *  Authors: Benedikt Kopf <benedikt.kopf@aisec.fraunhofer.de>
+ *           Lukas Auer <lukas.auer@aisec.fraunhofer.de>
+ *           Mathias Morbitzer <mathias.morbitzer@aisec.fraunhofer.de>
+ *
+ *  data-sealing.c
+ *
+ *  Shows how to use the sealing key feature of Keystone
+ *
+ *  All Rights Reserved. See LICENSE for license details.
+ */
+
+#include "eapp_utils.h"
+#include "string.h"
+#include <syscall.h>
+#include "data-sealing.h"
+
+int hextostring(const unsigned char *hex_in, size_t hex_in_size,
+                char *str_out, size_t str_out_size);
+
+/*
+ *  Function main:
+ *
+ *  Description:
+ *     Derives the sealing key
+ */
+int main()
+{
+  char *key_identifier = "identifier";
+  char *key_identifier_2 = "identifier2";
+  struct sealing_key key_buffer;
+  int ret = 0;
+
+  /* Derive the sealing key */
+  ret = get_sealing_key(&key_buffer, sizeof(key_buffer),
+                        (void *)key_identifier, strlen(key_identifier));
+
+  size_t string_key_size = SEALING_KEY_SIZE * 2 + 1;
+  char string_key[string_key_size];
+  size_t string_signature_size = SIGNATURE_SIZE * 2 + 1;
+  char string_signature[string_signature_size];
+
+  hextostring((const unsigned char *)&key_buffer.key, SEALING_KEY_SIZE, string_key, string_key_size);
+  hextostring((const unsigned char *)&key_buffer.signature, SIGNATURE_SIZE, string_signature, string_signature_size);
+
+  ocall_print_buffer("Key:\n", 6);
+  ocall_print_buffer(string_key, string_key_size);
+  ocall_print_buffer("\nSignature:\n", 13);
+  ocall_print_buffer(string_signature, string_signature_size);
+  ocall_print_buffer("\n", 2);
+
+  ret = get_sealing_key(&key_buffer, sizeof(key_buffer),
+                        (void *)key_identifier_2, strlen(key_identifier_2));
+
+  hextostring((const unsigned char *)&key_buffer.key, SEALING_KEY_SIZE, string_key, string_key_size);
+  hextostring((const unsigned char *)&key_buffer.signature, SIGNATURE_SIZE, string_signature, string_signature_size);
+
+  ocall_print_buffer("Key:\n", 6);
+  ocall_print_buffer(string_key, string_key_size);
+  ocall_print_buffer("\nSignature:\n", 13);
+  ocall_print_buffer(string_signature, string_signature_size);
+  ocall_print_buffer("\n", 2);
+
+  if (ret) {
+    ocall_print_buffer("Sealing key derivation failed!\n", 32);
+    EAPP_RETURN(-1);
+  } else {
+    ocall_print_buffer("Sealing key derivation successful!\n", 36);
+    EAPP_RETURN(0);
+  }
+}
+
+/*
+ *  Function ocall_print_buffer:
+ *
+ *  Description:
+ *     Prints the buffer to the console
+ */
+unsigned long ocall_print_buffer(char *data, size_t data_len)
+{
+  unsigned long retval;
+
+  ocall(OCALL_PRINT_BUFFER, data, data_len, &retval ,sizeof(unsigned long));
+
+  return retval;
+}
+
+/*
+ *  Function hextostring:
+ *
+ *  Description:
+ *     Writes the string representation using the hexadecimal system into the
+ *     output buffer and terminates the generated string with \0
+ *
+ *  Parameters:
+ *     hex_in:        Pointer to the source buffer
+ *     hex_in_size:   Size of the source buffer
+ *     str_out:       Pointer to the buffer for the string representation
+ *     str_out_size:  Size of the output buffer
+ *
+ *  Return value: 0 if function has performed correctly
+ */
+int hextostring(const unsigned char *hex_in, size_t hex_in_size,
+                char *str_out, size_t str_out_size)
+{
+  char *hex = "0123456789ABCDEF";
+  int i;
+
+  if (str_out_size < 2 * hex_in_size + 1) {
+    return -1;
+  }
+
+  for (i = 0; i < hex_in_size; i++) {
+    str_out[2 * i] = hex[hex_in[i] >> 4];
+    str_out[2 * i + 1] = hex[hex_in[i] & 0x0F];
+  }
+
+  str_out[2 * i] = 0x00;
+  return 0;
+}

tests/tests/vault.sh

@@ -19,6 +19,7 @@ PACKAGE_FILES="stack/stack.eapp_riscv \
                fib-bench/fib-bench.eapp_riscv \
                untrusted/untrusted.eapp_riscv \
                attestation/attestation.eapp_riscv \
+               data-sealing/data-sealing.eapp_riscv \
                test-runner.riscv \
                test \
                $EYRIE_DIR/eyrie-rt"