1.\" $OpenBSD: d2i_X509_NAME.3,v 1.14 2018/03/27 17:35:50 schwarze 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, 2017, 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: March 27 2018 $ 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_hash , 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 unsigned long 60.Fo X509_NAME_hash 61.Fa "X509_NAME *val_in" 62.Fc 63.Ft X509_NAME_ENTRY * 64.Fo d2i_X509_NAME_ENTRY 65.Fa "X509_NAME_ENTRY **val_out" 66.Fa "unsigned char **der_in" 67.Fa "long length" 68.Fc 69.Ft int 70.Fo i2d_X509_NAME_ENTRY 71.Fa "X509_NAME_ENTRY *val_in" 72.Fa "unsigned char **der_out" 73.Fc 74.Ft X509_NAME_ENTRY * 75.Fo X509_NAME_ENTRY_dup 76.Fa "X509_NAME_ENTRY *val_in" 77.Fc 78.Sh DESCRIPTION 79These functions decode and encode X.501 80.Vt Name 81objects using DER format. 82For details about the semantics, examples, caveats, and bugs, see 83.Xr ASN1_item_d2i 3 . 84.Pp 85.Fn d2i_X509_NAME 86and 87.Fn i2d_X509_NAME 88decode and encode an ASN.1 89.Vt Name 90structure defined in RFC 5280 section 4.1.2.4. 91.Pp 92.Fn X509_NAME_get0_der 93is a variant of 94.Fn i2d_X509_NAME 95that does not copy the encoded output but instead returns a pointer 96to the internally cached DER-encoded version of the name. 97Also, it does not return the length of the output in bytes, 98but instead stores it in 99.Fa out_len . 100If the cached encoded form happens to be out of date, both functions 101update it before copying it or returning a pointer to it. 102.Pp 103.Fn X509_NAME_dup 104copies 105.Fa val_in 106by calling 107.Fn i2d_X509_NAME 108and 109.Fn d2i_X509_NAME . 110.Pp 111.Fn X509_NAME_hash 112calculates a 113.Xr SHA1 3 114hash of the DER-encoded form of the name 115.Pf * Fa val_in . 116It is for example used by 117.Xr X509_LOOKUP_hash_dir 3 118to locate certificate files in the file system. 119.Pp 120.Fn d2i_X509_NAME_ENTRY 121and 122.Fn i2d_X509_NAME_ENTRY 123decode and encode an ASN.1 124.Vt RelativeDistinguishedName 125structure defined in RFC 5280 section 4.1.2.4. 126.Pp 127.Fn X509_NAME_ENTRY_dup 128copies 129.Fa val_in 130by calling 131.Fn i2d_X509_NAME_ENTRY 132and 133.Fn d2i_X509_NAME_ENTRY . 134.Sh RETURN VALUES 135.Fn d2i_X509_NAME 136and 137.Fn X509_NAME_dup 138return the new 139.Vt X509_NAME 140object or 141.Dv NULL 142if an error occurs. 143.Pp 144.Fn X509_NAME_get0_der 145returns 1 on success or 0 if an error occurs. 146.Pp 147.Fn X509_NAME_hash 148returns the hash value or 0 if an error occurs. 149.Pp 150.Fn d2i_X509_NAME_ENTRY 151and 152.Fn X509_NAME_ENTRY_dup 153return the new 154.Vt X509_NAME_ENTRY 155object or 156.Dv NULL 157if an error occurs. 158.Pp 159.Fn i2d_X509_NAME 160and 161.Fn i2d_X509_NAME_ENTRY 162return the number of bytes successfully encoded or a negative value 163if an error occurs. 164.Sh SEE ALSO 165.Xr ASN1_item_d2i 3 , 166.Xr X509_NAME_ENTRY_new 3 , 167.Xr X509_NAME_new 3 , 168.Xr X509_NAME_print_ex 3 169.Sh STANDARDS 170RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 171Certificate Revocation List (CRL) Profile 172.Pp 173ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 174Information technology - ASN.1 encoding rules: 175Specification of Basic Encoding Rules (BER), Canonical Encoding 176Rules (CER) and Distinguished Encoding Rules (DER). 177.Sh HISTORY 178.Fn X509_NAME_dup 179first appeared in SSLeay 0.4.4. 180.Fn d2i_X509_NAME , 181.Fn i2d_X509_NAME , 182.Fn d2i_X509_NAME_ENTRY , 183.Fn i2d_X509_NAME_ENTRY , 184and 185.Fn X509_NAME_ENTRY_dup 186first appeared in SSLeay 0.5.1. 187.Fn X509_NAME_hash 188first appeared in SSLeay 0.8.0. 189These functions have been available since 190.Ox 2.4 . 191.Pp 192.Fn X509_NAME_get0_der 193first appeared in OpenSSL 1.1.0 and has been available since 194.Ox 6.3 . 195