1.\" $OpenBSD: ASN1_item_d2i.3,v 1.18 2023/05/01 07:37:45 tb Exp $ 2.\" selective merge up to: 3.\" OpenSSL doc/man3/d2i_X509.pod 256989ce Jun 19 15:00:32 2020 +0200 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2016, 2021 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2002, 2003, 2015 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: May 1 2023 $ 70.Dt ASN1_ITEM_D2I 3 71.Os 72.Sh NAME 73.Nm ASN1_item_d2i , 74.Nm ASN1_item_d2i_bio , 75.Nm ASN1_item_d2i_fp , 76.Nm d2i_ASN1_TYPE , 77.Nm ASN1_item_i2d , 78.Nm ASN1_item_i2d_bio , 79.Nm ASN1_item_i2d_fp , 80.Nm i2d_ASN1_TYPE , 81.Nm ASN1_item_dup , 82.Nm ASN1_item_print 83.Nd decode and encode ASN.1 objects 84.Sh SYNOPSIS 85.In openssl/asn1.h 86.Ft ASN1_VALUE * 87.Fo ASN1_item_d2i 88.Fa "ASN1_VALUE **val_out" 89.Fa "const unsigned char **der_in" 90.Fa "long length" 91.Fa "const ASN1_ITEM *it" 92.Fc 93.Ft void * 94.Fo ASN1_item_d2i_bio 95.Fa "const ASN1_ITEM *it" 96.Fa "BIO *in_bio" 97.Fa "void *val_out" 98.Fc 99.Ft void * 100.Fo ASN1_item_d2i_fp 101.Fa "const ASN1_ITEM *it" 102.Fa "FILE *in_fp" 103.Fa "void *val_out" 104.Fc 105.Ft ASN1_TYPE * 106.Fo d2i_ASN1_TYPE 107.Fa "ASN1_TYPE **val_out" 108.Fa "const unsigned char **der_in" 109.Fa "long length" 110.Fc 111.Ft int 112.Fo ASN1_item_i2d 113.Fa "ASN1_VALUE *val_in" 114.Fa "unsigned char **der_out" 115.Fa "const ASN1_ITEM *it" 116.Fc 117.Ft int 118.Fo ASN1_item_i2d_bio 119.Fa "const ASN1_ITEM *it" 120.Fa "BIO *out_bio" 121.Fa "void *val_in" 122.Fc 123.Ft int 124.Fo ASN1_item_i2d_fp 125.Fa "const ASN1_ITEM *it" 126.Fa "FILE *out_fp" 127.Fa "void *val_in" 128.Fc 129.Ft int 130.Fo i2d_ASN1_TYPE 131.Fa "ASN1_TYPE *val_in" 132.Fa "unsigned char **der_out" 133.Fc 134.Ft void * 135.Fo ASN1_item_dup 136.Fa "const ASN1_ITEM *it" 137.Fa "void *val_in" 138.Fc 139.Ft int 140.Fo ASN1_item_print 141.Fa "BIO *out_bio" 142.Fa "ASN1_VALUE *val_in" 143.Fa "int indent" 144.Fa "const ASN1_ITEM *it" 145.Fa "const ASN1_PCTX *pctx" 146.Fc 147.Sh DESCRIPTION 148These functions convert ASN.1 values from their BER encoding to 149internal C structures 150.Pq Dq d2i 151and vice versa 152.Pq Dq i2d . 153Unlike the C structures which contain pointers to sub-objects, BER 154is a serialized encoding, suitable for transfer over the network 155and for storage in a file. 156.Pp 157.Fn ASN1_item_d2i 158interprets 159.Pf * Fa der_in 160as a DER- or BER-encoded byte array and decodes one value of type 161.Fa it 162represented by up to 163.Fa length 164bytes. 165If successful, 166.Pf * Fa der_in 167is advanced to the byte following the parsed data. 168.Pp 169If decoding succeeds and 170.Fa val_out 171or 172.Pf * Fa val_out 173is 174.Dv NULL , 175a new object is allocated. 176.Pp 177If decoding succeeds and 178.Pf * Fa val_out 179is not 180.Dv NULL , 181it is assumed to point to a valid populated object and an attempt 182is made to reuse it. 183It must not be an empty structure such as one returned by 184.Xr ASN1_item_new 3 185or by one of the various type-specific 186.Fn *_new 187functions. 188This 189.Dq reuse 190capability is present for backward compatibility, but its use is 191strongly discouraged; see the 192.Sx BUGS 193section below. 194.Pp 195.Fn ASN1_item_d2i_bio 196and 197.Fn ASN1_item_d2i_fp 198are similar to 199.Fn ASN1_item_d2i 200except that they read from a 201.Vt BIO 202or 203.Vt FILE , 204respectively. 205.Pp 206.Fn d2i_ASN1_TYPE 207is similar to 208.Fn ASN1_item_d2i 209except that it does not require a desired type to be specified by 210the user, but instead returns an 211.Vt ASN1_TYPE 212wrapper object containing both the type and the value found in the input. 213.Pp 214.Fn ASN1_item_i2d 215encodes the object pointed to by 216.Fa val_in 217into DER format. 218.Pp 219If 220.Pf * Fa der_out 221is not 222.Dv NULL , 223it writes the DER-encoded data to the buffer at 224.Pf * Fa der_out 225and increments it to point after the data just written. 226In this case, it is the responsibility of the user to make sure 227that the buffer pointed to by 228.Pf * Fa der_out 229is long enough, such that no buffer overflow can occur. 230.Pp 231If 232.Pf * Fa der_out 233is 234.Dv NULL , 235memory is allocated for a buffer, and 236.Pf * Fa der_out 237is not incremented, but points to the start of the data just written. 238.Pp 239If 240.Fa der_out 241is 242.Dv NULL , 243the encoded bytes are not written anywhere but discarded. 244For 245.Fa val_in 246objects of variable encoding size, this is sometimes used to first 247find the number of bytes that will be written. 248Then, a sufficient amount of memory is allocated before calling 249.Fn ASN1_item_i2d 250again. 251This explicit double-call technique is often not needed because the 252auto-allocation technique described in the previous paragraph can 253be used. 254.Pp 255.Fn ASN1_item_i2d_bio 256and 257.Fn ASN1_item_i2d_fp 258are similar to 259.Fn ASN1_item_i2d 260except that they write to a 261.Vt BIO 262or 263.Vt FILE , 264respectively. 265.Pp 266.Fn i2d_ASN1_TYPE 267is similar to 268.Fn ASN1_item_i2d 269except that the type and the value are not provided separately, 270but in the form of a single 271.Vt ASN1_TYPE 272object. 273.Pp 274.Fn ASN1_item_dup 275creates a deep copy of 276.Fa val_in 277by calling 278.Fn ASN1_item_i2d 279and 280.Fn ASN1_item_d2i . 281.Sh RETURN VALUES 282If successful, 283.Fn ASN1_item_d2i , 284.Fn ASN1_item_d2i_bio , 285.Fn ASN1_item_d2i_fp , 286and 287.Fn d2i_ASN1_TYPE 288return a pointer to the decoded ASN.1 value. 289In addition, if 290.Fa val_out 291is not 292.Dv NULL , 293the pointer is also written to 294.Pf * Fa val_out . 295If an error occurs, 296.Dv NULL 297is returned. 298.Pp 299.Fn ASN1_item_i2d 300and 301.Fn i2d_ASN1_TYPE 302return the number of bytes written 303or a negative value if an error occurs. 304.Pp 305.Fn ASN1_item_i2d_bio 306and 307.Fn ASN1_item_i2d_fp 308return 1 for success or 0 for failure. 309.Pp 310.Fn ASN1_item_dup 311returns the new 312.Vt ASN1_VALUE 313object or 314.Dv NULL 315if an error occurs. 316.Sh EXAMPLES 317Many type-specific wrapper functions exist. 318Using those wrappers is recommended in application code 319because it restores part of the type safety that the low-level 320interfaces using 321.Vt ASN1_VALUE 322lack. 323.Pp 324For example, to allocate a buffer and write the DER encoding of an 325.Vt X509 326object into it: 327.Bd -literal -offset indent 328X509 *x; 329unsigned char *buf; 330int len; 331 332buf = NULL; 333len = i2d_X509(x, &buf); 334if (len < 0) 335 /* error */ 336.Ed 337.Pp 338Attempt to decode a buffer: 339.Bd -literal -offset indent 340X509 *x; 341unsigned char *buf; 342const unsigned char *p; 343int len; 344 345/* Set up buf and len to point to the input buffer. */ 346p = buf; 347x = d2i_X509(NULL, &p, len); 348if (x == NULL) 349 /* error */ 350.Ed 351.Pp 352Equivalent technique: 353.Bd -literal -offset indent 354X509 *x; 355unsigned char *buf; 356const unsigned char *p; 357int len; 358 359/* Set up buf and len to point to the input buffer. */ 360p = buf; 361x = NULL; 362 363if (d2i_X509(&x, &p, len) == NULL) 364 /* error */ 365.Ed 366.Sh SEE ALSO 367.Xr ASN1_get_object 3 , 368.Xr ASN1_item_digest 3 , 369.Xr ASN1_item_new 3 , 370.Xr ASN1_item_pack 3 , 371.Xr ASN1_item_sign 3 , 372.Xr ASN1_item_verify 3 , 373.Xr ASN1_TYPE_new 3 374.Sh HISTORY 375.Fn d2i_ASN1_TYPE 376and 377.Fn i2d_ASN1_TYPE 378first appeared in SSLeay 0.5.1 and have been available since 379.Ox 2.4 . 380.Pp 381.Fn ASN1_item_d2i , 382.Fn ASN1_item_d2i_bio , 383.Fn ASN1_item_d2i_fp , 384.Fn ASN1_item_i2d , 385.Fn ASN1_item_i2d_bio , 386.Fn ASN1_item_i2d_fp , 387and 388.Fn ASN1_item_dup 389first appeared in OpenSSL 0.9.7 and have been available since 390.Ox 3.2 . 391.Pp 392.Fn ASN1_item_print 393first appeared in OpenSSL 1.0.0 and has been available since 394.Ox 4.9 . 395.Sh CAVEATS 396If the type described by 397.Fa it 398fails to match the true type of 399.Fa val_in 400or 401.Pf * Fa val_out , 402buffer overflows and segmentation faults are likely to occur. 403For more details about why the type 404.Vt ASN1_VALUE 405constitutes dangerous user interface design, see 406.Xr ASN1_item_new 3 . 407.Pp 408The encoded data is in binary form and may contain embedded NUL bytes. 409Functions such as 410.Xr strlen 3 411will not return the correct length of the encoded data. 412.Pp 413While the way that 414.Pf * Fa der_in 415and 416.Pf * Fa der_out 417are incremented after the operation supports the typical usage 418patterns of reading or writing one object after another, this 419behaviour can trap the unwary. 420.Pp 421Using a temporary pointer into the buffer is mandatory. 422A common mistake is to attempt to use a buffer directly as follows: 423.Bd -literal -offset indent 424X509 *x; 425unsigned char *buf; 426int len; 427 428len = i2d_X509(x, NULL); 429buf = malloc(len); 430i2d_X509(x, &buf); 431/* do something with buf[] */ 432free(buf); 433.Ed 434.Pp 435This code will result in 436.Va buf 437apparently containing garbage because it was incremented during 438.Fn i2d_X509 439to point after the data just written. 440Also 441.Va buf 442will no longer contain the pointer allocated by 443.Xr malloc 3 444and the subsequent call to 445.Xr free 3 446is likely to crash. 447.Pp 448Another trap to avoid is misuse of the 449.Fa val_out 450argument: 451.Bd -literal -offset indent 452X509 *x; 453 454if (d2i_X509(&x, &p, len) == NULL) 455 /* error */ 456.Ed 457.Pp 458This will probably crash somewhere in 459.Fn d2i_X509 460because 461.Va x 462is uninitialized and an attempt will be made to interpret its invalid 463content as an 464.Vt X509 465object, typically causing a segmentation violation. 466If 467.Va x 468is set to 469.Dv NULL 470first, then this will not happen. 471.Sh BUGS 472If the 473.Dq reuse 474capability is used, a valid object is passed in via 475.Pf * Fa val_out , 476and an error occurs, then the object is not freed and may be left 477in an invalid or inconsistent state. 478.Pp 479In some versions of OpenSSL, the 480.Dq reuse 481behaviour is broken such that some parts of the reused object may 482persist if they are not present in the new one. 483.Pp 484In many versions of OpenSSL, 485.Fn ASN1_item_i2d 486will not return an error if mandatory fields are not initialized 487due to a programming error. 488In that case, the encoded structure may contain invalid data and 489some fields may be missing entirely, such that trying to parse it 490with 491.Fn ASN1_item_d2i 492may fail. 493