206 lines
8.1 KiB
HTML
Executable File
206 lines
8.1 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>property</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#property_names">Property Names</a></li>
|
|
<li><a href="#properties">Properties</a></li>
|
|
<li><a href="#implementations">Implementations</a></li>
|
|
<li><a href="#queries">Queries</a></li>
|
|
<li><a href="#lookups">Lookups</a></li>
|
|
<li><a href="#shortcut">Shortcut</a></li>
|
|
<li><a href="#global_and_local">Global and Local</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#syntax">SYNTAX</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>property - Properties, a selection mechanism for algorithm implementations</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>As of OpenSSL 3.0, a new method has been introduced to decide which of
|
|
multiple implementations of an algorithm will be used.
|
|
The method is centered around the concept of properties.
|
|
Each implementation defines a number of properties and when an algorithm
|
|
is being selected, filters based on these properties can be used to
|
|
choose the most appropriate implementation of the algorithm.</p>
|
|
<p>Properties are like variables, they are referenced by name and have a value
|
|
assigned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="property_names">Property Names</a></h2>
|
|
<p>Property names fall into two categories: those reserved by the OpenSSL
|
|
project and user defined names.
|
|
A <em>reserved</em> property name consists of a single C-style identifier
|
|
(except for leading underscores not being permitted), which begins
|
|
with a letter and can be followed by any number of letters, numbers
|
|
and underscores.
|
|
Property names are case-insensitive, but OpenSSL will only use lowercase
|
|
letters.</p>
|
|
<p>A <em>user defined</em> property name is similar, but it <strong>must</strong> consist of
|
|
two or more C-style identifiers, separated by periods.
|
|
The last identifier in the name can be considered the 'true' property
|
|
name, which is prefixed by some sort of 'namespace'.
|
|
Providers for example could include their name in the prefix and use
|
|
property names like</p>
|
|
<pre>
|
|
<provider_name>.<property_name>
|
|
<provider_name>.<algorithm_name>.<property_name></pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="properties">Properties</a></h2>
|
|
<p>A <em>property</em> is a <em>name=value</em> pair.
|
|
A <em>property definition</em> 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 <em>my.foo</em> which has a string value <em>bar</em> and
|
|
"iteration.count=3" defines a property named <em>iteration.count</em> which
|
|
has a numeric value of <em>3</em>.
|
|
The full syntax for property definitions appears below.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="implementations">Implementations</a></h2>
|
|
<p>Each implementation of an algorithm can define any number of
|
|
properties.
|
|
For example, the default provider defines the property <em>provider=default</em>
|
|
for all of its algorithms.
|
|
Likewise, OpenSSL's FIPS provider defines <em>provider=fips</em> and the legacy
|
|
provider defines <em>provider=legacy</em> for all of their algorithms.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="queries">Queries</a></h2>
|
|
<p>A <em>property query clause</em> is a single conditional test.
|
|
For example, "fips=yes", "provider!=default" or "?iteration.count!=3".
|
|
The first two represent mandatory clauses, such clauses <strong>must</strong> match
|
|
for any algorithm to even be under consideration.
|
|
The third clause represents an optional clause.
|
|
Matching such clauses is not a requirement, but any additional optional
|
|
match counts in favor of the algorithm.
|
|
More details about that in the <strong>Lookups</strong> section.
|
|
A <em>property query</em> is a sequence of comma separated property query clauses.
|
|
The full syntax for property queries appears below, but the available syntactic
|
|
features are:</p>
|
|
<ul>
|
|
<li>
|
|
<p><strong>=</strong> is an infix operator providing an equality test.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>!=</strong> is an infix operator providing an inequality test.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>?</strong> is a prefix operator that means that the following clause is optional
|
|
but preferred.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>-</strong> is a prefix operator that means any global query clause involving the
|
|
following property name should be ignored.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>"..."</strong> is a quoted string.
|
|
The quotes are not included in the body of the string.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>'...'</strong> is a quoted string.
|
|
The quotes are not included in the body of the string.</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
</p>
|
|
<h2><a name="lookups">Lookups</a></h2>
|
|
<p>When an algorithm is looked up, a property query is used to determine
|
|
the best matching algorithm.
|
|
All mandatory query clauses <strong>must</strong> be present and the implementation
|
|
that additionally has the largest number of matching optional query
|
|
clauses will be used.
|
|
If there is more than one such optimal candidate, the result will be
|
|
chosen from amongst those in an indeterminate way.
|
|
Ordering of optional clauses is not significant.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="shortcut">Shortcut</a></h2>
|
|
<p>In order to permit a more concise expression of boolean properties, there
|
|
is one short cut: a property name alone (e.g. "my.property") is
|
|
exactly equivalent to "my.property=yes" in both definitions and queries.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="global_and_local">Global and Local</a></h2>
|
|
<p>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.</p>
|
|
<p>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".</p>
|
|
<p>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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="syntax">SYNTAX</a></h1>
|
|
<p>The lexical syntax in EBNF is given by:</p>
|
|
<pre>
|
|
Definition ::= PropertyName ( '=' Value )?
|
|
( ',' PropertyName ( '=' Value )? )*
|
|
Query ::= PropertyQuery ( ',' PropertyQuery )*
|
|
PropertyQuery ::= '-' PropertyName
|
|
| '?'? ( PropertyName (( '=' | '!=' ) Value)?)
|
|
Value ::= NumberLiteral | StringLiteral
|
|
StringLiteral ::= QuotedString | UnquotedString
|
|
QuotedString ::= '"' [^"]* '"' | "'" [^']* "'"
|
|
UnquotedString ::= [^{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_]* )*</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>Properties were added in OpenSSL 3.0</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>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
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|