summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authortb <>2024-01-12 19:28:02 +0000
committertb <>2024-01-12 19:28:02 +0000
commitfdc0b6d6723ac761e12533c4208099d4bbc2af0e (patch)
tree9b6a78ed1036cb8965aab669af327a0f91c674cf /src
parent49891798a7d66f2ea94103d9b16029d4f73cf164 (diff)
downloadopenbsd-fdc0b6d6723ac761e12533c4208099d4bbc2af0e.tar.gz
openbsd-fdc0b6d6723ac761e12533c4208099d4bbc2af0e.tar.bz2
openbsd-fdc0b6d6723ac761e12533c4208099d4bbc2af0e.zip
Remove X509_STORE_CTX_purpose_inherit(3) documentation
This abomination of an API will be removed. Remove the hairy details of its internals and make the documentation of X509_STORE_CTX_set_trust(3) and X509_STORE_CTX_set_purpose(3) independent of it. Neither of these two remaining APIs can be recommended. Once set, trust and purpose are sticky. Setting the trust to a different (valid) value will indicate success but leave the value unchanged. I suppose it means the new trust value was successfully ignored. Also, setting the trust to X509_TRUST_DEFAULT can succeed or fail depending on which OpenSSL derivative you use. Setting the purpose will also set the trust (unless it is already set). Setting some purposes may or may not fail depending on the OpenSSL lib. The only way you have a chance of knowing what will be set is by calling only one of these functions directly after X509_STORE_CTX_init(). This isn't really safe either because in some versions the user can override the values stored in a global table by writing directly to it. The actual contributions here are rather minimal. State more explicitly that 0 is invalid (but results in success being returned), document the error values to be accurate across implementations and call out some of the nonsense in a CAVEATS section. Many thanks to schwarze for the very helpful review with lots of input. ok schwarze
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/man/X509_STORE_CTX_set_flags.3172
1 files changed, 41 insertions, 131 deletions
diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_set_flags.3 b/src/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
index 2ac76951fa..db991bd52b 100644
--- a/src/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
+++ b/src/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
@@ -1,4 +1,4 @@
1.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.6 2021/11/17 16:08:32 schwarze Exp $ 1.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.7 2024/01/12 19:28:02 tb Exp $
2.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100 2.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100
3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
4.\" 4.\"
@@ -67,7 +67,7 @@
67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" OF THE POSSIBILITY OF SUCH DAMAGE.
69.\" 69.\"
70.Dd $Mdocdate: November 17 2021 $ 70.Dd $Mdocdate: January 12 2024 $
71.Dt X509_STORE_CTX_SET_FLAGS 3 71.Dt X509_STORE_CTX_SET_FLAGS 3
72.Os 72.Os
73.Sh NAME 73.Sh NAME
@@ -76,7 +76,8 @@
76.Nm X509_STORE_CTX_set_depth , 76.Nm X509_STORE_CTX_set_depth ,
77.Nm X509_STORE_CTX_set_trust , 77.Nm X509_STORE_CTX_set_trust ,
78.Nm X509_STORE_CTX_set_purpose , 78.Nm X509_STORE_CTX_set_purpose ,
79.Nm X509_STORE_CTX_purpose_inherit , 79.\" .Nm X509_STORE_CTX_purpose_inherit is intentionally undocumented
80.\" because it will be removed in the next major bump.
80.Nm X509_STORE_CTX_get0_param , 81.Nm X509_STORE_CTX_get0_param ,
81.Nm X509_STORE_CTX_set0_param , 82.Nm X509_STORE_CTX_set0_param ,
82.Nm X509_STORE_CTX_set_default 83.Nm X509_STORE_CTX_set_default
@@ -109,13 +110,6 @@
109.Fa "X509_STORE_CTX *ctx" 110.Fa "X509_STORE_CTX *ctx"
110.Fa "int purpose" 111.Fa "int purpose"
111.Fc 112.Fc
112.Ft int
113.Fo X509_STORE_CTX_purpose_inherit
114.Fa "X509_STORE_CTX *ctx"
115.Fa "int def_purpose"
116.Fa "int purpose"
117.Fa "int trust"
118.Fc
119.Ft X509_VERIFY_PARAM * 113.Ft X509_VERIFY_PARAM *
120.Fo X509_STORE_CTX_get0_param 114.Fo X509_STORE_CTX_get0_param
121.Fa "X509_STORE_CTX *ctx" 115.Fa "X509_STORE_CTX *ctx"
@@ -178,9 +172,6 @@ argument is 0 or invalid
178or the trust identifier is already set to a non-zero value in the 172or the trust identifier is already set to a non-zero value in the
179.Vt X509_VERIFY_PARAM 173.Vt X509_VERIFY_PARAM
180object, no action occurs. 174object, no action occurs.
181Here and in the following,
182.Dv X509_TRUST_DEFAULT
183counts as invalid.
184.Pp 175.Pp
185.Fn X509_STORE_CTX_set_purpose 176.Fn X509_STORE_CTX_set_purpose
186sets the 177sets the
@@ -200,7 +191,7 @@ is called the
200.Pp 191.Pp
201The function fails if the 192The function fails if the
202.Fa purpose 193.Fa purpose
203argument or the associated trust is not 0 but invalid; otherwise, 194argument or the associated trust is invalid but not 0; otherwise,
204.Fn X509_STORE_CTX_set_purpose 195.Fn X509_STORE_CTX_set_purpose
205also does the equivalent of calling 196also does the equivalent of calling
206.Fn X509_STORE_CTX_set_trust 197.Fn X509_STORE_CTX_set_trust
@@ -212,62 +203,6 @@ object, it is not changed, even if the
212.Fa purpose 203.Fa purpose
213argument is valid, too. 204argument is valid, too.
214.Pp 205.Pp
215.Fn X509_STORE_CTX_purpose_inherit
216is similar to
217.Fn X509_STORE_CTX_set_purpose ,
218with the following modifications:
219.Bl -bullet
220.It
221If the
222.Fa purpose
223argument is 0,
224.Fa def_purpose
225is used instead.
226.It
227If the associated trust is
228.Dv X509_TRUST_DEFAULT ,
229the trust associated with
230.Fa def_purpose
231is used instead, or if
232.Fa def_purpose
233is 0 or invalid, the function fails.
234.It
235If the
236.Fa trust
237argument is not 0, it is used instead of the associated trust,
238and the equivalent of calling
239.Fn X509_STORE_CTX_set_trust
240is done even if both
241.Fa purpose
242and
243.Fa def_purpose
244are 0.
245Even if the
246.Fa trust
247argument is not 0, if the (then unused) associated trust is
248.Dv X509_TRUST_DEFAULT ,
249.Fa def_purpose
250is still required to be valid.
251.El
252.Pp
253Note that, even if all arguments are valid and the return value is 1,
254it is possible that nothing changed, or that only either one of the
255purpose and trust identifiers were set, or that both were set.
256It can also happen that the purpose identifier gets set according to the
257.Fa purpose
258argument, but the trust identifier gets set according to the
259.Fa def_purpose
260argument in the same call.
261.Pp
262The intended way of using this function is to pass the purpose and
263trust attributes of another structure of an arbitrary type as the
264.Fa purpose
265and
266.Fa trust
267arguments, and to provide
268.Fa def_purpose
269as a fallback in case the settings in the other structure are incomplete.
270.Pp
271.Fn X509_STORE_CTX_get0_param 206.Fn X509_STORE_CTX_get0_param
272retrieves an internal pointer to the verification parameters associated 207retrieves an internal pointer to the verification parameters associated
273with 208with
@@ -293,7 +228,7 @@ and copies them using
293.Fn X509_STORE_CTX_set_trust 228.Fn X509_STORE_CTX_set_trust
294returns 1 if the 229returns 1 if the
295.Fa trust 230.Fa trust
296argument is 0 or valid or 0 if it is not 0 but invalid. 231argument is 0 or valid or 0 if it is invalid but not 0.
297A return value of 1 does 232A return value of 1 does
298.Em not 233.Em not
299imply that the trust identifier stored in the 234imply that the trust identifier stored in the
@@ -306,45 +241,9 @@ returns 1 if both the
306argument and the associated trust are 0 or valid. 241argument and the associated trust are 0 or valid.
307It returns 0 if either the 242It returns 0 if either the
308.Fa purpose 243.Fa purpose
309argument or the associated trust is not 0 but invalid. 244argument or the associated trust is invalid but not 0.
310A return value of 1 does not imply that any data was changed. 245A return value of 1 does not imply that any data was changed.
311.Pp 246.Pp
312.Fn X509_STORE_CTX_purpose_inherit
313returns 0 if:
314.Bl -bullet
315.It
316The
317.Fa purpose
318argument is not 0 and invalid.
319.It
320The
321.Fa purpose
322argument is 0 and the
323.Fa def_purpose
324argument is not 0 and invalid.
325.It
326The associated trust is
327.Dv X509_TRUST_DEFAULT
328and the
329.Fa def_purpose
330argument is 0 or invalid,
331or the trust identifier associated with it is not 0 but invalid.
332.It
333The
334.Fa trust
335argument is not 0 and invalid.
336.It
337The
338.Fa trust
339argument is 0 and the associated trust is neither 0 nor
340.Dv X509_TRUST_DEFAULT
341but invalid.
342.El
343.Pp
344Otherwise,
345.Fn X509_STORE_CTX_purpose_inherit
346returns 1, which does not imply that any data was changed.
347.Pp
348.Fn X509_STORE_CTX_get0_param 247.Fn X509_STORE_CTX_get0_param
349returns a pointer to an 248returns a pointer to an
350.Vt X509_VERIFY_PARAM 249.Vt X509_VERIFY_PARAM
@@ -355,37 +254,26 @@ if an error occurred.
355.Fn X509_STORE_CTX_set_default 254.Fn X509_STORE_CTX_set_default
356returns 1 for success or 0 if an error occurred. 255returns 1 for success or 0 if an error occurred.
357.Sh ERRORS 256.Sh ERRORS
358For 257The following diagnostics can be retrieved with
359.Fn X509_STORE_CTX_set_trust ,
360.Fn X509_STORE_CTX_set_purpose ,
361and
362.Fn X509_STORE_CTX_purpose_inherit ,
363the following diagnostics can be retrieved with
364.Xr ERR_get_error 3 , 258.Xr ERR_get_error 3 ,
365.Xr ERR_GET_REASON 3 , 259.Xr ERR_GET_REASON 3 ,
366and 260and
367.Xr ERR_reason_error_string 3 : 261.Xr ERR_reason_error_string 3 :
368.Bl -tag -width Ds 262.Bl -tag -width Ds
369.It Dv X509_R_UNKNOWN_TRUST_ID Qq "unknown trust id" 263.It Dv X509_R_UNKNOWN_TRUST_ID Qq "unknown trust id"
370The 264.Fn X509_STORE_CTX_set_trust
265was called with a
371.Fa trust 266.Fa trust
372argument or the trust identifier associated with 267argument that is invalid but not 0.
268Other implementations may also return this when
269.Fn X509_STORE_CTX_set_purpose
270is called with a
373.Fa purpose 271.Fa purpose
374or 272argument with invalid associated trust.
375.Fa def_purpose
376is not 0 but invalid,
377.It Dv X509_R_UNKNOWN_PURPOSE_ID Qq "unknown purpose id" 273.It Dv X509_R_UNKNOWN_PURPOSE_ID Qq "unknown purpose id"
378The 274The
379.Fa purpose 275.Fa purpose
380argument is not 0 and invalid. 276argument is invalid but not 0.
381Or it is 0 and the
382.Fa def_purpose
383argument is not 0 and invalid.
384Or the associated trust is
385.Dv X509_TRUST_DEFAULT
386and
387.Fa def_purpose
388is 0 or invalid.
389.El 277.El
390.Pp 278.Pp
391The other functions provide no diagnostics. 279The other functions provide no diagnostics.
@@ -405,10 +293,9 @@ The other functions provide no diagnostics.
405first appeared in OpenSSL 0.9.3 and has been available since 293first appeared in OpenSSL 0.9.3 and has been available since
406.Ox 2.4 . 294.Ox 2.4 .
407.Pp 295.Pp
408.Fn X509_STORE_CTX_set_trust , 296.Fn X509_STORE_CTX_set_trust
409.Fn X509_STORE_CTX_set_purpose ,
410and 297and
411.Fn X509_STORE_CTX_purpose_inherit 298.Fn X509_STORE_CTX_set_purpose
412first appeared in OpenSSL 0.9.5 and have been available since 299first appeared in OpenSSL 0.9.5 and have been available since
413.Ox 2.7 . 300.Ox 2.7 .
414.Pp 301.Pp
@@ -424,3 +311,26 @@ and
424.Fn X509_STORE_CTX_set_default 311.Fn X509_STORE_CTX_set_default
425first appeared in OpenSSL 0.9.8 and have been available since 312first appeared in OpenSSL 0.9.8 and have been available since
426.Ox 4.5 . 313.Ox 4.5 .
314.Sh CAVEATS
315The precise effect of a successful call to
316.Fn X509_STORE_CTX_set_trust
317and
318.Fn X509_STORE_CTX_set_purpose
319is unclear unless only one of these functions is used immediately after
320.Xr X509_STORE_CTX_init 3 .
321It is therefore recommended to use
322.Fn X509_STORE_CTX_get0_param ,
323.Xr X509_VERIFY_PARAM_set_trust 3 ,
324and
325.Xr X509_VERIFY_PARAM_set_purpose 3
326instead.
327.Pp
328The confusingly named
329.Dv X509_TRUST_DEFAULT
330is less than
331.Dv X509_TRUST_MIN
332and different implementations treat it as valid or invalid
333when used as an associated trust or as a
334.Fa trust
335argument for
336.Fn X509_STORE_CTX_set_trust .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-26 16:56:35 +0000