1.\" $OpenBSD: bn_dump.3,v 1.9 2023/11/16 18:10:19 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL crypto/bn/README.pod aebb9aac Jul 19 09:27:53 2016 -0400 4.\" 5.\" This file was written by Ulf Moeller <ulf@openssl.org>. 6.\" Copyright (c) 2000, 2003, 2006, 2009 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: November 16 2023 $ 54.Dt BN_DUMP 3 55.Os 56.Sh NAME 57.Nm bn_mul_words , 58.Nm bn_mul_add_words , 59.Nm bn_sqr_words , 60.Nm bn_div_words , 61.Nm bn_add_words , 62.Nm bn_sub_words , 63.Nm bn_mul_comba4 , 64.Nm bn_mul_comba8 , 65.Nm bn_sqr_comba4 , 66.Nm bn_sqr_comba8 , 67.Nm bn_mul_normal , 68.Nm bn_expand , 69.Nm bn_wexpand 70.Nd BIGNUM library internal functions 71.Sh SYNOPSIS 72.Fd #include "bn_local.h" 73.Ft BN_ULONG 74.Fo bn_mul_words 75.Fa "BN_ULONG *rp" 76.Fa "BN_ULONG *ap" 77.Fa "int num" 78.Fa "BN_ULONG w" 79.Fc 80.Ft BN_ULONG 81.Fo bn_mul_add_words 82.Fa "BN_ULONG *rp" 83.Fa "BN_ULONG *ap" 84.Fa "int num" 85.Fa "BN_ULONG w" 86.Fc 87.Ft void 88.Fo bn_sqr_words 89.Fa "BN_ULONG *rp" 90.Fa "BN_ULONG *ap" 91.Fa "int num" 92.Fc 93.Ft BN_ULONG 94.Fo bn_div_words 95.Fa "BN_ULONG h" 96.Fa "BN_ULONG l" 97.Fa "BN_ULONG d" 98.Fc 99.Ft BN_ULONG 100.Fo bn_add_words 101.Fa "BN_ULONG *rp" 102.Fa "BN_ULONG *ap" 103.Fa "BN_ULONG *bp" 104.Fa "int num" 105.Fc 106.Ft BN_ULONG 107.Fo bn_sub_words 108.Fa "BN_ULONG *rp" 109.Fa "BN_ULONG *ap" 110.Fa "BN_ULONG *bp" 111.Fa "int num" 112.Fc 113.Ft void 114.Fo bn_mul_comba4 115.Fa "BN_ULONG *r" 116.Fa "BN_ULONG *a" 117.Fa "BN_ULONG *b" 118.Fc 119.Ft void 120.Fo bn_mul_comba8 121.Fa "BN_ULONG *r" 122.Fa "BN_ULONG *a" 123.Fa "BN_ULONG *b" 124.Fc 125.Ft void 126.Fo bn_sqr_comba4 127.Fa "BN_ULONG *r" 128.Fa "BN_ULONG *a" 129.Fc 130.Ft void 131.Fo bn_sqr_comba8 132.Fa "BN_ULONG *r" 133.Fa "BN_ULONG *a" 134.Fc 135.Ft void 136.Fo bn_mul_normal 137.Fa "BN_ULONG *r" 138.Fa "BN_ULONG *a" 139.Fa "int na" 140.Fa "BN_ULONG *b" 141.Fa "int nb" 142.Fc 143.Ft BIGNUM * 144.Fo bn_expand 145.Fa "BIGNUM *a" 146.Fa "int bits" 147.Fc 148.Ft BIGNUM * 149.Fo bn_wexpand 150.Fa "BIGNUM *a" 151.Fa "int n" 152.Fc 153.Sh DESCRIPTION 154This page documents some internal functions used by the 155.Vt BIGNUM 156implementation. 157They are described here to facilitate debugging and extending the 158library. 159They are 160.Em not 161to be used by applications. 162.Ss The BIGNUM structure 163.Bd -literal 164typedef struct bignum_st BIGNUM; 165 166struct bignum_st { 167 BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ 168 int top; /* Index of last used d +1. */ 169 /* The next are internal book keeping for bn_expand. */ 170 int dmax; /* Size of the d array. */ 171 int neg; /* one if the number is negative */ 172 int flags; 173}; 174.Ed 175.Pp 176The integer value is stored in 177.Fa d , 178a 179.Xr malloc 3 Ap ed 180array of words 181.Pq Vt BN_ULONG , 182least significant word first. 183.Vt BN_ULONG 184is a macro that expands to 185.Vt unsigned long Pq = Vt uint64_t 186on 187.Dv _LP64 188platforms and 189.Vt unsigned int Pq = Vt uint32_t 190elsewhere. 191.Pp 192.Fa dmax 193is the size of the 194.Fa d 195array that has been allocated. 196.Fa top 197is the number of words being used, so for a value of 4, bn.d[0]=4 and 198bn.top=1. 199.Fa neg 200is 1 if the number is negative. 201When a 202.Vt BIGNUM 203is 0, the 204.Fa d 205field can be 206.Dv NULL 207and 208.Fa top 209== 0. 210.Pp 211.Fa flags 212is a bit field of flags which are defined in 213.In openssl/bn.h . 214The flags begin with 215.Dv BN_FLG_ . 216The functions 217.Xr BN_set_flags 3 218and 219.Xr BN_get_flags 3 220enable or inspect 221.Fa flags . 222.Pp 223Various routines in this library require the use of temporary 224.Vt BIGNUM 225variables during their execution. 226Since dynamic memory allocation to create 227.Vt BIGNUM Ns s 228is rather expensive when used in conjunction with repeated subroutine 229calls, the 230.Vt BN_CTX 231structure is used. 232This structure contains BN_CTX_NUM 233.Vt BIGNUM Ns s ; 234see 235.Xr BN_CTX_start 3 . 236.Ss Low level arithmetic operations 237These functions are implemented in C and for several platforms in 238assembly language: 239.Pp 240.Fn bn_mul_words rp ap num w 241operates on the 242.Fa num 243word arrays 244.Fa rp 245and 246.Fa ap . 247It computes 248.Fa ap 249* 250.Fa w , 251places the result in 252.Fa rp , 253and returns the high word (carry). 254.Pp 255.Fn bn_mul_add_words rp ap num w 256operates on the 257.Fa num 258word arrays 259.Fa rp 260and 261.Fa ap . 262It computes 263.Fa ap 264* 265.Fa w 266+ 267.Fa rp , 268places the result in 269.Fa rp , 270and returns the high word (carry). 271.Pp 272.Fn bn_sqr_words rp ap num 273operates on the 274.Fa num 275word array 276.Fa ap 277and the 278.Pf 2* Fa num 279word array 280.Fa ap . 281It computes 282.Fa ap 283* 284.Fa ap 285word-wise, and places the low and high bytes of the result in 286.Fa rp . 287.Pp 288.Fn bn_div_words h l d 289divides the two word number 290.Pq Fa h , Fa l 291by 292.Fa d 293and returns the result. 294.Pp 295.Fn bn_add_words rp ap bp num 296operates on the 297.Fa num 298word arrays 299.Fa ap , 300.Fa bp 301and 302.Fa rp . 303It computes 304.Fa ap 305+ 306.Fa bp , 307places the result in 308.Fa rp , 309and returns the high word (carry). 310.Pp 311.Fn bn_sub_words rp ap bp num 312operates on the 313.Fa num 314word arrays 315.Fa ap , 316.Fa bp 317and 318.Fa rp . 319It computes 320.Fa ap 321- 322.Fa bp , 323places the result in 324.Fa rp , 325and returns the carry (1 if 326.Fa bp 327\(ra 328.Fa ap , 3290 otherwise). 330.Pp 331.Fn bn_mul_comba4 r a b 332operates on the 4 word arrays 333.Fa a 334and 335.Fa b 336and the 8-word array 337.Fa r . 338It computes 339.Fa a Ns * Ns Fa b 340and places the result in 341.Fa r . 342.Pp 343.Fn bn_mul_comba8 r a b 344operates on the 8-word arrays 345.Fa a 346and 347.Fa b 348and the 16-word array 349.Fa r . 350It computes 351.Fa a Ns * Ns Fa b 352and places the result in 353.Fa r . 354.Pp 355.Fn bn_sqr_comba4 r a b 356operates on the 4-word arrays 357.Fa a 358and 359.Fa b 360and the 8-word array 361.Fa r . 362.Pp 363.Fn bn_sqr_comba8 r a b 364operates on the 8-word arrays 365.Fa a 366and 367.Fa b 368and the 16 word array 369.Fa r . 370.Pp 371The following functions are implemented in C: 372.Pp 373.Fn bn_mul_normal r a na b nb 374operates on the 375.Fa na 376word array 377.Fa a , 378the 379.Fa nb 380word array 381.Fa b 382and the 383.Fa na Ns + Ns Fa nb 384word array 385.Fa r . 386It computes 387.Fa a Ns * Ns Fa b 388and places the result in 389.Fa r . 390.Pp 391.Xr BN_mul 3 392calls 393.Fn bn_mul_comba4 394if both factors are 4 words long, 395.Fn bn_mul_comba8 396if both factors are 8 words long, 397or 398.Fn bn_mul_normal 399otherwise. 400.Ss Size changes 401.Fn bn_expand 402ensures that 403.Fa b 404has enough space for a 405.Fa bits 406bit number. 407.Fn bn_wexpand 408ensures that 409.Fa b 410has enough space for an 411.Fa n 412word number. 413They return 0 on error or 1 otherwise. 414.Sh SEE ALSO 415.Xr BN_new 3 416