1=pod 2 3=head1 NAME 4 5X509_new, X509_new_ex, 6X509_free, X509_up_ref, 7X509_chain_up_ref - X509 certificate ASN1 allocation functions 8 9=head1 SYNOPSIS 10 11 #include <openssl/x509.h> 12 13 X509 *X509_new(void); 14 X509 *X509_new_ex(OSSL_LIB_CTX *libctx, const char *propq); 15 void X509_free(X509 *a); 16 int X509_up_ref(X509 *a); 17 STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x); 18 19=head1 DESCRIPTION 20 21The X509 ASN1 allocation routines allocate and free an 22X509 structure, which represents an X509 certificate. 23 24X509_new_ex() allocates and initializes a X509 structure with a 25library context of I<libctx>, property query of I<propq> and a reference 26count of B<1>. Many X509 functions such as X509_check_purpose(), and 27X509_verify() use this library context to select which providers supply the 28fetched algorithms (SHA1 is used internally). This created X509 object can then 29be used when loading binary data using d2i_X509(). 30 31X509_new() is similar to X509_new_ex() but sets the library context 32and property query to NULL. This results in the default (NULL) library context 33being used for any X509 operations requiring algorithm fetches. 34 35X509_free() decrements the reference count of B<X509> structure B<a> and 36frees it up if the reference count is zero. If the argument is NULL, 37nothing is done. 38 39X509_up_ref() increments the reference count of B<a>. 40 41X509_chain_up_ref() increases the reference count of all certificates in 42chain B<x> and returns a copy of the stack, or an empty stack if B<a> is NULL. 43 44=head1 NOTES 45 46The function X509_up_ref() if useful if a certificate structure is being 47used by several different operations each of which will free it up after 48use: this avoids the need to duplicate the entire certificate structure. 49 50The function X509_chain_up_ref() doesn't just up the reference count of 51each certificate. It also returns a copy of the stack, using sk_X509_dup(), 52but it serves a similar purpose: the returned chain persists after the 53original has been freed. 54 55=head1 RETURN VALUES 56 57If the allocation fails, X509_new() returns NULL and sets an error 58code that can be obtained by L<ERR_get_error(3)>. 59Otherwise it returns a pointer to the newly allocated structure. 60 61X509_up_ref() returns 1 for success and 0 for failure. 62 63X509_chain_up_ref() returns a copy of the stack or NULL if an error occurred. 64 65=head1 SEE ALSO 66 67L<d2i_X509(3)>, 68L<ERR_get_error(3)>, 69L<X509_CRL_get0_by_serial(3)>, 70L<X509_get0_signature(3)>, 71L<X509_get_ext_d2i(3)>, 72L<X509_get_extension_flags(3)>, 73L<X509_get_pubkey(3)>, 74L<X509_get_subject_name(3)>, 75L<X509_get_version(3)>, 76L<X509_NAME_add_entry_by_txt(3)>, 77L<X509_NAME_ENTRY_get_object(3)>, 78L<X509_NAME_get_index_by_NID(3)>, 79L<X509_NAME_print_ex(3)>, 80L<X509_sign(3)>, 81L<X509V3_get_d2i(3)>, 82L<X509_verify_cert(3)> 83 84=head1 HISTORY 85 86The function X509_new_ex() was added in OpenSSL 3.0. 87 88=head1 COPYRIGHT 89 90Copyright 2002-2024 The OpenSSL Project Authors. All Rights Reserved. 91 92Licensed under the Apache License 2.0 (the "License"). You may not use 93this file except in compliance with the License. You can obtain a copy 94in the file LICENSE in the source distribution or at 95L<https://www.openssl.org/source/license.html>. 96 97=cut 98