1.\" $OpenBSD: ASN1_STRING_length.3,v 1.30 2024/12/27 15:30:17 schwarze Exp $ 2.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2018, 2019, 2021 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson. 22.\" Copyright (c) 2002, 2006, 2013, 2015, 2016, 2017 The OpenSSL Project. 23.\" 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: December 27 2024 $ 70.Dt ASN1_STRING_LENGTH 3 71.Os 72.Sh NAME 73.Nm ASN1_STRING_cmp , 74.Nm ASN1_OCTET_STRING_cmp , 75.Nm ASN1_STRING_data , 76.Nm ASN1_STRING_dup , 77.Nm ASN1_OCTET_STRING_dup , 78.Nm ASN1_STRING_get0_data , 79.Nm ASN1_STRING_length , 80.Nm ASN1_STRING_length_set , 81.Nm ASN1_STRING_set0 , 82.Nm ASN1_STRING_set , 83.Nm ASN1_OCTET_STRING_set , 84.Nm ASN1_STRING_copy , 85.Nm ASN1_STRING_to_UTF8 , 86.Nm ASN1_STRING_type 87.\" deprecated aliases, intentionally undocumented: 88.\" M_ASN1_STRING_data, M_ASN1_STRING_length 89.Nd ASN1_STRING utility functions 90.Sh SYNOPSIS 91.In openssl/asn1.h 92.Ft int 93.Fo ASN1_STRING_cmp 94.Fa "const ASN1_STRING *a" 95.Fa "const ASN1_STRING *b" 96.Fc 97.Ft int 98.Fo ASN1_OCTET_STRING_cmp 99.Fa "const ASN1_OCTET_STRING *a" 100.Fa "const ASN1_OCTET_STRING *b" 101.Fc 102.Ft unsigned char * 103.Fo ASN1_STRING_data 104.Fa "ASN1_STRING *x" 105.Fc 106.Ft ASN1_STRING * 107.Fo ASN1_STRING_dup 108.Fa "const ASN1_STRING *a" 109.Fc 110.Ft ASN1_OCTET_STRING * 111.Fo ASN1_OCTET_STRING_dup 112.Fa "const ASN1_OCTET_STRING *a" 113.Fc 114.Ft const unsigned char * 115.Fo ASN1_STRING_get0_data 116.Fa "const ASN1_STRING *x" 117.Fc 118.Ft int 119.Fo ASN1_STRING_length 120.Fa "const ASN1_STRING *x" 121.Fc 122.Ft void 123.Fo ASN1_STRING_length_set 124.Fa "ASN1_STRING *x" 125.Fa "int len" 126.Fc 127.Ft void 128.Fo ASN1_STRING_set0 129.Fa "ASN1_STRING *str" 130.Fa "void *data" 131.Fa "int len" 132.Fc 133.Ft int 134.Fo ASN1_STRING_set 135.Fa "ASN1_STRING *str" 136.Fa "const void *data" 137.Fa "int len" 138.Fc 139.Ft int 140.Fo ASN1_OCTET_STRING_set 141.Fa "ASN1_OCTET_STRING *str" 142.Fa "const unsigned char *data" 143.Fa "int len" 144.Fc 145.Ft int 146.Fo ASN1_STRING_copy 147.Fa "ASN1_STRING *dst" 148.Fa "const ASN1_STRING *src" 149.Fc 150.Ft int 151.Fo ASN1_STRING_to_UTF8 152.Fa "unsigned char **out" 153.Fa "const ASN1_STRING *in" 154.Fc 155.Ft int 156.Fo ASN1_STRING_type 157.Fa "const ASN1_STRING *x" 158.Fc 159.Sh DESCRIPTION 160These functions manipulate 161.Vt ASN1_STRING 162structures. 163.Pp 164.Fn ASN1_STRING_cmp 165compares the type, the length, and the content of 166.Fa a 167and 168.Fa b . 169.Pp 170.Fn ASN1_OCTET_STRING_cmp 171does exactly the same as 172.Fn ASN1_STRING_cmp 173without providing any type safety. 174.Pp 175.Fn ASN1_STRING_data 176is similar to 177.Fn ASN1_STRING_get0_data 178except that the returned value is not constant. 179This function is deprecated. 180Applications should use 181.Fn ASN1_STRING_get0_data 182instead. 183.Pp 184.Fn ASN1_STRING_dup 185allocates a new 186.Vt ASN1_STRING 187object and copies the type, length, data, and flags from 188.Fa a 189into it. 190.Pp 191.Fn ASN1_OCTET_STRING_dup 192does exactly the same as 193.Fn ASN1_STRING_dup 194without providing any type safety. 195.Pp 196.Fn ASN1_STRING_get0_data 197returns an internal pointer to the data of 198.Fa x . 199It should not be freed or modified in any way. 200.Pp 201.Fn ASN1_STRING_length 202returns the length attribute of 203.Fa x , 204measured in bytes. 205.Pp 206.Fn ASN1_STRING_length_set 207sets the length attribute of 208.Fa x 209to 210.Fa len . 211It may put 212.Fa x 213into an inconsistent internal state. 214.Pp 215.Fn ASN1_STRING_set0 216frees any data stored in 217.Fa str , 218sets the length attribute to 219.Fa len 220bytes, and sets the data attribute to 221.Fa data , 222transferring ownership, without doing any validation. 223.Pp 224.Fn ASN1_STRING_set 225sets the length attribute of 226.Fa str 227to 228.Fa len 229and copies that number of bytes from 230.Fa data 231into 232.Fa str , 233overwriting any previous data. 234If 235.Fa len 236is \-1, then 237.Fn strlen data 238is used instead of 239.Fa len . 240If 241.Fa data 242is 243.Dv NULL , 244the content of 245.Fa str 246remains uninitialized; that is not considered an error unless 247.Fa len 248is negative. 249.Pp 250.Fn ASN1_OCTET_STRING_set 251does exactly the same as 252.Fn ASN1_STRING_set 253without providing any type safety. 254.Pp 255.Fn ASN1_STRING_copy 256copies the length and data of 257.Fa src 258into 259.Fa dst 260using 261.Fn ASN1_STRING_set 262and changes the type and flags of 263.Fa dst 264to match the type and flags of 265.Fa src . 266.Pp 267.Fn ASN1_STRING_to_UTF8 268converts the string 269.Fa in 270to UTF-8 format. 271The converted data is copied into a newly allocated buffer 272.Pf * Fa out . 273The buffer 274.Pf * Fa out 275should be freed using 276.Xr free 3 . 277.Pp 278.Fn ASN1_STRING_type 279returns the type of 280.Fa x . 281If the bit 282.Dv V_ASN1_NEG 283is set in the return value, 284.Fa x 285is an ASN.1 INTEGER or ENUMERATED object with a negative value. 286.Pp 287Almost all ASN.1 types are represented as 288.Vt ASN1_STRING 289structures. 290Other types such as 291.Vt ASN1_OCTET_STRING 292are simply typedefed to 293.Vt ASN1_STRING 294and the functions call the 295.Vt ASN1_STRING 296equivalents. 297.Vt ASN1_STRING 298is also used for some CHOICE types which consist entirely of primitive 299string types such as 300.Vt DirectoryString 301and 302.Vt Time . 303.Pp 304These functions should 305.Em not 306be used to examine or modify 307.Vt ASN1_INTEGER 308or 309.Vt ASN1_ENUMERATED 310types: the relevant INTEGER or ENUMERATED utility functions should 311be used instead. 312.Pp 313In general it cannot be assumed that the data returned by 314.Fn ASN1_STRING_get0_data 315and 316.Fn ASN1_STRING_data 317is NUL terminated, and it may contain embedded NUL characters. 318The format of the data depends on the string type: 319for example for an 320.Vt IA5String 321the data contains ASCII characters, for a 322.Vt BMPString 323two bytes per character in big endian format, and for a 324.Vt UTF8String 325UTF-8 characters. 326.Pp 327Similar care should be taken to ensure the data is in the correct format 328when calling 329.Fn ASN1_STRING_set 330or 331.Fn ASN1_STRING_set0 . 332.Sh RETURN VALUES 333.Fn ASN1_STRING_cmp 334and 335.Fn ASN1_OCTET_STRING_cmp 336return 0 if the type, the length, and the content of 337.Fa a 338and 339.Fa b 340agree, or a non-zero value otherwise. 341In contrast to 342.Xr strcmp 3 , 343the sign of the return value does not indicate lexicographical ordering. 344.Pp 345.Fn ASN1_STRING_data 346and 347.Fn ASN1_STRING_get0_data 348return an internal pointer to the data of 349.Fa x . 350.Pp 351.Fn ASN1_STRING_dup 352and 353.Fn ASN1_OCTET_STRING_dup 354return a pointer to a newly allocated 355.Vt ASN1_STRING 356structure or 357.Dv NULL 358if an error occurred. 359.Pp 360.Fn ASN1_STRING_length 361returns a number of bytes. 362.Pp 363.Fn ASN1_STRING_set , 364.Fn ASN1_OCTET_STRING_set , 365and 366.Fn ASN1_STRING_copy 367return 1 on success or 0 on failure. 368They fail if memory allocation fails. 369.Fn ASN1_STRING_set 370and 371.Fn ASN1_OCTET_STRING_set 372also fail if 373.Fa data 374is 375.Dv NULL 376and 377.Fa len 378is \-1 in the same call. 379.Fn ASN1_STRING_copy 380also fails if 381.Fa src 382is 383.Dv NULL . 384.Pp 385.Fn ASN1_STRING_to_UTF8 386returns the number of bytes in the output buffer 387.Pf * Fa out , 388or a negative number if an error occurred. 389.Pp 390.Fn ASN1_STRING_type 391returns an integer constant, for example 392.Dv V_ASN1_OCTET_STRING 393or 394.Dv V_ASN1_NEG_INTEGER . 395.Pp 396In some cases of failure of 397.Fn ASN1_STRING_dup , 398.Fn ASN1_STRING_set , 399and 400.Fn ASN1_STRING_to_UTF8 , 401the reason can be determined with 402.Xr ERR_get_error 3 . 403.Sh SEE ALSO 404.Xr a2i_ASN1_STRING 3 , 405.Xr a2i_ipadd 3 , 406.Xr ASN1_BIT_STRING_set 3 , 407.Xr ASN1_mbstring_copy 3 , 408.Xr ASN1_PRINTABLE_type 3 , 409.Xr ASN1_STRING_new 3 , 410.Xr ASN1_UNIVERSALSTRING_to_string 3 , 411.Xr s2i_ASN1_INTEGER 3 412.Sh HISTORY 413.Fn ASN1_STRING_cmp , 414.Fn ASN1_STRING_dup , 415.Fn ASN1_STRING_set , 416and 417.Fn ASN1_OCTET_STRING_set 418first appeared in SSLeay 0.6.5. 419.Fn ASN1_OCTET_STRING_cmp , 420.Fn ASN1_STRING_data , 421.Fn ASN1_OCTET_STRING_dup , 422and 423.Fn ASN1_STRING_type 424first appeared in SSLeay 0.8.0. 425.Fn ASN1_STRING_length 426first appeared in SSLeay 0.9.0. 427All these functions have been available since 428.Ox 2.4 . 429.Pp 430.Fn ASN1_STRING_length_set 431first appeared in OpenSSL 0.9.5 and has been available since 432.Ox 2.7 . 433.Pp 434.Fn ASN1_STRING_to_UTF8 435first appeared in OpenSSL 0.9.6 and has been available since 436.Ox 2.9 . 437.Pp 438.Fn ASN1_STRING_set0 439first appeared in OpenSSL 0.9.8h and has been available since 440.Ox 4.5 . 441.Pp 442.Fn ASN1_STRING_copy 443first appeared in OpenSSL 1.0.0 and has been available since 444.Ox 4.9 . 445.Pp 446.Fn ASN1_STRING_get0_data 447first appeared in OpenSSL 1.1.0 and has been available since 448.Ox 6.3 . 449.Sh BUGS 450.Fn ASN1_OCTET_STRING_cmp , 451.Fn ASN1_OCTET_STRING_dup , 452and 453.Fn ASN1_OCTET_STRING_set 454do not check whether their arguments are really of the type 455.Dv V_ASN1_OCTET_STRING . 456They may report success even if their arguments are of a wrong type. 457Consequently, even in case of success, the return value of 458.Fn ASN1_OCTET_STRING_dup 459is not guaranteed to be of the type 460.Dv V_ASN1_OCTET_STRING 461either. 462