RSAsetmethod(3) OpenSSL RSAsetmethod(3)

NAME
       RSAsetdefaultmethod, RSAgetdefaultmethod, RSAsetmethod,
       RSAgetmethod, RSAPKCS1SSLeay, RSAnullmethod, RSAflags,
       RSAnewmethod - select RSA method

SYNOPSIS
        #include 

        void RSAsetdefaultmethod(const RSAMETHOD *meth);

        RSAMETHOD *RSAgetdefaultmethod(void);

        int RSAsetmethod(RSA *rsa, const RSAMETHOD *meth);

        RSAMETHOD *RSAgetmethod(const RSA *rsa);

        RSAMETHOD *RSAPKCS1SSLeay(void);

        RSAMETHOD *RSAnullmethod(void);

        int RSAflags(const RSA *rsa);

        RSA *RSAnewmethod(RSAMETHOD *method);

DESCRIPTION
       An RRSSAAMMEETTHHOODD specifies the functions that OpenSSL uses for RSA
       operations. By modifying the method, alternative implementations such
       as hardware accelerators may be used. IMPORTANT: See the NOTES section
       for important information about how these RSA API functions are
       affected by the use of EENNGGIINNEE API calls.

       Initially, the default RSAMETHOD is the OpenSSL internal
       implementation, as returned by RSAPKCS1SSLeay().

       RSAsetdefaultmethod() makes mmeetthh the default method for all RSA
       structures created later. NNBB: This is true only whilst no ENGINE has
       been set as a default for RSA, so this function is no longer
       recommended.

       RSAgetdefaultmethod() returns a pointer to the current default
       RSAMETHOD. However, the meaningfulness of this result is dependant on
       whether the ENGINE API is being used, so this function is no longer
       recommended.

       RSAsetmethod() selects mmeetthh to perform all operations using the key
       rrssaa. This will replace the RSAMETHOD used by the RSA key and if the
       previous method was supplied by an ENGINE, the handle to that ENGINE
       will be released during the change. It is possible to have RSA keys
       that only work with certain RSAMETHOD implementations (eg. from an
       ENGINE module that supports embedded hardware-protected keys), and in
       such cases attempting to change the RSAMETHOD for the key can have
       unexpected results.

       RSAgetmethod() returns a pointer to the RSAMETHOD being used by rrssaa.
       This method may or may not be supplied by an ENGINE implementation, but
       if it is, the return value can only be guaranteed to be valid as long
       as the RSA key itself is valid and does not have its implementation
       changed by RSAsetmethod().

       RSAflags() returns the ffllaaggss that are set for rrssaa's current
       RSAMETHOD. See the BUGS section.

       RSAnewmethod() allocates and initializes an RSA structure so that
       eennggiinnee will be used for the RSA operations. If eennggiinnee is NULL, the
       default ENGINE for RSA operations is used, and if no default ENGINE is
       set, the RSAMETHOD controlled by RSAsetdefaultmethod() is used.

       RSAflags() returns the ffllaaggss that are set for rrssaa's current method.

       RSAnewmethod() allocates and initializes an RRSSAA structure so that
       mmeetthhoodd will be used for the RSA operations. If mmeetthhoodd is NNUULLLL, the
       default method is used.

