doc: documentation for SM3 hash

To: Niels Möller <nisse@lysator.liu.se>, nettle-bugs@lists.lysator.liu.se
Cc: Tianjia Zhang <tianjia.zhang@linux.alibaba.com>
Date: Mon,  6 Dec 2021 16:57:00 +0800 (1 day, 11 hours, 33 minutes ago)

Signed-off-by: Tianjia Zhang <tianjia.zhang@linux.alibaba.com>

1 files changed, 72 insertions, 2 deletions

diff --git a/nettle.texinfo b/nettle.texinfo
index 39d01159..76934637 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -950,6 +950,52 @@ This function also resets the context in the same way as
 @code{streebog256_init}.
 @end deftypefun
 
+@subsubsection @acronym{SM3}
+
+SM3 is a cryptographic hash function standard adopted by the government of the
+People's Republic of China, which was issued by the Cryptography Standardization
+Technical Committee of China on December 17, 2010. The corresponding standard
+is GM/T 0004-2012 "SM3 Cryptographic Hash Algorithm".
+
+SM3 algorithm is a hash algorithm in ShangMi cryptosystems. SM3 is mainly used
+for digital signature and verification, message authentication code generation
+and verification, random number generation, and the RFC 8998 specification
+defines the usage of ShangMi algorithm suite in TLS 1.3, etc. According to the
+State Cryptography Administration of China, its security and efficiency are
+equivalent to SHA-256.
+
+Nettle defines SM3 in @file{<nettle/sm3.h>}.
+
+@deftp {Context struct} {struct sm3_ctx}
+@end deftp
+
+@defvr Constant SM3_DIGEST_SIZE
+The size of a SM3 digest, i.e. 32.
+@end defvr
+
+@defvr Constant SM3_BLOCK_SIZE
+The internal block size of SM3. Useful for some special constructions,
+in particular HMAC-SM3.
+@end defvr
+
+@deftypefun void sm3_init (struct sm3_ctx *@var{ctx})
+Initialize the SM3 state.
+@end deftypefun
+
+@deftypefun void sm3_update (struct sm3_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data})
+Hash some more data.
+@end deftypefun
+
+@deftypefun void sm3_digest (struct sm3_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest})
+Performs final processing and extracts the message digest, writing it
+to @var{digest}. @var{length} may be smaller than
+@code{SM3_DIGEST_SIZE}, in which case only the first @var{length}
+octets of the digest are written.
+
+This function also resets the context in the same way as
+@code{sm3_init}.
+@end deftypefun
+
 
 @node Legacy hash functions
 @subsection Legacy hash functions
@@ -1256,6 +1302,7 @@ The last three attributes are function pointers, of types
 @deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha3_256
 @deftypevrx {Constant Struct} {struct nettle_hash} nettle_gosthash94
 @deftypevrx {Constant Struct} {struct nettle_hash} nettle_gosthash94cp
+@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sm3
 These are all the hash functions that Nettle implements.
 @end deftypevr
 
@@ -3775,8 +3822,8 @@ There are abstract functions that use a pointer to a @code{struct
 nettle_hash} to represent the underlying hash function and @code{void *}
 pointers that point to three different context structs for that hash
 function. There are also concrete functions for @acronym{HMAC-MD5},
-@acronym{HMAC-RIPEMD160} @acronym{HMAC-SHA1}, @acronym{HMAC-SHA256}, and
-@acronym{HMAC-SHA512}. First, the abstract functions:
+@acronym{HMAC-RIPEMD160} @acronym{HMAC-SHA1}, @acronym{HMAC-SHA256},
+@acronym{HMAC-SHA512}, and @acronym{HMAC-SM3}. First, the abstract functions:
 
 @deftypefun void hmac_set_key (void *@var{outer}, void *@var{inner}, void *@var{state}, const struct nettle_hash *@var{H}, size_t @var{length}, const uint8_t *@var{key})
 Initializes the three context structs from the key. The @var{outer} and
@@ -3963,6 +4010,29 @@ This function also resets the context for processing new messages, with
 the same key.
 @end deftypefun
 
+
+@subsubsection @acronym{HMAC-SM3}
+
+@deftp {Context struct} {struct hmac_sm3_ctx}
+@end deftp
+
+@deftypefun void hmac_sm3_set_key (struct hmac_sm3_ctx *@var{ctx}, size_t @var{key_length}, const uint8_t *@var{key})
+Initializes the context with the key.
+@end deftypefun
+
+@deftypefun void hmac_sm3_update (struct hmac_sm3_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data})
+Process some more data.
+@end deftypefun
+
+@deftypefun void hmac_sm3_digest (struct hmac_sm3_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest})
+Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than
+@code{SM3_DIGEST_SIZE}, in which case only the first @var{length}
+octets of the @acronym{MAC} are written.
+
+This function also resets the context for processing new messages, with
+the same key.
+@end deftypefun
+
 @node UMAC
 @subsection @acronym{UMAC}
 @cindex UMAC