Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Encrypting data

You can use REST API to perform operations related to data encryption that utilizes Encryption License Key.

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.

NoteIf the settings are specified so that an encryption environment for the storage system links with the key management server, you cannot use the REST API to perform the following operations:
  • 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

The workflow for using the REST API to perform operations to encrypt and use data stored in a volume of a storage system is as follows.
Specifying encryption environment settings

Specify settings for an environment used to encrypt data stored in a volume.

The following figure shows the workflow.

GUID-B7171B9F-1D0E-42BF-8F52-332AA651FE17-low.gif

  • 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.

Encrypting new data

The following describes how to create a volume, and then encrypt data to be newly written to the volume.

GUID-D9068145-7105-4137-B986-6D1D3C10CE75-low.gif

  • 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.

Encrypting existing data

The following describes how to encrypt the existing data stored in a volume.

GUID-D6752CE4-52A5-40AF-B3F8-7181F7E1448D-low.gif
  • 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).

Encrypting existing data without changing the drive configuration

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.

GUID-4557E943-818A-481E-9937-562F90939E9F-low.gif

  • 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).

Note
  • 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.

Getting information about the encryption environment settings

The following request gets information about the encryption environment settings.
Execution permission

Security Administrator (View & Modify)

Request line
GET base-URL/v1/objects/encryption-settings/instance
Request message
  • 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.

Response message
  • Body

    {
        "isEnabled": true,
        "detectsError": false
    }

    Attribute

    Type

    Description

    isEnabled

    boolean

    Whether the encryption environment is enabled

    • true: The encryption environment is enabled
    • false: 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.

Status codes

For details about the status codes of the request for this operation, see the description of HTTP status codes.

Coding example
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

You can change the encryption environment settings. If you change the settings to enable the encryption environment, encryption is applied. If you change the settings to disable the encryption environment, the encryption environment settings are initialized.
Note

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.

Execution permission

Security Administrator (View & Modify)

Request line
PATCH base-URL/v1/objects/encryption-settings/instance
Request message
  • 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 environment
    • false: Disables (initialize) the encryption environment
Response message
  • 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

Action template

None.

Status codes

For details on the status codes of the request for this operation, see the description of HTTP status codes.

Coding example
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

This request obtains the number of encryption keys.
Execution permission

Security Administrator (View Only)

Request line
GET base-URL/v1/objects/encryption-key-counts/instance
Request message
  • 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.

Response message
  • 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

Status codes

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.

Coding example
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

You can get information about a list of encryption keys.
Execution permission

Security Administrator (View Only)

Request line
GET base-URL/v1/objects/encryption-keys
Request message
  • 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 the endCreatedTime 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 the startCreatedTime parameter.

    This parameter is valid only if you specify DEK, FREE, or DEKANDFREE for the keyType parameter.

  • Body

    None.

Response message
  • 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 is CEK or KEK, a hyphen (-) is output.

    createdTime

    ISO8601string

    Date and time when the key was created

    If the value of the keyType attribute is KEK and the value of the keyGeneratedLocation attribute is DKC, a hyphen (-) is output.

    keyType

    string

    Type of the key

    • DEK: Encryption key

      The key is used to encrypt stored data.

    • CEK: Key for authentication

      This key is used to encrypt a certificate. It is also used when a DEK is stored in a DKB.

    • KEK: Key for encrypting keys

      This 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 not KEK, or if the value of the keyType attribute is KEK 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 system
    • KMS: Key management server

    numOfBackups

    int

    Number of times the key was backed up

    If the value of the keyType attribute is KEK, -1 is output, indicating an invalid value.

Status codes

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.

Coding example
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

You can get information about a specific encryption key by specifying the ID of the key. You can use this API request to get information about a key whose type is DEK or FREE. To get information about a key whose type is CEK or KEK, use the API request that gets information about a list of encryption keys.
Execution permission

Security Administrator (View Only)

Request line
GET base-URL/v1/objects/encryption-keys/object-ID
Request message
  • 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.

Response message
  • 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 key

      The 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 system
    • KMS: Key management server

    numOfBackups

    int

    Number of times the key was backed up

Status codes

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.

Coding example
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

You can create encryption keys by specifying the number of encryption keys you want to create. After creating an encryption key, be sure to back it up.
Note

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.

Execution permission

Security Administrator (View & Modify)

Request line
POST base-URL/v1/objects/encryption-keys
Request message
  • 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.

Response message
  • 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.

Status codes

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.

Coding example
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

You can delete unused (FREE) keys by specifying the ID of the key you want to delete. Keys whose type is CEK or DEK cannot be deleted.
Note

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.

Execution permission

Security Administrator (View & Modify)

Request line
DELETE base-URL/v1/objects/encryption-keys/object-ID
Request message
  • 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.

Response message
  • 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

Status codes

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.

Coding example
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

You can back up encryption keys to a file on the REST API client. In the request header of this API function, specify application/octet-stream for Accept.
Note
  • 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.

Execution permission

Security Administrator (View & Modify)

Request header

This API request downloads an encryption key file to the REST API client. Specify application/octet-stream for the Accept of the request header.

Request line
POST base-URL/v1/objects/encryption-keys/file/actions/backup/invoke
Request message
  • 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.

Response header

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

Response message
  • Body

    None.

Action template

None.

Status codes

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.

Coding example
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

You can restore encryption key file that was previously backed up. In the request header of this API function, specify multipart/form-data for Content-Type.
Note

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.

Execution permission

Security Administrator (View & Modify)

Request header

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.

Request line
POST base-URL/v1/objects/encryption-keys/file/actions/restore/invoke
Request message
  • 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.

Response message
  • 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.

Action template

None.

Status codes

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.

Coding example
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