Encryption policy rules

In many respects encryption policy rules are handled like file placement rules:
  • An encryption policy that defines the encryption of new files and restored files must be installed into IBM Storage Scale with the mmchpolicy command.
  • An encryption policy is applied with the mmapplypolicy command.
  • When a file is created or restored, the encryption policy determines whether the file is to be encrypted and how it is to be encrypted.
  • Existing files are not encrypted. To encrypt a file that is currently not encrypted, copy it into a new file whose encryption policy rules dictate that the file is to be encrypted. Note that renaming a file does not change its encryption policy. The encryption policy is defined at the time that the file is created.
For more information, see Encryption policies and Overview of policies.
GPFS provides the following rules with which you can specify encryption policies:
ENCRYPTION IS
This rule is used to specify how a file is to be encrypted and how the FEK is to be wrapped.
The syntax of the ENCRYPTION IS rule is:
RULE 'RuleName' ENCRYPTION 'EncryptionSpecificationName' IS
    ALGO 'EncParamString'
    COMBINE 'CombineParamString'
    WRAP 'WrapParamString' 
    KEYS('Keyname'[, 'Keyname', ... ])
where:
ALGO EncParamString
specifies the encryption parameter string, which defines the following:
  • encryption algorithm
  • key length
  • mode of operation
  • key derivation function
The following encryption parameter strings are valid:
Table 1. Valid EncParamString values
Value Description
AES:128:XTS:FEK:HMACSHA512 Encrypt the file with AES in XTS mode. The FEK is 128 bits long and is preprocessed using HMAC with SHA-512.
AES:256:XTS:FEK:HMACSHA512 Encrypt the file with AES in XTS mode. The FEK is 256 bits long and is preprocessed using HMAC with SHA-512.
AES:128:CBC:FEK:HMACSHA512 Encrypt the file with AES in CBC mode. The FEK is 128 bits long and is preprocessed using HMAC with SHA-512.
AES:192:CBC:FEK:HMACSHA512 Encrypt the file with AES in CBC mode. The FEK is 192 bits long and is preprocessed using HMAC with SHA-512.
AES:256:CBC:FEK:HMACSHA512 Encrypt the file with AES in CBC mode. The FEK is 256 bits long and is preprocessed using HMAC with SHA-512.
COMBINE CombineParamString
specifies a string that defines the mode to be used to combine MEKs specified by the KEY statement.
The following combine parameter string values are valid:
Table 2. Valid combine parameter string values
Value Description
XORHMACSHA512 Combine MEKs with a round of XOR followed by a round of HMAC with SHA-512.
XOR Combine MEKs with a round of XOR.
WRAP WrapParamString
specifies a string that defines the encryption algorithm and the wrapping mode to be used to wrap the FEK.
The following wrapping parameter string values are valid:
Table 3. Valid wrapping parameter string values
Value Description
AES:KWRAP Use AES key wrap to wrap the FEK.
AES:CBCIV Use AES in CBC-IV mode to wrap the FEK.
KEYS ('Keyname'[, 'Keyname', ... ])
specifies one or more keys to be applied. Each Keyname is a unique identifier that combines the name of the key and the RKM server on which it resides. The format for Keyname is: 
KeyId:RkmId
where
KeyId
An internal identifier that uniquely identifies the key inside the RKM. Valid characters for KeyId are the following: 'A' through 'Z'; 'a' through 'z'; '0' through '9'; and '-' (hyphen). The minimum length of KeyId is one character; the maximum length is 60 characters.
RkmId
The identifier of the /var/mmfs/etc/RKM.conf entry for the RKM that manages the key. An RKM ID must be unique within the cluster, must be 1-21 characters in length, and can contain only the characters a - z, A - Z, 0 - 9, or underscore (_). The first character cannot be a numeral.
Notes:
  1. The maximum number of keys you can specify with the ENCRYPTION IS rule is eight.
  2. The number of keys that can be used to encrypt a single file is permanently limited by the inode size of the file system.
  3. You cannot specify the same key more than once in a given ENCRYPTION IS rule. Also, do not specify keys with identical values in an ENCRYPTION IS rule. Specifying the same key or identically-valued keys could result in a security breach for your data.
