Merge branch 'master' into normal_sleep_por

NOTICE

@@ -0,0 +1,19 @@
+The OpenTitan Project
+Copyright 2024 lowRISC contributors.
+
+This product includes hardware and/or software developed as part of the
+OpenTitan(R) project (https://www.opentitan.org,
+https://github.com/lowRISC/opentitan).
+
+-
+
+The Ibex Project
+Copyright 2024 lowRISC contributors.
+
+This product includes hardware and/or software developed as part of the
+Ibex(R) (https://github.com/lowRISC/ibex) and OpenTitan(R) projects.
+
+Ibex was originally developed by the PULP team at ETH Zurich and University of
+Bologna under the name zero-riscy. Ibex verification, performance enhancement
+and security hardening have been supported by the OpenTitan project
+(https://www.opentitan.org).

WORKSPACE

@@ -7,6 +7,12 @@
 
 workspace(name = "lowrisc_opentitan")
 
+# Bazel skylib library
+load("//third_party/skylib:repos.bzl", "bazel_skylib_repos")
+bazel_skylib_repos()
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+bazel_skylib_workspace()
+
 # CRT is the Compiler Repository Toolkit.  It contains the configuration for
 # the windows compiler.
 load("//third_party/crt:repos.bzl", "crt_repos")
@@ -149,10 +155,6 @@ nonhermetic_repo(name = "nonhermetic")
 load("//third_party/hyperdebug:repos.bzl", "hyperdebug_repos")
 hyperdebug_repos()
 
-# Bazel skylib library
-load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
-bazel_skylib_workspace()
-
 register_toolchains(
     "//rules/opentitan:localtools",
 )

azure-pipelines.yml

@@ -612,7 +612,7 @@ jobs:
       set -e
       . util/build_consts.sh
       module load "xilinx/vivado/$(VIVADO_VERSION)"
-      ci/scripts/run-fpga-tests.sh hyper310 cw310_sival || { res=$?; echo "To reproduce failures locally, follow the instructions at https://opentitan.org/book/doc/getting_started/setup_fpga.html#reproducing-fpga-ci-failures-locally"; exit "${res}"; }
+      ci/scripts/run-fpga-tests.sh hyper310 cw310_sival,-broken || { res=$?; echo "To reproduce failures locally, follow the instructions at https://opentitan.org/book/doc/getting_started/setup_fpga.html#reproducing-fpga-ci-failures-locally"; exit "${res}"; }
     displayName: Execute tests
   - template: ci/publish-bazel-test-results.yml
 
@@ -703,7 +703,7 @@ jobs:
       set -e
       . util/build_consts.sh
       module load "xilinx/vivado/$(VIVADO_VERSION)"
-      ci/scripts/run-fpga-tests.sh cw310 manuf,-cw310_sival || { res=$?; echo "To reproduce failures locally, follow the instructions at https://opentitan.org/book/doc/getting_started/setup_fpga.html#reproducing-fpga-ci-failures-locally"; exit "${res}"; }
+      ci/scripts/run-fpga-tests.sh cw310 manuf,-cw310_sival,-broken || { res=$?; echo "To reproduce failures locally, follow the instructions at https://opentitan.org/book/doc/getting_started/setup_fpga.html#reproducing-fpga-ci-failures-locally"; exit "${res}"; }
     displayName: Execute tests
   - template: ci/publish-bazel-test-results.yml
 

ci/azure-pipelines-nightly.yml

@@ -154,7 +154,7 @@ jobs:
         --define bitstream=gcp_splice \
         --build_tests_only \
         --test_output=errors \
-        --test_tag_filters="cw310_sival" \
+        --test_tag_filters=cw310_sival,-broken \
         $(bash ./bazelisk.sh query 'attr("tags", "[\[ ]pmod[,\]]", tests(//...))')
     displayName: "Run the PMOD tests for Sival"
   - template: ../ci/publish-bazel-test-results.yml

doc/project_governance/technical_committee.md

@@ -22,7 +22,6 @@ The OpenTitan Technical Committee membership is:
 * Cyril Guyot
 * Felix Miller
 * Dominic Rizzo (observer)
-* Alphan Ulusoy
 * Michael Munday
 * Rupert Swarbrick
 * Michael Tempelmeier

doc/security/cryptolib/cryptolib_api.md

@@ -17,7 +17,7 @@ This page:
   - [Elliptic curve cryptography](#elliptic-curve-cryptography)
   - [Deterministic random bit generation (DRBG)](#deterministic-random-bit-generation)
   - [Key derivation functions (KDF)](#key-derivation)
-  - [Key import and export](#key-import-and-export)
+  - [Key transport](#key-transport)
 - Explains how [asynchronous operations](#asynchronous-operations) work
 - Lists the [security strength](#security-strength) of each algorithm
 - Lists [references](#reference) for further reading
@@ -71,29 +71,32 @@ Word buffers can be safely interpreted as byte streams by the caller; the bytes
 ### Key data structures
 
 Keys receive extra protection from the cryptolib.
-Public keys are represented in plain, "unblinded" form, but have a checksum to protect their integrity.
+Public keys are represented in plain, "unblinded" form, but include a checksum to protect them against accidental corruption.
 The checksum is implementation-specific and may change over time.
-Therefore, the caller should not compute the checksum themselves; use the key import/export functions to construct unblinded keys.
+The caller should use algorithm-specific routines to construct unblinded keys; see e.g. the ECC and RSA sections for details.
 
 {{#header-snippet sw/device/lib/crypto/include/datatypes.h crypto_unblinded_key }}
 
 Secret keys are "blinded", meaning that keys are represented by at least two "shares" the same size as the key.
+Blinded keys are also sometimes referred to as "masked".
 This helps protect against e.g. power side-channel attacks, because the code will never handle a bit of the "real" key, only the independent shares.
-The choice of blinding method depends on the algorithm and is implementation-specific.
-Callers should use key import/export functions to interpret blinded keys.
+The exact blinding method and internal representation of blinded key data is opaque to the caller and subject to change in future library versions.
+Lke unblinded keys, they include a checksum.
+Callers should use key import/export functions to generate, construct, and interpret blinded keys.
 
 {{#header-snippet sw/device/lib/crypto/include/datatypes.h crypto_blinded_key }}
 
 As shown above, all secret keys have a configuration value.
+Once the key is created, or imported, the configuration is not expected to change; the cryptolib will never change it, and the caller would have to recompute the key checksum to change it, which is not recommended.
 The configuration helps the cryptolib interpret how the key is represented and how it is permitted to be used.
 Nothing in the configuration is typically secret.
 
 {{#header-snippet sw/device/lib/crypto/include/datatypes.h crypto_key_config }}
 
 In most cases, the caller needs to provide a configuration before calling algorithms which generate secret keys.
-
-Callers may request keys from OpenTitan's [key manager block][keymgr] by setting `hw_backed` and `diversification_hw_backed` in the key configuration.
-If the key is produced by the key manager, then the keyblob has length 0; the diversification information is enough to produce the key.
+Callers may request keys from OpenTitan's [key manager block][keymgr] by setting `hw_backed` in the key configuration.
+In this case, the keyblob is the diversification input for key manager instead of the key material itself.
+See the [key transport](#key-transport) section for more details.
 
 ### Bookkeeping data structures
 
@@ -186,14 +189,19 @@ It protects both the confidentiality and authenticity of the main input and the
 GCM is specified in [NIST SP800-38D][gcm-spec].
 One important note for using AES-GCM is that shorter tags degrade authentication guarantees, so it is important to fully understand the implications before using shortened tags.
 
-In addition, we expose the internal GHASH and GCTR operation that GCM relies upon (from [NIST SP800-38D][gcm-spec], section 6.4).
-This allows flexibility for use-cases that need custom GCM constructs: for example, we do not provide AES-GCM in streaming mode here because it encourages decryption and processing of unauthenticated data, but some users may need it for compatibility purposes.
-Additionally, the GHASH operation can be used to construct GCM with block ciphers other than AES.
+The cryptolib offers GCM in one-shot and in streaming mode.
+In streaming mode, it is strongly recommended not to process the decrypted data before verifying the authentication tag.
 
 #### GCM - Authenticated Encryption and Decryption
 
-{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_encrypt_gcm }}
-{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_decrypt_gcm }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_encrypt }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_decrypt }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_encrypt_init }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_decrypt_init }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_update_aad }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_update_encrypted_data }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_encrypt_final }}
+{{#header-snippet sw/device/lib/crypto/include/aes.h otcrypto_aes_gcm_decrypt_final }}
 
 ### AES-KWP
 
@@ -478,21 +486,15 @@ To learn more about PRFs, various key derivation mechanisms and security conside
 {{#header-snippet sw/device/lib/crypto/include/kdf.h otcrypto_kdf_hkdf_extract }}
 {{#header-snippet sw/device/lib/crypto/include/kdf.h otcrypto_kdf_hkdf_expand }}
 
-## Key import and export
-
-The following section defines the interface for importing keys to and exporting keys from the crypto library.
+## Key transport
 
-The crypto library typically represents private keys in blinded form, where the exact shape of the blinded key is opaque to the user.
-Public keys are in unblinded form, and the user can easily extract the plain key data.
-However, in some cases, a user might want to import a key generated elsewhere into the cryptolib, or might want to export a private key for use in a different piece of code.
+This is the interface for generating, importing, and exporting crypto library symmetric keys.
+Asymmetric schemes (e.g. RSA or elliptic-curve cryptography) use algorithm-specific routines for key generation; refer to the RSA and ECC sections instead to generate, import, or export asymmetric keys.
 
-### Supported Modes
-
-The crypto library provides four functions for this purpose:
-- Build an unblinded key from user-provided key data and mode
-- Build a blinded key from user-provided key data and configuration
-- Export an unblinded key to the user-provided key data
-- Export a blinded key to the user-provided key data in shares
+The crypto library represents private keys in masked form ("blinded keys").
+The internal structure of blinded keys is opaque to the user and may change in subsequent versions of the crypto library.
+The caller can control certain characteristics of the generated key via the key configuration.
+See the [key data structures](#key-data-structures) section for more details.
 
 ### Generate random keys
 
@@ -502,16 +504,17 @@ The crypto library provides four functions for this purpose:
 
 {{#header-snippet sw/device/lib/crypto/include/key_transport.h otcrypto_hw_backed_key }}
 
-### Import Keys
+### Import Symmetric Keys
 
-{{#header-snippet sw/device/lib/crypto/include/key_transport.h otcrypto_import_unblinded_key }}
 {{#header-snippet sw/device/lib/crypto/include/key_transport.h otcrypto_import_blinded_key }}
 
-### Export Keys
+### Export Symmetric Keys
 
-{{#header-snippet sw/device/lib/crypto/include/key_transport.h otcrypto_export_unblinded_key }}
 {{#header-snippet sw/device/lib/crypto/include/key_transport.h otcrypto_export_blinded_key }}
 
+Some blinded keys are marked as non-exportable in their configurations.
+The crypto library will always refuse to export these keys.
+
 ## Asynchronous operations
 
 For some functions, OpenTitan's cryptolib supports asynchronous calls.

hw/ip/adc_ctrl/doc/theory_of_operation.md

@@ -45,7 +45,7 @@ Note that the time taken in this step depends on the properties of the ADC.
 8. *Wait sleep time*: The controller will wait for the next sample timer to time out before restarting at step (1).
 
 If the controller is configured as oneshot mode, ([`adc_en_ctl.oneshot_mode`](registers.md#adc_en_ctl)), the controller waits for high value (1) from channel 0 and 1 in order.
-Once it gets high value from both channel, it goes back to power off state without evaluatging the filters after setting [`adc_intr_status.oneshot`](registers.md#adc_intr_status).
+Once it gets high value from both channels, it goes back to power off state without evaluating the filters after setting [`adc_intr_status.oneshot`](registers.md#adc_intr_status).
 
 In active operation the controller is in continuous scanning mode:
 * The ADC is continually powered on.