Adabas Encryption for Linux

#### Search Results

Search

# Adabas Encryption for Linux

Adabas Encryption for Linux provides functionality to protect data-at-rest from unauthorized access. With Adabas Encryption for Linux, data-at-rest refers to container files, backup copies, PLOG files and other files created by Adabas, containing sensitive data container files and also PLOG and backup copies. Access to the information in these containers is controlled by means of encryption.

- Prerequisite

- Encryption of Data-At-Rest

- Key Management System

- Administration

- Database Access

## Prerequisite

A license for Adabas Encryption for Linux (AEL) is required.

## Encryption of Data-At-Rest

### Encryption Object

In the context of Adabas Encryption for Linux, data-at-rest refers to the following containers and files:

- ASSO

- DATA

- WORK

- TEMP

- SORT

- PLOG

- backup copies

- CMPDTA, DCUDTA, MUPDTA, ULDDTA (Compressed data)

- CMPDVT, MUPDVT, ULDDVT (Descriptor Value Table)

- MUPLOG and MUPLOB (Compressed data and LOB data)

- ORDEXP (Export copy)

### Encryption Algorithm

Encryption is the process of converting plain data into cipher text which cannot be deciphered without access to the encryption key.

Decryption is the process of converting encrypted data back to its original form. Decryption of encrypted data requires the key. Without the key the original information cannot be recovered.

Adabas Encryption for Linux supports Advanced Encryption Standard (AES) in XTS mode, a symmetric-key algorithm, where the same key is used for both processes, encrypting and decrypting the data.

XTS-AES with a key length of 128 and 256 bits are supported.

### Encryption Process

When formatting a database, the corresponding containers are encrypted according to the given parameters. All blocks written to disk are encrypted as well. Keys for encryption are managed by Adabas using the given Key Management System.

Note
Encryption cannot be disabled for existing databases. Encryption can only be undone by dumping and restoring a backup with the option ENCRYPTION=NO.

## Key Management System

A key management system (KMS), also known as a cryptographic key management system (CKMS) or enterprise key management system (EKMS), is an integrated approach for generating, distributing, and managing cryptographic keys for devices and applications.

Adabas currently supports the following types of key management systems:

- File-based management system on the local disk

- Microsoft Azure Key Management System

- Amazon AWS Key Management Service

- Google GCP Key Management Service

- HashiCorp Vault Key Management System

This section describes how Adabas uses the KMS.

Adabas provides the ADATED library for the cryptographic functionality. The KMS function of ADATED uses plugin libraries, also provided by Adabas, for each supported key management system.

Adabas uses two types of encryption keys, the key encryption key (KEK) and the encrypted data encryption key (DEK). The KEK encrypts the DEK, which in turn encrypts the data in the database. The advantage of using two keys is that you can regularly change the key encryption key, so only the data encryption key is decrypted and newly encrypted. The data itself does not have to be decrypted and encrypted again.

Important
If the KEK is lost or corrupted, the data in the database is also lost regardless of which KMS is used.

- File-Based Key Management System

- Amazon AWS Key Management System

- Microsoft Azure Key Management System

- Google GCP Key Management Service

- HashiCorp Vault Key Management System

### File-Based Key Management System

The file-based key management system uses a local disk file to store the key encryption keys. Database operations are performed only with the KMS file.

Select the file-based KMS by configuring the KMSTARGET=FILE parameter for either the ADAFRM or ADABCK utility when creating a database. The selected KMS type is stored in the database.

The file to store the keys is specified by the ADAKMSFILE environment variable. You can specify a fully qualified path name or directory name. The default location is $ADADATADIR/etc and the default file name is adatedkmsfile.db.

Important
If the Adabas file-based key management system is used, all Adabas utilities require access to the file $ADADATADIR/etc/adatedkmsfile.db. Otherwise an encrypted database becomes unusable.

The KMS file is stored encrypted in the file system. Nevertheless, access to it must be restricted with operating system features. File permissions must allow access only to the user/group that will run Adabas utilities.

| Warning: It is recommended to implement a dedicated backup strategy to have the file-based KMS available in case of a disaster recovery. Without the corresponding KEK, it is not possible to restore Adabas backup copies or use encrypted data. To avoid this effort and possible risks, cloud-based key management services should be preferred.

