Document the RSA library.

doc/crypto/RSA_set_method.pod

@@ -0,0 +1,153 @@
+=pod
+
+=head1 NAME
+
+RSA_set_default_method, RSA_get_default_method, RSA_set_method,
+RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
+RSA_PKCS1_null_method, RSA_flags, RSA_new_method - Select RSA method
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ void RSA_set_default_method(RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_default_method(void);
+
+ RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_method(RSA *rsa);
+
+ RSA_METHOD *RSA_PKCS1_SSLeay(void);
+
+ RSA_METHOD *RSA_PKCS1_RSAref(void);
+
+ RSA_METHOD *RSA_null_method(void);
+
+ int RSA_flags(RSA *rsa);
+
+ RSA *RSA_new_method(RSA_METHOD *method);
+
+=head1 DESCRIPTION
+
+An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
+operations. By modifying the method, alternative implementations
+such as hardware accelerators may be used.
+
+Initially, the default is to use the OpenSSL internal implementation,
+unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL>
+options. RSA_PKCS1_SSLeay() returns a pointer to that method.
+
+RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref
+library. This is the default method in the C<rsaref> configuration;
+the function is not available in other configurations.
+RSA_null_method() returns a pointer to a method that does not support
+the RSA transformation. It is the default if OpenSSL is compiled with
+C<-DRSA_NULL>. These methods may be useful in the USA because of a
+patent on the RSA cryptosystem.
+
+RSA_set_default_method() makes B<meth> the default method for all B<RSA>
+structures created later.
+
+RSA_get_default_method() returns a pointer to the current default
+method.
+
+RSA_set_method() selects B<meth> for all operations using the key
+B<rsa>.
+
+RSA_get_method() returns a pointer to the method currently selected
+for B<rsa>.
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
+
+RSA_new_method() allocates and initializes an B<RSA> structure so that
+B<method> will be used for the RSA operations. If B<method> is B<NULL>,
+the default method is used.
+
+=head1 THE RSA_METHOD STRUCTURE
+
+ typedef struct rsa_meth_st
+ {
+     /* name of the implementation */
+	const char *name;
+
+     /* encrypt */
+	int (*rsa_pub_enc)(int flen, unsigned char *from,
+          unsigned char *to, RSA *rsa, int padding);
+
+     /* verify arbitrary data */
+	int (*rsa_pub_dec)(int flen, unsigned char *from,
+          unsigned char *to, RSA *rsa, int padding);
+
+     /* sign arbitrary data */
+	int (*rsa_priv_enc)(int flen, unsigned char *from,
+          unsigned char *to, RSA *rsa, int padding);
+
+     /* decrypt */
+	int (*rsa_priv_dec)(int flen, unsigned char *from,
+          unsigned char *to, RSA *rsa, int padding);
+
+     /* compute r0 = r0 ^ I mod rsa->n. May be NULL */
+	int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
+
+     /* compute r = a ^ p mod m. May be NULL */
+	int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+          const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+
+     /* called at RSA_new */
+	int (*init)(RSA *rsa);
+
+     /* called at RSA_free */
+	int (*finish)(RSA *rsa);
+
+     /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
+      *                            operations, even if p,q,dmp1,dmq1,iqmp
+      *                            are NULL
+      * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
+      * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
+      */
+	int flags;
+
+	char *app_data; /* ?? */
+
+     /* sign. For backward compatibility, this is used only
+      * if (flags & RSA_FLAG_SIGN_VER)
+      */
+	int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
+           unsigned char *sigret, unsigned int *siglen, RSA *rsa);
+
+     /* verify. For backward compatibility, this is used only
+      * if (flags & RSA_FLAG_SIGN_VER)
+      */
+	int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
+           unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
+
+ } RSA_METHOD;
+
+=head1 RETURN VALUES
+
+RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(),
+RSA_get_default_method() and RSA_get_method() return pointers to the
+respective B<RSA_METHOD>s.
+
+RSA_set_default_method() returns no value.
+
+RSA_set_method() returns a pointer to the B<RSA_METHOD> previously
+associated with B<rsa>.
+
+RSA_new_method() returns B<NULL> and sets an error code that can be
+obtained by ERR_get_error(3) if the allocation fails. Otherwise it
+returns a pointer to the newly allocated structure.
+
+=head1 SEE ALSO
+
+rsa(3), RSA_new(3)
+
+=head1 HISTORY
+
+RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
+RSA_get_default_method(), RSA_set_method() and RSA_get_method() as
+well as the rsa_sign and rsa_verify components of RSA_METHOD were
+added in OpenSSL 0.9.4.
+
+=cut