1X509_NEW(3ossl)                     OpenSSL                    X509_NEW(3ossl)
2
3
4

NAME

6       X509_new, X509_new_ex, X509_free, X509_up_ref, X509_chain_up_ref - X509
7       certificate ASN1 allocation functions
8

SYNOPSIS

10        #include <openssl/x509.h>
11
12        X509 *X509_new(void);
13        X509 *X509_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
14        void X509_free(X509 *a);
15        int X509_up_ref(X509 *a);
16        STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
17

DESCRIPTION

19       The X509 ASN1 allocation routines, allocate and free an X509 structure,
20       which represents an X509 certificate.
21
22       X509_new_ex() allocates and initializes a X509 structure with a library
23       context of libctx, property query of propq and a reference count of 1.
24       Many X509 functions such as X509_check_purpose(), and X509_verify() use
25       this library context to select which providers supply the fetched
26       algorithms (SHA1 is used internally). This created X509 object can then
27       be used when loading binary data using d2i_X509().
28
29       X509_new() is similar to X509_new_ex() but sets the library context and
30       property query to NULL. This results in the default (NULL) library
31       context being used for any X509 operations requiring algorithm fetches.
32
33       X509_free() decrements the reference count of X509 structure a and
34       frees it up if the reference count is zero. If a is NULL nothing is
35       done.
36
37       X509_up_ref() increments the reference count of a.
38
39       X509_chain_up_ref() increases the reference count of all certificates
40       in chain x and returns a copy of the stack, or an empty stack if a is
41       NULL.
42

NOTES

44       The function X509_up_ref() if useful if a certificate structure is
45       being used by several different operations each of which will free it
46       up after use: this avoids the need to duplicate the entire certificate
47       structure.
48
49       The function X509_chain_up_ref() doesn't just up the reference count of
50       each certificate. It also returns a copy of the stack, using
51       sk_X509_dup(), but it serves a similar purpose: the returned chain
52       persists after the original has been freed.
53

RETURN VALUES

55       If the allocation fails, X509_new() returns NULL and sets an error code
56       that can be obtained by ERR_get_error(3).  Otherwise it returns a
57       pointer to the newly allocated structure.
58
59       X509_up_ref() returns 1 for success and 0 for failure.
60
61       X509_chain_up_ref() returns a copy of the stack or NULL if an error
62       occurred.
63

SEE ALSO

65       d2i_X509(3), ERR_get_error(3), X509_CRL_get0_by_serial(3),
66       X509_get0_signature(3), X509_get_ext_d2i(3),
67       X509_get_extension_flags(3), X509_get_pubkey(3),
68       X509_get_subject_name(3), X509_get_version(3),
69       X509_NAME_add_entry_by_txt(3), X509_NAME_ENTRY_get_object(3),
70       X509_NAME_get_index_by_NID(3), X509_NAME_print_ex(3), X509_sign(3),
71       X509V3_get_d2i(3), X509_verify_cert(3)
72

HISTORY

74       The function X509_new_ex() was added in OpenSSL 3.0.
75

77       Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.
78
79       Licensed under the Apache License 2.0 (the "License").  You may not use
80       this file except in compliance with the License.  You can obtain a copy
81       in the file LICENSE in the source distribution or at
82       <https://www.openssl.org/source/license.html>.
83
84
85
863.1.1                             2023-08-31                   X509_NEW(3ossl)
Impressum