Text reflow

Signed-off-by: Simo Sorce <[email protected]>

Author: simo5

working/doc/spec/digests.md

@@ -64,9 +64,10 @@ Mechanisms:
 
 ### Digest
 
-The digest mechanism, denoted **CKM_\<hash\>** where \<hash\> identifies a hash function as per table 137, is a mechanism for message
-digesting, following the hash function as per table 137, 
-defined in [FIPS PUB 180-4]^1^, [FIPS PUB 202]^2^ or [RFC 7693]^3^ respectively.
+The digest mechanism, denoted **CKM_\<hash\>** where \<hash\> identifies a hash
+function as per table 137, is a mechanism for message digesting, following the
+hash function as per table 137, defined in [FIPS PUB 180-4]^1^, [FIPS PUB
+202]^2^ or [RFC 7693]^3^ respectively.
 
 +------------------+----------------------------+-------------------------+-------------------------+
 | Mechanism        | Hash function              | Digest length in bits   | Digest length in bytes  |
@@ -112,9 +113,12 @@ table 138: Digest: Data Length
 
 ### Truncated Digest
 
-The truncated digest mechanism, denoted **CKM_SHA512_\<t\>**, is a mechanism for message
-digesting, following the Secure Hash Algorithm 
-defined in [FIPS PUB 180-4] section 5.3.6. It is based on a 512-bit message digest with a distinct initial hash value and truncated to \<t\> bits as per table 139. **CKM_SHA512_\<t\>** is the same as **CKM_SHA512_T** with a parameter value of \<t\>.
+The truncated digest mechanism, denoted **CKM_SHA512_\<t\>**, is a mechanism for
+message digesting, following the Secure Hash Algorithm defined in [FIPS PUB
+180-4] section 5.3.6. It is based on a 512-bit message digest with a distinct
+initial hash value and truncated to \<t\> bits as per table 139.
+**CKM_SHA512_\<t\>** is the same as **CKM_SHA512_T** with a parameter value of
+\<t\>.
 
 +------------------+-----------------+-------------------------+-------------------------+
 | Mechanism        | Hash function   | Truncated digest length | Truncated digest length |
@@ -130,7 +134,9 @@ table 139: Truncated digest: mechanisms and hash functions
 
 **CKM_SHA512_224** and **CKM_SHA512_256** do not have a parameter.
 
-**CKM_SHA512_T** has a parameter, a **CK_MAC_GENERAL_PARAMS**, which holds the value of t in bits. The length in bytes of the desired output should be in the range of 0-⌈t/8⌉, where 0 < t < 512, and t <> 384.
+**CKM_SHA512_T** has a parameter, a **CK_MAC_GENERAL_PARAMS**, which holds the
+value of t in bits. The length in bytes of the desired output should be in the
+range of 0-⌈t/8⌉, where 0 < t < 512, and t <> 384.
 
 Constraints on the length of input and output data are summarized in the
 following table. For single-part digesting, the data and the digest may begin at

working/doc/spec/hash_based_key_derivations.md

@@ -70,7 +70,12 @@ Mechanisms:
 
 ### Hash-based key derivation
 
-The hash-based key derivation mechanism, denoted **CKM_**\<hash\>**\_KEY_DERIVATION** or **CKM_**\<hash\>**\_KEY_DERIVE** where \<hash\> identifies a hash function or expansion function as per table 142 and as defined in [FIPS PUB 180-4]^1^, [FIPS PUB 202]^2^ or [RFC 7693]^3^ respectively, is a mechanism which provides the capability of deriving a secret key by digesting the value of another secret key with function \<hash\>. 
+The hash-based key derivation mechanism, denoted
+**CKM_**\<hash\>**\_KEY_DERIVATION** or **CKM_**\<hash\>**\_KEY_DERIVE** where
+\<hash\> identifies a hash function or expansion function as per table 142 and
+as defined in [FIPS PUB 180-4]^1^, [FIPS PUB 202]^2^ or [RFC 7693]^3^
+respectively, is a mechanism which provides the capability of deriving a secret
+key by digesting the value of another secret key with function \<hash\>. 
 
 +-------------------------------+----------------------------+-------------------------+
 | Mechanism                     | Hash function              | Digest length in bytes  |
