secure/lib/libcrypto/man/man3/BN_BLINDING_new.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "BN_BLINDING_NEW 3"
 136 .TH BN_BLINDING_NEW 3 "2020-03-31" "1.1.1f" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, BN_BLINDING_set_flags, BN_BLINDING_create_param \- blinding related BIGNUM 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 \& int BN_BLINDING_is_current_thread(BN_BLINDING *b);
 159 \& void BN_BLINDING_set_current_thread(BN_BLINDING *b);
 160 \& int BN_BLINDING_lock(BN_BLINDING *b);
 161 \& int BN_BLINDING_unlock(BN_BLINDING *b);
 162 \& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
 163 \& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
 164 \& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
 165 \&                                       const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
 166 \&                                       int (*bn_mod_exp)(BIGNUM *r,
 167 \&                                                         const BIGNUM *a,
 168 \&                                                         const BIGNUM *p,
 169 \&                                                         const BIGNUM *m,
 170 \&                                                         BN_CTX *ctx,
 171 \&                                                         BN_MONT_CTX *m_ctx),
 172 \&                                       BN_MONT_CTX *m_ctx);
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 \&\fBBN_BLINDING_new()\fR allocates a new \fB\s-1BN_BLINDING\s0\fR structure and copies
 177 the \fBA\fR and \fBAi\fR values into the newly created \fB\s-1BN_BLINDING\s0\fR object.
 178 .PP
 179 \&\fBBN_BLINDING_free()\fR frees the \fB\s-1BN_BLINDING\s0\fR structure.
 180 If \fBb\fR is \s-1NULL,\s0 nothing is done.
 181 .PP
 182 \&\fBBN_BLINDING_update()\fR updates the \fB\s-1BN_BLINDING\s0\fR parameters by squaring
 183 the \fBA\fR and \fBAi\fR or, after specific number of uses and if the
 184 necessary parameters are set, by re-creating the blinding parameters.
 185 .PP
 186 \&\fBBN_BLINDING_convert_ex()\fR multiplies \fBn\fR with the blinding factor \fBA\fR.
 187 If \fBr\fR is not \s-1NULL\s0 a copy the inverse blinding factor \fBAi\fR will be
 188 returned in \fBr\fR (this is useful if a \fB\s-1RSA\s0\fR object is shared among
 189 several threads). \fBBN_BLINDING_invert_ex()\fR multiplies \fBn\fR with the
 190 inverse blinding factor \fBAi\fR. If \fBr\fR is not \s-1NULL\s0 it will be used as
 191 the inverse blinding.
 192 .PP
 193 \&\fBBN_BLINDING_convert()\fR and \fBBN_BLINDING_invert()\fR are wrapper
 194 functions for \fBBN_BLINDING_convert_ex()\fR and \fBBN_BLINDING_invert_ex()\fR
 195 with \fBr\fR set to \s-1NULL.\s0
 196 .PP
 197 \&\fBBN_BLINDING_is_current_thread()\fR returns whether the \fB\s-1BN_BLINDING\s0\fR
 198 structure is owned by the current thread. This is to help users
 199 provide proper locking if needed for multi-threaded use.
 200 .PP
 201 \&\fBBN_BLINDING_set_current_thread()\fR sets the current thread as the
 202 owner of the \fB\s-1BN_BLINDING\s0\fR structure.
 203 .PP
 204 \&\fBBN_BLINDING_lock()\fR locks the \fB\s-1BN_BLINDING\s0\fR structure.
 205 .PP
 206 \&\fBBN_BLINDING_unlock()\fR unlocks the \fB\s-1BN_BLINDING\s0\fR structure.
 207 .PP
 208 \&\fBBN_BLINDING_get_flags()\fR returns the \s-1BN_BLINDING\s0 flags. Currently
 209 there are two supported flags: \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR and
 210 \&\fB\s-1BN_BLINDING_NO_RECREATE\s0\fR. \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR inhibits the
 211 automatic update of the \fB\s-1BN_BLINDING\s0\fR parameters after each use
 212 and \fB\s-1BN_BLINDING_NO_RECREATE\s0\fR inhibits the automatic re-creation
 213 of the \fB\s-1BN_BLINDING\s0\fR parameters after a fixed number of uses (currently
 214 32). In newly allocated \fB\s-1BN_BLINDING\s0\fR objects no flags are set.
 215 \&\fBBN_BLINDING_set_flags()\fR sets the \fB\s-1BN_BLINDING\s0\fR parameters flags.
 216 .PP
 217 \&\fBBN_BLINDING_create_param()\fR creates new \fB\s-1BN_BLINDING\s0\fR parameters
 218 using the exponent \fBe\fR and the modulus \fBm\fR. \fBbn_mod_exp\fR and
 219 \&\fBm_ctx\fR can be used to pass special functions for exponentiation
 220 (normally \fBBN_mod_exp_mont()\fR and \fB\s-1BN_MONT_CTX\s0\fR).
 221 .SH "RETURN VALUES"
 222 .IX Header "RETURN VALUES"
 223 \&\fBBN_BLINDING_new()\fR returns the newly allocated \fB\s-1BN_BLINDING\s0\fR structure
 224 or \s-1NULL\s0 in case of an error.
 225 .PP
 226 \&\fBBN_BLINDING_update()\fR, \fBBN_BLINDING_convert()\fR, \fBBN_BLINDING_invert()\fR,
 227 \&\fBBN_BLINDING_convert_ex()\fR and \fBBN_BLINDING_invert_ex()\fR return 1 on
 228 success and 0 if an error occurred.
 229 .PP
 230 \&\fBBN_BLINDING_is_current_thread()\fR returns 1 if the current thread owns
 231 the \fB\s-1BN_BLINDING\s0\fR object, 0 otherwise.
 232 .PP
 233 \&\fBBN_BLINDING_set_current_thread()\fR doesn't return anything.
 234 .PP
 235 \&\fBBN_BLINDING_lock()\fR, \fBBN_BLINDING_unlock()\fR return 1 if the operation
 236 succeeded or 0 on error.
 237 .PP
 238 \&\fBBN_BLINDING_get_flags()\fR returns the currently set \fB\s-1BN_BLINDING\s0\fR flags
 239 (a \fBunsigned long\fR value).
 240 .PP
 241 \&\fBBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
 242 parameters or \s-1NULL\s0 on error.
 243 .SH "HISTORY"
 244 .IX Header "HISTORY"
 245 \&\fBBN_BLINDING_thread_id()\fR was first introduced in OpenSSL 1.0.0, and it
 246 deprecates \fBBN_BLINDING_set_thread_id()\fR and \fBBN_BLINDING_get_thread_id()\fR.
 247 .SH "COPYRIGHT"
 248 .IX Header "COPYRIGHT"
 249 Copyright 2005\-2017 The OpenSSL Project Authors. All Rights Reserved.
 250 .PP
 251 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 252 this file except in compliance with the License.  You can obtain a copy
 253 in the file \s-1LICENSE\s0 in the source distribution or at
 254 <https://www.openssl.org/source/license.html>.