diff --git a/doc/crypto/RSA_check_key.pod b/doc/crypto/RSA_check_key.pod index 5737ecdc3e286b57c2b977a12e1f36ef02fa66cf..3d824a07f570130f158c0e7e569e5ac5e9dc7d04 100644 --- a/doc/crypto/RSA_check_key.pod +++ b/doc/crypto/RSA_check_key.pod @@ -18,7 +18,9 @@ in fact prime, and that B. It also checks that B, and that B, B and B are set correctly or are B. -The key's public components may not be B. +As such, this function can not be used with any arbitrary RSA key object, +even if it is otherwise fit for regular RSA operation. See B for more +information. =head1 RETURN VALUE @@ -30,12 +32,29 @@ obtained using L. =head1 NOTES -RSA_check_key() can only check soft keys. If given hard keys, i.e. keys -that were retreived from an ENGINE (with ENGINE_load_private_key()), -RSA_check_key() will always return 0, as if the key was invalid. The -reason is that the private components B

, B and B are normally -not available to OpenSSL for hard keys, and the checks can therefore not -be done. +This function does not work on RSA public keys that have only the modulus +and public exponent elements populated. It performs integrity checks on all +the RSA key material, so the RSA key structure must contain all the private +key data too. + +Unlike most other RSA functions, this function does B work +transparently with any underlying ENGINE implementation because it uses the +key data in the RSA structure directly. An ENGINE implementation can +override the way key data is stored and handled, and can even provide +support for HSM keys - in which case the RSA structure may contain B +key data at all! If the ENGINE in question is only being used for +acceleration or analysis purposes, then in all likelihood the RSA key data +is complete and untouched, but this can't be assumed in the general case. + +=head1 BUGS + +A method of verifying the RSA key using opaque RSA API functions might need +to be considered. Right now RSA_check_key() simply uses the RSA structure +elements directly, bypassing the RSA_METHOD table altogether (and +completely violating encapsulation and object-orientation in the process). +The best fix will probably be to introduce a "check_key()" handler to the +RSA_METHOD function table so that alternative implementations can also +provide their own verifiers. =head1 SEE ALSO