From cec3901aa2ad09d504cb076100cf6e4b37d01775 Mon Sep 17 00:00:00 2001 From: Pauli Date: Thu, 30 May 2019 10:57:53 +1000 Subject: [PATCH] Add man 7 page about properties. Add a page about properties in the man7 section of the public documentation. Reviewed-by: Richard Levitte Reviewed-by: Matthias St. Pierre (Merged from https://github.com/openssl/openssl/pull/9011) --- crypto/property/properties.ebnf | 2 +- crypto/property/properties.xhtml | 382 ++++++++++++++----------------- doc/man7/property.pod | 122 ++++++++++ 3 files changed, 290 insertions(+), 216 deletions(-) create mode 100644 doc/man7/property.pod diff --git a/crypto/property/properties.ebnf b/crypto/property/properties.ebnf index 0051c7e430..62e4f77cca 100644 --- a/crypto/property/properties.ebnf +++ b/crypto/property/properties.ebnf @@ -4,7 +4,7 @@ Definition ::= PropertyName ( '=' Value )? ( ',' PropertyName ( '=' Value )? )* Query ::= PropertyQuery ( ',' PropertyQuery )* PropertyQuery ::= '-'? PropertyName - | '?' ( PropertyName (( '=' | '!=' ) Value)?) + | '?'? ( PropertyName (( '=' | '!=' ) Value)?) Value ::= NumberLiteral | StringLiteral StringLiteral ::= QuotedString | UnquotedString diff --git a/crypto/property/properties.xhtml b/crypto/property/properties.xhtml index 766d885bf0..0a613ef002 100755 --- a/crypto/property/properties.xhtml +++ b/crypto/property/properties.xhtml @@ -6,13 +6,13 @@ @@ -223,30 +223,30 @@ @@ -263,39 +263,34 @@ , - - - -
         ::= PropertyName ( '=' Value )? ( ',' PropertyName ( '=' Value )? )*
 - - no referencesQuery: + no referencesQuery: @@ -307,38 +302,34 @@ , - - -
Query    ::= PropertyQuery ( ',' PropertyQuery )*
 - - no referencesPropertyQuery: + no referencesPropertyQuery: @@ -348,28 +339,22 @@ - - PropertyName - - ? - - - PropertyName - - = - - - != - - - Value - - - - -
         ::= '-'? PropertyName
-
           | '?' PropertyName ( ( '=' | '!=' ) Value )?
 - - referenced by: + PropertyName + + ? + + + PropertyName + + = + + + != + + + Value + + referenced by: Query @@ -377,30 +362,30 @@ @@ -412,12 +397,7 @@ StringLiteral - - -
Value    ::= NumberLiteral
-
           | StringLiteral
 - - referenced by: + referenced by: Definition PropertyQuery @@ -426,30 +406,30 @@ @@ -461,13 +441,7 @@ UnquotedString - - - -
         ::= QuotedString
-
           | UnquotedString
 - - referenced by: + referenced by: Value @@ -475,30 +449,30 @@ @@ -523,13 +497,7 @@ ' - - - -
         ::= '"' [^"]* '"'
-
           | "'" [^']* "'"
 - - referenced by: + referenced by: StringLiteral @@ -537,30 +505,30 @@ @@ -570,12 +538,7 @@ [^{space},] - - - -
         ::= [^{space},]+
 - - referenced by: + referenced by: StringLiteral @@ -583,30 +546,30 @@ @@ -640,13 +603,7 @@ [0-9] - - - -
         ::= '0' ( [0-7]* | 'x' [0-9A-Fa-f]+ )
-
           | '-'? [1-9] [0-9]+
 - - referenced by: + referenced by: Value @@ -654,30 +611,30 @@ @@ -699,12 +656,7 @@ . - - - -
         ::= [A-Z] [A-Z0-9_]* ( '.' [A-Z] [A-Z0-9_]* )*
 - - referenced by: + referenced by: Definition PropertyQuery diff --git a/doc/man7/property.pod b/doc/man7/property.pod new file mode 100644 index 0000000000..1f8ee541b1 --- /dev/null +++ b/doc/man7/property.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +property - Properties, a selection mechanism for algorithm implementations + +=head1 DESCRIPTION + +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. + +Properties are like variables, they are referenced by name and have a value +assigned. + +=head2 Property Names + +Property names fall into two categories: those reserved by the OpenSSL +project and user defined names. +A I 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. + +A I property name is similar, but it B 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 + + . + .. + +=head2 Properties + +A I is a I pair. +A I 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 which has a string value I and +"iteration.count=3" defines a property named I which +has a numeric value of I<3>. +The full syntax for property definitions appears below. + +=head2 Implementations + +Each implementation of an algorithm can define any number of +properties. +For example, the default provider defines the property I +for all of its algorithms. +Likewise, the FIPS provider defines I and the legacy provider +defines I for all of their algorithms. + +=head2 Queries + +A I is a single conditional test. +For example, "fips=yes", "default!=yes" or "?iteration.count!=3". +The first two represent mandatory clauses, such clauses B 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 B section. +A I is a sequence of comma separated property query clauses. +The full syntax for property queries appears below. + +=head2 Lookups + +When an algorithm is looked up, a property query is used to determine +the best matching algorithm. +All mandatory query clauses B 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. + +=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. + +=head1 Syntax + +The lexical syntax in EBNF is given by: + + 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_]* )* + +Railroad diagrams for this grammar can be found in the +F file. + +=head1 HISTORY + +Properties were added in OpenSSL 3.0 + +=head1 COPYRIGHT + +Copyright 2019 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 +in the file LICENSE in the source distribution or at +L. + +=cut -- 2.40.0