Encrypting data
Overview of data encryption
You can use the Encryption License Key functionality to encrypt data stored in a volume of the storage system. If you encrypt data, you can prevent information leakage when hard disks in the storage system are replaced or the hard disks are stolen. Even if you encrypt data, the processing time or waiting time during I/O will not increase and the existing applications and infrastructure will not be affected.
With the REST API, you can use the Encryption License Key functionality if the storage system is VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.
The operations for data encryption to be performed by using the REST API are as follows:
-
Setting an encryption environment
You can use the REST API to change the encryption environment settings for the storage system or initialize the encryption environment.
-
Encrypting data to be stored in a volume
If you enable data encryption when creating a parity group and create a volume from the parity group, data to be stored in that volume is encrypted. In addition, if you migrate exiting volumes to the volume, the data stored in these existing volumes can also be encrypted.
-
Managing encryption keys
You can use the REST API to manage encryption keys used to encrypt and decrypt data. Encryption keys are automatically created when an encryption environment is enabled for the first time. You can create a new key if unassigned keys become insufficient due to replacement of a drive, or delete unnecessary unassigned keys. In addition, you can back up encryption keys to a REST API client and restore them if needed.
- Change or get the encryption environment settings
- Create or delete encryption keys
- Back up or restore encryption keys
For details on the Encryption License Key functionality such as the encryption specifications and system requirements, see the Encryption License Key User Guide.
Workflow for operations related to data encryption
Specify settings for an environment used to encrypt data stored in a volume.
The following figure shows the workflow.
Installing software
Install the license key for the Encryption License Key software.
Installing the encryption disk board (DKB)
Install the encryption DKB.
Changing the encryption environment settings
Enable the encryption environment settings.
Backing up an encryption key
When you enable the encryption environment settings and create an encryption key, you need to back up the encryption key.
The following describes how to create a volume, and then encrypt data to be newly written to the volume.
Creating a parity group
Create a parity group for which data encryption is enabled (specify true for the attribute
isEncryptionEnabled
).Creating a volume
Create a volume by specifying the parity group for which data encryption is enabled.
When using a DP volume
Creating a pool
Create a pool by specifying volumes whose data is encrypted.
Creating a volume
Create a DP volume by specifying a pool consisting only of volumes whose data is encrypted.
Setting the LU path
Specify the LU path from the host to the volume.
The following describes how to encrypt the existing data stored in a volume.
Creating a parity group
Create a parity group for which data encryption is enabled (specify true for the attribute
isEncryptionEnabled
).Creating a volume
Create a volume by specifying the parity group for which data encryption is enabled.
When using a DP volume
Creating a pool
Create a pool by specifying volumes whose data is encrypted.
Creating a volume
Create a DP volume by specifying a pool consisting only of volumes whose data is encrypted.
Creating a pair to be used for Volume Migration
Create a pair by specifying the volume whose data is to be encrypted as the source volume (P-VOL). For the target volume (S-VOL), specify a volume created from a parity group for which data encryption is enabled.
Performing migration
Perform migration to copy the data of the source volume (P-VOL) that is to be encrypted to the target volume (S-VOL).
The following describes how to encrypt the data in a volume in a parity group for which data encryption is disabled, without changing the drive configuration.
Creating a pair to be used for Volume Migration
Create a pair to which to back up the data to be encrypted, by specifying a volume in one parity group as the source volume (P-VOL). For the target volume (S-VOL), specify a volume in another parity group as the destination volume for the volume to be backed up.
Performing migration
Back up (migrate) the data of the source volume (P-VOL) to the target volume (S-VOL).
Deleting a parity group
Verify that the data has been migrated, and then delete the parity group.
Creating a parity group
Create a parity group for which data encryption is enabled (specify true for the attribute
isEncryptionEnabled
).Creating a volume
Create a volume by specifying the parity group for which data encryption is enabled.
When using a DP volume
Creating a pool
Create a pool by specifying volumes whose data is encrypted.
Creating a volume
Create a DP volume by specifying a pool consisting only of volumes whose data is encrypted.
Creating a pair to be used for Volume Migration
Create a pair by specifying the migrated volume as the source volume (P-VOL) to be encrypted. For the target volume (S-VOL), specify a volume created from a parity group for which data encryption is enabled.
Performing migration
Restore (migrate) the data of the source volume (P-VOL) to be encrypted to the target volume (S-VOL).
Use the following method to check whether the data in a volume is encrypted.
- To check a basic volume:
Get information about the volume by running the API request for getting information about a specific volume.
If ENCD is output for the
attributes
attribute, this indicates that the data in the volume is encrypted. - To check a DP volume:
Get information about a list of volumes that make up a pool, by running the API request for getting volume information with the pool number specified for the query parameter
poolId
.If ENCD is output for the
attributes
attribute of each pool volume that makes up the pool, this indicates that the data in the DP volume is encrypted.
- To check a basic volume:
Getting information about the encryption environment settings
Security Administrator (View & Modify)
GET base-URL/v1/objects/encryption-settings/instance
Object ID
Specify instance.
If an object has only one instance, the instance is the fixed value that specifies the object ID.
Query parameters
None.
Body
None.
Body
{ "isEnabled": true, "detectsError": false }
Attribute
Type
Description
isEnabled
boolean
Whether the encryption environment is enabled
true
: The encryption environment is enabledfalse
: The encryption environment is disabled
detectsError
boolean
Whether an error occurred while the encryption environment settings were being changed
true
: An error occurred.false
: No error occurred.
If this value is
true
, data encryption cannot be performed. Disable (initialize) the encryption environment settings by running the API request that changes the encryption environment settings, and then enable the encryption environment settings again.
For details about the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/encryption-settings/instance
Changing the encryption environment settings
If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.
Security Administrator (View & Modify)
PATCH base-URL/v1/objects/encryption-settings/instance
Object ID
Specify instance
If an object has only one instance, the instance is the fixed value that specifies the object ID.
Query parameters
None.
Body
{ "isEnabled": true }
Attribute
Type
Description
isEnabled
boolean
(Required) Specify whether to enable the encryption environment.
true
: Enables the encryption environmentfalse
: Disables (initialize) the encryption environment
Body
A job object is returned. For details on attributes other than
affectedResources,
see the section explaining job objects.Attribute
Description
affectedResources
URL of the encryption environment settings specified for the storage system
None.
For details on the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X PATCH --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/encryption-settings/instance
Getting the number of encryption keys
Security Administrator (View Only)
GET base-URL/v1/objects/encryption-key-counts/instance
Object ID
Specify instance.
If an object has only one instance, the instance is the fixed value that specifies the object ID.
Query parameters
None.
Body
None.
Body
{ "cek": 4, "dek": 12, "free": 1003 }
Attribute
Type
Description
cek
int
The number of certificate encryption keys (CEKs)
dek
int
The number of data encryption keys (DEKs)
free
int
The number of unused keys
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
This operation is not supported for the microcode version of the storage system. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/encryption-key-counts/instance
Getting information about a list of encryption keys
Security Administrator (View Only)
GET base-URL/v1/objects/encryption-keys
Object ID
None.
Query parameters
Parameter
Type
Filter condition
keyType
string
(Required) Type of keys for which information is to be obtained
- DEK
- CEK
- KEK
- FREE
- DEKANDFREE (DEK and FREE)
If you specify DEK, FREE, or DEKANDFREE for this parameter, you can specify other optional parameters.
startKeyId
int
(Optional) ID of the key from which to start getting information
Specify a value in the range from 0 to 4095.
This parameter is valid only if you specify DEK, FREE, or DEKANDFREE for the
keyType
parameter.If this parameter is omitted, 0 is assumed.
count
int
(Optional) Number of keys for which information is to be obtained
Specify a value in the range from 1 to 1024.
This parameter is valid only if you specify DEK, FREE, or DEKANDFREE for the
keyType
parameter.If this parameter is omitted, 1024 is assumed.
startCreatedTime
ISO8601string
(Optional) Information is obtained about keys that were created on or after the specified date and time.
Specify a value in YYYY-MM-DDThh:mm:ssZ format.
If you also specify the
endCreatedTime
parameter, specify a date and time that is earlier than the date and time specified for theendCreatedTime
parameter.This parameter is valid only if you specify DEK, FREE, or DEKANDFREE for the
keyType
parameter.endCreatedTime
ISO8601string
(Optional) Information is obtained about keys that were created on or before the specified date and time.
Specify a value in YYYY-MM-DDThh:mm:ssZ format.
If you also specify the
startCreatedTime
parameter, specify a date and time that is later than the date and time specified for thestartCreatedTime
parameter.This parameter is valid only if you specify DEK, FREE, or DEKANDFREE for the
keyType
parameter.
Body
None.
Body
{ "data": [ { "keyId": "6", "createdTime": "2018-10-29T04:32:26Z", "keyType": "DEK", "uuid": "-", "targetDeviceLocation": "HDD00-08", "keyGeneratedLocation": "DKC", "numOfBackups": 4 }, { "keyId": "7", "createdTime": "2018-10-29T04:32:26Z", "keyType": "DEK", "uuid": "-", "targetDeviceLocation": "HDD00-09", "keyGeneratedLocation": "DKC", "numOfBackups": 4 } ] }
Attribute
Type
Description
keyId
string
ID of the key
If the value of the
keyType
attribute isCEK
orKEK
, a hyphen (-) is output.createdTime
ISO8601string
Date and time when the key was created
If the value of the
keyType
attribute isKEK
and the value of thekeyGeneratedLocation
attribute isDKC
, a hyphen (-) is output.keyType
string
Type of the key
-
DEK
: Encryption keyThe key is used to encrypt stored data.
-
CEK
: Key for authenticationThis key is used to encrypt a certificate. It is also used when a DEK is stored in a DKB.
-
KEK
: Key for encrypting keysThis key is used to encrypt a CEK, a DEK, or a FREE key. Only one KEK exists for each storage system.
-
FREE
: Unused key that has not been assigned an encryption key
uuid
string
UUID of the key
If the value of the
keyType
attribute is notKEK
, or if the value of thekeyType
attribute isKEK
but no key management server is linked, a hyphen (-) is output.targetDeviceLocation
string
Device to which the key is assigned
- Location number of the drive (if the key type is DEK)
- Location number of the controller (if the key type is CEK)
- A hyphen (-) (if the key type is KEK or FREE)
keyGeneratedLocation
string
Location where the key was created
DKC
: Storage systemKMS
: Key management server
numOfBackups
int
Number of times the key was backed up
If the value of the
keyType
attribute isKEK
, -1 is output, indicating an invalid value.-
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
This operation is not supported for the microcode version of the storage system. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/encryption-keys?keyType=DEK
Getting a specific encryption key
Security Administrator (View Only)
GET base-URL/v1/objects/encryption-keys/object-ID
Object ID
Specify the value for
keyId
that you acquired by running the API request to obtain a list of encryption keys.Attribute
Type
Description
keyId
string
(Required) ID of the key
Query parameters
None.
Body
None.
Body
{ "keyId": "7", "createdTime": "2018-10-29T04:32:26Z", "keyType": "DEK", "uuid": "-", "targetDeviceLocation": "HDD00-09", "keyGeneratedLocation": "DKC", "numOfBackups": 4 }
Attribute
Type
Description
keyId
string
ID of the key
createdTime
ISO8601string
Date and time when the key was created
keyType
string
Type of the key
-
DEK
: Encryption keyThe key is used to encrypt stored data.
-
FREE
: Unused key that has not been assigned an encryption key
uuid
string
UUID of the key
A hyphen (-) is always output.
targetDeviceLocation
string
Device to which the key is assigned
- Location number of the drive (if the key type is DEK)
- A hyphen (-) (if the key type is FREE)
keyGeneratedLocation
string
Location where the key was created
DKC
: Storage systemKMS
: Key management server
numOfBackups
int
Number of times the key was backed up
-
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
The microcode version of the storage system does not support this operation. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/encryption-keys/7
Creating encryption keys
If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.
Security Administrator (View & Modify)
POST base-URL/v1/objects/encryption-keys
Object ID
None.
Query parameters
None.
Body
{ "count": 10 }
Attribute
Type
Description
count
int
(Required) The number of encryption keys to be created
Specify a value equal to or greater than 1.
If the sum of the value specified for the
count
attribute and the number of existing keys exceeds the maximum number of keys that can be created, no keys are created, and an error occurs.
Body
A job object is returned. See the description for the job object.
affectedResources
is not displayed for this API. To confirm that the encryption keys have been created, run the API request for obtaining the number of encryption keys or the API request for obtaining a list of encryption keys.
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
The microcode version of the storage system does not support this operation. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/encryption-keys
Deleting an encryption key
If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.
Security Administrator (View & Modify)
DELETE base-URL/v1/objects/encryption-keys/object-ID
Object ID
Specify the value for
keyId
that you acquired by running the API request to obtain a list of encryption keys.Attribute
Type
Description
keyId
string
(Required) The key ID
Query parameters
None.
Body
None.
Body
A job object is returned. For details on attributes other than
affectedResources,
see the section explaining job objects.Attribute
Description
affectedResources
The URL of the key that was deleted
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
The microcode version of the storage system does not support this operation. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X DELETE https://192.0.2.100/ConfigurationManager/v1/objects/encryption-keys/4
Backing up encryption keys
- When you create an encryption key, be sure to back it up. We also recommend that you periodically back up encryption keys.
-
If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.
Security Administrator (View & Modify)
This API request downloads an encryption key file to the REST API client. Specify application/octet-stream for the Accept of the request header.
POST base-URL/v1/objects/encryption-keys/file/actions/backup/invoke
Object ID
Specify a value for
file
.When backing up encryption keys to a file or restoring encryption keys from a file, the value of file is a fixed value (the object ID).
Query parameters
None.
Body
{ "parameters": { "password": "backuppassword" } }
Attribute
Type
Description
password
string
(Required) Password.
Specify a character string consisting of 6 to 255 characters.
You can use the following characters:
- Alphanumeric characters
-
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
You will need this password when you restore the encryption key.
This API request returns the following response header.
Header |
Description |
Content-Disposition |
attachment |
Content-Length |
The size of the backup data (in bytes) |
Content-type |
application/octet-stream |
Body
None.
None.
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
The microcode version of the storage system does not support this operation. |
curl -v -H "Accept:application/octet-stream" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/encryption-keys/file/actions/backup/invoke -o "backupfile.ekf"
Restoring encryption keys
If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.
Security Administrator (View & Modify)
In this API, the request body is sent in the format of multipart/form-data. Specify multipart/form-data for the Content-Type of the request header.
POST base-URL/v1/objects/encryption-keys/file/actions/restore/invoke
Object ID
Specify a value for
file
.When backing up encryption keys to a file or restoring encryption keys from a file, the value of
file
is a fixed value (the object ID).
Query parameters
None.
Body
Attribute
Type
Description
password
string
(Required) The password that was specified when the encryption key was backed up.
file
file
(Required) The backed-up encryption key file.
Specify the most recent backup file.
Encryption keys that are not up to date (for example, encryption keys that were changed after the file was backed up) cannot be restored.
Body
A job object is returned. For details on the schema of job objects, see the description of job objects. Note, however, that this API function does not display the
affectedResources
attribute.
None.
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.
Status code |
Message |
Description |
412 |
Precondition Failed |
The microcode version of the storage system does not support this operation. |
curl -v -H "Accept:application/json" -H "Content-Type: multipart/form-data" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -H "Expect:" -X POST -F "file=@C:\backupfile.ekf" -F "password=backuppassword" https://192.0.2.100/ConfigurationManager/v1/objects/encryption-keys/file/actions/restore/invoke