1.\" $OpenBSD: d2i_X509_NAME.3,v 1.17 2021/12/11 17:25:10 jmc Exp $ 2.\" checked up to: 3.\" OpenSSL crypto/d2i_X509_NAME 4692340e Jun 7 15:49:08 2016 -0400 and 4.\" OpenSSL man3/X509_NAME_get0_der 99d63d46 Oct 26 13:56:48 2016 -0400 5.\" 6.\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: December 11 2021 $ 21.Dt D2I_X509_NAME 3 22.Os 23.Sh NAME 24.Nm d2i_X509_NAME , 25.Nm i2d_X509_NAME , 26.Nm X509_NAME_get0_der , 27.Nm X509_NAME_dup , 28.Nm X509_NAME_set , 29.Nm d2i_X509_NAME_ENTRY , 30.Nm i2d_X509_NAME_ENTRY , 31.Nm X509_NAME_ENTRY_dup 32.\" In the following line, "X.501" and "Name" are not typos. 33.\" The "Name" type is defined in X.501, not in X.509. 34.\" The type is called "Name" with capital "N", not "name". 35.Nd decode and encode X.501 Name objects 36.Sh SYNOPSIS 37.In openssl/x509.h 38.Ft X509_NAME * 39.Fo d2i_X509_NAME 40.Fa "X509_NAME **val_out" 41.Fa "unsigned char **der_in" 42.Fa "long length" 43.Fc 44.Ft int 45.Fo i2d_X509_NAME 46.Fa "X509_NAME *val_in" 47.Fa "unsigned char **der_out" 48.Fc 49.Ft int 50.Fo X509_NAME_get0_der 51.Fa "X509_NAME *val_in" 52.Fa "const unsigned char **der_out" 53.Fa "size_t *out_len" 54.Fc 55.Ft X509_NAME * 56.Fo X509_NAME_dup 57.Fa "X509_NAME *val_in" 58.Fc 59.Ft int 60.Fo X509_NAME_set 61.Fa "X509_NAME **val_out" 62.Fa "X509_NAME *val_in" 63.Fc 64.Ft X509_NAME_ENTRY * 65.Fo d2i_X509_NAME_ENTRY 66.Fa "X509_NAME_ENTRY **val_out" 67.Fa "unsigned char **der_in" 68.Fa "long length" 69.Fc 70.Ft int 71.Fo i2d_X509_NAME_ENTRY 72.Fa "X509_NAME_ENTRY *val_in" 73.Fa "unsigned char **der_out" 74.Fc 75.Ft X509_NAME_ENTRY * 76.Fo X509_NAME_ENTRY_dup 77.Fa "X509_NAME_ENTRY *val_in" 78.Fc 79.Sh DESCRIPTION 80These functions decode and encode X.501 81.Vt Name 82objects using DER format. 83For details about the semantics, examples, caveats, and bugs, see 84.Xr ASN1_item_d2i 3 . 85.Pp 86.Fn d2i_X509_NAME 87and 88.Fn i2d_X509_NAME 89decode and encode an ASN.1 90.Vt Name 91structure defined in RFC 5280 section 4.1.2.4. 92.Pp 93.Fn X509_NAME_get0_der 94is a variant of 95.Fn i2d_X509_NAME 96that does not copy the encoded output but instead returns a pointer 97to the internally cached DER-encoded version of the name. 98Also, it does not return the length of the output in bytes, 99but instead stores it in 100.Fa out_len . 101If the cached encoded form happens to be out of date, both functions 102update it before copying it or returning a pointer to it. 103.Pp 104.Fn X509_NAME_dup 105copies 106.Fa val_in 107by calling 108.Fn i2d_X509_NAME 109and 110.Fn d2i_X509_NAME . 111.Pp 112.Fn X509_NAME_set 113makes sure that 114.Pf * Fa val_out 115contains the same data as 116.Fa val_in 117after the call, except that it fails if 118.Fa val_in 119is 120.Dv NULL . 121If 122.Pf * Fa val_out 123is the same pointer as 124.Fa val_in , 125the function succeeds without changing anything. 126Otherwise, it copies 127.Fa val_in 128using 129.Fn X509_NAME_dup , 130and in case of success, it frees 131.Pf * Fa val_out 132and sets it to a pointer to the new object. 133When the function fails, it never changes anything. 134In any case, 135.Fa val_in 136remains valid and may or may not be the same pointer as 137.Pf * Fa val_out 138after the call. 139.Pp 140.Fn d2i_X509_NAME_ENTRY 141and 142.Fn i2d_X509_NAME_ENTRY 143decode and encode an ASN.1 144.Vt RelativeDistinguishedName 145structure defined in RFC 5280 section 4.1.2.4. 146.Pp 147.Fn X509_NAME_ENTRY_dup 148copies 149.Fa val_in 150by calling 151.Fn i2d_X509_NAME_ENTRY 152and 153.Fn d2i_X509_NAME_ENTRY . 154.Sh RETURN VALUES 155.Fn d2i_X509_NAME 156and 157.Fn X509_NAME_dup 158return the new 159.Vt X509_NAME 160object or 161.Dv NULL 162if an error occurs. 163.Pp 164.Fn X509_NAME_set 165and 166.Fn X509_NAME_get0_der 167return 1 on success or 0 if an error occurs. 168.Pp 169.Fn d2i_X509_NAME_ENTRY 170and 171.Fn X509_NAME_ENTRY_dup 172return the new 173.Vt X509_NAME_ENTRY 174object or 175.Dv NULL 176if an error occurs. 177.Pp 178.Fn i2d_X509_NAME 179and 180.Fn i2d_X509_NAME_ENTRY 181return the number of bytes successfully encoded or a negative value 182if an error occurs. 183.Sh SEE ALSO 184.Xr ASN1_item_d2i 3 , 185.Xr X509_NAME_ENTRY_new 3 , 186.Xr X509_NAME_new 3 , 187.Xr X509_NAME_print_ex 3 188.Sh STANDARDS 189RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 190Certificate Revocation List (CRL) Profile 191.Pp 192ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 193Information technology - ASN.1 encoding rules: 194Specification of Basic Encoding Rules (BER), Canonical Encoding 195Rules (CER) and Distinguished Encoding Rules (DER). 196.Sh HISTORY 197.Fn X509_NAME_dup 198first appeared in SSLeay 0.4.4. 199.Fn d2i_X509_NAME , 200.Fn i2d_X509_NAME , 201.Fn d2i_X509_NAME_ENTRY , 202.Fn i2d_X509_NAME_ENTRY , 203and 204.Fn X509_NAME_ENTRY_dup 205first appeared in SSLeay 0.5.1. 206.Fn X509_NAME_set 207first appeared in SSLeay 0.8.0. 208These functions have been available since 209.Ox 2.4 . 210.Pp 211.Fn X509_NAME_get0_der 212first appeared in OpenSSL 1.1.0 and has been available since 213.Ox 6.3 . 214