[cryptolib] Add a top-level otcrypto.h header

1. Include a definition for `status_t`.
2. Add a top-level header file that includes all other cryptolib headers.
3. Add a test to build a binary with the exported header files.

Signed-off-by: Chris Frantz <[email protected]>
(cherry picked from commit b848298)

sw/device/lib/crypto/BUILD

@@ -25,6 +25,9 @@ ot_static_library(
     ],
 )
 
+# This library imports the archive created by the static library rule
+# above. This can be used within the codebase to test the cryptolib
+# as built.
 cc_import(
     name = "crypto",
     static_library = ":otcrypto",
@@ -34,6 +37,25 @@ cc_import(
     ],
 )
 
+# This library imports the archive created by the static library rule
+# above AND provides the header files as though they'd been exported
+# from the repo in the same way as the packaged headers in the
+# cryptolib.tar.xz output below.  This is used to create tests that
+# verify the exported library and header files work correctly when
+# exported.  Because we export a version of the `hardended_bool_t` and
+# `status_t` types, it can be somewhat difficult to use this target
+# within the repo (ie: you cannot use the in-repo definitions of those
+# types, nor can you directly use anything that depends on those types).
+# See //sw/device/test/crypto:otcrypto_export_test as an example.
+cc_import(
+    name = "crypto_exported_for_test",
+    static_library = ":otcrypto",
+    target_compatible_with = [OPENTITAN_CPU],
+    deps = [
+        "//sw/device/lib/crypto/include:exported_headers_for_test",
+    ],
+)
+
 pkg_files(
     name = "package",
     srcs = [

sw/device/lib/crypto/include/BUILD

@@ -31,6 +31,7 @@ cc_library(
         "kdf.h",
         "key_transport.h",
         "mac.h",
+        "otcrypto.h",
         "rsa.h",
     ],
     defines = ["OTCRYPTO_IN_REPO=1"],
@@ -41,6 +42,28 @@ cc_library(
     ],
 )
 
+# Create a library that makes the headers available as though we've been
+# exported from the repo (ie: OTCRYPTO_IN_REPO is not set).
+cc_library(
+    name = "exported_headers_for_test",
+    hdrs = [
+        "aes.h",
+        "datatypes.h",
+        "drbg.h",
+        "ecc.h",
+        "hash.h",
+        "kdf.h",
+        "key_transport.h",
+        "mac.h",
+        "otcrypto.h",
+        "rsa.h",
+        "//sw/device/lib/crypto/include/freestanding:absl_status.h",
+        "//sw/device/lib/crypto/include/freestanding:defs.h",
+        "//sw/device/lib/crypto/include/freestanding:hardened.h",
+    ],
+    includes = ["."],
+)
+
 pkg_files(
     name = "package",
     srcs = glob(["*.h"]),

sw/device/lib/crypto/include/datatypes.h

@@ -5,11 +5,15 @@
 #ifndef OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_DATATYPES_H_
 #define OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_DATATYPES_H_
 
+#include <stddef.h>
+#include <stdint.h>
+
 #ifdef OTCRYPTO_IN_REPO
 #include "sw/device/lib/base/hardened.h"
 #include "sw/device/lib/base/status.h"
 #else
 #include "freestanding/absl_status.h"
+#include "freestanding/defs.h"
 #include "freestanding/hardened.h"
 #endif
 

sw/device/lib/crypto/include/freestanding/BUILD

@@ -6,6 +6,8 @@ package(default_visibility = ["//visibility:public"])
 
 load("@rules_pkg//pkg:mappings.bzl", "pkg_files")
 
+exports_files(glob(["*.h"]))
+
 pkg_files(
     name = "package",
     srcs = glob(["*.h"]),

sw/device/lib/crypto/include/freestanding/defs.h

@@ -0,0 +1,35 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_FREESTANDING_DEFS_H_
+#define OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_FREESTANDING_DEFS_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif  // __cplusplus
+
+/**
+ * OpenTitan's status_t is a single 32-bit word conveying either a result code
+ * or an error code.
+ * - The otcrypto has only one result code: The `Ok` value which is
+ *   equivalent in value to kHardenedBoolTrue.
+ * - The otcrypto error codes all have the MSB set and encode an error type of
+ *   absl_status_t in the lower 5 bits.
+ *
+ *   This definition is supplied to provide the status_t definition when
+ *   otcrypto is exported out of the OpenTitan repository.
+ */
+typedef struct status {
+  int32_t value;
+} status_t;
+
+/**
+ * Attribute for functions which return errors that must be acknowledged.
+ */
+#define OT_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif  // __cplusplus
+#endif  // OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_FREESTANDING_DEFS_H_

sw/device/lib/crypto/include/freestanding/hardened.h

@@ -29,11 +29,11 @@ typedef enum hardened_bool {
   /**
    * The truthy value, expected to be used like #true.
    */
-  kHardenedBoolTrue = HARDENED_BOOL_TRUE,
+  kHardenedBoolTrue = 0x739,
   /**
    * The falsey value, expected to be used like #false.
    */
-  kHardenedBoolFalse = HARDENED_BOOL_FALSE,
+  kHardenedBoolFalse = 0x1d4,
 } hardened_bool_t;
 
 #ifdef __cplusplus

sw/device/lib/crypto/include/otcrypto.h

@@ -0,0 +1,31 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_OTCRYPTO_H_
+#define OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_OTCRYPTO_H_
+
+#include "aes.h"
+#include "datatypes.h"
+#include "drbg.h"
+#include "ecc.h"
+#include "hash.h"
+#include "kdf.h"
+#include "key_transport.h"
+#include "mac.h"
+#include "rsa.h"
+
+/**
+ * @file
+ * @brief Unified header file that includes the full crypto library.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif  // __cplusplus
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif  // __cplusplus
+
+#endif  // OPENTITAN_SW_DEVICE_LIB_CRYPTO_INCLUDE_OTCRYPTO_H_

sw/device/tests/crypto/BUILD

@@ -836,6 +836,18 @@ opentitan_test(
     ],
 )
 
+opentitan_test(
+    name = "otcrypto_export_test",
+    srcs = ["otcrypto_export_test.c"],
+    exec_env = {
+        "//hw/top_earlgrey:fpga_cw310_rom_ext": None,
+    },
+    deps = [
+        "//sw/device/lib/crypto:crypto_exported_for_test",
+        "//sw/device/lib/testing/test_framework:ottf_main",
+    ],
+)
+
 filegroup(
     name = "template_files",
     srcs = [

sw/device/tests/crypto/otcrypto_export_test.c

@@ -0,0 +1,80 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <string.h>
+
+#include "otcrypto.h"
+#include "sw/device/lib/testing/test_framework/ottf_test_config.h"
+
+// This test checks that the static-linked `otcrypto` library is usable and that
+// the otcrypto include files can stand on their own outside the repository.
+//
+// Because we are trying to test the functionality of the includes outside the
+// repo, we link with the special `crypto_exported_for_test` target and avoid
+// in-repo definitions of `status_t` and other in-repo macro definitions.
+
+// From: http://www.abrahamlincolnonline.org/lincoln/speeches/gettysburg.htm
+static const char kGettysburgPrelude[] =
+    "Four score and seven years ago our fathers brought forth on this "
+    "continent, a new nation, conceived in Liberty, and dedicated to the "
+    "proposition that all men are created equal.";
+
+// The following shell command will produce the sha256sum and convert the
+// digest into valid C hexadecimal constants:
+//
+// $ echo -n "Four score and seven years ago our fathers brought forth on this
+// continent, a new nation, conceived in Liberty, and dedicated to the
+// proposition that all men are created equal." |
+//     sha256sum - | cut -f1 -d' ' | sed -e "s/../0x&, /g"
+//
+static const uint8_t kGettysburgDigest[] = {
+    0x1e, 0x6f, 0xd4, 0x03, 0x0f, 0x90, 0x34, 0xcd, 0x77, 0x57, 0x08,
+    0xa3, 0x96, 0xc3, 0x24, 0xed, 0x42, 0x0e, 0xc5, 0x87, 0xeb, 0x3d,
+    0xd4, 0x33, 0xe2, 0x9f, 0x6a, 0xc0, 0x8b, 0x8c, 0xc7, 0xba,
+};
+
+enum {
+  kHashLength = 8,
+};
+
+// Check the value of the status_t.  If the MSB is set, the value is an
+// error and we return the error value.
+#define RETURN_IF_ERROR(expr_) \
+  do {                         \
+    status_t e = expr_;        \
+    if (e.value < 0)           \
+      return e.value;          \
+  } while (0)
+
+int32_t hash_test(void) {
+  uint32_t digest_content[kHashLength];
+  otcrypto_hash_context_t ctx;
+  otcrypto_hash_digest_t digest = {
+      .mode = kOtcryptoHashModeSha256,
+      .len = kHashLength,
+      .data = digest_content,
+  };
+  otcrypto_const_byte_buf_t buf = {
+      .len = sizeof(kGettysburgPrelude) - 1,
+      .data = (const uint8_t *)kGettysburgPrelude,
+  };
+
+  RETURN_IF_ERROR(otcrypto_hash_init(&ctx, kOtcryptoHashModeSha256));
+  RETURN_IF_ERROR(otcrypto_hash_update(&ctx, buf));
+  RETURN_IF_ERROR(otcrypto_hash_final(&ctx, digest));
+
+  if (memcmp(digest.data, kGettysburgDigest, sizeof(kGettysburgDigest)) != 0) {
+    return -1;
+  }
+  return 0;
+}
+
+OTTF_DEFINE_TEST_CONFIG();
+
+bool test_main(void) {
+  int result = hash_test();
+  return result == 0;
+}

sw/device/tests/crypto/otcrypto_hash_test.c

@@ -48,7 +48,7 @@ status_t hash_test(void) {
 
   TRY(otcrypto_hash_init(&ctx, kOtcryptoHashModeSha256));
   TRY(otcrypto_hash_update(&ctx, buf));
-  TRY(otcrypto_hash_final(&ctx, &digest));
+  TRY(otcrypto_hash_final(&ctx, digest));
 
   TRY_CHECK_ARRAYS_EQ((const uint8_t *)digest.data, kGettysburgDigest,
                       ARRAYSIZE(kGettysburgDigest));