1PROPERTY(7ossl)                     OpenSSL                    PROPERTY(7ossl)
2
3
4

NAME

6       property - Properties, a selection mechanism for algorithm
7       implementations
8

DESCRIPTION

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
17       Properties are like variables, they are referenced by name and have a
18       value assigned.
19
20   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
28       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
34         <provider_name>.<property_name>
35         <provider_name>.<algorithm_name>.<property_name>
36
37   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
47   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
54   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
67= is an infix operator providing an equality test.
68
69!= is an infix operator providing an inequality test.
70
71? is a prefix operator that means that the following clause is
72           optional but preferred.
73
74- is a prefix operator that means any global query clause involving
75           the following property name should be ignored.
76
77"..." is a quoted string.  The quotes are not included in the body
78           of the string.
79
80'...' is a quoted string.  The quotes are not included in the body
81           of the string.
82
83   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
92   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
98   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
104       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
109       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

SYNTAX

116       The lexical syntax in EBNF is given by:
117
118        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
130       The flavour of EBNF being used is defined by:
131       <https://www.w3.org/TR/2010/REC-xquery-20101214/#EBNFNotation>.
132

HISTORY

134       Properties were added in OpenSSL 3.0
135
137       Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
138
139       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>.
143
144
145
1463.0.9                             2023-07-27                   PROPERTY(7ossl)
Impressum