### Amazon AWS Key Management System

Amazon Web Services (AWS) provides a built-in key management service which you can use when Adabas is on an AWS virtual machine. The AWS KMS allows for the creation and storage of the key encryption key. The encrypted DEK is passed to the AWS KMS for decryption.

Select the AWS KMS by configuring the KMSTARGET=AWS parameter for either the ADAFRM or ADABCK utility when creating a database. The selected KMS type is stored in the database.

Within AWS, you must configure your virtual machine to be able to access the AWS Key Management System. The Adabas AWS plugin uses a number of AWS APIs and KMS resources, which are managed through AWS Identity and Access Management (IAM). To use the APIs and access the specific KMS resources you must create an IAM role with a permission policy. The IAM role must be assigned to an EC2 instance (Amazon Elastic Compute Cloud) so that the EC2 instance can assume that role during its lifetime. The IAM role can be used for multiple EC2 instances.

For more information on how to create an IAM role and assign it to an EC2 instance, see the AWS Identity and Access Management and Amazon Elastic Compute Cloud documentation.

### Microsoft Azure Key Management System

Azure provides a key management service for generating, storing, and accessing secrets, such as cryptographic keys. You can use this service when running Adabas in the Azure cloud. The cryptographic keys are stored and accessed in an Azure Key Vault. Adabas can use the Azure Key Management Service to store the keys used in an encrypted database.

To use the Azure Key Vault for Key Management purposes, specify KMSTARGET=Azure for either the ADAFRM or ADABCK utility when creating a database. The selected KMS type is stored in the database.

You must reference the key vault with the environment variable AZURE_KEY_VAULT.

    export AZURE_KEY_VAULT=<key-vault-name>

#### Authentication

To access the key vault, you must be an authenticated user with access rights. It is recommended to use a managed identity if Adabas is run on the Azure Cloud.

To create a managed identity:

- Go to the Azure Portal and navigate to the virtual machine or container Adabas is running on.

- Select Identity.

- In the tab System assigned, set the Status to On. This creates a service principal that is tied to the resource.

To authenticate multiple resources, you can use a User assigned managed identity. If you require a different form of authentication, visit the Azure resources.

#### Key Vault Access

The created security principal needs to be given access to the Azure Key Vault resource. You can do this on the Azure Portal.

- Navigate to the used Key Vault and select Access Policies.

- Click Create.

- From the Permissions, check Select all for Key Management Operations and Cryptographic Operations.

- Choose the created managed identity for authentication with the Key Vault.

- Create the access policy.

Note
As the Key Vault holds the key encryption key of your database, the access rights to this resource should be kept to a minimum.

For more information about the Azure Key Vault, managed identities, or authentication with Azure, you can visit Microsoft Learn.

### Google GCP Key Management Service

Google Cloud Portal (GCP) provides a key management service for generating, storing, and accessing secrets, such as cryptographic keys. This key management service can be used when running Adabas in the Google Cloud. The cryptographic keys are stored and accessed in a Google key ring. Adabas can use the Google Key Management Service to store the keys used in an encrypted database.

To use the key ring for key management purposes, specify the `KMSTARGET=GCP` parameter for either the ADAFRM or ADABCK utility when creating a database. The selected KMS type is stored in the database.

The key ring resource must be located in the same region as your virtual machine. You must reference the key ring with: `export GCP_KEY_RING=key-ring-name`

Within the GCP, you must configure your VM service account to be able to access the key ring resource. Ensure that the VM service account has access to the following permissions:

cloudkms.cryptoKeyVersions.create
cloudkms.cryptoKeyVersions.destroy
cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.list
cloudkms.cryptoKeyVersions.useToDecrypt
cloudkms.cryptoKeyVersions.useToEncrypt
cloudkms.cryptoKeys.create
cloudkms.cryptoKeys.get
cloudkms.cryptoKeys.list

Note
As the key ring holds the encryption key of your database, the access rights to this resource should be kept to a minimum.

For more information about the hierarchy of resources and roles within Cloud KMS, see the Google Cloud Key Management Service documentation.

