From a48309cb5c58be8fa310608124925d4729664cf8 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 18 Sep 2020 12:10:21 +0100 Subject: Document the provider side SM2 Asymmetric Cipher support Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/12913) --- doc/man7/EVP_ASYM_CIPHER-SM2.pod | 41 +++++++++++++++++++++ doc/man7/EVP_PKEY-SM2.pod | 73 ++++++++++++++++++++++++++++++++++++++ doc/man7/OSSL_PROVIDER-default.pod | 2 ++ doc/man7/SM2.pod | 72 ------------------------------------- doc/man7/provider-asym_cipher.pod | 9 +++++ 5 files changed, 125 insertions(+), 72 deletions(-) create mode 100644 doc/man7/EVP_ASYM_CIPHER-SM2.pod create mode 100644 doc/man7/EVP_PKEY-SM2.pod delete mode 100644 doc/man7/SM2.pod (limited to 'doc/man7') diff --git a/doc/man7/EVP_ASYM_CIPHER-SM2.pod b/doc/man7/EVP_ASYM_CIPHER-SM2.pod new file mode 100644 index 0000000000..27f0032b78 --- /dev/null +++ b/doc/man7/EVP_ASYM_CIPHER-SM2.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +EVP_ASYM_CIPHER-SM2 +- SM2 Asymmetric Cipher algorithm support + +=head1 DESCRIPTION + +Asymmetric Cipher support for the B key type. + +=head2 SM2 Asymmetric Cipher parameters + +=over 4 + +=item "digest" (B) + +=item "digest-props" (B) + +See L. + +=back + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2020 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. + +=cut diff --git a/doc/man7/EVP_PKEY-SM2.pod b/doc/man7/EVP_PKEY-SM2.pod new file mode 100644 index 0000000000..bb6258c873 --- /dev/null +++ b/doc/man7/EVP_PKEY-SM2.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +EVP_PKEY-SM2, EVP_KEYMGMT-SM2, SM2 +- EVP_PKEY keytype support for the Chinese SM2 signature and encryption algorithms + +=head1 DESCRIPTION + +The B algorithm was first defined by the Chinese national standard GM/T +0003-2012 and was later standardized by ISO as ISO/IEC 14888. B is actually +an elliptic curve based algorithm. The current implementation in OpenSSL supports +both signature and encryption schemes via the EVP interface. + +When doing the B signature algorithm, it requires a distinguishing identifier +to form the message prefix which is hashed before the real message is hashed. + +=head1 NOTES + +B signatures can be generated by using the 'DigestSign' series of APIs, for +instance, EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal(). +Ditto for the verification process by calling the 'DigestVerify' series of APIs. + +Before computing an B signature, an B needs to be created, +and an B ID must be set for it, like this: + + EVP_PKEY_CTX_set1_id(pctx, id, id_len); + +Before calling the EVP_DigestSignInit() or EVP_DigestVerifyInit() functions, +that B should be assigned to the B, like this: + + EVP_MD_CTX_set_pkey_ctx(mctx, pctx); + +There is normally no need to pass a B parameter to EVP_DigestSignInit() +or EVP_DigestVerifyInit() in such a scenario. + +SM2 can be tested with the L application since version 3.0. +Currently, the only valid algorithm name is B. + +=head1 EXAMPLES + +This example demonstrates the calling sequence for using an B to verify +a message with the SM2 signature algorithm and the SM3 hash algorithm: + + #include + + /* obtain an EVP_PKEY using whatever methods... */ + mctx = EVP_MD_CTX_new(); + pctx = EVP_PKEY_CTX_new(pkey, NULL); + EVP_PKEY_CTX_set1_id(pctx, id, id_len); + EVP_MD_CTX_set_pkey_ctx(mctx, pctx); + EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); + EVP_DigestVerifyUpdate(mctx, msg, msg_len); + EVP_DigestVerifyFinal(mctx, sig, sig_len) + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2018-2020 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. + +=cut diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod index 848c887b29..da6185c4d3 100644 --- a/doc/man7/OSSL_PROVIDER-default.pod +++ b/doc/man7/OSSL_PROVIDER-default.pod @@ -180,6 +180,8 @@ The OpenSSL default provider supports these operations and algorithms: =item RSA, see L +=item SM2, see L + =back =head2 Asymmetric Key Encapsulation diff --git a/doc/man7/SM2.pod b/doc/man7/SM2.pod deleted file mode 100644 index de52d05329..0000000000 --- a/doc/man7/SM2.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -SM2 - Chinese SM2 signature and encryption algorithm support - -=head1 DESCRIPTION - -The B algorithm was first defined by the Chinese national standard GM/T -0003-2012 and was later standardized by ISO as ISO/IEC 14888. B is actually -an elliptic curve based algorithm. The current implementation in OpenSSL supports -both signature and encryption schemes via the EVP interface. - -When doing the B signature algorithm, it requires a distinguishing identifier -to form the message prefix which is hashed before the real message is hashed. - -=head1 NOTES - -B signatures can be generated by using the 'DigestSign' series of APIs, for -instance, EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal(). -Ditto for the verification process by calling the 'DigestVerify' series of APIs. - -Before computing an B signature, an B needs to be created, -and an B ID must be set for it, like this: - - EVP_PKEY_CTX_set1_id(pctx, id, id_len); - -Before calling the EVP_DigestSignInit() or EVP_DigestVerifyInit() functions, -that B should be assigned to the B, like this: - - EVP_MD_CTX_set_pkey_ctx(mctx, pctx); - -There is normally no need to pass a B parameter to EVP_DigestSignInit() -or EVP_DigestVerifyInit() in such a scenario. - -SM2 can be tested with the L application since version 3.0.0. -Currently, the only valid algorithm name is B. - -=head1 EXAMPLES - -This example demonstrates the calling sequence for using an B to verify -a message with the SM2 signature algorithm and the SM3 hash algorithm: - - #include - - /* obtain an EVP_PKEY using whatever methods... */ - mctx = EVP_MD_CTX_new(); - pctx = EVP_PKEY_CTX_new(pkey, NULL); - EVP_PKEY_CTX_set1_id(pctx, id, id_len); - EVP_MD_CTX_set_pkey_ctx(mctx, pctx); - EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); - EVP_DigestVerifyUpdate(mctx, msg, msg_len); - EVP_DigestVerifyFinal(mctx, sig, sig_len) - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2018-2020 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. - -=cut diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index 5531a08f37..ca3e12fa85 100644 --- a/doc/man7/provider-asym_cipher.pod +++ b/doc/man7/provider-asym_cipher.pod @@ -193,10 +193,19 @@ further details. Gets or sets the name of the OAEP digest algorithm used when OAEP padding is in use. +=item "digest" (B) + +Gets or sets the name of the digest algorithm used by the algorithm (where +applicable). + =item "digest-props" (B) Gets or sets the properties to use when fetching the OAEP digest algorithm. +=item "digest-props" (B) + +Gets or sets the properties to use when fetching the cipher digest algorithm. + =item "mgf1-digest" (B) Gets or sets the name of the MGF1 digest algorithm used when OAEP or PSS padding -- cgit v1.2.3