@@ -113,20 +118,40 @@ The hash-based key derivation mechanism, denoted **CKM_**\<hash\>**\_KEY_DERIVAT
 +-------------------------------+----------------------------+-------------------------+
 table 142: Hash-based key derivation: mechanisms and hash / expansion functions
 
-The value of the base key is digested once, and the result is used to make the value of the derived secret key.
+The value of the base key is digested once, and the result is used to make the
+value of the derived secret key.
 
-* If no length or key type is provided in the template, then the key produced by this mechanism will be a generic secret key. Its length will be the digest length in bytes as per table 142.
-* If no key type is provided in the template, but a length is, then the key produced by this mechanism will be a generic secret key of the specified length.
-* If no length was provided in the template, but a key type is, then that key type must have a well-defined length. If it does, then the key produced by this mechanism will be of the type specified in the template. If it doesn’t, an error will be returned.
-* If both a key type and a length are provided in the template, the length must be compatible with that key type. The key produced by this mechanism will be of the specified type and length.
+* If no length or key type is provided in the template, then the key produced by
+  this mechanism will be a generic secret key. Its length will be the digest
+  length in bytes as per table 142.
+* If no key type is provided in the template, but a length is, then the key
+  produced by this mechanism will be a generic secret key of the specified
+  length.
+* If no length was provided in the template, but a key type is, then that key
+  type must have a well-defined length. If it does, then the key produced by
+  this mechanism will be of the type specified in the template. If it doesn’t, an
+  error will be returned.
+* If both a key type and a length are provided in the template, the length must
+  be compatible with that key type. The key produced by this mechanism will be
+  of the specified type and length.
 
-If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of the key will be set properly.
-If the requested type of key requires more than the digest length in bytes, an error is generated.
+If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of
+the key will be set properly.  If the requested type of key requires more than
+the digest length in bytes, an error is generated.
 
 This mechanism has the following rules about key sensitivity and extractability:
 
-* The **CKA_SENSITIVE** and **CKA_EXTRACTABLE** attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
-* If the base key has its **CKA_ALWAYS_SENSITIVE** attribute set to CK_FALSE, then the derived key will as well. If the base key has its **CKA_ALWAYS_SENSITIVE** attribute set to CK_TRUE, then the derived key has its **CKA_ALWAYS_SENSITIVE** attribute set to the same value as its **CKA_SENSITIVE attribute**.
-* Similarly, if the base key has its **CKA_NEVER_EXTRACTABLE** attribute set to CK_FALSE, then the derived key will, too. 
+* The **CKA_SENSITIVE** and **CKA_EXTRACTABLE** attributes in the template for
+  the new key can both be specified to be either CK_TRUE or CK_FALSE. If
+  omitted, these attributes each take on some default value.
+* If the base key has its **CKA_ALWAYS_SENSITIVE** attribute set to CK_FALSE,
+  then the derived key will as well. If the base key has its
+  **CKA_ALWAYS_SENSITIVE** attribute set to CK_TRUE, then the derived key has
+  its **CKA_ALWAYS_SENSITIVE** attribute set to the same value as its
+  **CKA_SENSITIVE** attribute.
+* Similarly, if the base key has its **CKA_NEVER_EXTRACTABLE** attribute set to
+  CK_FALSE, then the derived key will, too. 
 
-If the base key has its **CKA_NEVER_EXTRACTABLE** attribute set to CK_TRUE, then the derived key has its **CKA_NEVER_EXTRACTABLE** attribute set to the opposite value from its **CKA_EXTRACTABLE** attribute.
+If the base key has its **CKA_NEVER_EXTRACTABLE** attribute set to CK_TRUE, then
+the derived key has its **CKA_NEVER_EXTRACTABLE** attribute set to the opposite
+value from its **CKA_EXTRACTABLE** attribute.

working/doc/spec/hash_based_message_authentication_codes.md

@@ -1,8 +1,14 @@
 ## Hash-Based Message Authentication Codes (HMAC)
 
