lib/libcrypto/man/RSA_set_method.3

   1 .\"     $OpenBSD: RSA_set_method.3,v 1.5 2016/12/11 12:21:48 schwarze Exp $
   2 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>
   5 .\" and Geoff Thorpe <geoff@openssl.org>.
   6 .\" Copyright (c) 2000, 2002, 2007, 2014 The OpenSSL Project.
   7 .\" All rights reserved.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\"
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\"
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in
  18 .\"    the documentation and/or other materials provided with the
  19 .\"    distribution.
  20 .\"
  21 .\" 3. All advertising materials mentioning features or use of this
  22 .\"    software must display the following acknowledgment:
  23 .\"    "This product includes software developed by the OpenSSL Project
  24 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  25 .\"
  26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  27 .\"    endorse or promote products derived from this software without
  28 .\"    prior written permission. For written permission, please contact
  29 .\"    openssl-core@openssl.org.
  30 .\"
  31 .\" 5. Products derived from this software may not be called "OpenSSL"
  32 .\"    nor may "OpenSSL" appear in their names without prior written
  33 .\"    permission of the OpenSSL Project.
  34 .\"
  35 .\" 6. Redistributions of any form whatsoever must retain the following
  36 .\"    acknowledgment:
  37 .\"    "This product includes software developed by the OpenSSL Project
  38 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  39 .\"
  40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  43 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  52 .\"
  53 .Dd $Mdocdate: December 11 2016 $
  54 .Dt RSA_SET_METHOD 3
  55 .Os
  56 .Sh NAME
  57 .Nm RSA_set_default_method ,
  58 .Nm RSA_get_default_method ,
  59 .Nm RSA_set_method ,
  60 .Nm RSA_get_method ,
  61 .Nm RSA_PKCS1_SSLeay ,
  62 .Nm RSA_null_method ,
  63 .Nm RSA_flags ,
  64 .Nm RSA_new_method ,
  65 .Nm RSA_get_default_openssl_method ,
  66 .Nm RSA_set_default_openssl_method
  67 .Nd select RSA method
  68 .Sh SYNOPSIS
  69 .In openssl/rsa.h
  70 .Ft void
  71 .Fo RSA_set_default_method
  72 .Fa "const RSA_METHOD *meth"
  73 .Fc
  74 .Ft RSA_METHOD *
  75 .Fn RSA_get_default_method void
  76 .Ft int
  77 .Fo RSA_set_method
  78 .Fa "RSA *rsa"
  79 .Fa "const RSA_METHOD *meth"
  80 .Fc
  81 .Ft RSA_METHOD *
  82 .Fo RSA_get_method
  83 .Fa "const RSA *rsa"
  84 .Fc
  85 .Ft RSA_METHOD *
  86 .Fn RSA_PKCS1_SSLeay void
  87 .Ft RSA_METHOD *
  88 .Fn RSA_null_method void
  89 .Ft int
  90 .Fo RSA_flags
  91 .Fa "const RSA *rsa"
  92 .Fc
  93 .Ft RSA *
  94 .Fo RSA_new_method
  95 .Fa "RSA_METHOD *meth"
  96 .Fc
  97 .Sh DESCRIPTION
  98 An
  99 .Vt RSA_METHOD
 100 specifies the functions that OpenSSL uses for RSA operations.
 101 By modifying the method, alternative implementations such as hardware
 102 accelerators may be used.
 103 See the
 104 .Sx CAVEATS
 105 section for how these RSA API functions are affected by the use of
 106 .Xr engine 3
 107 API calls.
 108 .Pp
 109 Initially, the default
 110 .Vt RSA_METHOD
 111 is the OpenSSL internal implementation, as returned by
 112 .Fn RSA_PKCS1_SSLeay .
 113 .Pp
 114 .Fn RSA_set_default_method
 115 makes
 116 .Fa meth
 117 the default method for all
 118 .Vt RSA
 119 structures created later.
 120 .Sy NB :
 121 This is true only whilst no
 122 .Vt ENGINE
 123 has been set as a default for RSA, so this function is no longer
 124 recommended.
 125 .Pp
 126 .Fn RSA_get_default_method
 127 returns a pointer to the current default
 128 .Vt RSA_METHOD .
 129 However, the meaningfulness of this result is dependent on whether
 130 the
 131 .Xr engine 3
 132 API is being used, so this function is no longer recommended.
 133 .Pp
 134 .Fn RSA_set_method
 135 selects
 136 .Fa meth
 137 to perform all operations using the key
 138 .Fa rsa .
 139 This will replace the
 140 .Vt RSA_METHOD
 141 used by the RSA key, and if the previous method was supplied by an
 142 .Vt ENGINE ,
 143 the handle to that
 144 .Vt ENGINE
 145 will be released during the change.
 146 It is possible to have RSA keys that only work with certain
 147 .Vt RSA_METHOD
 148 implementations (e.g. from an
 149 .Vt ENGINE
 150 module that supports embedded hardware-protected keys),
 151 and in such cases attempting to change the
 152 .Vt RSA_METHOD
 153 for the key can have unexpected results.
 154 .Pp
 155 .Fn RSA_get_method
 156 returns a pointer to the
 157 .Vt RSA_METHOD
 158 being used by
 159 .Fa rsa .
 160 This method may or may not be supplied by an
 161 .Vt ENGINE
 162 implementation but if it is, the return value can only be guaranteed
 163 to be valid as long as the RSA key itself is valid and does not
 164 have its implementation changed by
 165 .Fn RSA_set_method .
 166 .Pp
 167 .Fn RSA_flags
 168 returns the flags that are set for the current
 169 .Vt RSA_METHOD
 170 of
 171 .Fa rsa .
 172 See the
 173 .Sx BUGS
 174 section.
 175 .Pp
 176 .Fn RSA_new_method
 177 allocates and initializes an
 178 .Vt RSA
 179 structure so that
 180 .Fa meth
 181 will be used for the RSA operations.
 182 If
 183 .Sy engine
 184 is NULL, the default ENGINE for RSA operations is used and, if no
 185 default ENGINE is set, the RSA_METHOD controlled by
 186 .Fn RSA_set_default_method
 187 is used.
 188 .Pp
 189 .Fn RSA_flags
 190 returns the
 191 .Sy flags
 192 that are set for
 193 .Fa rsa Ns 's
 194 current method.
 195 .Pp
 196 .Fn RSA_new_method
 197 allocates and initializes an
 198 .Vt RSA
 199 structure so that
 200 .Fa meth
 201 will be used for the RSA operations.
 202 If
 203 .Fa meth
 204 is
 205 .Dv NULL ,
 206 the default method is used.
 207 .Sh THE RSA_METHOD STRUCTURE
 208 .Bd -literal
 209 typedef struct rsa_meth_st
 210 {
 211      /* name of the implementation */
 212         const char *name;
 213
 214      /* encrypt */
 215         int (*rsa_pub_enc)(int flen, unsigned char *from,
 216           unsigned char *to, RSA *rsa, int padding);
 217
 218      /* verify arbitrary data */
 219         int (*rsa_pub_dec)(int flen, unsigned char *from,
 220           unsigned char *to, RSA *rsa, int padding);
 221
 222      /* sign arbitrary data */
 223         int (*rsa_priv_enc)(int flen, unsigned char *from,
 224           unsigned char *to, RSA *rsa, int padding);
 225
 226      /* decrypt */
 227         int (*rsa_priv_dec)(int flen, unsigned char *from,
 228           unsigned char *to, RSA *rsa, int padding);
 229
 230      /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
 231                                         implementations) */
 232         int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
 233
 234      /* compute r = a ^ p mod m (May be NULL for some implementations) */
 235         int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
 236           const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
 237
 238      /* called at RSA_new */
 239         int (*init)(RSA *rsa);
 240
 241      /* called at RSA_free */
 242         int (*finish)(RSA *rsa);
 243
 244      /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
 245       *                            operations, even if p,q,dmp1,dmq1,iqmp
 246       *                            are NULL
 247       * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
 248       * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
 249       */
 250         int flags;
 251
 252         char *app_data; /* ?? */
 253
 254      /* sign. For backward compatibility, this is used only
 255       * if (flags & RSA_FLAG_SIGN_VER)
 256       */
 257         int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
 258            unsigned char *sigret, unsigned int *siglen, RSA *rsa);
 259
 260      /* verify. For backward compatibility, this is used only
 261       * if (flags & RSA_FLAG_SIGN_VER)
 262       */
 263         int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
 264            unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
 265
 266 } RSA_METHOD;
 267 .Ed
 268 .Sh RETURN VALUES
 269 .Fn RSA_PKCS1_SSLeay ,
 270 .Fn RSA_null_method ,
 271 .Fn RSA_get_default_method
 272 and
 273 .Fn RSA_get_method
 274 return pointers to the respective
 275 .Vt RSA_METHOD .
 276 .Pp
 277 .Fn RSA_set_method
 278 returns a pointer to the old
 279 .Vt RSA_METHOD
 280 implementation that was replaced.
 281 However, this return value should probably be ignored because if it was
 282 supplied by an
 283 .Vt ENGINE ,
 284 the pointer could be invalidated at any time if the
 285 .Vt ENGINE
 286 is unloaded.
 287 In fact, it could be unloaded as a result of the
 288 .Fn RSA_set_method
 289 function releasing its handle to the
 290 .Vt ENGINE .
 291 For this reason, the return type may be replaced with a
 292 .Vt void
 293 declaration in a future release.
 294 .Pp
 295 .Fn RSA_new_method
 296 returns
 297 .Dv NULL
 298 and sets an error code that can be obtained by
 299 .Xr ERR_get_error 3
 300 if the allocation fails.
 301 Otherwise it returns a pointer to the newly allocated structure.
 302 .Sh SEE ALSO
 303 .Xr RSA_new 3
 304 .Sh HISTORY
 305 .Fn RSA_new_method
 306 and
 307 .Fn RSA_set_default_method
 308 appeared in SSLeay 0.8.
 309 .Fn RSA_get_default_method ,
 310 .Fn RSA_set_method ,
 311 and
 312 .Fn RSA_get_method
 313 as well as the
 314 .Fa rsa_sign
 315 and
 316 .Fa rsa_verify
 317 components of
 318 .Vt RSA_METHOD
 319 were added in OpenSSL 0.9.4.
 320 .Pp
 321 .Fn RSA_set_default_openssl_method
 322 and
 323 .Fn RSA_get_default_openssl_method
 324 replaced
 325 .Fn RSA_set_default_method
 326 and
 327 .Fn RSA_get_default_method
 328 respectively, and
 329 .Fn RSA_set_method
 330 and
 331 .Fn RSA_new_method
 332 were altered to use
 333 .Vt ENGINE Ns s
 334 rather than
 335 .Vt RSA_METHOD Ns s
 336 during development of the
 337 .Xr engine 3
 338 version of OpenSSL 0.9.6.
 339 For 0.9.7, the handling of defaults in the
 340 .Xr engine 3
 341 API was restructured so that this change was reversed, and behaviour
 342 of the other functions resembled more closely the previous behaviour.
 343 The behaviour of defaults in the
 344 .Xr engine 3
 345 API now transparently overrides the behaviour of defaults in the
 346 RSA API without requiring changing these function prototypes.
 347 .Sh CAVEATS
 348 As of version 0.9.7,
 349 .Vt RSA_METHOD
 350 implementations are grouped together with other algorithmic APIs (e.g.\&
 351 .Vt DSA_METHOD
 352 or
 353 .Vt EVP_CIPHER )
 354 into
 355 .Vt ENGINE
 356 modules.
 357 If a default
 358 .Vt ENGINE
 359 is specified for RSA functionality using an
 360 .Xr engine 3
 361 API function, that will override any RSA defaults set using the RSA
 362 API, i.e.\&
 363 .Fn RSA_set_default_method .
 364 For this reason, the
 365 .Xr engine 3
 366 API is the recommended way to control default implementations for
 367 use in RSA and other cryptographic algorithms.
 368 .Sh BUGS
 369 The behaviour of
 370 .Fn RSA_flags
 371 is a misfeature that is left as-is for now to avoid creating
 372 compatibility problems.
 373 RSA functionality, such as the encryption functions, are controlled by
 374 the
 375 .Fa flags
 376 value in the
 377 .Vt RSA
 378 key itself, not by the
 379 .Fa flags
 380 value in the
 381 .Vt RSA_METHOD
 382 attached to the RSA key (which is what this function returns).
 383 If the flags element of an
 384 .Vt RSA
 385 key is changed, the changes will be honoured by RSA functionality
 386 but will not be reflected in the return value of the
 387 .Fn RSA_flags
 388 function - in effect
 389 .Fn RSA_flags
 390 behaves more like a RSA_default_flags() function, which does not
 391 currently exist.