diff options
author | Paul Yang <yang.yang@baishancloud.com> | 2017-11-01 00:45:24 +0800 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2017-11-20 07:20:30 +0100 |
commit | b0004708730f300a2e5c6a11c887caab50b6c42a (patch) | |
tree | cdfb52867403b6dee0f8c1c9860111076dd37144 /doc | |
parent | 5d99881e6a58a8775b8ca866b794f615a16bb033 (diff) |
Support public key and param check in EVP interface
EVP_PKEY_public_check() and EVP_PKEY_param_check()
Doc and test cases are added
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4647)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man1/pkey.pod | 6 | ||||
-rw-r--r-- | doc/man1/pkeyparam.pod | 5 | ||||
-rw-r--r-- | doc/man3/DH_generate_parameters.pod | 18 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_ASN1_METHOD.pod | 22 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_keygen.pod | 21 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_meth_new.pod | 18 |
6 files changed, 79 insertions, 11 deletions
diff --git a/doc/man1/pkey.pod b/doc/man1/pkey.pod index 47ffb6649f..9569fe0e41 100644 --- a/doc/man1/pkey.pod +++ b/doc/man1/pkey.pod @@ -24,6 +24,7 @@ B<openssl> B<pkey> [B<-pubout>] [B<-engine id>] [B<-check>] +[B<-pubcheck>] =head1 DESCRIPTION @@ -117,6 +118,11 @@ for all available algorithms. This option checks the consistency of a key pair for both public and private components. +=item B<-pubcheck> + +This option checks the correctness of either a public key or the public component +of a key pair. + =back =head1 EXAMPLES diff --git a/doc/man1/pkeyparam.pod b/doc/man1/pkeyparam.pod index 45c053cf43..117970582d 100644 --- a/doc/man1/pkeyparam.pod +++ b/doc/man1/pkeyparam.pod @@ -14,6 +14,7 @@ B<openssl> B<pkeyparam> [B<-text>] [B<-noout>] [B<-engine id>] +[B<-check>] =head1 DESCRIPTION @@ -53,6 +54,10 @@ to attempt to obtain a functional reference to the specified engine, thus initialising it if needed. The engine will then be set as the default for all available algorithms. +=item B<-check> + +This option checks the correctness of parameters. + =back =head1 EXAMPLE diff --git a/doc/man3/DH_generate_parameters.pod b/doc/man3/DH_generate_parameters.pod index 2e8c3b7172..56ad4b12fe 100644 --- a/doc/man3/DH_generate_parameters.pod +++ b/doc/man3/DH_generate_parameters.pod @@ -3,7 +3,9 @@ =head1 NAME DH_generate_parameters_ex, DH_generate_parameters, -DH_check, DH_check_params - generate and check Diffie-Hellman +DH_check, DH_check_params, +DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex +- generate and check Diffie-Hellman parameters =head1 SYNOPSIS @@ -15,6 +17,10 @@ parameters int DH_check(DH *dh, int *codes); int DH_check_params(DH *dh, int *codes); + int DH_check_ex(const DH *dh); + int DH_check_params_ex(const DH *dh); + int DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key); + Deprecated: #if OPENSSL_API_COMPAT < 0x00908000L @@ -105,6 +111,11 @@ The parameter B<j> is invalid. =back +DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similiar with +DH_check() and DH_check_params() respectively, but the error reasons are set +to the OpenSSL error handling framework instead of returning by the function +parameters. + =head1 RETURN VALUES DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1 @@ -113,6 +124,9 @@ if the check could be performed, 0 otherwise. DH_generate_parameters() returns a pointer to the DH structure or NULL if the parameter generation fails. +DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() return 1 if the +check is successful, 0 for failed. + The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO @@ -127,7 +141,7 @@ DH_generate_parameters_ex() instead. =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/EVP_PKEY_ASN1_METHOD.pod b/doc/man3/EVP_PKEY_ASN1_METHOD.pod index 2ebabd10af..cb03b473aa 100644 --- a/doc/man3/EVP_PKEY_ASN1_METHOD.pod +++ b/doc/man3/EVP_PKEY_ASN1_METHOD.pod @@ -16,6 +16,8 @@ EVP_PKEY_asn1_set_ctrl, EVP_PKEY_asn1_set_item, EVP_PKEY_asn1_set_siginf, EVP_PKEY_asn1_set_check, +EVP_PKEY_asn1_set_public_check, +EVP_PKEY_asn1_set_param_check, EVP_PKEY_asn1_set_security_bits, EVP_PKEY_get0_asn1 - manipulating and registering EVP_PKEY_ASN1_METHOD structure @@ -100,6 +102,12 @@ EVP_PKEY_get0_asn1 void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth, int (*pkey_check) (const EVP_PKEY *pk)); + void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth, + int (*pkey_pub_check) (const EVP_PKEY *pk)); + + void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth, + int (*pkey_param_check) (const EVP_PKEY *pk)); + void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth, int (*pkey_security_bits) (const EVP_PKEY *pk)); @@ -309,10 +317,15 @@ It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)> and L<X509_check_issued(3)>. int (*pkey_check) (const EVP_PKEY *pk); + int (*pkey_public_check) (const EVP_PKEY *pk); + int (*pkey_param_check) (const EVP_PKEY *pk); -The pkey_check() method is used to check the validity of B<pk>. -It MUST return 0 for an invalid key, or 1 for a valid key. -It's called by L<EVP_PKEY_check(3)>. +The pkey_check(), pkey_public_check() and pkey_param_check() methods are used +to check the validity of B<pk> for key-pair, public component and parameters, +respectively. +They MUST return 0 for an invalid key, or 1 for a valid key. +They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and +L<EVP_PKEY_param_check(3)> respectively. =head2 Functions @@ -354,7 +367,8 @@ when initializing the application. EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(), EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(), EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(), -EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(), and +EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(), +EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check() and EVP_PKEY_asn1_set_security_bits() set the diverse methods of the given B<EVP_PKEY_ASN1_METHOD> object. diff --git a/doc/man3/EVP_PKEY_keygen.pod b/doc/man3/EVP_PKEY_keygen.pod index 099cd0cf8f..a18579c09a 100644 --- a/doc/man3/EVP_PKEY_keygen.pod +++ b/doc/man3/EVP_PKEY_keygen.pod @@ -6,7 +6,8 @@ EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data, -EVP_PKEY_gen_cb, EVP_PKEY_check +EVP_PKEY_gen_cb, EVP_PKEY_check, EVP_PKEY_public_check, +EVP_PKEY_param_check - key and parameter generation and check functions =head1 SYNOPSIS @@ -29,6 +30,8 @@ EVP_PKEY_gen_cb, EVP_PKEY_check void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); int EVP_PKEY_check(EVP_PKEY_CTX *ctx); + int EVP_PKEY_public_check(EVP_PKEY_CTX *ctx); + int EVP_PKEY_param_check(EVP_PKEY_CTX *ctx); =head1 DESCRIPTION @@ -64,6 +67,14 @@ EVP_PKEY_check() validates the key-pair given by B<ctx>. This function first tri to use customized key check method in B<EVP_PKEY_METHOD> if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>. +EVP_PKEY_public_check() validates the public component of the key-pair given by B<ctx>. +This function first tries to use customized key check method in B<EVP_PKEY_METHOD> +if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>. + +EVP_PKEY_param_check() validates the algorithm parameters of the key-pair given by B<ctx>. +This function first tries to use customized key check method in B<EVP_PKEY_METHOD> +if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>. + =head1 NOTES After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm @@ -95,8 +106,9 @@ EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm. -EVP_PKEY_check() returns 1 for success or others for failure. It -returns -2 if the operation is not supported for the specific algorithm. +EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() return 1 +for success or others for failure. They return -2 if the operation is not supported +for the specific algorithm. =head1 EXAMPLES @@ -178,6 +190,9 @@ L<EVP_PKEY_derive(3)> These functions were first added to OpenSSL 1.0.0. +EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() were added +in OpenSSL 1.1.1. + =head1 COPYRIGHT Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod index 672ac29cb3..918e4fa141 100644 --- a/doc/man3/EVP_PKEY_meth_new.pod +++ b/doc/man3/EVP_PKEY_meth_new.pod @@ -9,11 +9,13 @@ EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, 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_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_remove - manipulating EVP_PKEY_METHOD structure @@ -110,6 +112,10 @@ EVP_PKEY_meth_remove const char *value)); void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth, int (*check) (EVP_PKEY *pkey)); + void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth, + 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_get_init(EVP_PKEY_METHOD *pmeth, int (**pinit) (EVP_PKEY_CTX *ctx)); @@ -191,6 +197,10 @@ EVP_PKEY_meth_remove const char *value)); void EVP_PKEY_meth_get_check(EVP_PKEY_METHOD *pmeth, int (**pcheck) (EVP_PKEY *pkey)); + void EVP_PKEY_meth_get_public_check(EVP_PKEY_METHOD *pmeth, + int (**pcheck) (EVP_PKEY *pkey)); + void EVP_PKEY_meth_get_param_check(EVP_PKEY_METHOD *pmeth, + int (**pcheck) (EVP_PKEY *pkey)); =head1 DESCRIPTION @@ -316,9 +326,13 @@ a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)> and L<EVP_DigestVerify(3)>. int (*check) (EVP_PKEY *pkey); + int (*public_check) (EVP_PKEY *pkey); + int (*param_check) (EVP_PKEY *pkey); -The check() method is used to validate a key-pair for a given B<pkey>. It -could be called by L<EVP_PKEY_check(3)>. +The check(), public_check() and param_check() methods are used to validate a +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. =head2 Functions |