Commit 0af9a89c authored by Geoff Thorpe's avatar Geoff Thorpe
Browse files

This documentation change was being written at the same time as Richard's 

changes. So I'm committing this version to overwrite his changes for now,
and he can always take his turn to overwrite my words if he wants :-)

PR: 86
parent db802c60

doc/crypto/RSA_check_key.pod

+26 −7
Original line number Diff line number Diff line
@@ -18,7 +18,9 @@ in fact prime, and that B<n = p*q>. 
It also checks that B<d*e = 1 mod (p-1*q-1)>,

and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>.



The key's public components may not be B<NULL>.

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<NOTES> for more

information.



=head1 RETURN VALUE
@@ -30,12 +32,29 @@ obtained using L<ERR_get_error(3)|ERR_get_error(3)>. 


=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<p>, B<q> and B<d> 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<not> 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<no>

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