1 files changed, 97 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/RSA_check_key.3 b/src/lib/libcrypto/man/RSA_check_key.3
new file mode 100644
index 0000000000..c57ed4b4db
--- /dev/null
+++ b/src/lib/libcrypto/man/RSA_check_key.3
@@ -0,0 +1,97 @@
+.Dd $Mdocdate: November 4 2016 $
+.Dt RSA_CHECK_KEY 3
+.Os
+.Sh NAME
+.Nm RSA_check_key
+.Nd validate private RSA keys
+.Sh SYNOPSIS
+.In openssl/rsa.h
+.Ft int
+.Fo RSA_check_key
+.Fa "RSA *rsa"
+.Fc
+.Sh DESCRIPTION
+This function validates RSA keys.
+It checks that
+.Fa rsa->p
+and
+.Fa rsa->q
+are in fact prime, and that
+.Fa rsa->n
+satifies n = p*q.
+.Pp
+It also checks that
+.Fa rsa->d
+and
+.Fa rsa->e
+satisfy d*e = 1 mod ((p-1)*(q-1)),
+and that
+.Fa rsa->dmp1 ,
+.Fa rsa->dmq1 ,
+and
+.Fa resa->iqmp
+are set correctly or are
+.Dv NULL .
+.Pp
+As such, this function cannot be used with any arbitrary
+.Vt RSA
+key object, even if it is otherwise fit for regular RSA operation.
+.Pp
+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
+.Vt RSA
+key structure must contain all the private key data too.
+.Pp
+Unlike most other RSA functions, this function does
+.Sy not
+work transparently with any underlying
+.Vt ENGINE
+implementation because it uses the key data in the
+.Vt RSA
+structure directly.
+An
+.Vt ENGINE
+implementation can override the way key data is stored and handled,
+and can even provide support for HSM keys - in which case the
+.Vt RSA
+structure may contain
+.Sy no
+key data at all!
+If the
+.Vt 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.
+.Sh RETURN VALUE
+.Fn RSA_check_key
+returns 1 if
+.Fa rsa
+is a valid RSA key, and 0 otherwise.
+-1 is returned if an error occurs while checking the key.
+.Pp
+If the key is invalid or an error occurred, the reason code can be
+obtained using
+.Xr ERR_get_error 3 .
+.Sh SEE ALSO
+.Xr ERR_get_error 3 ,
+.Xr rsa 3
+.Sh HISTORY
+.Fn RSA_check_key
+appeared in OpenSSL 0.9.4.
+.Sh BUGS
+A method of verifying the RSA key using opaque RSA API functions might
+need to be considered.
+Right now
+.Fn RSA_check_key
+simply uses the
+.Vt RSA
+structure elements directly, bypassing the
+.Vt 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
+.Vt RSA_METHOD
+function table so that alternative implementations can also provide
+their own verifiers.

diff --git a/src/lib/libcrypto/man/RSA_check_key.3 b/src/lib/libcrypto/man/RSA_check_key.3 new file mode 100644 index 0000000000..c57ed4b4db --- /dev/null +++ b/src/lib/libcrypto/man/RSA_check_key.3
@@ -0,0 +1,97 @@
	1	.Dd $Mdocdate: November 4 2016 $
	2	.Dt RSA_CHECK_KEY 3
	3	.Os
	4	.Sh NAME
	5	.Nm RSA_check_key
	6	.Nd validate private RSA keys
	7	.Sh SYNOPSIS
	8	.In openssl/rsa.h
	9	.Ft int
	10	.Fo RSA_check_key
	11	.Fa "RSA *rsa"
	12	.Fc
	13	.Sh DESCRIPTION
	14	This function validates RSA keys.
	15	It checks that
	16	.Fa rsa->p
	17	and
	18	.Fa rsa->q
	19	are in fact prime, and that
	20	.Fa rsa->n
	21	satifies n = p*q.
	22	.Pp
	23	It also checks that
	24	.Fa rsa->d
	25	and
	26	.Fa rsa->e
	27	satisfy de = 1 mod ((p-1)(q-1)),
	28	and that
	29	.Fa rsa->dmp1 ,
	30	.Fa rsa->dmq1 ,
	31	and
	32	.Fa resa->iqmp
	33	are set correctly or are
	34	.Dv NULL .
	35	.Pp
	36	As such, this function cannot be used with any arbitrary
	37	.Vt RSA
	38	key object, even if it is otherwise fit for regular RSA operation.
	39	.Pp
	40	This function does not work on RSA public keys that have only the
	41	modulus and public exponent elements populated.
	42	It performs integrity checks on all the RSA key material, so the
	43	.Vt RSA
	44	key structure must contain all the private key data too.
	45	.Pp
	46	Unlike most other RSA functions, this function does
	47	.Sy not
	48	work transparently with any underlying
	49	.Vt ENGINE
	50	implementation because it uses the key data in the
	51	.Vt RSA
	52	structure directly.
	53	An
	54	.Vt ENGINE
	55	implementation can override the way key data is stored and handled,
	56	and can even provide support for HSM keys - in which case the
	57	.Vt RSA
	58	structure may contain
	59	.Sy no
	60	key data at all!
	61	If the
	62	.Vt ENGINE
	63	in question is only being used for acceleration or analysis purposes,
	64	then in all likelihood the RSA key data is complete and untouched,
	65	but this can't be assumed in the general case.
	66	.Sh RETURN VALUE
	67	.Fn RSA_check_key
	68	returns 1 if
	69	.Fa rsa
	70	is a valid RSA key, and 0 otherwise.
	71	-1 is returned if an error occurs while checking the key.
	72	.Pp
	73	If the key is invalid or an error occurred, the reason code can be
	74	obtained using
	75	.Xr ERR_get_error 3 .
	76	.Sh SEE ALSO
	77	.Xr ERR_get_error 3 ,
	78	.Xr rsa 3
	79	.Sh HISTORY
	80	.Fn RSA_check_key
	81	appeared in OpenSSL 0.9.4.
	82	.Sh BUGS
	83	A method of verifying the RSA key using opaque RSA API functions might
	84	need to be considered.
	85	Right now
	86	.Fn RSA_check_key
	87	simply uses the
	88	.Vt RSA
	89	structure elements directly, bypassing the
	90	.Vt RSA_METHOD
	91	table altogether (and completely violating encapsulation and
	92	object-orientation in the process).
	93	The best fix will probably be to introduce a check_key() handler
	94	to the
	95	.Vt RSA_METHOD
	96	function table so that alternative implementations can also provide
	97	their own verifiers.