Debian Codegraph @

upstream/debian-unstable/man3/OSSL_STORE_expect.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 "OSSL_STORE_EXPECT 3SSL"
58 .TH OSSL_STORE_EXPECT 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 OSSL_STORE_expect,
65 OSSL_STORE_supports_search,
66 OSSL_STORE_find
67 \&\- Specify what object type is expected
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/store.h>
72 \&
73 \& int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);
74 \&
75 \& int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type);
76 \&
77 \& int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search);
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 \&\fBOSSL_STORE_expect()\fR helps applications filter what \fBOSSL_STORE_load()\fR returns
82 by specifying a \fBOSSL_STORE_INFO\fR type.
83 By default, no expectations on the types of objects to be loaded are made.
84 \&\fIexpected_type\fR may be 0 to indicate explicitly that no expectation is made,
85 or it may be any of the known object types (see
86 "SUPPORTED OBJECTS" in \fBOSSL_STORE_INFO\fR\|(3)) except for \fBOSSL_STORE_INFO_NAME\fR.
87 For example, if \f(CW\*(C`file:/foo/bar/store.pem\*(C'\fR contains several objects of different
88 type and only certificates are interesting, the application can simply say
89 that it expects the type \fBOSSL_STORE_INFO_CERT\fR.
90 .PP
91 \&\fBOSSL_STORE_find()\fR helps applications specify a criterion for a more fine
92 grained search of objects.
93 .PP
94 \&\fBOSSL_STORE_supports_search()\fR checks if the loader of the given OSSL_STORE
95 context supports the given search type.
96 See "SUPPORTED CRITERION TYPES" in \fBOSSL_STORE_SEARCH\fR\|(3) for information on the
97 supported search criterion types.
98 .PP
99 \&\fBOSSL_STORE_expect()\fR and OSSL_STORE_find \fImust\fR be called before the first
100 \&\fBOSSL_STORE_load()\fR of a given session, or they will fail.
101 .SH NOTES
102 .IX Header "NOTES"
103 If a more elaborate filter is required by the application, a better choice
104 would be to use a post-processing function.
105 See \fBOSSL_STORE_open\fR\|(3) for more information.
106 .PP
107 However, some loaders may take advantage of the knowledge of an expected type
108 to make object retrieval more efficient, so if a single type is expected, this
109 method is usually preferable.
110 .SH "RETURN VALUES"
111 .IX Header "RETURN VALUES"
112 \&\fBOSSL_STORE_expect()\fR returns 1 on success, or 0 on failure.
113 .PP
114 \&\fBOSSL_STORE_supports_search()\fR returns 1 if the criterion is supported, or 0
115 otherwise.
116 .PP
117 \&\fBOSSL_STORE_find()\fR returns 1 on success, or 0 on failure.
118 .SH "SEE ALSO"
119 .IX Header "SEE ALSO"
120 \&\fBossl_store\fR\|(7), \fBOSSL_STORE_INFO\fR\|(3), \fBOSSL_STORE_SEARCH\fR\|(3),
121 \&\fBOSSL_STORE_load\fR\|(3)
122 .SH HISTORY
123 .IX Header "HISTORY"
124 \&\fBOSSL_STORE_expect()\fR, \fBOSSL_STORE_supports_search()\fR and \fBOSSL_STORE_find()\fR
125 were added in OpenSSL 1.1.1.
126 .SH COPYRIGHT
127 .IX Header "COPYRIGHT"
128 Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved.
129 .PP
130 Licensed under the Apache License 2.0 (the "License"). You may not use
131 this file except in compliance with the License. You can obtain a copy
132 in the file LICENSE in the source distribution or at
133 <https://www.openssl.org/source/license.html>.