### HashiCorp Vault Key Management System

HashiCorp Vault provides a key management service for generating, storing, and accessing secrets, such as cryptographic keys. Adabas uses Vault to securely manage cryptographic keys, particularly for encrypting databases.

Select the file-based KMS by configuring the `KMSTARGET=HCV` parameter for either the ADAFRM or ADABCK utility when creating a database. The selected KMS type is stored in the database.

#### Using the Vault Transit Engine with Adabas

To use Vault for key management, the following environment variables must be set:

`export HCV_VAULT_ADDR=<vault-address>`
`export HCV_AUTH_METHOD=<auth-method>`
`export HCV_BASE_PATH=<base-path>` # Required: Set the base path for transit and metadata
`export HCV_EXPIRATION_DAYS=<expiration-days>` # Optional: Set the number of days after which the key expires (Default: 7 days)

- The `HCV_BASE_PATH` is not optional and must be set. This path defines the base path for transit and metadata in Vault.

- The `HCV_EXPIRATION_DAYS` environment variable is optional. If not set, the default is 7 days. You can specify a different number of days for the key expiration. If set to 0, the key will be immediately deleted.

#### Automatic Path Mounting by Adabas

After configuring the `HCV_BASE_PATH`, Adabas automatically mounts the necessary paths in Vault for managing cryptographic keys. These paths are used for encryption operations in the Adabas database, ensuring seamless integration between Adabas and Vault.

#### Soft Deletion of Keys by Adabas

Adabas implements a Soft Deletion feature, allowing keys marked for deletion to be recovered within a specified time frame. This helps prevent accidental data loss and provides an additional layer of security.

1. Mark for Deletion: A key is marked for deletion but not removed immediately.

2. Recovery: The deleted key can be restored within the specified recovery period.

3. Permanent Deletion: After the recovery period expires, the key is automatically permanently deleted.

Note
Adabas will show the keys, and once the key is marked for deletion and the recovery period has expired, these keys will be automatically deleted from Vault when displayed by Adabas.

#### Authentication and Access Control

To use Vault, Adabas must authenticate either via AppRole or UserPass. The relevant environment variables must be set:

#### AppRole Authentication

For AppRole authentication, the following environment variables must be set:

- `HCV_ROLE_ID`: The Role ID for AppRole authentication.

- `HCV_SECRET_ID`: The Secret ID for AppRole authentication.

- `HCV_APPROLE_PATH`: The path where the AppRole is configured (e.g., approle).

#### Example:

`export HCV_ROLE_ID=<role-id>`
`export HCV_SECRET_ID=<secret-id>`
`export HCV_APPROLE_PATH=<approle-path>`

#### UserPass Authentication

For UserPass authentication, the following environment variables must be set:

`HCV_USERNAME`: The username for authentication.
`HCV_PASSWORD`: The password for the user.
`HCV_USERPASS_PATH`: The path where the UserPass authentication is configured (e.g., userpass).

#### Example:

`export HCV_USERNAME=<username>`
`export HCV_PASSWORD=<password>`
`export HCV_USERPASS_PATH=<userpass-path>`

#### Vault Policies

It is highly recommended to grant AppRole or UserPass users only the minimum necessary rights. Use appropriate Vault Policies to restrict access to sensitive data to the minimum required. The Principle of Least Privilege should be strictly followed to ensure that only authorized entities can access keys and other resources.

#### Important Note on Access Control

Vault uses policies to control which users and applications can access specific resources. Policies allow you to define precisely which permissions are required for key operations such as create, read, update, delete, and list.

#### Example of a Vault Policy

Here is an example of a Vault policy that restricts access to the necessary paths:

    # Required permissions for AppRole or UserPass authentication
    path "sys/mounts/*" {
      capabilities = ["create", "read", "update", "delete", "list"]
    }

    path "<HCV_BASE_PATH>/*" {  # Replace <HCV_BASE_PATH> with your specific base path
      capabilities = ["create", "read", "update", "delete", "list"]
    }

#### Security Notes

It is recommended to restrict access to Vault and the associated key resources to authorized users and machines only. Apply the principle of least privilege and ensure that only users and applications that genuinely need access to the keys have it. A regular review of access rights should also be conducted to ensure no unnecessary permissions exist.

