Debian Codegraph @

upstream/debian-unstable/man3/X509_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_NEW 3SSL"
58 .TH X509_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_new, X509_new_ex,
65 X509_free, X509_up_ref,
66 X509_chain_up_ref,
67 OSSL_STACK_OF_X509_free
68 \&\- X509 certificate ASN1 allocation and deallocation functions
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/x509.h>
73 \&
74 \& X509 *X509_new(void);
75 \& X509 *X509_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
76 \& void X509_free(X509 *a);
77 \& int X509_up_ref(X509 *a);
78 \& STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
79 \& void OSSL_STACK_OF_X509_free(STACK_OF(X509) *certs);
80 .Ve
81 .SH DESCRIPTION
82 .IX Header "DESCRIPTION"
83 The X509 ASN1 allocation routines allocate and free an
84 X509 structure, which represents an X509 certificate.
85 .PP
86 \&\fBX509_new_ex()\fR allocates and initializes a X509 structure with a
87 library context of \fIlibctx\fR, property query of \fIpropq\fR and a reference
88 count of \fB1\fR. Many X509 functions such as \fBX509_check_purpose()\fR, and
89 \&\fBX509_verify()\fR use this library context to select which providers supply the
90 fetched algorithms (SHA1 is used internally). This created X509 object can then
91 be used when loading binary data using \fBd2i_X509()\fR.
92 .PP
93 \&\fBX509_new()\fR is similar to \fBX509_new_ex()\fR but sets the library context
94 and property query to NULL. This results in the default (NULL) library context
95 being used for any X509 operations requiring algorithm fetches.
96 .PP
97 \&\fBX509_free()\fR decrements the reference count of \fBX509\fR structure \fBa\fR and
98 frees it up if the reference count is zero. If the argument is NULL,
99 nothing is done.
100 .PP
101 \&\fBX509_up_ref()\fR increments the reference count of \fBa\fR.
102 .PP
103 \&\fBX509_chain_up_ref()\fR increases the reference count of all certificates in
104 chain \fBx\fR and returns a copy of the stack, or an empty stack if \fBa\fR is NULL.
105 .PP
106 \&\fBOSSL_STACK_OF_X509_free()\fR deallocates the given list of pointers to
107 certificates after calling \fBX509_free()\fR on all its elements.
108 If the argument is NULL, nothing is done.
109 .SH NOTES
110 .IX Header "NOTES"
111 The function \fBX509_up_ref()\fR if useful if a certificate structure is being
112 used by several different operations each of which will free it up after
113 use: this avoids the need to duplicate the entire certificate structure.
114 .PP
115 The function \fBX509_chain_up_ref()\fR doesn't just up the reference count of
116 each certificate. It also returns a copy of the stack, using \fBsk_X509_dup()\fR,
117 but it serves a similar purpose: the returned chain persists after the
118 original has been freed.
119 .SH "RETURN VALUES"
120 .IX Header "RETURN VALUES"
121 If the allocation fails, \fBX509_new()\fR returns NULL and sets an error
122 code that can be obtained by \fBERR_get_error\fR\|(3).
123 Otherwise it returns a pointer to the newly allocated structure.
124 .PP
125 \&\fBX509_up_ref()\fR returns 1 for success and 0 for failure.
126 .PP
127 \&\fBX509_chain_up_ref()\fR returns a copy of the stack or NULL if an error occurred.
128 .PP
129 \&\fBOSSL_STACK_OF_X509_free()\fR has no return value.
130 .SH "SEE ALSO"
131 .IX Header "SEE ALSO"
132 \&\fBd2i_X509\fR\|(3),
133 \&\fBERR_get_error\fR\|(3),
134 \&\fBX509_CRL_get0_by_serial\fR\|(3),
135 \&\fBX509_get0_signature\fR\|(3),
136 \&\fBX509_get_ext_d2i\fR\|(3),
137 \&\fBX509_get_extension_flags\fR\|(3),
138 \&\fBX509_get_pubkey\fR\|(3),
139 \&\fBX509_get_subject_name\fR\|(3),
140 \&\fBX509_get_version\fR\|(3),
141 \&\fBX509_NAME_add_entry_by_txt\fR\|(3),
142 \&\fBX509_NAME_ENTRY_get_object\fR\|(3),
143 \&\fBX509_NAME_get_index_by_NID\fR\|(3),
144 \&\fBX509_NAME_print_ex\fR\|(3),
145 \&\fBX509_sign\fR\|(3),
146 \&\fBX509V3_get_d2i\fR\|(3),
147 \&\fBX509_verify_cert\fR\|(3)
148 .SH HISTORY
149 .IX Header "HISTORY"
150 \&\fBX509_new_ex()\fR was added in OpenSSL 3.0.
151 .PP
152 \&\fBOSSL_STACK_OF_X509_free()\fR was added in OpenSSL 3.2.
153 .SH COPYRIGHT
154 .IX Header "COPYRIGHT"
155 Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved.
156 .PP
157 Licensed under the Apache License 2.0 (the "License"). You may not use
158 this file except in compliance with the License. You can obtain a copy
159 in the file LICENSE in the source distribution or at
160 <https://www.openssl.org/source/license.html>.