xref: /openssl/doc/man7/property.pod (revision da1c088f)
1=pod
2
3=head1 NAME
4
5property - Properties, a selection mechanism for algorithm implementations
6
7=head1 DESCRIPTION
8
9As of OpenSSL 3.0, a new method has been introduced to decide which of
10multiple implementations of an algorithm will be used.
11The method is centered around the concept of properties.
12Each implementation defines a number of properties and when an algorithm
13is being selected, filters based on these properties can be used to
14choose the most appropriate implementation of the algorithm.
15
16Properties are like variables, they are referenced by name and have a value
17assigned.
18
19=head2 Property Names
20
21Property names fall into two categories: those reserved by the OpenSSL
22project and user defined names.
23A I<reserved> property name consists of a single C-style identifier
24(except for leading underscores not being permitted), which begins
25with a letter and can be followed by any number of letters, numbers
26and underscores.
27Property names are case-insensitive, but OpenSSL will only use lowercase
28letters.
29
30A I<user defined> property name is similar, but it B<must> consist of
31two or more C-style identifiers, separated by periods.
32The last identifier in the name can be considered the 'true' property
33name, which is prefixed by some sort of 'namespace'.
34Providers for example could include their name in the prefix and use
35property names like
36
37  <provider_name>.<property_name>
38  <provider_name>.<algorithm_name>.<property_name>
39
40=head2 Properties
41
42A I<property> is a I<name=value> pair.
43A I<property definition> is a sequence of comma separated properties.
44There can be any number of properties in a definition, however each name must
45be unique.
46For example: "" defines an empty property definition (i.e., no restriction);
47"my.foo=bar" defines a property named I<my.foo> which has a string value I<bar>
48and "iteration.count=3" defines a property named I<iteration.count> which
49has a numeric value of I<3>.
50The full syntax for property definitions appears below.
51
52=head2 Implementations
53
54Each implementation of an algorithm can define any number of
55properties.
56For example, the default provider defines the property I<provider=default>
57for all of its algorithms.
58Likewise, OpenSSL's FIPS provider defines I<provider=fips> and the legacy
59provider defines I<provider=legacy> for all of their algorithms.
60
61=head2 Queries
62
63A I<property query clause> is a single conditional test.
64For example, "fips=yes", "provider!=default" or "?iteration.count=3".
65The first two represent mandatory clauses, such clauses B<must> match
66for any algorithm to even be under consideration.
67The third clause represents an optional clause.
68Matching such clauses is not a requirement, but any additional optional
69match counts in favor of the algorithm.
70More details about that in the B<Lookups> section.
71A I<property query> is a sequence of comma separated property query clauses.
72It is an error if a property name appears in more than one query clause.
73The full syntax for property queries appears below, but the available syntactic
74features are:
75
76=over 4
77
78=item *
79
80B<=> is an infix operator providing an equality test.
81
82=item *
83
84B<!=> is an infix operator providing an inequality test.
85
86=item *
87
88B<?> is a prefix operator that means that the following clause is optional
89but preferred.
90
91=item *
92
93B<-> is a prefix operator that means any global query clause involving the
94following property name should be ignored.
95
96=item *
97
98B<"..."> is a quoted string.
99The quotes are not included in the body of the string.
100
101=item *
102
103B<'...'> is a quoted string.
104The quotes are not included in the body of the string.
105
106=back
107
108=head2 Lookups
109
110When an algorithm is looked up, a property query is used to determine
111the best matching algorithm.
112All mandatory query clauses B<must> be present and the implementation
113that additionally has the largest number of matching optional query
114clauses will be used.
115If there is more than one such optimal candidate, the result will be
116chosen from amongst those in an indeterminate way.
117Ordering of optional clauses is not significant.
118
119=head2 Shortcut
120
121In order to permit a more concise expression of boolean properties, there
122is one short cut: a property name alone (e.g. "my.property") is
123exactly equivalent to "my.property=yes" in both definitions and queries.
124
125=head2 Global and Local
126
127Two levels of property query are supported.
128A context based property query that applies to all fetch operations and a local
129property query.
130Where both the context and local queries include a clause with the same name,
131the local clause overrides the context clause.
132
133It is possible for a local property query to remove a clause in the context
134property query by preceding the property name with a '-'.
135For example, a context property query that contains "fips=yes" would normally
136result in implementations that have "fips=yes".
137
138However, if the setting of the "fips" property is irrelevant to the
139operations being performed, the local property query can include the
140clause "-fips".
141Note that the local property query could not use "fips=no" because that would
142disallow any implementations with "fips=yes" rather than not caring about the
143setting.
144
145=head1 SYNTAX
146
147The lexical syntax in EBNF is given by:
148
149 Definition     ::= PropertyName ( '=' Value )?
150                        ( ',' PropertyName ( '=' Value )? )*
151 Query          ::= PropertyQuery ( ',' PropertyQuery )*
152 PropertyQuery  ::= '-' PropertyName
153                  | '?'? ( PropertyName (( '=' | '!=' ) Value)?)
154 Value          ::= NumberLiteral | StringLiteral
155 StringLiteral  ::= QuotedString | UnquotedString
156 QuotedString   ::= '"' [^"]* '"' | "'" [^']* "'"
157 UnquotedString ::= [A-Za-z] [^{space},]+
158 NumberLiteral  ::= '0' ( [0-7]* | 'x' [0-9A-Fa-f]+ ) | '-'? [1-9] [0-9]+
159 PropertyName   ::= [A-Za-z] [A-Za-z0-9_]* ( '.' [A-Za-z] [A-Za-z0-9_]* )*
160
161The flavour of EBNF being used is defined by:
162L<https://www.w3.org/TR/2010/REC-xquery-20101214/#EBNFNotation>.
163
164=head1 HISTORY
165
166Properties were added in OpenSSL 3.0
167
168=head1 COPYRIGHT
169
170Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
171
172Licensed under the Apache License 2.0 (the "License").  You may not use
173this file except in compliance with the License.  You can obtain a copy
174in the file LICENSE in the source distribution or at
175L<https://www.openssl.org/source/license.html>.
176
177=cut
178