SET ENCRYPTION
The SET ENCRYPTION rule is similar to the SET POOL rule. If more than one such rule is present, all SET ENCRYPTION rules are considered and the FEK is wrapped once for each of the rules that apply (up to the maximum of eight). As mentioned in Encryption keys, if an FEK is wrapped multiple times, only one of the wrapped-FEK instances needs to be unwrapped for the file to be accessed.
If no SET ENCRYPTION rule is applicable when a file is created, the file is not encrypted.
The syntax of the SET ENCRYPTION rule is:
RULE 'RuleName' SET ENCRYPTION 'EncryptionSpecificationName'[, 'EncryptionSpecificationName',...]
    [FOR FILESET ('FilesetName'[,'FilesetName']...)]
    [WHERE SqlExpression]
where:
EncryptionSpecificationName
is the name of a specification defined by an ENCRYPTION IS rule.
To stop traversing policy rules at a certain point and encrypt using only those rules that have matched up to that point, use the SET ENCRYPTION EXCLUDE rule: 
RULE ['RuleName']  SET ENCRYPTION EXCLUDE
     [FOR FILESET ('FilesetName'[,'FilesetName']...)]
     [WHERE SqlExpression]
Note: Encryption policies do not support the ACTION clause.

Default encryption parameters

In addition to the values that are shown in Table 1, the ALGO parameter can also be followed by one of the following default values:
  • DEFAULTNISTSP800131A
    This value is equivalent to the following parameters:
    ALGO ’AES:256:XTS:FEK:HMACSHA512’
COMBINE ’XORHMACSHA512’
WRAP ’AES:KWRAP
  • DEFAULTNISTSP800131AFAST
    This value is equivalent to the following parameters:
    ALGO ’AES:128:XTS:FEK:HMACSHA512’
COMBINE ’XORHMACSHA512’
WRAP ’AES:KWRAP
The two default values have almost equivalent effects. The only difference is in the resulting length of the FEK. The FEK is 256 bits in the first default value but 128 bits in the second one. Of the two default values, DEFAULTNISTSP800131A is the better choice in most situations, because the 256-bit FEK provides better security. However, because of its shorter FEK, DEFAULTNISTSP800131AFAST provides a 5 - 20% speedup in workloads that involve large block random reads and direct I/O. It is available in the following IBM Storage Scale releases:
  • 5.0.1 and later
  • 5.0.0 with APAR IJ04786
  • 4.2.3 with APAR IJ04788
  • 4.1.1 with APAR IJ04789

Before you apply an encryption rule that contains -- DEFAULTNISTSP800131AFAST, ensure that all the nodes are at the required release or APAR number.

The following example shows the use of -- DEFAULTNISTSP800131A:
RULE ’somerule’ ENCRYPTION ’somename’ IS
ALGO ’DEFAULTNISTSP800131A’
KEYS(’KEY-2f1f7700-de74-4e55-a9be-bee49c5b3af8:RKMKMIP3’)

Do not use the COMBINE parameter or the WRAP parameter in the same rule with -- DEFAULTNISTSP800131A or -- DEFAULTNISTSP800131AFAST.

Example of an encryption policy

This is an example of an encryption policy:
RULE 'myEncRule1' ENCRYPTION 'E1' IS
         ALGO 'DEFAULTNISTSP800131A'
         KEYS('1:RKM_1', '2:RKM_2')

RULE 'myEncRule2' ENCRYPTION 'E2' IS
         ALGO 'AES:256:XTS:FEK:HMACSHA512'
         COMBINE 'XOR'
         WRAP 'AES:KWRAP'
         KEYS('3:RKM_1')

RULE 'myEncRule3' ENCRYPTION 'E3' IS
         ALGO 'AES:128:CBC:FEK:HMACSHA512'
         COMBINE 'XORHMACSHA512'
         WRAP 'AES:CBCIV'
         KEYS('4:RKM_2')

RULE 'Do not encrypt files with extension enc4'
         SET ENCRYPTION EXCLUDE
         FOR FILESET('fs1')
         WHERE NAME LIKE '%.enc4'

RULE 'Encrypt files with extension enc1 with rule E1'
         SET ENCRYPTION 'E1'
         FOR FILESET('fs1')
         WHERE NAME LIKE '%.enc1'

RULE 'Encrypt files with extension enc2 with rule E2'
         SET ENCRYPTION 'E2'
         FOR FILESET('fs1')
         WHERE NAME LIKE '%.enc2'

RULE 'Encrypt files with extension enc* with rule E3'
         SET ENCRYPTION 'E3'
         FOR FILESET('fs1')
         WHERE NAME LIKE '%.enc%'
Note:

