| blob | a12a33e30192b77d322cbf5c2f1d8fe95e718abd |
1 .\" $OpenBSD: BN_bn2bin.3,v 1.10 2018/03/23 23:18:17 schwarze Exp $
2 .\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
3 .\"
4 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
5 .\" Copyright (c) 2000, 2002, 2016 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: March 23 2018 $
52 .Dt BN_BN2BIN 3
53 .Os
54 .Sh NAME
55 .Nm BN_bn2bin ,
56 .Nm BN_bin2bn ,
57 .Nm BN_bn2hex ,
58 .Nm BN_bn2dec ,
59 .Nm BN_hex2bn ,
60 .Nm BN_dec2bn ,
61 .Nm BN_asc2bn ,
62 .Nm BN_print ,
63 .Nm BN_print_fp ,
64 .Nm BN_bn2mpi ,
65 .Nm BN_mpi2bn
66 .Nd format conversions
67 .Sh SYNOPSIS
68 .In openssl/bn.h
69 .Ft int
70 .Fo BN_bn2bin
71 .Fa "const BIGNUM *a"
72 .Fa "unsigned char *to"
73 .Fc
74 .Ft BIGNUM *
75 .Fo BN_bin2bn
76 .Fa "const unsigned char *s"
77 .Fa "int len"
78 .Fa "BIGNUM *ret"
79 .Fc
80 .Ft char *
81 .Fo BN_bn2hex
82 .Fa "const BIGNUM *a"
83 .Fc
84 .Ft char *
85 .Fo BN_bn2dec
86 .Fa "const BIGNUM *a"
87 .Fc
88 .Ft int
89 .Fo BN_hex2bn
90 .Fa "BIGNUM **a"
91 .Fa "const char *str"
92 .Fc
93 .Ft int
94 .Fo BN_dec2bn
95 .Fa "BIGNUM **a"
96 .Fa "const char *str"
97 .Fc
98 .Ft int
99 .Fo BN_asc2bn
100 .Fa "BIGNUM **a"
101 .Fa "const char *str"
102 .Fc
103 .Ft int
104 .Fo BN_print
105 .Fa "BIO *fp"
106 .Fa "const BIGNUM *a"
107 .Fc
108 .Ft int
109 .Fo BN_print_fp
110 .Fa "FILE *fp"
111 .Fa "const BIGNUM *a"
112 .Fc
113 .Ft int
114 .Fo BN_bn2mpi
115 .Fa "const BIGNUM *a"
116 .Fa "unsigned char *to"
117 .Fc
118 .Ft BIGNUM *
119 .Fo BN_mpi2bn
120 .Fa "unsigned char *s"
121 .Fa "int len"
122 .Fa "BIGNUM *ret"
123 .Fc
124 .Sh DESCRIPTION
125 .Fn BN_bn2bin
126 converts the absolute value of
127 .Fa a
128 into big-endian form and stores it at
129 .Fa to .
130 .Fa to
131 must point to
132 .Fn BN_num_bytes a
133 bytes of memory.
134 .Pp
135 .Fn BN_bin2bn
136 converts the positive integer in big-endian form of length
137 .Fa len
138 at
139 .Fa s
140 into a
141 .Vt BIGNUM
142 and places it in
143 .Fa ret .
144 If
145 .Fa ret
146 is
147 .Dv NULL ,
148 a new
149 .Vt BIGNUM
150 is created.
151 .Pp
152 .Fn BN_bn2hex
153 and
154 .Fn BN_bn2dec
155 return printable strings containing the hexadecimal and decimal encoding of
156 .Fa a
157 respectively.
158 For negative numbers, the string is prefaced with a leading minus sign.
159 The string must be freed later using
160 .Xr free 3 .
161 .Pp
162 .Fn BN_hex2bn
163 interprets
164 .Fa str
165 as a hexadecimal number.
166 The string may start with a minus sign
167 .Pq Sq - .
168 Conversion stops at the first byte that is not a hexadecimal digit.
169 The number is converted to a
170 .Vt BIGNUM
171 and stored in
172 .Pf * Fa a .
173 If
174 .Pf * Fa a
175 is
176 .Dv NULL ,
177 a new
178 .Vt BIGNUM
179 is created.
180 If
181 .Fa a
182 is
183 .Dv NULL ,
184 it only computes the number's length in hexadecimal digits.
185 A "negative zero" is converted to zero.
186 .Fn BN_dec2bn
187 is the same using the decimal system.
188 .Fn BN_asc2bn
189 infers the number base from an optional prefix.
190 If
191 .Fa str
192 starts with
193 .Qq 0x
194 or
195 .Qq 0X ,
196 it calls
197 .Fn BN_hex2bn ,
198 otherwise
199 .Fn BN_dec2bn .
200 If the number is negative, the minus sign can be given before or
201 after the prefix.
202 .Pp
203 .Fn BN_print
204 and
205 .Fn BN_print_fp
206 write the hexadecimal encoding of
207 .Fa a ,
208 with a leading minus sign for negative numbers, to the
209 .Vt BIO
210 or
211 .Vt FILE
212 .Fa fp .
213 .Pp
214 .Fn BN_bn2mpi
215 and
216 .Fn BN_mpi2bn
217 convert
218 .Vt BIGNUM Ns s
219 from and to a format that consists of the number's length in bytes
220 represented as a 4-byte big-endian number, and the number itself in
221 big-endian format, where the most significant bit signals a negative
222 number (the representation of numbers with the MSB set is prefixed with
223 a NUL byte).
224 .Pp
225 .Fn BN_bn2mpi
226 stores the representation of
227 .Fa a
228 at
229 .Fa to ,
230 where
231 .Fa to
232 must be large enough to hold the result.
233 The size can be determined by calling
234 .Fn BN_bn2mpi a NULL .
235 .Pp
236 .Fn BN_mpi2bn
237 converts the
238 .Fa len
239 bytes long representation at
240 .Fa s
241 to a
242 .Vt BIGNUM
243 and stores it at
244 .Fa ret ,
245 or in a newly allocated
246 .Vt BIGNUM
247 if
248 .Fa ret
249 is
250 .Dv NULL .
251 .Sh RETURN VALUES
252 .Fn BN_bn2bin
253 returns the length of the big-endian number placed at
254 .Fa to .
255 .Fn BN_bin2bn
256 returns the
257 .Vt BIGNUM ,
258 or
259 .Dv NULL
260 on error.
261 .Pp
262 .Fn BN_bn2hex
263 and
264 .Fn BN_bn2dec
265 return a NUL-terminated string, or
266 .Dv NULL
267 on error.
268 .Fn BN_hex2bn
269 and
270 .Fn BN_dec2bn
271 return the number's length in hexadecimal or decimal digits
272 or 0 on error, in which case no new
273 .Vt BIGNUM
274 is created.
275 .Fn BN_asc2bn
276 returns 1 on success or 0 on error, in which case no new
277 .Vt BIGNUM
278 is created.
279 .Pp
280 .Fn BN_print_fp
281 and
282 .Fn BN_print
283 return 1 on success, 0 on write errors.
284 .Pp
285 .Fn BN_bn2mpi
286 returns the length of the representation.
287 .Fn BN_mpi2bn
288 returns the
289 .Vt BIGNUM ,
290 or
291 .Dv NULL
292 on error.
293 .Pp
294 The error codes can be obtained by
295 .Xr ERR_get_error 3 .
296 .Sh SEE ALSO
297 .Xr BN_new 3 ,
298 .Xr BN_num_bytes 3 ,
299 .Xr BN_zero 3 ,
300 .Xr ERR_get_error 3
301 .Sh HISTORY
302 .Fn BN_bn2bin ,
303 .Fn BN_bin2bn ,
304 .Fn BN_print ,
305 and
306 .Fn BN_print_fp
307 appeared before SSLeay 0.8.
308 .Fn BN_bn2hex ,
309 .Fn BN_bn2dec ,
310 .Fn BN_hex2bn ,
311 .Fn BN_dec2bn ,
312 .Fn BN_bn2mpi ,
313 and
314 .Fn BN_mpi2bn
315 first appeared in SSLeay 0.9.0.
316 All these functions have been available since
317 .Ox 2.4 .
318 .Pp
319 .Fn BN_asc2bin
320 first appeared in OpenSSL 1.0.0 and has been available since
321 .Ox 4.9 .