From: Xu Yizhou <xuyizhou1@huawei.com>
Date: Fri, 25 Nov 2022 05:57:37 +0000 (+0800)
Subject: doc: add note for sm4 xts
X-Git-Tag: openssl-3.2.0-alpha1~1650
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e44b34185268e99ee2dc499073cf56d0465d60e2;p=thirdparty%2Fopenssl.git

doc: add note for sm4 xts

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19619)
---

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 1fa31d3f532..dafa71c9f66 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -993,6 +993,40 @@ Byte 11-12: Input length (Always 0)
 
 "tls1multi_interleave" must also be set for this operation.
 
+=item "xts_standard" (B<OSSL_CIPHER_PARAM_XTS_STANDARD>) <UTF8 string>
+
+Sets the XTS standard to use with SM4-XTS algorithm. XTS mode has two
+implementations, one is standardized in IEEE Std. 1619-2007 and has
+been widely used (e.g., XTS AES), the other is proposed recently
+(GB/T 17964-2021 implemented in May 2022) and is currently only used
+in SM4.
+
+The main difference between them is the multiplication by the
+primitive element E<alpha> to calculate the tweak values. The IEEE
+Std 1619-2007 noted that the multiplication "is a left shift of each
+byte by one bit with carry propagating from one byte to the next
+one", which means that in each byte, the leftmost bit is the most
+significant bit. But in GB/T 17964-2021, the rightmost bit is the
+most significant bit, thus the multiplication becomes a right shift
+of each byte by one bit with carry propagating from one byte to the
+next one.
+
+Valid values for the mode are:
+
+=over 4
+
+=item "GB"
+
+The GB/T 17964-2021 variant of SM4-XTS algorithm.
+
+=item "IEEE"
+
+The IEEE Std. 1619-2007 variant of SM4-XTS algorithm.
+
+=back
+
+The default value is "GB".
+
 =back
 
 =head1 CONTROLS
diff --git a/doc/man7/EVP_CIPHER-SM4.pod b/doc/man7/EVP_CIPHER-SM4.pod
index 36a51d18a42..b0c292757e7 100644
--- a/doc/man7/EVP_CIPHER-SM4.pod
+++ b/doc/man7/EVP_CIPHER-SM4.pod
@@ -24,6 +24,12 @@ The following algorithms are available in the default provider:
 
 =item "SM4-CFB" or "SM4-CFB128"
 
+=item "SM4-GCM"
+
+=item "SM4-CCM"
+
+=item "SM4-XTS"
+
 =back
 
 =head2 Parameters