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