[PATCH v1 1/2] nvmem: bsec: Add support for OTP permanent write lock

[PATCH v1 1/2] nvmem: bsec: Add support for OTP permanent write lock

[Oleksij Rempel]

From: Robin van der Gracht <robin@protonic.nl>

Introduce a mechanism to permanently lock OTP eFuses after programming by
adding a new `writelock` parameter. When `writelock` is enabled, the
driver:

- Programs the OTP fuse using `BSEC_SMC_PROG_OTP`.
- If successful, triggers `BSEC_SMC_WRLOCK_OTP` (OP-TEE:
  `STM32_SIP_SVC_BSEC_WRLOCK_OTP`) to permanently disable further
  modifications to the OTP word.

Security Concern:
Without this lock mechanism, an OTP word can still be altered by OR-ing
additional bits onto the existing value, as STM32 BSEC OTP fuses only
allow one-way bit transitions from 0 to 1. This is a potential security
risk when dealing with keys or sensitive configuration values, as an
attacker could modify certain OTP bits without fully replacing the
original value.

Warning! Write lock is enabled globally per BSEC device:
- While `writelock=1`, all writes via the BSEC device will be
  permanently locked.
- The user must avoid writing unintended values during this period,
  as they will become irrevocable.

Example Use Case:
To program and permanently lock an OTP word:
bsec0.permanent_write_enable=1
bsec0.writelock=1
mw -l -d /dev/stm32-bsec 0x00000170+4 $some_data
bsec0.permanent_write_enable=0
bsec0.writelock=0

After execution, the OTP at address `0x170` will be permanently
write-locked.

