1.\" $OpenBSD: X509_new.3,v 1.45 2024/09/02 08:04:32 tb Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2016, 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 <steve@openssl.org>. 22.\" Copyright (c) 2002, 2006, 2015, 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: September 2 2024 $ 70.Dt X509_NEW 3 71.Os 72.Sh NAME 73.Nm X509_new , 74.Nm X509_dup , 75.Nm X509_REQ_to_X509 , 76.Nm X509_free , 77.Nm X509_up_ref , 78.Nm X509_chain_up_ref 79.Nd X.509 certificate object 80.Sh SYNOPSIS 81.In openssl/x509.h 82.Ft X509 * 83.Fn X509_new void 84.Ft X509 * 85.Fo X509_dup 86.Fa "X509 *a" 87.Fc 88.Ft X509 * 89.Fo X509_REQ_to_X509 90.Fa "X509_REQ *req" 91.Fa "int days" 92.Fa "EVP_PKEY *pkey" 93.Fc 94.Ft void 95.Fo X509_free 96.Fa "X509 *a" 97.Fc 98.Ft int 99.Fo X509_up_ref 100.Fa "X509 *a" 101.Fc 102.Ft STACK_OF(X509) * 103.Fo X509_chain_up_ref 104.Fa "STACK_OF(X509) *chain" 105.Fc 106.Sh DESCRIPTION 107.Fn X509_new 108allocates and initializes an empty 109.Vt X509 110object with reference count 1. 111It represents an ASN.1 112.Vt Certificate 113structure defined in RFC 5280 section 4.1. 114It can hold a public key together with information about the person, 115organization, device, or function the associated private key belongs to. 116.Pp 117.Fn X509_dup 118creates a deep copy of 119.Fa a 120using 121.Xr ASN1_item_dup 3 , 122setting the reference count of the copy to 1. 123.Pp 124.Fn X509_REQ_to_X509 125allocates a new certificate object, copies the public key from 126.Fa req 127into it, copies the subject name of 128.Fa req 129to both the subject and issuer names of the new certificate, sets the 130.Fa notBefore 131field to the current time and the 132.Fa notAfter 133field to the given number of 134.Fa days 135in the future, and signs the new certificate with 136.Xr X509_sign 3 137using 138.Fa pkey 139and the MD5 algorithm. 140If 141.Fa req 142contains at least one attribute, 143the version of the new certificate is set to 2. 144.Pp 145.Fn X509_free 146decrements the reference count of the 147.Vt X509 148structure 149.Fa a 150and frees it up if the reference count reaches 0. 151If 152.Fa a 153is a 154.Dv NULL 155pointer, no action occurs. 156.Pp 157.Fn X509_up_ref 158increments the reference count of 159.Fa a 160by 1. 161This function is useful if a certificate structure is being used 162by several different operations each of which will free it up after 163use: this avoids the need to duplicate the entire certificate 164structure. 165.Pp 166.Fn X509_chain_up_ref 167performs a shallow copy of the given 168.Fa chain 169using 170.Fn sk_X509_dup 171and increments the reference count of each contained certificate 172by 1. 173Its purpose is similar to 174.Fn X509_up_ref : 175The returned chain persists after the original is freed. 176.Sh RETURN VALUES 177.Fn X509_new , 178.Fn X509_dup , 179and 180.Fn X509_REQ_to_X509 181return a pointer to the newly allocated object or 182.Dv NULL 183if an error occurs; an error code can be obtained by 184.Xr ERR_get_error 3 . 185.Pp 186.Fn X509_up_ref 187returns 1 for success or 0 for failure. 188.Pp 189.Fn X509_chain_up_ref 190returns the copy of the 191.Fa chain 192or 193.Dv NULL 194if an error occurs. 195.Sh SEE ALSO 196.Xr ASIdentifiers_new 3 , 197.Xr ASRange_new 3 , 198.Xr AUTHORITY_KEYID_new 3 , 199.Xr BASIC_CONSTRAINTS_new 3 , 200.Xr crypto 3 , 201.Xr d2i_X509 3 , 202.Xr IPAddressRange_new 3 , 203.Xr PKCS8_PRIV_KEY_INFO_new 3 , 204.Xr X509_ALGOR_new 3 , 205.Xr X509_ATTRIBUTE_new 3 , 206.Xr X509_check_ca 3 , 207.Xr X509_check_host 3 , 208.Xr X509_check_issued 3 , 209.Xr X509_check_private_key 3 , 210.Xr X509_check_purpose 3 , 211.Xr X509_CINF_new 3 , 212.Xr X509_cmp 3 , 213.Xr X509_CRL_new 3 , 214.Xr X509_digest 3 , 215.Xr X509_EXTENSION_new 3 , 216.Xr X509_find_by_subject 3 , 217.Xr X509_get0_notBefore 3 , 218.Xr X509_get0_signature 3 , 219.Xr X509_get1_email 3 , 220.Xr X509_get_ex_new_index 3 , 221.Xr X509_get_extension_flags 3 , 222.Xr X509_get_pubkey 3 , 223.Xr X509_get_pubkey_parameters 3 , 224.Xr X509_get_serialNumber 3 , 225.Xr X509_get_subject_name 3 , 226.Xr X509_get_version 3 , 227.Xr X509_INFO_new 3 , 228.Xr X509_load_cert_file 3 , 229.Xr X509_LOOKUP_hash_dir 3 , 230.Xr X509_LOOKUP_new 3 , 231.Xr X509_NAME_new 3 , 232.Xr X509_OBJECT_new 3 , 233.Xr X509_PKEY_new 3 , 234.Xr X509_print_ex 3 , 235.Xr X509_PUBKEY_new 3 , 236.Xr X509_PURPOSE_set 3 , 237.Xr X509_REQ_new 3 , 238.Xr X509_SIG_new 3 , 239.Xr X509_sign 3 , 240.Xr X509_STORE_CTX_new 3 , 241.Xr X509_STORE_get_by_subject 3 , 242.Xr X509_STORE_new 3 , 243.Xr X509v3_addr_add_inherit 3 , 244.Xr X509v3_addr_get_range 3 , 245.Xr X509v3_addr_inherits 3 , 246.Xr X509v3_addr_subset 3 , 247.Xr X509v3_addr_validate_path 3 , 248.Xr X509v3_asid_add_id_or_range 3 249.Sh STANDARDS 250RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 251Certificate Revocation List (CRL) Profile 252.Sh HISTORY 253.Fn X509_new 254and 255.Fn X509_free 256appeared in SSLeay 0.4 or earlier, 257.Fn X509_dup 258in SSLeay 0.4.4, and 259.Fn X509_REQ_to_X509 260in SSLeay 0.6.0 . 261These functions have been available since 262.Ox 2.4 . 263.Pp 264.Fn X509_up_ref 265first appeared in OpenSSL 1.1.0 and has been available since 266.Ox 6.1 . 267.Pp 268.Fn X509_chain_up_ref 269first appeared in OpenSSL 1.0.2 and has been available since 270.Ox 6.3 . 271.Sh BUGS 272The X.509 public key infrastructure and its data types contain too 273many design bugs to list them. 274For lots of examples, see the classic 275.Lk https://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt\ 276 "X.509 Style Guide" 277that 278.An Peter Gutmann 279published in 2000. 280