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-09-11" "1.1.1" "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, 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/bn.h>
 143 \&
 144 \& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
 145 \&                              BIGNUM *mod);
 146 \& void BN_BLINDING_free(BN_BLINDING *b);
 147 \& int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
 148 \& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
 149 \& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
 150 \& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
 151 \&                            BN_CTX *ctx);
 152 \& int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
 153 \&                           BN_CTX *ctx);
 154 \& int BN_BLINDING_is_current_thread(BN_BLINDING *b);
 155 \& void BN_BLINDING_set_current_thread(BN_BLINDING *b);
 156 \& int BN_BLINDING_lock(BN_BLINDING *b);
 157 \& int BN_BLINDING_unlock(BN_BLINDING *b);
 158 \& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
 159 \& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
 160 \& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
 161 \&                                       const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
 162 \&                                       int (*bn_mod_exp)(BIGNUM *r,
 163 \&                                                         const BIGNUM *a,
 164 \&                                                         const BIGNUM *p,
 165 \&                                                         const BIGNUM *m,
 166 \&                                                         BN_CTX *ctx,
 167 \&                                                         BN_MONT_CTX *m_ctx),
 168 \&                                       BN_MONT_CTX *m_ctx);
 169 .Ve
 170 .SH "DESCRIPTION"
 171 .IX Header "DESCRIPTION"
 172 \&\fIBN_BLINDING_new()\fR allocates a new \fB\s-1BN_BLINDING\s0\fR structure and copies
 173 the \fBA\fR and \fBAi\fR values into the newly created \fB\s-1BN_BLINDING\s0\fR object.
 174 .PP
 175 \&\fIBN_BLINDING_free()\fR frees the \fB\s-1BN_BLINDING\s0\fR structure.
 176 If \fBb\fR is \s-1NULL,\s0 nothing is done.
 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_is_current_thread()\fR returns whether the \fB\s-1BN_BLINDING\s0\fR
 194 structure is owned by the current thread. This is to help users
 195 provide proper locking if needed for multi-threaded use.
 196 .PP
 197 \&\fIBN_BLINDING_set_current_thread()\fR sets the current thread as the
 198 owner of the \fB\s-1BN_BLINDING\s0\fR structure.
 199 .PP
 200 \&\fIBN_BLINDING_lock()\fR locks the \fB\s-1BN_BLINDING\s0\fR structure.
 201 .PP
 202 \&\fIBN_BLINDING_unlock()\fR unlocks the \fB\s-1BN_BLINDING\s0\fR structure.
 203 .PP
 204 \&\fIBN_BLINDING_get_flags()\fR returns the \s-1BN_BLINDING\s0 flags. Currently
 205 there are two supported flags: \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR and
 206 \&\fB\s-1BN_BLINDING_NO_RECREATE\s0\fR. \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR inhibits the
 207 automatic update of the \fB\s-1BN_BLINDING\s0\fR parameters after each use
 208 and \fB\s-1BN_BLINDING_NO_RECREATE\s0\fR inhibits the automatic re-creation
 209 of the \fB\s-1BN_BLINDING\s0\fR parameters after a fixed number of uses (currently
 210 32). In newly allocated \fB\s-1BN_BLINDING\s0\fR objects no flags are set.
 211 \&\fIBN_BLINDING_set_flags()\fR sets the \fB\s-1BN_BLINDING\s0\fR parameters flags.
 212 .PP
 213 \&\fIBN_BLINDING_create_param()\fR creates new \fB\s-1BN_BLINDING\s0\fR parameters
 214 using the exponent \fBe\fR and the modulus \fBm\fR. \fBbn_mod_exp\fR and
 215 \&\fBm_ctx\fR can be used to pass special functions for exponentiation
 216 (normally \fIBN_mod_exp_mont()\fR and \fB\s-1BN_MONT_CTX\s0\fR).
 217 .SH "RETURN VALUES"
 218 .IX Header "RETURN VALUES"
 219 \&\fIBN_BLINDING_new()\fR returns the newly allocated \fB\s-1BN_BLINDING\s0\fR structure
 220 or \s-1NULL\s0 in case of an error.
 221 .PP
 222 \&\fIBN_BLINDING_update()\fR, \fIBN_BLINDING_convert()\fR, \fIBN_BLINDING_invert()\fR,
 223 \&\fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR return 1 on
 224 success and 0 if an error occurred.
 225 .PP
 226 \&\fIBN_BLINDING_is_current_thread()\fR returns 1 if the current thread owns
 227 the \fB\s-1BN_BLINDING\s0\fR object, 0 otherwise.
 228 .PP
 229 \&\fIBN_BLINDING_set_current_thread()\fR doesn't return anything.
 230 .PP
 231 \&\fIBN_BLINDING_lock()\fR, \fIBN_BLINDING_unlock()\fR return 1 if the operation
 232 succeeded or 0 on error.
 233 .PP
 234 \&\fIBN_BLINDING_get_flags()\fR returns the currently set \fB\s-1BN_BLINDING\s0\fR flags
 235 (a \fBunsigned long\fR value).
 236 .PP
 237 \&\fIBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
 238 parameters or \s-1NULL\s0 on error.
 239 .SH "HISTORY"
 240 .IX Header "HISTORY"
 241 \&\fIBN_BLINDING_thread_id()\fR was first introduced in OpenSSL 1.0.0, and it
 242 deprecates \fIBN_BLINDING_set_thread_id()\fR and \fIBN_BLINDING_get_thread_id()\fR.
 243 .SH "COPYRIGHT"
 244 .IX Header "COPYRIGHT"
 245 Copyright 2005\-2017 The OpenSSL Project Authors. All Rights Reserved.
 246 .PP
 247 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 248 this file except in compliance with the License.  You can obtain a copy
 249 in the file \s-1LICENSE\s0 in the source distribution or at
 250 <https://www.openssl.org/source/license.html>.