Encryption policy rules

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 42 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, you can also specify either of two default values following the ALGO keyword. These two values have the same effect as to policy, but the second value provides faster runtime performance in certain environments:
  • DEFAULTNISTSP800131A
  • DEFAULTNISTSP800131AFAST
    Note: DEFAULTNISTSP800131AFAST provides 5 - 20% speedup on workloads involving large block random reads and direct I/O by defaulting to 128-bit AES keys instead of 256-bit keys. It is available with IBM Spectrum Scale 5.0.1 and later. It is also available in earlier releases as an APAR:
    • 5.0.0 - IJ04786
    • 4.2.3 - IJ04788
    • 4.1.1 - IJ04789
    Before you apply an encryption rule that contains DEFAULTNISTSP800131AFAST, ensure that all the nodes are at the required release or APAR number.
In a policy rule, either of these default values is equivalent to the following parameters:
ALGO ’AES:256:XTS:FEK:HMACSHA512’
COMBINE ’XORHMACSHA512’
WRAP ’AES:KWRAP’
For example, the following two policy rules are equivalent:
  • This policy rule does not contain a default ALGO value and includes specific values for the COMBINE and WRAP terms:
    RULE ’somerule’ ENCRYPTION ’somename’ IS
    ALGO ’AES:256:XTS:FEK:HMACSHA512’
    COMBINE ’XORHMACSHA512’
    WRAP ’AES:KWRAP’
    KEYS(’KEY-2f1f7700-de74-4e55-a9be-bee49c5b3af8:RKMKMIP3’)
  • This policy rule contains the default ALGO value DEFAULTNISTSP800131A, which causes default values to be set for the ALGO, COMBINE, and WRAP terms:
    RULE ’somerule’ ENCRYPTION ’somename’ IS
    ALGO ’DEFAULTNISTSP800131A’
    KEYS(’KEY-2f1f7700-de74-4e55-a9be-bee49c5b3af8:RKMKMIP3’)
In the preceding code blocks, RKMKMIP3 is the RKM ID, which is defined in an RKM stanza in the RKM.conf file.
Note: You cannot use COMBINE or WRAP in a policy rule that contains a default ALGO value, because the default ALGO value generates its own default values for COMBINE and WRAP.

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.
Parent topic: Encryption