]>
Commit | Line | Data |
---|---|---|
571286b0 PY |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a48309cb MC |
5 | EVP_PKEY-SM2, EVP_KEYMGMT-SM2, SM2 |
6 | - EVP_PKEY keytype support for the Chinese SM2 signature and encryption algorithms | |
571286b0 PY |
7 | |
8 | =head1 DESCRIPTION | |
9 | ||
f922dac8 PY |
10 | The B<SM2> algorithm was first defined by the Chinese national standard GM/T |
11 | 0003-2012 and was later standardized by ISO as ISO/IEC 14888. B<SM2> is actually | |
12 | an elliptic curve based algorithm. The current implementation in OpenSSL supports | |
13 | both signature and encryption schemes via the EVP interface. | |
571286b0 PY |
14 | |
15 | When doing the B<SM2> signature algorithm, it requires a distinguishing identifier | |
16 | to form the message prefix which is hashed before the real message is hashed. | |
17 | ||
5135a9bd SL |
18 | =head2 Common SM2 parameters |
19 | ||
20 | SM2 uses the parameters defined in L<EVP_PKEY-EC(7)/Common EC parameters>. | |
21 | The following parameters are different: | |
22 | ||
23 | =over 4 | |
24 | ||
25 | =item "cofactor" (B<OSSL_PKEY_PARAM_EC_COFACTOR>) <unsigned integer> | |
26 | ||
27 | This parameter is ignored for B<SM2>. | |
28 | ||
29 | =item (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string> | |
30 | ||
31 | Getter that returns the default digest name. | |
32 | (Currently returns "SM3" as of OpenSSL 3.0). | |
33 | ||
34 | =back | |
35 | ||
571286b0 PY |
36 | =head1 NOTES |
37 | ||
f922dac8 PY |
38 | B<SM2> signatures can be generated by using the 'DigestSign' series of APIs, for |
39 | instance, EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal(). | |
40 | Ditto for the verification process by calling the 'DigestVerify' series of APIs. | |
4feb4a2b NH |
41 | Note that the SM2 algorithm requires the presence of the public key for signatures, |
42 | as such the B<OSSL_PKEY_PARAM_PUB_KEY> option must be set on any key used in signature | |
43 | generation. | |
571286b0 | 44 | |
f4e4382c RL |
45 | Before computing an B<SM2> signature, an B<EVP_PKEY_CTX> needs to be created, |
46 | and an B<SM2> ID must be set for it, like this: | |
571286b0 PY |
47 | |
48 | EVP_PKEY_CTX_set1_id(pctx, id, id_len); | |
49 | ||
f4e4382c RL |
50 | Before calling the EVP_DigestSignInit() or EVP_DigestVerifyInit() functions, |
51 | that B<EVP_PKEY_CTX> should be assigned to the B<EVP_MD_CTX>, like this: | |
571286b0 PY |
52 | |
53 | EVP_MD_CTX_set_pkey_ctx(mctx, pctx); | |
54 | ||
f4e4382c | 55 | There is normally no need to pass a B<pctx> parameter to EVP_DigestSignInit() |
f922dac8 | 56 | or EVP_DigestVerifyInit() in such a scenario. |
571286b0 | 57 | |
a48309cb | 58 | SM2 can be tested with the L<openssl-speed(1)> application since version 3.0. |
1903a9b7 | 59 | Currently, the only valid algorithm name is B<sm2>. |
a56f68ad | 60 | |
77072e27 TM |
61 | Since version 3.0, SM2 keys can be generated and loaded only when the domain |
62 | parameters specify the SM2 elliptic curve. | |
63 | ||
cda77422 | 64 | =head1 EXAMPLES |
571286b0 | 65 | |
f922dac8 PY |
66 | This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify |
67 | a message with the SM2 signature algorithm and the SM3 hash algorithm: | |
571286b0 PY |
68 | |
69 | #include <openssl/evp.h> | |
70 | ||
f922dac8 | 71 | /* obtain an EVP_PKEY using whatever methods... */ |
571286b0 PY |
72 | mctx = EVP_MD_CTX_new(); |
73 | pctx = EVP_PKEY_CTX_new(pkey, NULL); | |
74 | EVP_PKEY_CTX_set1_id(pctx, id, id_len); | |
f4e4382c | 75 | EVP_MD_CTX_set_pkey_ctx(mctx, pctx); |
571286b0 PY |
76 | EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); |
77 | EVP_DigestVerifyUpdate(mctx, msg, msg_len); | |
78 | EVP_DigestVerifyFinal(mctx, sig, sig_len) | |
79 | ||
80 | =head1 SEE ALSO | |
81 | ||
82 | L<EVP_PKEY_CTX_new(3)>, | |
571286b0 PY |
83 | L<EVP_DigestSignInit(3)>, |
84 | L<EVP_DigestVerifyInit(3)>, | |
85 | L<EVP_PKEY_CTX_set1_id(3)>, | |
86 | L<EVP_MD_CTX_set_pkey_ctx(3)> | |
87 | ||
88 | =head1 COPYRIGHT | |
89 | ||
5135a9bd | 90 | Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved. |
571286b0 | 91 | |
3187791e | 92 | Licensed under the Apache License 2.0 (the "License"). You may not use |
571286b0 PY |
93 | this file except in compliance with the License. You can obtain a copy |
94 | in the file LICENSE in the source distribution or at | |
95 | L<https://www.openssl.org/source/license.html>. | |
96 | ||
97 | =cut |