[crypto,devbundle] Package cryptolib as part of the release devbundle (+ doxygen fixes)

release/devbundle/BUILD

@@ -51,6 +51,41 @@ pkg_filegroup(
     tags = ["manual"],
 )
 
+# Build up a cryptolib package with a conventional 'include/lib/*.h` and `lib/*.a` structure
+pkg_files(
+    name = "cryptolib_headers_pkg",
+    srcs = [
+        "//sw/device/lib/crypto/include:package",
+    ],
+    prefix = "include/libotcrypto",
+)
+
+pkg_files(
+    name = "cryptolib_freestanding_headers_pkg",
+    srcs = [
+        "//sw/device/lib/crypto/include/freestanding:package",
+    ],
+    prefix = "include/libotcrypto/freestanding",
+)
+
+pkg_files(
+    name = "cryptolib_archive_pkg",
+    srcs = [
+        "//sw/device/lib/crypto:package",
+    ],
+    prefix = "lib",
+)
+
+pkg_filegroup(
+    name = "cryptolib_pkg",
+    srcs = [
+        ":cryptolib_archive_pkg",
+        ":cryptolib_freestanding_headers_pkg",
+        ":cryptolib_headers_pkg",
+    ],
+    prefix = "libotcrypto",
+)
+
 pkg_files(
     name = "bazel",
     srcs = [
@@ -86,6 +121,7 @@ pkg_tar(
     srcs = [
         ":bazel",
         ":bitstreams_pkg",
+        ":cryptolib_pkg",
         ":opentitantool",
         "//hw:package",
         "//hw/ip/otp_ctrl/data:package",

sw/device/lib/crypto/include/BUILD

@@ -5,6 +5,7 @@
 package(default_visibility = ["//visibility:public"])
 
 load("@rules_pkg//pkg:mappings.bzl", "pkg_files")
+load("//sw/device/lib/crypto/include:api_config.bzl", "cryptolib_api_config_header")
 
 config_setting(
     name = "disable_buf_integrity_checks",
@@ -16,15 +17,28 @@ config_setting(
 # Export all headers.
 exports_files(glob(["*.h"]))
 
+# Header defining build options for the public ABI
+cryptolib_api_config_header(
+    name = "api_config.h",
+    buffer_integrity_checks = select({
+        ":disable_buf_integrity_checks": False,
+        "//conditions:default": True,
+    }),
+)
+
+cc_library(
+    name = "api_config",
+    hdrs = [":api_config.h"],
+    defines = ["OTCRYPTO"],
+)
+
 cc_library(
     name = "datatypes",
     hdrs = ["datatypes.h"],
-    defines = ["OTCRYPTO_IN_REPO=1"] + select({
-        ":disable_buf_integrity_checks": ["OTCRYPTO_DISABLE_BUF_INTEGRITY_CHECKS"],
-        "//conditions:default": [],
-    }),
+    defines = ["OTCRYPTO_IN_REPO=1"],
     includes = ["."],
     deps = [
+        ":api_config",
         "//sw/device/lib/base:hardened",
         "//sw/device/lib/base:status",
     ],
@@ -57,12 +71,10 @@ cc_library(
         "sha2.h",
         "sha3.h",
     ],
-    defines = ["OTCRYPTO_IN_REPO=1"] + select({
-        ":disable_buf_integrity_checks": ["OTCRYPTO_DISABLE_BUF_INTEGRITY_CHECKS"],
-        "//conditions:default": [],
-    }),
+    defines = ["OTCRYPTO_IN_REPO=1"],
     includes = ["."],
     deps = [
+        ":api_config",
         "//sw/device/lib/base:hardened",
         "//sw/device/lib/base:status",
     ],
@@ -96,6 +108,7 @@ cc_library(
         "self_integrity.h",
         "sha2.h",
         "sha3.h",
+        ":api_config.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",
@@ -105,13 +118,17 @@ cc_library(
 
 pkg_files(
     name = "package",
-    srcs = glob(["*.h"]),
+    srcs = glob(["*.h"]) + [
+        ":api_config.h",
+    ],
     prefix = "crypto/include",
 )
 
 genrule(
     name = "doxygen",
-    srcs = glob(["*.h"]),
+    srcs = glob(["*.h"]) + [
+        ":api_config.h",
+    ],
     outs = [
         "Doxyfile",
         "latex/refman.pdf",
@@ -128,6 +145,7 @@ OUTPUT_DIRECTORY="$(RULEDIR)"
 HAVE_DOT=NO
 OPTIMIZE_OUTPUT_FOR_C=YES
 LATEX_HIDE_INDICES=YES
+FULL_PATH_NAMES=NO
 EOF
 
         for f in $(SRCS); do

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

@@ -70,7 +70,7 @@ typedef enum otcrypto_aes_padding {
  *
  * @param plaintext_len Plaintext data length in bytes.
  * @param aes_padding Padding scheme to be used for the data.
- * @return Size of the padded input or ciphertext.
+ * @param[out] padded_len Size of the padded input or ciphertext.
  * @return Result of the operation.
  */
 otcrypto_status_t otcrypto_aes_padded_plaintext_length(

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

@@ -40,6 +40,7 @@ typedef enum otcrypto_aes_gcm_tag_len {
  */
 typedef struct otcrypto_aes_gcm_context {
   // TODO: update the size and the restore and save context functions.
+  /// AES-GCM internal context.
   uint32_t data[194];
 } otcrypto_aes_gcm_context_t;
 

sw/device/lib/crypto/include/api_config.bzl

@@ -0,0 +1,60 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+CRYPTOLIB_API_CONFIG_HEADER = """\
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef OPENTITAN_CRYPTOLIB_BUILD_CONFIG_H_
+#define OPENTITAN_CRYPTOLIB_BUILD_CONFIG_H_
+
+/**
+ * @file
+ * @brief Build configuration options for the OpenTitan cryptography library.
+ *
+ * Generated as part of an OpenTitan cryptography library build.
+ *
+ * It describes the configuration of the the library and must match the library
+ * archive being linked. Specifically, it defines ABI-affecting configuration
+ * selected when building the library. Consumers should not modify or define
+ * these values manually.
+ */
+{cryptolib_defines}
+#endif /* OPENTITAN_CRYPTOLIB_BUILD_CONFIG_H_ */
+"""
+
+def _cryptolib_api_config_header_impl(ctx):
+    output_name = ctx.attr.name
+    if not output_name.endswith(".h"):
+        output_name = "{}.h".format(output_name)
+    header = ctx.actions.declare_file(output_name)
+
+    lines = []
+    if ctx.attr.buffer_integrity_checks:
+        lines += [
+            "#ifdef OTCRYPTO_DISABLE_BUF_INTEGRITY_CHECKS",
+            "#error \"This release has been built with buffer integrity checks, so these cannot be disabled.\"",
+            "#endif /* OTCRYPTO_DISABLE_BUF_INTEGRITY_CHECKS */",
+        ]
+    else:
+        lines.append("#define OTCRYPTO_DISABLE_BUF_INTEGRITY_CHECKS")
+    defines = "\n{}\n".format("\n".join(lines)) if lines else ""
+
+    content = CRYPTOLIB_API_CONFIG_HEADER.format(
+        cryptolib_defines = defines,
+    )
+    ctx.actions.write(
+        output = header,
+        content = content,
+    )
+
+    return [DefaultInfo(files = depset([header]))]
+
+cryptolib_api_config_header = rule(
+    implementation = _cryptolib_api_config_header_impl,
+    attrs = {
+        "buffer_integrity_checks": attr.bool(default = True, doc = "Perform additional integrity checks of buffers, at some additional cost"),
+    },
+)

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

@@ -46,6 +46,7 @@ enum {
  * with #otcrypto_cmac_init.
  */
 typedef struct otcrypto_cmac_context {
+  /// CMAC internal context.
   uint32_t data[kOtcryptoCmacCtxStructWords];
 } otcrypto_cmac_context_t;
 

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

@@ -8,7 +8,7 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#include "sw/device/lib/crypto/include/datatypes.h"
+#include "datatypes.h"
 
 #ifdef __cplusplus
 extern "C" {