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