diff options
Diffstat (limited to 'src/lib/libcrypto/man/X509_STORE_CTX_new.3')
-rw-r--r-- | src/lib/libcrypto/man/X509_STORE_CTX_new.3 | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_new.3 b/src/lib/libcrypto/man/X509_STORE_CTX_new.3 new file mode 100644 index 0000000000..6a4b9e3e53 --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_CTX_new.3 | |||
@@ -0,0 +1,229 @@ | |||
1 | .Dd $Mdocdate: November 4 2016 $ | ||
2 | .Dt X509_STORE_CTX_NEW 3 | ||
3 | .Os | ||
4 | .Sh NAME | ||
5 | .Nm X509_STORE_CTX_new , | ||
6 | .Nm X509_STORE_CTX_cleanup , | ||
7 | .Nm X509_STORE_CTX_free , | ||
8 | .Nm X509_STORE_CTX_init , | ||
9 | .Nm X509_STORE_CTX_trusted_stack , | ||
10 | .Nm X509_STORE_CTX_set_cert , | ||
11 | .Nm X509_STORE_CTX_set_chain , | ||
12 | .Nm X509_STORE_CTX_set0_crls , | ||
13 | .Nm X509_STORE_CTX_get0_param , | ||
14 | .Nm X509_STORE_CTX_set0_param , | ||
15 | .Nm X509_STORE_CTX_set_default | ||
16 | .Nd X509_STORE_CTX initialisation | ||
17 | .Sh SYNOPSIS | ||
18 | .In openssl/x509_vfy.h | ||
19 | .Ft X509_STORE_CTX * | ||
20 | .Fn X509_STORE_CTX_new void | ||
21 | .Ft void | ||
22 | .Fo X509_STORE_CTX_cleanup | ||
23 | .Fa "X509_STORE_CTX *ctx" | ||
24 | .Fc | ||
25 | .Ft void | ||
26 | .Fo X509_STORE_CTX_free | ||
27 | .Fa "X509_STORE_CTX *ctx" | ||
28 | .Fc | ||
29 | .Ft int | ||
30 | .Fo X509_STORE_CTX_init | ||
31 | .Fa "X509_STORE_CTX *ctx" | ||
32 | .Fa "X509_STORE *store" | ||
33 | .Fa "X509 *x509" | ||
34 | .Fa "STACK_OF(X509) *chain" | ||
35 | .Fc | ||
36 | .Ft void | ||
37 | .Fo X509_STORE_CTX_trusted_stack | ||
38 | .Fa "X509_STORE_CTX *ctx" | ||
39 | .Fa "STACK_OF(X509) *sk" | ||
40 | .Fc | ||
41 | .Ft void | ||
42 | .Fo X509_STORE_CTX_set_cert | ||
43 | .Fa "X509_STORE_CTX *ctx" | ||
44 | .Fa "X509 *x" | ||
45 | .Fc | ||
46 | .Ft void | ||
47 | .Fo X509_STORE_CTX_set_chain | ||
48 | .Fa "X509_STORE_CTX *ctx" | ||
49 | .Fa "STACK_OF(X509) *sk" | ||
50 | .Fc | ||
51 | .Ft void | ||
52 | .Fo X509_STORE_CTX_set0_crls | ||
53 | .Fa "X509_STORE_CTX *ctx" | ||
54 | .Fa "STACK_OF(X509_CRL) *sk" | ||
55 | .Fc | ||
56 | .Ft X509_VERIFY_PARAM * | ||
57 | .Fo X509_STORE_CTX_get0_param | ||
58 | .Fa "X509_STORE_CTX *ctx" | ||
59 | .Fc | ||
60 | .Ft void | ||
61 | .Fo X509_STORE_CTX_set0_param | ||
62 | .Fa "X509_STORE_CTX *ctx" | ||
63 | .Fa "X509_VERIFY_PARAM *param" | ||
64 | .Fc | ||
65 | .Ft int | ||
66 | .Fo X509_STORE_CTX_set_default | ||
67 | .Fa "X509_STORE_CTX *ctx" | ||
68 | .Fa "const char *name" | ||
69 | .Fc | ||
70 | .Sh DESCRIPTION | ||
71 | These functions initialise an | ||
72 | .Vt X509_STORE_CTX | ||
73 | structure for subsequent use by | ||
74 | .Xr X509_verify_cert 3 . | ||
75 | .Pp | ||
76 | .Fn X509_STORE_CTX_new | ||
77 | returns a newly initialised | ||
78 | .Vt X509_STORE_CTX | ||
79 | structure. | ||
80 | .Pp | ||
81 | .Fn X509_STORE_CTX_cleanup | ||
82 | internally cleans up an | ||
83 | .Vt X509_STORE_CTX | ||
84 | structure. | ||
85 | The context can then be reused with an new call to | ||
86 | .Fn X509_STORE_CTX_init . | ||
87 | .Pp | ||
88 | .Fn X509_STORE_CTX_free | ||
89 | completely frees up | ||
90 | .Fa ctx . | ||
91 | After this call | ||
92 | .Fa ctx | ||
93 | is no longer valid. | ||
94 | .Pp | ||
95 | .Fn X509_STORE_CTX_init | ||
96 | sets up | ||
97 | .Fa ctx | ||
98 | for a subsequent verification operation. | ||
99 | The trusted certificate store is set to | ||
100 | .Fa store , | ||
101 | the end entity certificate to be verified is set to | ||
102 | .Fa x509 | ||
103 | and a set of additional certificates (which will be untrusted but may be | ||
104 | used to build the chain) in | ||
105 | .Fa chain . | ||
106 | Any or all of the | ||
107 | .Fa store , | ||
108 | .Fa x509 , | ||
109 | and | ||
110 | .Fa chain | ||
111 | parameters can be | ||
112 | .Dv NULL . | ||
113 | .Pp | ||
114 | .Fn X509_STORE_CTX_trusted_stack | ||
115 | sets the set of trusted certificates of | ||
116 | .Fa ctx | ||
117 | to | ||
118 | .Fa sk . | ||
119 | This is an alternative way of specifying trusted certificates instead of | ||
120 | using an | ||
121 | .Vt X509_STORE . | ||
122 | .Pp | ||
123 | .Fn X509_STORE_CTX_set_cert | ||
124 | sets the certificate to be verified in | ||
125 | .Fa ctx | ||
126 | to | ||
127 | .Fa x . | ||
128 | .Pp | ||
129 | .Fn X509_STORE_CTX_set_chain | ||
130 | sets the additional certificate chain used by | ||
131 | .Fa ctx | ||
132 | to | ||
133 | .Fa sk . | ||
134 | .Pp | ||
135 | .Fn X509_STORE_CTX_set0_crls | ||
136 | sets a set of CRLs to use to aid certificate verification to | ||
137 | .Fa sk . | ||
138 | These CRLs will only be used if CRL verification is enabled in the | ||
139 | associated | ||
140 | .Vt X509_VERIFY_PARAM | ||
141 | structure. | ||
142 | This might be used where additional "useful" CRLs are supplied as part | ||
143 | of a protocol, for example in a PKCS#7 structure. | ||
144 | .Pp | ||
145 | X509_VERIFY_PARAM | ||
146 | .Fn X509_STORE_CTX_get0_param | ||
147 | retrieves an internal pointer to the verification parameters associated | ||
148 | with | ||
149 | .Fa ctx . | ||
150 | .Pp | ||
151 | .Fn X509_STORE_CTX_set0_param | ||
152 | sets the internal verification parameter pointer to | ||
153 | .Fa param . | ||
154 | After this call | ||
155 | .Fa param | ||
156 | should not be used. | ||
157 | .Pp | ||
158 | .Fn X509_STORE_CTX_set_default | ||
159 | looks up and sets the default verification method to | ||
160 | .Fa name . | ||
161 | This uses the function | ||
162 | .Xr X509_VERIFY_PARAM_lookup 3 | ||
163 | to find an appropriate set of parameters from | ||
164 | .Fa name . | ||
165 | .Pp | ||
166 | The certificates and CRLs in a store are used internally and should | ||
167 | .Sy not | ||
168 | be freed up until after the associated | ||
169 | .Vt X509_STORE_CTX | ||
170 | is freed. | ||
171 | Legacy applications might implicitly use an | ||
172 | .Vt X509_STORE_CTX | ||
173 | like this: | ||
174 | .Bd -literal -offset indent | ||
175 | X509_STORE_CTX ctx; | ||
176 | X509_STORE_CTX_init(&ctx, store, cert, chain); | ||
177 | .Ed | ||
178 | .Pp | ||
179 | This is | ||
180 | .Sy not | ||
181 | recommended in new applications they should instead do: | ||
182 | .Bd -literal -offset indent | ||
183 | X509_STORE_CTX *ctx; | ||
184 | ctx = X509_STORE_CTX_new(); | ||
185 | if (ctx == NULL) | ||
186 | /* Bad error */ | ||
187 | X509_STORE_CTX_init(ctx, store, cert, chain); | ||
188 | .Ed | ||
189 | .Sh RETURN VALUES | ||
190 | .Fn X509_STORE_CTX_new | ||
191 | returns an newly allocates context or | ||
192 | .Dv NULL | ||
193 | if an error occurred. | ||
194 | .Pp | ||
195 | .Fn X509_STORE_CTX_init | ||
196 | returns 1 for success or 0 if an error occurred. | ||
197 | .Pp | ||
198 | .Fn X509_STORE_CTX_get0_param | ||
199 | returns a pointer to an | ||
200 | .Vt X509_VERIFY_PARAM | ||
201 | structure or | ||
202 | .Dv NULL | ||
203 | if an error occurred. | ||
204 | .Pp | ||
205 | .Fn X509_STORE_CTX_cleanup , | ||
206 | .Fn X509_STORE_CTX_free , | ||
207 | .Fn X509_STORE_CTX_trusted_stack , | ||
208 | .Fn X509_STORE_CTX_set_cert , | ||
209 | .Fn X509_STORE_CTX_set_chain , | ||
210 | .Fn X509_STORE_CTX_set0_crls , | ||
211 | and | ||
212 | .Fn X509_STORE_CTX_set0_param | ||
213 | do not return values. | ||
214 | .Pp | ||
215 | .Fn X509_STORE_CTX_set_default | ||
216 | returns 1 for success or 0 if an error occurred. | ||
217 | .Sh SEE ALSO | ||
218 | .Xr X509_verify_cert 3 , | ||
219 | .Xr X509_VERIFY_PARAM_set_flags 3 | ||
220 | .Sh HISTORY | ||
221 | .Fn X509_STORE_CTX_set0_crls | ||
222 | was first added to OpenSSL 1.0.0. | ||
223 | .Sh BUGS | ||
224 | The certificates and CRLs in a context are used internally and should | ||
225 | .Sy not | ||
226 | be freed up until after the associated | ||
227 | .Vt X509_STORE_CTX | ||
228 | is freed. | ||
229 | Copies should be made or reference counts increased instead. | ||