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