Signed-off-by: Robin van der Gracht <robin@protonic.nl>
Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 drivers/nvmem/bsec.c        | 14 +++++++++++---
 include/mach/stm32mp/bsec.h |  1 +
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/drivers/nvmem/bsec.c b/drivers/nvmem/bsec.c
index b92d925956ee..c0ca0a2ab6a4 100644
--- a/drivers/nvmem/bsec.c
+++ b/drivers/nvmem/bsec.c
@@ -27,6 +27,7 @@ struct bsec_priv {
 	int permanent_write_enable;
 	u8 lower;
 	struct tee_context *ctx;
+	int writelock;
 };

 struct stm32_bsec_data {
@@ -67,11 +68,16 @@ static int stm32_bsec_read_shadow(void *ctx, unsigned reg, unsigned *val)
 static int stm32_bsec_reg_write(void *ctx, unsigned reg, unsigned val)
 {
 	struct bsec_priv *priv = ctx;
+	int ret;

-	if (priv->permanent_write_enable)
-		return bsec_smc(BSEC_SMC_PROG_OTP, reg, val, NULL);
-	else
+	if (!priv->permanent_write_enable)
 		return bsec_smc(BSEC_SMC_WRITE_SHADOW, reg, val, NULL);
+
+	ret = bsec_smc(BSEC_SMC_PROG_OTP, reg, val, NULL);
+	if (!ret && priv->writelock)
+		ret = bsec_smc(BSEC_SMC_WRLOCK_OTP, reg, 0, NULL);
+
+	return ret;
 }

 static struct regmap_bus stm32_bsec_regmap_bus = {
@@ -245,6 +251,8 @@ static int stm32_bsec_probe(struct device *dev)
 	if (IS_ENABLED(CONFIG_STM32_BSEC_WRITE)) {
 		dev_add_param_bool(&priv->dev, "permanent_write_enable",
 				NULL, NULL, &priv->permanent_write_enable, NULL);
+		dev_add_param_bool(&priv->dev, "writelock",
+				NULL, NULL, &priv->writelock, NULL);
 	}

 	nvmem = nvmem_regmap_register(map, "stm32-bsec");
diff --git a/include/mach/stm32mp/bsec.h b/include/mach/stm32mp/bsec.h
index 45eb0a3f4523..be8cec536a40 100644
--- a/include/mach/stm32mp/bsec.h
+++ b/include/mach/stm32mp/bsec.h
@@ -26,6 +26,7 @@ enum bsec_op {
 	BSEC_SMC_READ_OTP	= 4,
 	BSEC_SMC_READ_ALL	= 5,
 	BSEC_SMC_WRITE_ALL	= 6,
+	BSEC_SMC_WRLOCK_OTP	= 7,
 };

 static inline enum bsec_smc bsec_read_field(unsigned field, unsigned *val)
--
2.39.5

[PATCH v1 2/2] Documentation: user: Add OTP support and parameter descriptions

[Oleksij Rempel]

Provide an overview of OTP support in Barebox.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 Documentation/user/otp.rst         | 199 +++++++++++++++++++++++++++++
 Documentation/user/user-manual.rst |   1 +
 2 files changed, 200 insertions(+)
 create mode 100644 Documentation/user/otp.rst

diff --git a/Documentation/user/otp.rst b/Documentation/user/otp.rst
new file mode 100644
index 000000000000..24a1f81fa449
--- /dev/null
+++ b/Documentation/user/otp.rst
@@ -0,0 +1,199 @@
+OTP (One-Time Programmable) Support
+====================================
+
+Overview
+========
+
+One-Time Programmable (OTP) memory is a type of non-volatile storage that
+allows data to be written only once. After programming, the data cannot be
+changed, or in some cases, only certain bits can transition from `0` to `1`.
+OTP is commonly used for:
+
+- Storing unique device identifiers (serial numbers, MAC addresses, etc.).
+- Configuring security settings (keys, fuses, hardware feature locks).
+- Setting permanent device configurations.
+
+In Barebox, most OTP drivers are implemented on top of the `nvmem` framework.
+Each specific driver may introduce device-specific parameters, but developers
+are encouraged to follow a common pattern when implementing OTP access.
+
+Supported Parameters
+====================
+
+Several parameters are used in different OTP drivers to provide consistent
+access to the hardware. These include:
+
+permanent_write_enable
+----------------------
+Controls whether OTP programming is done directly or via shadow memory.
+
+- This is a global setting per OTP device.
+- permanent_write_enable=1 -> All writes go directly to OTP fuses
+  (permanent)
+- permanent_write_enable=0 -> All writes go to shadow memory (volatile)
+  if supported.
+- Toggling `permanent_write_enable` does not automatically commit shadow
+  memory.
+- If shadow memory is not supported, writes always go directly to OTP.
+
+Understanding Shadow Memory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Shadow memory acts as a volatile cache that holds OTP values temporarily.
+- Shadow values are lost on power cycle unless explicitly committed.
+- On some SoCs, shadow memory can be used for testing. The system can
+  reboot (without power cycling) and use shadow values temporarily before
+  committing them.
+
+Writing to OTP with and without Shadow Memory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example 1: Immediate Permanent Write (Bypassing Shadow Memory)
+::
+
+    # Enable direct OTP write mode (all writes will be permanent)
+    bsec0.permanent_write_enable=1
+
+    # Write directly to an OTP register (bypasses shadow)
+    mw -l -d /dev/stm32-bsec 0x00000170+4 0x12345678
+
+    # Disable OTP write mode (future writes go to shadow, if available)
+    bsec0.permanent_write_enable=0
+
+Example 2: Using Shadow Memory Without Committing
+::
+
+    # Ensure shadow writes are enabled
+    bsec0.permanent_write_enable=0
+
+    # Write to shadow memory (not permanent yet)
+    mw -l -d /dev/imx-ocotp 0x20+4 0xAABBCCDD
+
+    # On power cycle, this data will be lost
+    # After reboot, OTP value remains unchanged
+
+Example 3: Using Shadow Memory for Testing Before Committing
+::
+
+    # Ensure shadow writes are enabled
+    ocotp0.permanent_write_enable=0
+
+    # Write to the shadow memory (not yet permanent)
+    mw -l -d /dev/imx-ocotp 0x20+4 0xAABBCCDD
+
+    # Perform a warm reboot (shadow memory is still active)
+    reset -w
+
+    # If configuration works as expected, commit shadow to OTP
+    ocotp0.permanent_write_enable=1
+    mw -l -d /dev/imx-ocotp 0x20+4 0xAABBCCDD
+    ocotp0.permanent_write_enable=0
+
+    # Now the value is permanently written to OTP fuses
+
+**Caution**
+^^^^^^^^^^^
+
+- Setting `permanent_write_enable=1` makes all writes permanent
+  immediately.
+- Setting `permanent_write_enable=0` does not commit shadow memory
+  automatically.
+- Shadow memory is lost on power cycle unless explicitly committed.
+
+writelock
+---------
+
+Permanently locks an OTP word after it is written.
+
+- writelock=1 -> Any OTP word written while this is enabled will be
+  permanently locked after writing.
+- writelock=0 -> Writes remain modifiable unless explicitly locked later.
+- Only the OTP words written while `writelock=1` is active will be locked.
+- Not all hardware or drivers support this functionality, or they may
+  implement locking differently.
+
+How OTP Word Locking Works
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Some OTP technologies allow bitwise OR-ing (changing `0` bits to `1` but
+  not back to `0`).
+- Without `writelock=1`, an attacker could modify certain bits after
+  provisioning (e.g., enabling additional security features but keeping a
+  backdoor open).
+- Setting `writelock=1` ensures that only the OTP words written while it is
+  active are locked, preventing further modification.
+
+Usage Example: Permanently Locking an OTP Word
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    # Enable OTP write mode (writes will be permanent)
+    bsec0.permanent_write_enable=1
+    bsec0.writelock=1
+
+    # Write data to OTP (this specific word will be permanently locked)
+    mw -l -d /dev/stm32-bsec 0x00000170+4 0x12345678
+
+    # Disable write mode and writelock (future writes will not be locked)
+    bsec0.permanent_write_enable=0
+    bsec0.writelock=0
+
+**Caution**
+^^^^^^^^^^^
+
+- Only the OTP words written while `writelock=1` is active will be locked.
+- Other OTP words remain modifiable unless explicitly written and locked.
+- Not all hardware or drivers support this functionality, or they may
+  implement locking differently.
+- If shadow memory is used (`permanent_write_enable=0`), writelock does not
+  apply.
+- Ensure all OTP values are correct before enabling `writelock=1`.
+
+sense_enable
+------------
+
+Controls whether OTP values are read from shadow memory or directly from the
+fuses.
+
+- sense_enable=1 -> Reads are performed directly from the OTP fuses.
+- sense_enable=0 -> Reads are performed from shadow memory (if supported).
+- If shadow memory is supported, `sense_enable=0` may return outdated values
+  if the shadow memory has not been updated.
+- If shadow memory is not supported, reads always come from OTP fuses, making
+  `sense_enable` ineffective.
+
+Use Cases
+^^^^^^^^^
+
+- Ensuring accuracy: Reading directly from the OTP fuses (`sense_enable=1`)
+  guarantees that the retrieved value reflects the actual state of the OTP
+  memory.
+- Avoiding outdated values: If `sense_enable=0` is used and the shadow
+  memory has not been refreshed, the read value may differ from the true OTP
+  fuse state.
+- Debugging & Validation: Direct OTP fuse reads can be used to confirm
+  whether a value has been successfully programmed.
+
+Usage Example
+^^^^^^^^^^^^^
+
+::
+
+    # Read OTP directly from fuses (ensures accuracy)
+    ocotp0.sense_enable=1
+    md -l /dev/nvmem/imx-ocotp
+
+    # Read OTP from shadow memory (may return outdated values if not refreshed)
+    ocotp0.sense_enable=0
+    md -l /dev/nvmem/imx-ocotp
+
+**Caution**
+^^^^^^^^^^^
+
+- If `sense_enable=0`, values may not reflect the actual OTP state until the
+  shadow memory is refreshed.
+- If `sense_enable=1`, the read is guaranteed to return the true OTP fuse
+  value.
+- Not all hardware supports shadow memory, making `sense_enable` ineffective
+  on some devices.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 565e6c11f82f..9f53f3aa449b 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -34,6 +34,7 @@ Contents:
    state
    random
    optee
+   otp
    debugging
    watchdog
    reboot-mode
-- 
2.39.5

Re: [PATCH v1 2/2] Documentation: user: Add OTP support and parameter descriptions

[Sascha Hauer]

On Thu, Jan 30, 2025 at 01:08:14PM +0100, Oleksij Rempel wrote:
> Provide an overview of OTP support in Barebox.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
>  Documentation/user/otp.rst         | 199 +++++++++++++++++++++++++++++
>  Documentation/user/user-manual.rst |   1 +
>  2 files changed, 200 insertions(+)
>  create mode 100644 Documentation/user/otp.rst
> 
> diff --git a/Documentation/user/otp.rst b/Documentation/user/otp.rst

...

> +    bsec0.permanent_write_enable=1
> +
> +    # Write directly to an OTP register (bypasses shadow)
> +    mw -l -d /dev/stm32-bsec 0x00000170+4 0x12345678
> +
> +    # Disable OTP write mode (future writes go to shadow, if available)
> +    bsec0.permanent_write_enable=0
> +
> +Example 2: Using Shadow Memory Without Committing
> +::
> +
> +    # Ensure shadow writes are enabled
> +    bsec0.permanent_write_enable=0
> +
> +    # Write to shadow memory (not permanent yet)
> +    mw -l -d /dev/imx-ocotp 0x20+4 0xAABBCCDD

Please drop the '+4' from the mw commands. The length is detected from
the number of words written and the '+4' has no meaning for mw.

Sascha

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [PATCH v1 1/2] nvmem: bsec: Add support for OTP permanent write lock

[Sascha Hauer]

On Thu, Jan 30, 2025 at 01:08:13PM +0100, Oleksij Rempel wrote:
> From: Robin van der Gracht <robin@protonic.nl>
> 
> Introduce a mechanism to permanently lock OTP eFuses after programming by
> adding a new `writelock` parameter. When `writelock` is enabled, the
> driver:
> 
> - Programs the OTP fuse using `BSEC_SMC_PROG_OTP`.
> - If successful, triggers `BSEC_SMC_WRLOCK_OTP` (OP-TEE:
>   `STM32_SIP_SVC_BSEC_WRLOCK_OTP`) to permanently disable further
>   modifications to the OTP word.
> 
> Security Concern:
> Without this lock mechanism, an OTP word can still be altered by OR-ing
> additional bits onto the existing value, as STM32 BSEC OTP fuses only
> allow one-way bit transitions from 0 to 1. This is a potential security
> risk when dealing with keys or sensitive configuration values, as an
> attacker could modify certain OTP bits without fully replacing the
> original value.
> 
> Warning! Write lock is enabled globally per BSEC device:
> - While `writelock=1`, all writes via the BSEC device will be
>   permanently locked.
> - The user must avoid writing unintended values during this period,
>   as they will become irrevocable.
> 
> Example Use Case:
> To program and permanently lock an OTP word:
> bsec0.permanent_write_enable=1
> bsec0.writelock=1
> mw -l -d /dev/stm32-bsec 0x00000170+4 $some_data
> bsec0.permanent_write_enable=0
> bsec0.writelock=0

I don't really like this writelock approach. It makes it hard to write
something to OTP without locking and then lock it later. This can only
be done by writing the same data again, with writelock enabled this
time.

We have support for a protect operation, originally used for flashes.
This looks like a good match for this purpose. Could we use it here?

Sascha

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |