1.\" $OpenBSD: X509_new.3,v 1.17 2019/06/10 14:58:48 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2002, 2006, 2015, 2016 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 10 2019 $ 53.Dt X509_NEW 3 54.Os 55.Sh NAME 56.Nm X509_new , 57.Nm X509_free , 58.Nm X509_up_ref , 59.Nm X509_chain_up_ref 60.Nd X.509 certificate object 61.Sh SYNOPSIS 62.In openssl/x509.h 63.Ft X509 * 64.Fn X509_new void 65.Ft void 66.Fo X509_free 67.Fa "X509 *a" 68.Fc 69.Ft int 70.Fo X509_up_ref 71.Fa "X509 *a" 72.Fc 73.Ft STACK_OF(X509) * 74.Fo X509_chain_up_ref 75.Fa "STACK_OF(X509) *chain" 76.Fc 77.Sh DESCRIPTION 78.Fn X509_new 79allocates and initializes an empty 80.Vt X509 81object with reference count 1. 82It represents an ASN.1 83.Vt Certificate 84structure defined in RFC 5280 section 4.1. 85It can hold a public key together with information about the person, 86organization, device, or function the associated private key belongs to. 87.Pp 88.Fn X509_free 89decrements the reference count of the 90.Vt X509 91structure 92.Fa a 93and frees it up if the reference count reaches 0. 94If 95.Fa a 96is a 97.Dv NULL 98pointer, no action occurs. 99.Pp 100.Fn X509_up_ref 101increments the reference count of 102.Fa a 103by 1. 104This function is useful if a certificate structure is being used 105by several different operations each of which will free it up after 106use: this avoids the need to duplicate the entire certificate 107structure. 108.Pp 109.Fn X509_chain_up_ref 110performs a shallow copy of the given 111.Fa chain 112using 113.Fn sk_X509_dup 114and increments the reference count of each contained certificate 115by 1. 116Its purpose is similar to 117.Fn X509_up_ref : 118The returned chain persists after the original is freed. 119.Pp 120The object 121.Vt X509_INFO , 122which can hold a certificate, the corresponding private key, 123and a certificate revocation list, is not yet documented. 124.Sh RETURN VALUES 125If the allocation fails, 126.Fn X509_new 127returns 128.Dv NULL 129and sets an error code that can be obtained by 130.Xr ERR_get_error 3 . 131Otherwise it returns a pointer to the newly allocated structure. 132.Pp 133.Fn X509_up_ref 134returns 1 for success or 0 for failure. 135.Pp 136.Fn X509_chain_up_ref 137returns the copy of the 138.Fa chain 139or 140.Dv NULL 141if an error occurs. 142.Sh SEE ALSO 143.Xr AUTHORITY_KEYID_new 3 , 144.Xr BASIC_CONSTRAINTS_new 3 , 145.Xr crypto 3 , 146.Xr d2i_X509 3 , 147.Xr PKCS8_PRIV_KEY_INFO_new 3 , 148.Xr X509_ALGOR_new 3 , 149.Xr X509_ATTRIBUTE_new 3 , 150.Xr X509_check_ca 3 , 151.Xr X509_check_host 3 , 152.Xr X509_check_issued 3 , 153.Xr X509_check_private_key 3 , 154.Xr X509_CINF_new 3 , 155.Xr X509_CRL_new 3 , 156.Xr X509_digest 3 , 157.Xr X509_EXTENSION_new 3 , 158.Xr X509_get0_notBefore 3 , 159.Xr X509_get0_signature 3 , 160.Xr X509_get_ex_new_index 3 , 161.Xr X509_get_pubkey 3 , 162.Xr X509_get_serialNumber 3 , 163.Xr X509_get_subject_name 3 , 164.Xr X509_get_version 3 , 165.Xr X509_NAME_new 3 , 166.Xr X509_PUBKEY_new 3 , 167.Xr X509_REQ_new 3 , 168.Xr X509_SIG_new 3 , 169.Xr X509_sign 3 , 170.Xr X509_STORE_CTX_new 3 , 171.Xr X509_STORE_new 3 172.Sh STANDARDS 173RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 174Certificate Revocation List (CRL) Profile 175.Sh HISTORY 176.Fn X509_new 177and 178.Fn X509_free 179appeared in SSLeay 0.4 or earlier and have been available since 180.Ox 2.4 . 181.Pp 182.Fn X509_up_ref 183first appeared in OpenSSL 1.1.0 and has been available since 184.Ox 6.1 . 185.Pp 186.Fn X509_chain_up_ref 187first appeared in OpenSSL 1.0.2 and has been available since 188.Ox 6.3 . 189.Sh BUGS 190The X.509 public key infrastructure and its data types contain too 191many design bugs to list them. 192For lots of examples, see the classic 193.Lk https://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt\ 194 "X.509 Style Guide" 195that 196.An Peter Gutmann 197published in 2000. 198