summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509_STORE_CTX_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/X509_STORE_CTX_new.3')
-rw-r--r--src/lib/libcrypto/man/X509_STORE_CTX_new.3229
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
71These functions initialise an
72.Vt X509_STORE_CTX
73structure for subsequent use by
74.Xr X509_verify_cert 3 .
75.Pp
76.Fn X509_STORE_CTX_new
77returns a newly initialised
78.Vt X509_STORE_CTX
79structure.
80.Pp
81.Fn X509_STORE_CTX_cleanup
82internally cleans up an
83.Vt X509_STORE_CTX
84structure.
85The context can then be reused with an new call to
86.Fn X509_STORE_CTX_init .
87.Pp
88.Fn X509_STORE_CTX_free
89completely frees up
90.Fa ctx .
91After this call
92.Fa ctx
93is no longer valid.
94.Pp
95.Fn X509_STORE_CTX_init
96sets up
97.Fa ctx
98for a subsequent verification operation.
99The trusted certificate store is set to
100.Fa store ,
101the end entity certificate to be verified is set to
102.Fa x509
103and a set of additional certificates (which will be untrusted but may be
104used to build the chain) in
105.Fa chain .
106Any or all of the
107.Fa store ,
108.Fa x509 ,
109and
110.Fa chain
111parameters can be
112.Dv NULL .
113.Pp
114.Fn X509_STORE_CTX_trusted_stack
115sets the set of trusted certificates of
116.Fa ctx
117to
118.Fa sk .
119This is an alternative way of specifying trusted certificates instead of
120using an
121.Vt X509_STORE .
122.Pp
123.Fn X509_STORE_CTX_set_cert
124sets the certificate to be verified in
125.Fa ctx
126to
127.Fa x .
128.Pp
129.Fn X509_STORE_CTX_set_chain
130sets the additional certificate chain used by
131.Fa ctx
132to
133.Fa sk .
134.Pp
135.Fn X509_STORE_CTX_set0_crls
136sets a set of CRLs to use to aid certificate verification to
137.Fa sk .
138These CRLs will only be used if CRL verification is enabled in the
139associated
140.Vt X509_VERIFY_PARAM
141structure.
142This might be used where additional "useful" CRLs are supplied as part
143of a protocol, for example in a PKCS#7 structure.
144.Pp
145X509_VERIFY_PARAM
146.Fn X509_STORE_CTX_get0_param
147retrieves an internal pointer to the verification parameters associated
148with
149.Fa ctx .
150.Pp
151.Fn X509_STORE_CTX_set0_param
152sets the internal verification parameter pointer to
153.Fa param .
154After this call
155.Fa param
156should not be used.
157.Pp
158.Fn X509_STORE_CTX_set_default
159looks up and sets the default verification method to
160.Fa name .
161This uses the function
162.Xr X509_VERIFY_PARAM_lookup 3
163to find an appropriate set of parameters from
164.Fa name .
165.Pp
166The certificates and CRLs in a store are used internally and should
167.Sy not
168be freed up until after the associated
169.Vt X509_STORE_CTX
170is freed.
171Legacy applications might implicitly use an
172.Vt X509_STORE_CTX
173like this:
174.Bd -literal -offset indent
175X509_STORE_CTX ctx;
176X509_STORE_CTX_init(&ctx, store, cert, chain);
177.Ed
178.Pp
179This is
180.Sy not
181recommended in new applications they should instead do:
182.Bd -literal -offset indent
183X509_STORE_CTX *ctx;
184ctx = X509_STORE_CTX_new();
185if (ctx == NULL)
186 /* Bad error */
187X509_STORE_CTX_init(ctx, store, cert, chain);
188.Ed
189.Sh RETURN VALUES
190.Fn X509_STORE_CTX_new
191returns an newly allocates context or
192.Dv NULL
193if an error occurred.
194.Pp
195.Fn X509_STORE_CTX_init
196returns 1 for success or 0 if an error occurred.
197.Pp
198.Fn X509_STORE_CTX_get0_param
199returns a pointer to an
200.Vt X509_VERIFY_PARAM
201structure or
202.Dv NULL
203if 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 ,
211and
212.Fn X509_STORE_CTX_set0_param
213do not return values.
214.Pp
215.Fn X509_STORE_CTX_set_default
216returns 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
222was first added to OpenSSL 1.0.0.
223.Sh BUGS
224The certificates and CRLs in a context are used internally and should
225.Sy not
226be freed up until after the associated
227.Vt X509_STORE_CTX
228is freed.
229Copies should be made or reference counts increased instead.