For detailed information on the Vault API, Vault policies and other Vault configuration options, please refer to the official HashiCorp Vault Documentation.

## Administration

### Database Creation

Adabas automatically creates a new KEK with a unique name (KEKNAME) within the KMS. The KMS API provides a function to create an encrypted DEK. Adabas stores the encrypted DEK along with the unique KEKNAME of the corresponding KEK and other encryption related settings in the ASSO1 container file.

Encrypted databases are created with Adabas utilities ADAFRM and ADABCK.

- ADAFRM

  The control parameters ENCRYPTION and KMSTARGET specify the encryption algorithm and the key management system to be used. The container files are encrypted according to the parameter values.

      ADAFRM	ENCRYPTION=AES_256_XTS | AES_128_XTS
              KMSTARGET=FILE (default) | AWS | Azure | GCP | HCV

  #### Example 1:

  The following example shows how to create an encrypted database with the encryption algorithm AES_256_XTS. The Adabas file-based key management system is used (default: KMSTARGET=FILE)

      adafrm dbid=100 datasize=100 assosize=100 worksize=100 encryption=aes_256_xts

- ADABCK RESTORE/OVERLAY

  The control parameters ENCRYPTION and KMSTARGET specify the encryption algorithm and the key management system to be used. The container files are encrypted according to the parameter values.

  As the target database is created and containers are encrypted, it must not already exist. For existing databases, these ADABCK control parameters ENCRYPTION and KMSTARGET will be rejected. An existing database will always retain its encryption settings, even in the case of "no encryption".

      ADABCK	ENCRYPTION=AES_256_XTS | AES_128_XTS
              KMSTARGET=FILE (default) | AWS | Azure | GCP | HCV

  #### Example 1:

  The following example shows how to restore an encrypted database with the encryption algorithm AES_256_XTS from an non-encrypted Adabas backup copy. The Adabas file-based key management system is used (default: KMSTARGET=FILE). In this example, BCK001 is a backup copy of a non-encrypted database.

      adabck dbid=100 restore=* encryption=aes_256_xts

  #### Example 2:

  The following example shows how to overlay an encrypted database with the encryption algorithm AES_128_XTS from an non-encrypted Adabas backup copy. The Adabas file-based key management system is used. In this example, BCK001 is a backup copy of a non-encrypted database.

      adabck dbid=100 overlay=* encryption=aes_128_xts kmstarget=file

  Note
  The control parameter ENCRYPTION is rejected if the database to be created already exists.

### Creating a Non-encrypted Database from an Encrypted Database

ADABCK, can be used to restore or overlay a non-encrypted database from the backup of an encrypted database.

- #### ADABCK

      ADABCK 	ENCRYPTION=NO

  #### Example:

  The following examples show how to restore or overlay a non-encrypted database from an Adabas backup copy of an encrypted database. In these examples, BCK001 is a backup copy of an encrypted database.

      adabck dbid=100 overlay=* encryption=no

      adabck dbid=100 restore=* encryption=no

### Database Report

The encryption settings include the encryption algorithm, the key management system and name of the key encryption key.

The ADAREP control parameter SUMMARY shows the encryption settings of an encrypted database.

The ADABCK control parameter SUMMARY shows the encryption settings of an Adabas backup copy of an encrypted database.

- #### ADAREP

      ADAREP SUMMARY

  #### Example:

  The following example shows the encryption settings of an encrypted database.

      adarep dbid=100 summary
      %ADAREP-I-STARTED,      02-MAY-2024 18:10:26, Version 7.3.0.0 (Linux 64Bit)
      %ADAREP-I-DBOFF, database 100 accessed offline
      Summary of Database 100           2-MAY-2024 18:10:26

      DATABASE NAME                    Database-100
      DATABASE ID                        100
      MAXIMUM FILE NUMBER LOADED           3
      SYSTEM FILES                         1 (CHK),     2 (SEC),     3 (USR)
      ACTUAL FILES LOADED                  3
      CURRENT PLOG NUMBER                  0
      CURRENT CLOG NUMBER                  0
      ENCRYPTION                       AES_256_XTS
      KMSTARGET                        FILE
      KEKNAME                          1714666215B382A0FD089977264681686464A029C3FA4497EE1EF150C0217295

      Container  Device      Extents in Blocks    Number of      Block    Total Size
        File     Type         from          to     Blocks        Size     (Megabytes)
      -------------------------------------------------------------------------------

       ASSO1     file            1      25,600       25,600      4,096         100.00

       DATA1     file            1       3,200        3,200     32,768         100.00

       WORK1     file            1       6,400        6,400     16,384         100.00

      -------------------------------------------------------------------------------
                                                                               300.00
                                                                               ======

      %ADAREP-I-IOCNT, 7 IOs on dataset ASSO
      %ADAREP-I-TERMINATED,   02-MAY-2024 18:10:26, elapsed time: 00:00:00