TTHHEE RRSSAAMMEETTHHOODD SSTTRRUUCCTTUURREE
        typedef struct rsamethst
        {
            /* name of the implementation */
               const char *name;

            /* encrypt */
               int (*rsapubenc)(int flen, unsigned char *from,
                 unsigned char *to, RSA *rsa, int padding);

            /* verify arbitrary data */
               int (*rsapubdec)(int flen, unsigned char *from,
                 unsigned char *to, RSA *rsa, int padding);

            /* sign arbitrary data */
               int (*rsaprivenc)(int flen, unsigned char *from,
                 unsigned char *to, RSA *rsa, int padding);

            /* decrypt */
               int (*rsaprivdec)(int flen, unsigned char *from,
                 unsigned char *to, RSA *rsa, int padding);

            /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
                                               implementations) */
               int (*rsamodexp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);

            /* compute r = a ^ p mod m (May be NULL for some implementations) */
               int (*bnmodexp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
                 const BIGNUM *m, BNCTX *ctx, BNMONTCTX *mctx);

            /* called at RSAnew */
               int (*init)(RSA *rsa);

            /* called at RSAfree */
               int (*finish)(RSA *rsa);

            /* RSAFLAGEXTPKEY        - rsamodexp is called for private key
             *                            operations, even if p,q,dmp1,dmq1,iqmp
             *                            are NULL
             * RSAFLAGSIGNVER        - enable rsasign and rsaverify
             * RSAMETHODFLAGNOCHECK - don't check pub/private match
             */
               int flags;

               char *appdata; /* ?? */

            /* sign. For backward compatibility, this is used only
             * if (flags & RSAFLAGSIGNVER)
             */
               int (*rsasign)(int type, unsigned char *m, unsigned int mlen,
                  unsigned char *sigret, unsigned int *siglen, RSA *rsa);

            /* verify. For backward compatibility, this is used only
             * if (flags & RSAFLAGSIGNVER)
             */
               int (*rsaverify)(int type, unsigned char *m, unsigned int mlen,
                  unsigned char *sigbuf, unsigned int siglen, RSA *rsa);

        } RSAMETHOD;

RETURN VALUES
       RSAPKCS1SSLeay(), RSAPKCS1nullmethod(), RSAgetdefaultmethod()
       and RSAgetmethod() return pointers to the respective RSAMETHODs.

       RSAsetdefaultmethod() returns no value.

       RSAsetmethod() returns a pointer to the old RSAMETHOD implementation
       that was replaced. However, this return value should probably be
       ignored because if it was supplied by an ENGINE, the pointer could be
       invalidated at any time if the ENGINE is unloaded (in fact it could be
       unloaded as a result of the RSAsetmethod() function releasing its
       handle to the ENGINE). For this reason, the return type may be replaced
       with a vvooiidd declaration in a future release.

       RSAnewmethod() returns NULL and sets an error code that can be
       obtained by ERRgeterror(3) if the allocation fails. Otherwise it
       returns a pointer to the newly allocated structure.

NNOOTTEESS
       As of version 0.9.7, RSAMETHOD implementations are grouped together
       with other algorithmic APIs (eg. DSAMETHOD, EVPCIPHER, etc) into
       EENNGGIINNEE modules. If a default ENGINE is specified for RSA functionality
       using an ENGINE API function, that will override any RSA defaults set
       using the RSA API (ie.  RSAsetdefaultmethod()). For this reason, the
       ENGINE API is the recommended way to control default implementations
       for use in RSA and other cryptographic algorithms.

BUGS
       The behaviour of RSAflags() is a mis-feature that is left as-is for
       now to avoid creating compatibility problems. RSA functionality, such
       as the encryption functions, are controlled by the ffllaaggss value in the
       RSA key itself, not by the ffllaaggss value in the RSAMETHOD attached to
       the RSA key (which is what this function returns). If the flags element
       of an RSA key is changed, the changes will be honoured by RSA
       functionality but will not be reflected in the return value of the
       RSAflags() function - in effect RSAflags() behaves more like an
       RSAdefaultflags() function (which does not currently exist).

SEE ALSO
       rsa(3), RSAnew(3)

HISTORY       RSAnewmethod() and RSAsetdefaultmethod() appeared in SSLeay 0.8.
       RSAgetdefaultmethod(), RSAsetmethod() and RSAgetmethod() as well
       as the rsasign and rsaverify components of RSAMETHOD were added in
       OpenSSL 0.9.4.

       RSAsetdefaultopensslmethod() and RSAgetdefaultopensslmethod()
       replaced RSAsetdefaultmethod() and RSAgetdefaultmethod()
       respectively, and RSAsetmethod() and RSAnewmethod() were altered to
       use EENNGGIINNEEs rather than RRSSAAMMEETTHHOODDs during development of the engine
       version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the
       ENGINE API was restructured so that this change was reversed, and
       behaviour of the other functions resembled more closely the previous
       behaviour. The behaviour of defaults in the ENGINE API now
       transparently overrides the behaviour of defaults in the RSA API
       without requiring changing these function prototypes.



0.9.7l                            2002-09-25                 RSAsetmethod(3)