Hi Heiko,
Typo in title, should be doc: and not doc_.
On 1/6/26 3:14 PM, Heiko Schocher wrote:
add documentation for sm3sum command.
Signed-off-by: Heiko Schocher <[email protected]>
---
doc/usage/cmd/sm3sum.rst | 117 +++++++++++++++++++++++++++++++++++++++
1 file changed, 117 insertions(+)
create mode 100644 doc/usage/cmd/sm3sum.rst
diff --git a/doc/usage/cmd/sm3sum.rst b/doc/usage/cmd/sm3sum.rst
new file mode 100644
index 00000000000..3b157779a0e
--- /dev/null
+++ b/doc/usage/cmd/sm3sum.rst
@@ -0,0 +1,117 @@
+.. SPDX-License-Identifier: GPL-2.0+:
Use the canonical version:
GPL-2.0-or-later
c.f. https://spdx.org/licenses/GPL-2.0-or-later.html
(Do not end it with a colon either).
+ Copyright 2025 Nabladev
Seems like we typically use a new comment for this line
.. Copyright 2025 Nabladev
I **think** the copyright should use the name of the legal entity (so
likely "Nabla Software Engineering GmbH"). But IANAL and I personally
don't care :)
+ Written by Heiko Schocher <[email protected]>
+
+.. index::
+ single: sm3sum (command)
+
+sm3sum command
+==============
+
+Synopsis
+--------
+
+::
+
+ sm3sum - compute SM3 message digest
+
+ Usage:
+ sm3sum address count [[*]sum]
+ - compute SM3 message digest [save to sum]
+ sm3sum -v address count [*]sum
+ - verify sm3sum of memory area
+
+
+Description
+-----------
+
+The sm3sum command calculates the SM3_256 Hash from a
Are there variants of SM3? From what I understood, it's "equivalent" to
sha256 in terms of security and efficiency, but it's SM3, just that?
+address with length of count bytes. If the -v option is
Can suggest:
"""
calculates the SM3 hash of data of ``count`` bytes at address ``address``.
"""
which highlights which parts of the command must be specific by the user.
s/-v/``-v``/
+passed to the command, it compares the calculated hash
+with the hash found at address sum.
+
s/sum/``sum``/.
+The SM3 secure hash, is calculated as specified by OSCCA GM/T
s/,//
+0004-2012 SM3 and described at
+
+https://datatracker.ietf.org/doc/html/draft-sca-cfrg-sm3-02
+
+Parameters
+----------
+
+address
+ address from where the sm3 hash is calculated
How is this value parsed? Is it deducted from the string (e.g. starts
with 0x or contains hex digits = hex, starts with 0, octal, otherwise
decimal), or is it a forced base? This needs to be specified.
+
+count
+ length in bytes of memory area for which the sm3 hash is calculated
+
+sum
+ address of hash to which the calculated hash gets stored
This is only true if you sum starts with "*" no? Otherwise it's the name
of the environment variable where to store the checksum?
+
+ or if "-v" option is passed:
s/"-v"/``-v``/
+
+ address of hash with which the calculated hash gets compared.
+
+Example
+-------
+
+create some data
+
+at address ``0x0000000100000000``
(do we need the leading zeroes?)
+::
+
+ u-boot=> mw 0x0000000100000000 0x426f6f46 1
+ u-boot=> md.b 0x0000000100000000 4
+ 00000000: 46 6f 6f 42 FooB
+
+and calculate the sm3sum from address and store it in environment
s/from address/of 4 bytes starting from address ``0x0000000100000000``/
+variable hashval
+
s/hashval/``hashval``/
+::
+
+ u-boot=> sm3sum 0x0000000100000000 4 hashval
+ sm3_256 for 100000000 ... 100000003 ==>
cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7
+ u-boot=> print hashval
+ hashval=cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7
+ u-boot=>
+
+or calculate sm3sum from address and store it at address sum
s/from address/of 4 bytes starting from address ``0x0000000100000000``/
s/sum/``0x0000000110000000``/
+
+::
+
+ u-boot=> sm3sum 0x0000000100000000 4 *0x0000000110000000
+ sm3_256 for 100000000 ... 100000003 ==>
cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7
+
+and now check if this hash is a valid sm3sum with "-v" option
s/is a valid sm3sum/is the expected sm3sum hash value/
s/"-v"/``-v``/
+
+::
+
+ u-boot=> sm3sum -v 0x0000000100000000 4 *0x0000000110000000
+ u-boot=> echo $?
+ 0
+
+example with wrong hash
+
+::
+
+ u-boot=> sm3sum -v 0x0000000100000000 4 *0x0000000110000004
+ sm3_256 for 100000000 ... 100000003 ==>
cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7 !=
e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7ffffffff ** ERROR **
+ u-boot=>
+
+
+Configuration
+-------------
+
+Enable the sm3sum command via Kconfig option CONFIG_CMD_SM3SUM.
s/CONFIG_CMD_SM3SUM/``CONFIG_CMD_SM3SUM``/
+The "-v" option is separate enabled through Kconfig option
s/"-v"/``-v``/
+CONFIG_SM3SUM_VERIFY.
s/CONFIG_SM3SUM_VERIFY/``CONFIG_SM3SUM_VERIFY``/
+
+
+Return value
+------------
+
+The return value $? is true (0) if the hash is calculated or if
+the created hash is the same as the hash stored in memory at
+address sum.
+
+The return value is false (1) if there is a problem with
+calculating the hash, or if the hash is not the same as
+the hash stored ar address sum.
This matches the expectations I got from reading
https://docs.u-boot.org/en/latest/usage/cmdline.html#general-rules
(point 3). So I would simply remove the return value section in this
patch here.
Cheers,
Quentin
