doc/crypto/RSA_set_method.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RSA_set_default_method, RSA_get_default_method, RSA_set_method,
   6 RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
   7 RSA_null_method, RSA_flags, RSA_new_method - select RSA method
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/rsa.h>
  12
  13  void RSA_set_default_method(RSA_METHOD *meth);
  14
  15  RSA_METHOD *RSA_get_default_method(void);
  16
  17  RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth);
  18
  19  RSA_METHOD *RSA_get_method(RSA *rsa);
  20
  21  RSA_METHOD *RSA_PKCS1_SSLeay(void);
  22
  23  RSA_METHOD *RSA_PKCS1_RSAref(void);
  24
  25  RSA_METHOD *RSA_null_method(void);
  26
  27  int RSA_flags(RSA *rsa);
  28
  29  RSA *RSA_new_method(RSA_METHOD *method);
  30
  31 =head1 DESCRIPTION
  32
  33 An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
  34 operations. By modifying the method, alternative implementations
  35 such as hardware accelerators may be used.
  36
  37 Initially, the default is to use the OpenSSL internal implementation,
  38 unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL>
  39 options. RSA_PKCS1_SSLeay() returns a pointer to that method.
  40
  41 RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref
  42 library. This is the default method in the C<rsaref> configuration;
  43 the function is not available in other configurations.
  44 RSA_null_method() returns a pointer to a method that does not support
  45 the RSA transformation. It is the default if OpenSSL is compiled with
  46 C<-DRSA_NULL>. These methods may be useful in the USA because of a
  47 patent on the RSA cryptosystem.
  48
  49 RSA_set_default_method() makes B<meth> the default method for all B<RSA>
  50 structures created later.
  51
  52 RSA_get_default_method() returns a pointer to the current default
  53 method.
  54
  55 RSA_set_method() selects B<meth> for all operations using the key
  56 B<rsa>.
  57
  58 RSA_get_method() returns a pointer to the method currently selected
  59 for B<rsa>.
  60
  61 RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
  62
  63 RSA_new_method() allocates and initializes an B<RSA> structure so that
  64 B<method> will be used for the RSA operations. If B<method> is B<NULL>,
  65 the default method is used.
  66
  67 =head1 THE RSA_METHOD STRUCTURE
  68
  69  typedef struct rsa_meth_st
  70  {
  71      /* name of the implementation */
  72         const char *name;
  73
  74      /* encrypt */
  75         int (*rsa_pub_enc)(int flen, unsigned char *from,
  76           unsigned char *to, RSA *rsa, int padding);
  77
  78      /* verify arbitrary data */
  79         int (*rsa_pub_dec)(int flen, unsigned char *from,
  80           unsigned char *to, RSA *rsa, int padding);
  81
  82      /* sign arbitrary data */
  83         int (*rsa_priv_enc)(int flen, unsigned char *from,
  84           unsigned char *to, RSA *rsa, int padding);
  85
  86      /* decrypt */
  87         int (*rsa_priv_dec)(int flen, unsigned char *from,
  88           unsigned char *to, RSA *rsa, int padding);
  89
  90      /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
  91                                         implementations) */
  92         int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
  93
  94      /* compute r = a ^ p mod m (May be NULL for some implementations) */
  95         int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
  96           const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
  97
  98      /* called at RSA_new */
  99         int (*init)(RSA *rsa);
 100
 101      /* called at RSA_free */
 102         int (*finish)(RSA *rsa);
 103
 104      /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
 105       *                            operations, even if p,q,dmp1,dmq1,iqmp
 106       *                            are NULL
 107       * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
 108       * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
 109       */
 110         int flags;
 111
 112         char *app_data; /* ?? */
 113
 114      /* sign. For backward compatibility, this is used only
 115       * if (flags & RSA_FLAG_SIGN_VER)
 116       */
 117         int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
 118            unsigned char *sigret, unsigned int *siglen, RSA *rsa);
 119
 120      /* verify. For backward compatibility, this is used only
 121       * if (flags & RSA_FLAG_SIGN_VER)
 122       */
 123         int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
 124            unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
 125
 126  } RSA_METHOD;
 127
 128 =head1 RETURN VALUES
 129
 130 RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(),
 131 RSA_get_default_method() and RSA_get_method() return pointers to the
 132 respective B<RSA_METHOD>s.
 133
 134 RSA_set_default_method() returns no value.
 135
 136 RSA_set_method() returns a pointer to the B<RSA_METHOD> previously
 137 associated with B<rsa>.
 138
 139 RSA_new_method() returns B<NULL> and sets an error code that can be
 140 obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it
 141 returns a pointer to the newly allocated structure.
 142
 143 =head1 SEE ALSO
 144
 145 L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)>
 146
 147 =head1 HISTORY
 148
 149 RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
 150 RSA_get_default_method(), RSA_set_method() and RSA_get_method() as
 151 well as the rsa_sign and rsa_verify components of RSA_METHOD were
 152 added in OpenSSL 0.9.4.
 153
 154 =cut