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