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