Hello Quentin,
sorry for long delay...
On 14.01.26 15:22, Quentin Schulz wrote:
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).
okay, but I just copied from other files... for example
doc/usage/cmd/dm.rst:
1 .. SPDX-License-Identifier: GPL-2.0+:
2
So of course I change it... but does that mean, we should fix all other
files too?
+ Copyright 2025 Nabladev
Seems like we typically use a new comment for this line
.. Copyright 2025 Nabladev
Fixed.
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?
As I know, there is only sm3_256 hash. If you look for example
into include/tpm-v2.h
33 #define TPM2_SM3_256_DIGEST_SIZE 32
[...]
277 TPM2_ALG_SM3_256 = 0x12,
[...]
301 #define TCG2_BOOT_HASH_ALG_SM3_256 0x00000010
+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``/
done.
+passed to the command, it compares the calculated hash
+with the hash found at address sum.
+
s/sum/``sum``/.
done.
+The SM3 secure hash, is calculated as specified by OSCCA GM/T
s/,//
done.
+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.
It is at the end from hextoul(), so it is at the end "hex"...
I added the line
Hexadecimal string, 0x prefix optional.
+
+count
+ length in bytes of memory area for which the sm3 hash is calculated
same here hextoul() used...
+
+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?
correct, good catch, see the examples.
+
+ or if "-v" option is passed:
s/"-v"/``-v``/
done.
+
+ address of hash with which the calculated hash gets compared.
+
+Example
+-------
+
+create some data
+
+at address ``0x0000000100000000``
(do we need the leading zeroes?)
removed them.
+::
+
+ 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``/
done.
+variable hashval
+
s/hashval/``hashval``/
done.
+::
+
+ 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``/
done.
+
+::
+
+ 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/
done.
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``/
done.
+The "-v" option is separate enabled through Kconfig option
s/"-v"/``-v``/
done.
+CONFIG_SM3SUM_VERIFY.
s/CONFIG_SM3SUM_VERIFY/``CONFIG_SM3SUM_VERIFY``/
done.
+
+
+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.
removed.
Many thanks for your input!
Azure build runs, if fine, I send v2...
bye,
Heiko
--
Nabla Software Engineering
HRB 40522 Augsburg
Phone: +49 821 45592596
E-Mail: [email protected]
Geschäftsführer : Stefano Babic