-HMAC mechanisms are mechanisms for signatures and verification, and for generation of HMAC keys.
-Refer to [RFC 2104] and [FIPS 198] for HMAC algorithm description. The HMAC secret key shall correspond to the PKCS #11 generic secret key type or the mechanism specific key types (see mechanism definition). Such keys for use with HMAC operations can be created using **C_CreateObject**, **C_GenerateKey**, or **C_UnwrapKey**.
-The RFC also specifies test vectors for the various hash function based HMAC mechanisms described in the respective hash mechanism descriptions. The RFC should be consulted to obtain these test vectors.
+HMAC mechanisms are mechanisms for signatures and verification, and for
+generation of HMAC keys.  Refer to [RFC 2104] and [FIPS 198] for HMAC algorithm
+description. The HMAC secret key shall correspond to the PKCS #11 generic secret
+key type or the mechanism specific key types (see mechanism definition). Such
+keys for use with HMAC operations can be created using **C_CreateObject**,
+**C_GenerateKey**, or **C_UnwrapKey**.  The RFC also specifies test vectors for
+the various hash function based HMAC mechanisms described in the respective hash
+mechanism descriptions. The RFC should be consulted to obtain these test
+vectors.
 
 +--------------------------------------+---------------------------------------------------+
 |                                      | Functions                                         |
@@ -184,12 +190,18 @@ Mechanisms:
 
 ### General-length HMAC
 
-The general-length HMAC mechanism, denoted **CKM_**\<hash>**\_HMAC_GENERAL**, where \<hash\> identifies a hash function or truncated hash function as per table 144 and as defined in [FIPS PUB 180-4]^1^, [FIPS PUB 202]^2^ or [RFC 7693]^3^ respectively, is a mechanism for signatures and verification. It uses the HMAC construction, based on the \<hash\> hash function. The keys it uses are generic secret keys and **CKK_**\<hash>**\_HMAC** keys.
+The general-length HMAC mechanism, denoted **CKM_**\<hash>**\_HMAC_GENERAL**,
+where \<hash\> identifies a hash function or truncated hash function as per
+table 144 and as defined in [FIPS PUB 180-4]^1^, [FIPS PUB 202]^2^ or [RFC
+7693]^3^ respectively, is a mechanism for signatures and verification. It uses
+the HMAC construction, based on the \<hash\> hash function. The keys it uses are
+generic secret keys and **CKK_**\<hash>**\_HMAC** keys.
 
 It has a parameter, a **CK_MAC_GENERAL_PARAMS**, which holds the length in bytes
-of the desired output. This length should be in the range 1-n, where len is the output size of the hash function in bytes as per table 144. Signatures (MACs)
-produced by this mechanism will be taken from the start of the full len-byte HMAC
-output.
+of the desired output. This length should be in the range 1-n, where len is the
+output size of the hash function in bytes as per table 144. Signatures (MACs)
+produced by this mechanism will be taken from the start of the full len-byte
+HMAC output.
 
 +-------------------------------+----------------------------+--------------------------+
 | Mechanism                     | Hash function              | Digest length in bytes   |
@@ -238,8 +250,9 @@ table 145: General-length HMAC: Key And Data Length
 
 ### HMAC
 
-The full-length HMAC mechanism, denoted **CKM_**\<hash\>**\_HMAC**, is a special case of
-the respective general-length **CKM_**\<hash\>**\_HMAC_GENERAL** mechanism in section 6.22.2.
+The full-length HMAC mechanism, denoted **CKM_**\<hash\>**\_HMAC**, is a special
+case of the respective general-length **CKM_**\<hash\>**\_HMAC_GENERAL**
+mechanism in section 6.22.2.
 
 It has no parameter, and always produces an output of length as per table 144.
 
@@ -250,8 +263,9 @@ key generation mechanism for NIST’s \<hash\>-HMAC.
 
 It does not have a parameter.
 
-The mechanism generates HMAC keys of key type **CKK_**\<hash\>**\_HMAC** with a particular length in bytes, as
-specified in the **CKA_VALUE_LEN** attribute of the template for the key.
+The mechanism generates HMAC keys of key type **CKK_**\<hash\>**\_HMAC** with a
+particular length in bytes, as specified in the **CKA_VALUE_LEN** attribute of
+the template for the key.
 
 The mechanism contributes the **CKA_CLASS**, **CKA_KEY_TYPE**, and **CKA_VALUE**
 attributes to the new key. Other attributes supported by the HMAC key