A I<property> is a I<name=value> pair.
A I<property definition> is a sequence of comma separated properties.
-There can be any number of properties in a definition.
-For example: "" defines a null property definition; "my.foo=bar"
-defines a property named I<my.foo> which has a string value I<bar> and
-"iteration.count=3" defines a property named I<iteration.count> which
+There can be any number of properties in a definition, however each name must
+be unique.
+For example: "" defines an empty property definition (i.e., no restriction);
+"my.foo=bar" defines a property named I<my.foo> which has a string value I<bar>
+and "iteration.count=3" defines a property named I<iteration.count> which
has a numeric value of I<3>.
The full syntax for property definitions appears below.
Each implementation of an algorithm can define any number of
properties.
-For example, the default provider defines the property I<default=yes>
+For example, the default provider defines the property I<provider=default>
for all of its algorithms.
-Likewise, the FIPS provider defines I<fips=yes> and the legacy provider
-defines I<legacy=yes> for all of their algorithms.
+Likewise, OpenSSL's FIPS provider defines I<provider=fips> and the legacy
+provider defines I<provider=legacy> for all of their algorithms.
=head2 Queries
A I<property query clause> is a single conditional test.
-For example, "fips=yes", "default!=yes" or "?iteration.count!=3".
+For example, "fips=yes", "provider!=default" or "?iteration.count=3".
The first two represent mandatory clauses, such clauses B<must> match
for any algorithm to even be under consideration.
The third clause represents an optional clause.
match counts in favor of the algorithm.
More details about that in the B<Lookups> section.
A I<property query> is a sequence of comma separated property query clauses.
-The full syntax for property queries appears below.
+It is an error if a property name appears in more than one query clause.
+The full syntax for property queries appears below, but the available syntactic
+features are:
+
+=over 4
+
+=item *
+
+B<=> is an infix operator providing an equality test.
+
+=item *
+
+B<!=> is an infix operator providing an inequality test.
+
+=item *
+
+B<?> is a prefix operator that means that the following clause is optional
+but preferred.
+
+=item *
+
+B<-> is a prefix operator that means any global query clause involving the
+following property name should be ignored.
+
+=item *
+
+B<"..."> is a quoted string.
+The quotes are not included in the body of the string.
+
+=item *
+
+B<'...'> is a quoted string.
+The quotes are not included in the body of the string.
+
+=back
=head2 Lookups
=head2 Shortcut
In order to permit a more concise expression of boolean properties, there
-is one short cut: a property name alone (e.g. "default") is
-exactly equivalent to "default=yes" in both definitions and queries.
+is one short cut: a property name alone (e.g. "my.property") is
+exactly equivalent to "my.property=yes" in both definitions and queries.
+
+=head2 Global and Local
+
+Two levels of property query are supported.
+A context based property query that applies to all fetch operations and a local
+property query.
+Where both the context and local queries include a clause with the same name,
+the local clause overrides the context clause.
+
+It is possible for a local property query to remove a clause in the context
+property query by preceding the property name with a '-'.
+For example, a context property query that contains "fips=yes" would normally
+result in implementations that have "fips=yes".
+
+However, if the setting of the "fips" property is irrelevant to the
+operations being performed, the local property query can include the
+clause "-fips".
+Note that the local property query could not use "fips=no" because that would
+disallow any implementations with "fips=yes" rather than not caring about the
+setting.
-=head1 Syntax
+=head1 SYNTAX
The lexical syntax in EBNF is given by:
- Definition ::= PropertyName ( '=' Value )?
+ Definition ::= PropertyName ( '=' Value )?
( ',' PropertyName ( '=' Value )? )*
Query ::= PropertyQuery ( ',' PropertyQuery )*
PropertyQuery ::= '-' PropertyName
Value ::= NumberLiteral | StringLiteral
StringLiteral ::= QuotedString | UnquotedString
QuotedString ::= '"' [^"]* '"' | "'" [^']* "'"
- UnquotedString ::= [^{space},]+
+ UnquotedString ::= [A-Za-z] [^{space},]+
NumberLiteral ::= '0' ( [0-7]* | 'x' [0-9A-Fa-f]+ ) | '-'? [1-9] [0-9]+
- PropertyName ::= [A-Z] [A-Z0-9_]* ( '.' [A-Z] [A-Z0-9_]* )*
+ PropertyName ::= [A-Za-z] [A-Za-z0-9_]* ( '.' [A-Za-z] [A-Za-z0-9_]* )*
-Railroad diagrams for this grammar can be found in the
-F<crypto/property/properties.xhtml> file.
+The flavour of EBNF being used is defined by:
+L<https://www.w3.org/TR/2010/REC-xquery-20101214/#EBNFNotation>.
=head1 HISTORY
=head1 COPYRIGHT
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
projects / openssl.git / blobdiff