In this example encryption policy:

  • All files in fileset fs1 are treated as follows:
    • If the extension is equal to enc4, the file is not encrypted. This happens because the ENCRYPTION EXCLUDE rule is matched first, stopping the traversal of the remaining rules before any additional matches can be made.
    • If the extension is equal to enc1, the file is encrypted with a 256-bit FEK, using AES in XTS mode; the FEK is preprocessed with HMAC with SHA-512, and the FEK is then wrapped twice:
      • once with AES key wrap, with keys 1:RKM_1 and 2:RKM_2 combined via one round of XOR followed by one round of HMAC with SHA-512
      • once with AES in CBC-IV mode using key 4:RKM_2

      This happens because both rules E1 and E3 apply, since extension enc1 matches both %.enc1 and %.enc%. Note that the encryption algorithms specified by rule E1, which grant a stronger security than those of rule E3, are chosen and applied.

    • If the extension is equal to enc2, the file is encrypted with a 256-bit FEK, using AES in XTS mode; the FEK is preprocessed with HMAC with SHA-512; and the FEK is then wrapped twice:
      • once with AES key wrap using key 3:RKM_1
      • once with AES in CBC-IV mode using key 4:RKM_2

      This happens because both rules E2 and E3 apply, since extension enc2 matches both %.enc2 and %.enc%.

    • If the extension is equal to enc3, the file is encrypted with a 128-bit FEK, using AES in CBC mode; the FEK is preprocessed with HMAC with SHA-512; and the FEK is then wrapped once with AES in CBC-IV mode using key 4:RKM_2.

      This happens because only rule E3 applies, since extension enc3 only matches %.enc%.

  • A GPFS node with access to both keys 1:RKM_1 and 2:RKM_2 or to key 4:RKM_2 can access a file with extension enc1.
  • A GPFS node with access to key 3:RKM_1 or to key 4:RKM_2 can access a file with extension enc2.
  • A GPFS node with access to key 4:RKM_2 can access a file with extension enc3.
  • No key is required to access a file with extension enc4.
  • A file with extension enc1 is securely deleted when either key 1:RKM_1 or 2:RKM_2 and key 4:RKM_2 are destroyed in their respective RKMs (and their cached copies have been flushed).
  • A file with extension enc2 is securely deleted when key 3:RKM_1 and key 4:RKM_2 are destroyed in their respective RKMs (and their cached copies have been flushed).
  • A file with extension enc3 is securely deleted when key 4:RKM_2 is destroyed in its respective RKM (and its cached copies have been flushed).
  • Once created, a file may not be encrypted with more MEKs, only with different MEKs using the REWRAP rule.

Rewrapping policies

Rewrapping policies are policies that change how a set of FEKs is encrypted by changing the set of MEKs that wrap the FEKs. Rewrapping applies only to files that are already encrypted, and the rewrapping operation acts only on the gpfs.Encryption EA of the files. Rewrapping is done by using the mmapplypolicy command to apply a set of policy rules containing one or more CHANGE ENCRYPTION KEYS rules. These rules have the form:

RULE 'ruleName' CHANGE ENCRYPTION KEYS FROM 'Keyname_1' to 'Keyname_2'
[FROM POOL 'poolName']
  [FOR FILESET(...)]
  [SHOW(...)]
  [WHERE ... ]
where:
  • Keyname_1 is the unique identifier of the MEK to be replaced. (See Encryption policy rules for Keyname format.)
  • Keyname_2 is the unique identifier of the new MEK, which replaces the old MEK identified by Keyname_1.
  • The FOR FILESET and WHERE clauses narrow down the set of affected files.

Both Keyname_1 and Keyname_2 are listed, and only the files that currently use Keyname_1 have their FEKs rewrapped with Keyname_2. Files that do not currently use Keyname_1 are not affected by the operation.

Notes:
  1. Only the first matching CHANGE ENCRYPTION KEYS rule is applied to each file. The rule rewraps each wrapped version of the FEK that was encrypted with the MEK in the CHANGE ENCRYPTION KEYS rule.
  2. The same MEK cannot be used more than once in a particular wrapping of the FEK.
Tip: The mmapplypolicy command always begins by scanning all of the files in the affected file system or fileset to discover files that meet the criteria of the policy rule. In the preceding example, the criterion is whether the file is encrypted with an FEK that is wrapped with the MEK Keyname_1. If your file system or fileset is very large, you might want to delay running mmapplypolicy until a time when the system is not running a heavy load of applications. For more information, see the topic Phase one: Selecting candidate files.