1.\" $OpenBSD: d2i_X509.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $ 2.\" OpenSSL 94480b57 Sep 12 23:34:41 2009 +0000 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2016 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 <steve@openssl.org>. 22.\" Copyright (c) 2002, 2003, 2005, 2009, 2016 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: March 27 2018 $ 70.Dt D2I_X509 3 71.Os 72.Sh NAME 73.Nm d2i_X509 , 74.Nm i2d_X509 , 75.Nm d2i_X509_bio , 76.Nm d2i_X509_fp , 77.Nm i2d_X509_bio , 78.Nm i2d_X509_fp , 79.Nm d2i_X509_AUX , 80.Nm i2d_X509_AUX , 81.Nm d2i_X509_CERT_AUX , 82.Nm i2d_X509_CERT_AUX , 83.Nm d2i_X509_CINF , 84.Nm i2d_X509_CINF , 85.Nm d2i_X509_VAL , 86.Nm i2d_X509_VAL 87.Nd decode and encode X.509 certificates 88.Sh SYNOPSIS 89.In openssl/x509.h 90.Ft X509 * 91.Fo d2i_X509 92.Fa "X509 **val_out" 93.Fa "const unsigned char **der_in" 94.Fa "long length" 95.Fc 96.Ft int 97.Fo i2d_X509 98.Fa "X509 *val_in" 99.Fa "unsigned char **der_out" 100.Fc 101.Ft X509 * 102.Fo d2i_X509_bio 103.Fa "BIO *in_bio" 104.Fa "X509 **val_out" 105.Fc 106.Ft X509 * 107.Fo d2i_X509_fp 108.Fa "FILE *in_fp" 109.Fa "X509 **val_out" 110.Fc 111.Ft int 112.Fo i2d_X509_bio 113.Fa "BIO *out_bio" 114.Fa "X509 *val_in" 115.Fc 116.Ft int 117.Fo i2d_X509_fp 118.Fa "FILE *out_fp" 119.Fa "X509 *val_in" 120.Fc 121.Ft X509 * 122.Fo d2i_X509_AUX 123.Fa "X509 **val_out" 124.Fa "const unsigned char **der_in" 125.Fa "long length" 126.Fc 127.Ft int 128.Fo i2d_X509_AUX 129.Fa "X509 *val_in" 130.Fa "unsigned char **der_out" 131.Fc 132.Ft X509_CERT_AUX * 133.Fo d2i_X509_CERT_AUX 134.Fa "X509_CERT_AUX **val_out" 135.Fa "const unsigned char **der_in" 136.Fa "long length" 137.Fc 138.Ft int 139.Fo i2d_X509_CERT_AUX 140.Fa "X509_CERT_AUX *val_in" 141.Fa "unsigned char **der_out" 142.Fc 143.Ft X509_CINF * 144.Fo d2i_X509_CINF 145.Fa "X509_CINF **val_out" 146.Fa "const unsigned char **der_in" 147.Fa "long length" 148.Fc 149.Ft int 150.Fo i2d_X509_CINF 151.Fa "X509_CINF *val_in" 152.Fa "unsigned char **der_out" 153.Fc 154.Ft X509_VAL * 155.Fo d2i_X509_VAL 156.Fa "X509_VAL **val_out" 157.Fa "const unsigned char **der_in" 158.Fa "long length" 159.Fc 160.Ft int 161.Fo i2d_X509_VAL 162.Fa "X509_VAL *val_in" 163.Fa "unsigned char **der_out" 164.Fc 165.Sh DESCRIPTION 166These functions decode and encode X.509 certificates 167and some of their substructures. 168For details about the semantics, examples, caveats, and bugs, see 169.Xr ASN1_item_d2i 3 . 170.Pp 171.Fn d2i_X509 172and 173.Fn i2d_X509 174decode and encode an ASN.1 175.Vt Certificate 176structure defined in RFC 5280 section 4.1. 177.Pp 178.Fn d2i_X509_bio , 179.Fn d2i_X509_fp , 180.Fn i2d_X509_bio , 181and 182.Fn i2d_X509_fp 183are similar except that they decode or encode using a 184.Vt BIO 185or 186.Vt FILE 187pointer. 188.Pp 189.Fn d2i_X509_AUX 190is similar to 191.Fn d2i_X509 , 192but the input is expected to consist of an X.509 certificate followed 193by auxiliary trust information. 194This is used by the PEM routines to read TRUSTED CERTIFICATE objects. 195This function should not be called on untrusted input. 196.Pp 197.Fn i2d_X509_AUX 198is similar to 199.Fn i2d_X509 , 200but the encoded output contains both the certificate and any auxiliary 201trust information. 202This is used by the PEM routines to write TRUSTED CERTIFICATE objects. 203Note that this is a non-standard OpenSSL-specific data format. 204.Pp 205.Fn d2i_X509_CERT_AUX 206and 207.Fn i2d_X509_CERT_AUX 208decode and encode optional non-standard auxiliary data appended to 209a certificate, for example friendly alias names and trust data. 210.Pp 211.Fn d2i_X509_CINF 212and 213.Fn i2d_X509_CINF 214decode and encode an ASN.1 215.Vt TBSCertificate 216structure defined in RFC 5280 section 4.1. 217.Pp 218.Fn d2i_X509_VAL 219and 220.Fn i2d_X509_VAL 221decode and encode an ASN.1 222.Vt Validity 223structure defined in RFC 5280 section 4.1. 224.Sh RETURN VALUES 225.Fn d2i_X509 , 226.Fn d2i_X509_bio , 227.Fn d2i_X509_fp , 228and 229.Fn d2i_X509_AUX 230return a valid 231.Vt X509 232structure or 233.Dv NULL 234if an error occurs. 235.Pp 236.Fn d2i_X509_CERT_AUX , 237.Fn d2i_X509_CINF , 238and 239.Fn d2i_X509_VAL 240return an 241.Vt X509_CERT_AUX , 242.Vt X509_CINF , 243or 244.Vt X509_VAL 245object, respectively, or 246.Dv NULL 247if an error occurs. 248.Pp 249.Fn i2d_X509 , 250.Fn i2d_X509_AUX , 251.Fn i2d_X509_CERT_AUX , 252.Fn i2d_X509_CINF , 253and 254.Fn i2d_X509_VAL 255return the number of bytes successfully encoded or a negative value 256if an error occurs. 257.Pp 258.Fn i2d_X509_bio 259and 260.Fn i2d_X509_fp 261return 1 for success or 0 if an error occurs. 262.Pp 263For all functions, the error code can be obtained by 264.Xr ERR_get_error 3 . 265.Sh SEE ALSO 266.Xr ASN1_item_d2i 3 , 267.Xr X509_CINF_new 3 , 268.Xr X509_new 3 269.Sh STANDARDS 270RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 271Certificate Revocation List (CRL) Profile 272.Sh HISTORY 273.Fn d2i_X509 , 274.Fn i2d_X509 , 275.Fn d2i_X509_fp , 276.Fn i2d_X509_fp , 277.Fn d2i_X509_CINF , 278.Fn i2d_X509_CINF , 279.Fn d2i_X509_VAL , 280and 281.Fn i2d_X509_VAL 282first appeared in SSLeay 0.5.1. 283.Fn d2i_X509_bio 284and 285.Fn i2d_X509_bio 286first appeared in SSLeay 0.6.0. 287These functions have been available since 288.Ox 2.4 . 289.Pp 290.Fn d2i_X509_AUX , 291.Fn i2d_X509_AUX , 292.Fn d2i_X509_CERT_AUX , 293and 294.Fn i2d_X509_CERT_AUX 295first appeared in OpenSSL 0.9.5 and have been available since 296.Ox 2.7 . 297