diff options
author | Paul Yang <yang.yang@baishancloud.com> | 2018-09-05 15:19:17 +0800 |
---|---|---|
committer | Paul Yang <yang.yang@baishancloud.com> | 2018-09-07 18:12:26 +0800 |
commit | 675f4ceef880f9c4eb0fda5dacd18b001fefb5bc (patch) | |
tree | efd1f41c908f873f0567576005b3cab148a76b42 /doc | |
parent | a6c4cb845a031f09c6303a2c3452e253d0d01518 (diff) |
Update document for SM2 stuffs
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/7113)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_DigestInit.pod | 18 | ||||
-rw-r--r-- | doc/man3/EVP_DigestSignInit.pod | 11 | ||||
-rw-r--r-- | doc/man3/EVP_DigestVerifyInit.pod | 9 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_CTX_ctrl.pod | 22 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_meth_new.pod | 17 |
5 files changed, 70 insertions, 7 deletions
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index 67f4f02196..02e7719274 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -11,7 +11,8 @@ EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data, EVP_md_null, EVP_get_digestbyname, EVP_get_digestbynid, -EVP_get_digestbyobj - EVP digest routines +EVP_get_digestbyobj, +EVP_MD_CTX_set_pkey_ctx - EVP digest routines =head1 SYNOPSIS @@ -54,6 +55,8 @@ EVP_get_digestbyobj - EVP digest routines const EVP_MD *EVP_get_digestbynid(int type); const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); + void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx); + =head1 DESCRIPTION The EVP digest routines are a high level interface to message digests, @@ -179,6 +182,13 @@ EVP_get_digestbyobj() Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an B<ASN1_OBJECT> structure respectively. +=item EVP_MD_CTX_set_pkey_ctx() + +Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide +a customzied B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or +L<EVP_DigestVerifyInit(3)>. The B<EVP_PKEY_CTX> passed to this function should +be freed by the caller. + =back =head1 FLAGS @@ -256,6 +266,10 @@ EVP_get_digestbyobj() Returns either an B<EVP_MD> structure or NULL if an error occurs. +=item EVP_MD_CTX_set_pkey_ctx() + +This function has no return value. + =back =head1 NOTES @@ -360,6 +374,8 @@ later, so now EVP_sha1() can be used with RSA and DSA. EVP_dss1() was removed in OpenSSL 1.1.0. +EVP_MD_CTX_set_pkey_ctx() is added in 1.1.1. + =head1 COPYRIGHT Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod index fe2be7bbf5..773de87efa 100644 --- a/doc/man3/EVP_DigestSignInit.pod +++ b/doc/man3/EVP_DigestSignInit.pod @@ -28,8 +28,15 @@ EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL, the EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can be used to set alternative signing options. Note that any existing value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed -directly by the application (it will be freed automatically when the EVP_MD_CTX -is freed). The digest B<type> may be NULL if the signing algorithm supports it. +directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before +being passed to EVP_DigestSignInit() (which means the EVP_PKEY_CTX is created +inside EVP_DigestSignInit() and it will be freed automatically when the +EVP_MD_CTX is freed). + +The digest B<type> may be NULL if the signing algorithm supports it. + +No B<EVP_PKEY_CTX> will be created by EVP_DigsetSignInit() if the passed B<ctx> +has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>. Only EVP_PKEY types that support signing can be used with these functions. This includes MAC algorithms where the MAC generation is considered as a form of diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod index 0d25debcb1..e93ac2ef08 100644 --- a/doc/man3/EVP_DigestVerifyInit.pod +++ b/doc/man3/EVP_DigestVerifyInit.pod @@ -26,10 +26,15 @@ B<type> from ENGINE B<e> and public key B<pkey>. B<ctx> must be created with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL, the EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this can be used to set alternative verification options. Note that any existing -value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be -freed directly by the application (it will be freed automatically when the +value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed +directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before +being passed to EVP_DigestSignInit() (which means the EVP_PKEY_CTX is created +inside EVP_DigestSignInit() and it will be freed automatically when the EVP_MD_CTX is freed). +No B<EVP_PKEY_CTX> will be created by EVP_DigsetSignInit() if the passed B<ctx> +has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>. + EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the verification context B<ctx>. This function can be called several times on the same B<ctx> to include additional data. This function is currently implemented diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 7eb9796bdd..d70dbb9cf2 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -17,7 +17,9 @@ EVP_PKEY_CTX_set_dh_paramgen_generator, EVP_PKEY_CTX_set_dh_pad, EVP_PKEY_CTX_set_dh_nid, EVP_PKEY_CTX_set_ec_paramgen_curve_nid, -EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations +EVP_PKEY_CTX_set_ec_param_enc, +EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len +- algorithm specific control operations =head1 SYNOPSIS @@ -53,6 +55,10 @@ EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); + int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len); + int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id); + int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len); + =head1 DESCRIPTION The function EVP_PKEY_CTX_ctrl() sends a control operation to the context @@ -160,6 +166,17 @@ For maximum compatibility the named curve form should be used. Note: the B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous versions should use 0 instead. +The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() +are used to manipulate special identifier field for specific signature algorithm +such as SM2. The EVP_PKEY_set1_id() sets an ID pointed by B<id> with the length +B<id_len> to the library. The library maintains the memory management stuffs so +the caller can safely free the original memory pointed by B<id>. The +EVP_PKEY_CTX_get1_id_len() returns the length of the ID set via a previous call +to EVP_PKEY_set1_id(). The length is usually used to allocate adequate memory for +further calls to EVP_PKEY_CTX_get1_id(). The EVP_PKEY_CTX_get1_id() returns the +previously set ID value to caller into B<id>, caller should allocate adequate +memory space to B<id> before calling EVP_PKEY_CTX_get1_id(). + =head1 RETURN VALUES EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 @@ -179,7 +196,8 @@ L<EVP_PKEY_keygen(3)> =head1 HISTORY -These functions were first added to OpenSSL 1.0.0. +EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() +were added in 1.1.1, other functions were first added to OpenSSL 1.0.0. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod index ddc99d2800..171d4da744 100644 --- a/doc/man3/EVP_PKEY_meth_new.pod +++ b/doc/man3/EVP_PKEY_meth_new.pod @@ -10,12 +10,14 @@ EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_si EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_check, EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check, +EVP_PKEY_meth_set_digest_custom, EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup, EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign, EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx, EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt, EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check, EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check, +EVP_PKEY_meth_get_digest_custom, EVP_PKEY_meth_remove - manipulating EVP_PKEY_METHOD structure @@ -116,6 +118,9 @@ EVP_PKEY_meth_remove int (*check) (EVP_PKEY *pkey)); void EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth, int (*check) (EVP_PKEY *pkey)); + void EVP_PKEY_meth_set_digest_custom(EVP_PKEY_METHOD *pmeth, + int (*digest_custom) (EVP_PKEY_CTX *ctx, + EVP_MD_CTX *mctx)); void EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth, int (**pinit) (EVP_PKEY_CTX *ctx)); @@ -201,6 +206,9 @@ EVP_PKEY_meth_remove int (**pcheck) (EVP_PKEY *pkey)); void EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth, int (**pcheck) (EVP_PKEY *pkey)); + void EVP_PKEY_meth_get_digest_custom(EVP_PKEY_METHOD *pmeth, + int (**pdigest_custom) (EVP_PKEY_CTX *ctx, + EVP_MD_CTX *mctx)); =head1 DESCRIPTION @@ -334,6 +342,15 @@ key-pair, the public component and parameters respectively for a given B<pkey>. They could be called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> respectively. + int (*digest_custom) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); + +The digest_custom() method is used to generate customized digest content before +the real message is passed to functions like L<EVP_DigestSignUpdate(3)> or +L<EVP_DigestVerifyInit(3)>. This is usually required by some public key +signature algorithms like SM2 which requires a hashed prefix to the message to +be signed. The digest_custom() will be called by L<EVP_DigestSignInit(3)> and +L<EVP_DigestVerifyInit(3)>. + =head2 Functions EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object, |