From 7eba43e837eb3669d6b32d4ba27c3e93db29b8c3 Mon Sep 17 00:00:00 2001
From: Paul Yang <yang.yang@baishancloud.com>
Date: Wed, 13 Mar 2019 17:22:31 +0800
Subject: [PATCH] Add documents for SM2 cert verification

This follows #8321 which added the SM2 certificate verification feature.
This commit adds the related docs - the newly added 2 APIs and options
in apps/verify.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8465)
---
 doc/man1/verify.pod           | 16 ++++++++++++-
 doc/man3/X509_get0_sm2_id.pod | 43 +++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 doc/man3/X509_get0_sm2_id.pod

diff --git a/doc/man1/verify.pod b/doc/man1/verify.pod
index 6465fd8b4d..10fd848622 100644
--- a/doc/man1/verify.pod
+++ b/doc/man1/verify.pod
@@ -50,6 +50,8 @@ B<openssl> B<verify>
 [B<-verify_name name>]
 [B<-x509_strict>]
 [B<-show_chain>]
+[B<-sm2-id string>]
+[B<-sm2-hex-id hex-string>]
 [B<->]
 [certificates]
 
@@ -316,6 +318,16 @@ Display information about the certificate chain that has been built (if
 successful). Certificates in the chain that came from the untrusted list will be
 flagged as "untrusted".
 
+=item B<-sm2-id>
+
+Specify the ID string to use when verifying an SM2 certificate. The ID string is
+required by the SM2 signature algorithm for signing and verification.
+
+=item B<-sm2-hex-id>
+
+Specify a binary ID string to use when signing or verifying using an SM2
+certificate. The argument for this option is string of hexadecimal digits.
+
 =item B<->
 
 Indicates the last option. All arguments following this are assumed to be
@@ -767,9 +779,11 @@ The B<-show_chain> option was added in OpenSSL 1.1.0.
 The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
 is silently ignored.
 
+The B<-sm2-id> and B<-sm2-hex-id> options were added in OpenSSL 3.0.0.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/X509_get0_sm2_id.pod b/doc/man3/X509_get0_sm2_id.pod
new file mode 100644
index 0000000000..84da71e831
--- /dev/null
+++ b/doc/man3/X509_get0_sm2_id.pod
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+X509_get0_sm2_id, X509_set_sm2_id - get or set SM2 ID for certificate operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ ASN1_OCTET_STRING *X509_get0_sm2_id(X509 *x);
+ void X509_set_sm2_id(X509 *x, ASN1_OCTET_STRING *sm2_id);
+
+=head1 DESCRIPTION
+
+X509_get0_sm2_id() gets the ID value of an SM2 certificate B<x> by returning an
+B<ASN1_OCTET_STRING> object which should not be freed by the caller.
+X509_set_sm2_id() sets the B<sm2_id> value to an SM2 certificate B<x>.
+
+=head1 NOTES
+
+SM2 signature algorithm requires an ID value when generating and verifying a
+signature. The functions described in this manual provide the user with the
+ability to set and retrieve the SM2 ID value.
+
+=head1 RETURN VALUES
+
+X509_set_sm2_id() does not return a value.
+
+=head1 SEE ALSO
+
+L<X509_verify(3)>, L<SM2(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
-- 
2.25.1