secure/lib/libcrypto/man/BN_BLINDING_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "BN_BLINDING_new 3"
 132 .TH BN_BLINDING_new 3 "2018-11-20" "1.0.2q" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
 139 BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
 140 BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags,
 141 BN_BLINDING_set_flags, BN_BLINDING_create_param \- blinding related BIGNUM
 142 functions.
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/bn.h>
 147 \&
 148 \& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
 149 \&        BIGNUM *mod);
 150 \& void BN_BLINDING_free(BN_BLINDING *b);
 151 \& int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
 152 \& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
 153 \& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
 154 \& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
 155 \&        BN_CTX *ctx);
 156 \& int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
 157 \&        BN_CTX *ctx);
 158 \& #ifndef OPENSSL_NO_DEPRECATED
 159 \& unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
 160 \& void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
 161 \& #endif
 162 \& CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
 163 \& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
 164 \& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
 165 \& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
 166 \&        const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
 167 \&        int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
 168 \&                          const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
 169 \&        BN_MONT_CTX *m_ctx);
 170 .Ve
 171 .SH "DESCRIPTION"
 172 .IX Header "DESCRIPTION"
 173 \&\fIBN_BLINDING_new()\fR allocates a new \fB\s-1BN_BLINDING\s0\fR structure and copies
 174 the \fBA\fR and \fBAi\fR values into the newly created \fB\s-1BN_BLINDING\s0\fR object.
 175 .PP
 176 \&\fIBN_BLINDING_free()\fR frees the \fB\s-1BN_BLINDING\s0\fR structure.
 177 .PP
 178 \&\fIBN_BLINDING_update()\fR updates the \fB\s-1BN_BLINDING\s0\fR parameters by squaring
 179 the \fBA\fR and \fBAi\fR or, after specific number of uses and if the
 180 necessary parameters are set, by re-creating the blinding parameters.
 181 .PP
 182 \&\fIBN_BLINDING_convert_ex()\fR multiplies \fBn\fR with the blinding factor \fBA\fR.
 183 If \fBr\fR is not \s-1NULL\s0 a copy the inverse blinding factor \fBAi\fR will be
 184 returned in \fBr\fR (this is useful if a \fB\s-1RSA\s0\fR object is shared among
 185 several threads). \fIBN_BLINDING_invert_ex()\fR multiplies \fBn\fR with the
 186 inverse blinding factor \fBAi\fR. If \fBr\fR is not \s-1NULL\s0 it will be used as
 187 the inverse blinding.
 188 .PP
 189 \&\fIBN_BLINDING_convert()\fR and \fIBN_BLINDING_invert()\fR are wrapper
 190 functions for \fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR
 191 with \fBr\fR set to \s-1NULL.\s0
 192 .PP
 193 \&\fIBN_BLINDING_thread_id()\fR provides access to the \fB\s-1CRYPTO_THREADID\s0\fR
 194 object within the \fB\s-1BN_BLINDING\s0\fR structure. This is to help users
 195 provide proper locking if needed for multi-threaded use. The \*(L"thread
 196 id\*(R" object of a newly allocated \fB\s-1BN_BLINDING\s0\fR structure is
 197 initialised to the thread id in which \fIBN_BLINDING_new()\fR was called.
 198 .PP
 199 \&\fIBN_BLINDING_get_flags()\fR returns the \s-1BN_BLINDING\s0 flags. Currently
 200 there are two supported flags: \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR and
 201 \&\fB\s-1BN_BLINDING_NO_RECREATE\s0\fR. \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR inhibits the
 202 automatic update of the \fB\s-1BN_BLINDING\s0\fR parameters after each use
 203 and \fB\s-1BN_BLINDING_NO_RECREATE\s0\fR inhibits the automatic re-creation
 204 of the \fB\s-1BN_BLINDING\s0\fR parameters after a fixed number of uses (currently
 205 32). In newly allocated \fB\s-1BN_BLINDING\s0\fR objects no flags are set.
 206 \&\fIBN_BLINDING_set_flags()\fR sets the \fB\s-1BN_BLINDING\s0\fR parameters flags.
 207 .PP
 208 \&\fIBN_BLINDING_create_param()\fR creates new \fB\s-1BN_BLINDING\s0\fR parameters
 209 using the exponent \fBe\fR and the modulus \fBm\fR. \fBbn_mod_exp\fR and
 210 \&\fBm_ctx\fR can be used to pass special functions for exponentiation
 211 (normally \fIBN_mod_exp_mont()\fR and \fB\s-1BN_MONT_CTX\s0\fR).
 212 .SH "RETURN VALUES"
 213 .IX Header "RETURN VALUES"
 214 \&\fIBN_BLINDING_new()\fR returns the newly allocated \fB\s-1BN_BLINDING\s0\fR structure
 215 or \s-1NULL\s0 in case of an error.
 216 .PP
 217 \&\fIBN_BLINDING_update()\fR, \fIBN_BLINDING_convert()\fR, \fIBN_BLINDING_invert()\fR,
 218 \&\fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR return 1 on
 219 success and 0 if an error occurred.
 220 .PP
 221 \&\fIBN_BLINDING_thread_id()\fR returns a pointer to the thread id object
 222 within a \fB\s-1BN_BLINDING\s0\fR object.
 223 .PP
 224 \&\fIBN_BLINDING_get_flags()\fR returns the currently set \fB\s-1BN_BLINDING\s0\fR flags
 225 (a \fBunsigned long\fR value).
 226 .PP
 227 \&\fIBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
 228 parameters or \s-1NULL\s0 on error.
 229 .SH "SEE ALSO"
 230 .IX Header "SEE ALSO"
 231 \&\fIbn\fR\|(3)
 232 .SH "HISTORY"
 233 .IX Header "HISTORY"
 234 BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it
 235 deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id.
 236 .PP
 237 BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
 238 BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
 239 and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
 240 .SH "AUTHOR"
 241 .IX Header "AUTHOR"
 242 Nils Larsch for the OpenSSL project (http://www.openssl.org).