- #### ADABCK

      ADABCK SUMMARY

  #### Example:

  The following example shows the encryption settings of an encrypted database within a backup copy (BCK001).

      adabck summary
      2024-05-02 18:25:55 %ADABCK-I-STARTED,      02-MAY-2024 18:25:55, Version 7.3.0.0 (Linux 64Bit)
      Database dumped on  2-MAY-2024 18:25:50

      Database 100, Database-100

      Summary of Database 100           2-MAY-2024 18:25:55

      DATABASE NAME                    Database-100
      DATABASE ID                        100
      MAXIMUM FILE NUMBER LOADED           3
      SYSTEM FILES                         1 (CHK),     2 (SEC),     3 (USR)
      ACTUAL FILES LOADED                  3
      CURRENT PLOG NUMBER                  0
      CURRENT CLOG NUMBER                  0
      ENCRYPTION                       AES_256_XTS
      KMSTARGET                        FILE
      KEKNAME                          1714666215B382A0FD089977264681686464A029C3FA4497EE1EF150C0217295

      Container  Device      Extents in Blocks    Number of      Block    Total Size
        File     Type         from          to     Blocks        Size     (Megabytes)
      -------------------------------------------------------------------------------

       ASSO1     file            1      25,600       25,600      4,096         100.00

       DATA1     file            1       3,200        3,200     32,768         100.00

       WORK1     file            1       6,400        6,400     16,384         100.00

      -------------------------------------------------------------------------------
                                                                               300.00
                                                                               ======

      2024-05-02 18:25:55 %ADABCK-I-IOCNT, 1 IOs on dataset BCK001
      2024-05-02 18:25:55 %ADABCK-I-TERMINATED,   02-MAY-2024 18:25:55, elapsed time: 00:00:00

Both reports show the current encryption algorithm, the key management system and the name of the key encryption key.

### Database Backup and Restore

The Adabas backup copy of an encrypted database contains the encryption settings such as the encryption algorithm and key management system of the encrypted database. This data itself is not encrypted, while all database blocks within the backup copy are encrypted with the encryption settings of the database. The KMS containing the KEK of the database must be available to restore this backup.

#### Restore as new database

To restore the Adabas backup copy of an encrypted database as a new database you can

- omit the control parameter ENCRYPTION. The encryption settings are taken from the Adabas backup copy.

- specify the control parameter ENCRYPTION. The encryption settings are taken from the parameter.

To restore an Adabas backup copy of an encrypted database as a new non-encrypted database, set the control parameter ENCRYPTION=NO.

#### Restore to an existing database

To restore an Adabas backup copy to an existing database, whether encrypted or not encrypted, omit the control parameter ENCRYPTION. The data is restored according to the target database’s encryption settings.

## Database Access

Access to an encrypted database is transparent to the Adabas utilities and to the Adabas direct call interface. The data are encrypted on write access, and decrypted on read access, according to the database’s encryption settings.

### Adabas Utilities

For all ADABAS utilities when reading encrypted data, access is transparent. The goal in implementation was not to change utility syntax. This could not always be achieved and will be explained in more detailed in the corresponding utility pages. The current syntax changes include:

- ADAFRM can accept a dbid when using tempsize or sortsize.

- ADACMP can accept a dbid when compressing output from ADADCU.

### On this page

- Prerequisite
- Encryption of Data-At-Rest
- Key Management System
- Administration
- Database Access