QlikWorld 2020 Global Conference. Join us to discover how to get the most from your data. Act fast. Register now and save.

Encryption certificates

Encryption keys are best managed through certificates. The certificates must be stored in a certificate store for the user running the Engine service, see User accounts.

Encryption keys

The encryption solution uses two types of keys:

  • Data encryption keys
  • Key encryption keys

Data encryption keys

Data encryption keys (DEK) are auto-generated keys for AES-256 encryption of the data. A new key is generated for each object that is encrypted.

Key encryption keys

Key encryption keys (KEK) are private and public key pair for secure, asymmetric encryption of the data encryption keys. The public key is used to encrypt the data and the private key is used to decrypt the data encrypted by the public key.

Note: Only keys using the RSA algorithm are supported.

The key used for key encryption is specified in the Qlik Management Console (QMC) Data encryption section of the Service cluster resource, see Service cluster.

It is stored in a Microsoft Cryptography Next Generation (CNG) Key Storage Provider. It is contained in a certificate stored in a Windows Certificate Store.

Specifying the key encryption key to use

Keys are best managed through certificates. The Qlik associative engine is configured by defining the encryption key thumbprint in QMC. Copy the value of the Thumbprint field from the certificate and paste it into the Encryption key field in the QMC.

Note: The certificate must be stored in a certificate store for the user running the Engine service.

Do the following:

  1. Open the Certificate Manager tool (certmgr.msc).
  2. Locate the certificate.
  3. Right click the certificate and select Open.
  4. On the Details tab, select the Thumbprint field and copy the value.
  5. In the QMC, paste the value into Service cluster > Data encryption > Encryption key, see Service cluster.

Qlik Sense Enterprise on Windows accepts Secure Hash Algorithm 1 (SHA-1) thumbprints in the 40-digit hexadecimal string form without spaces.

Example:  

If your certificate thumbprint contain spaces, like 56 38 88 bb 6a ea 55 eb 0d 33 d9 d8 b9 09 e0 d2 ef 26 ff bd, you enter it in the Encryption key field as follows:

563888bb6aea55eb0d33d9d8b909e0d2ef26ffbd
Note: If your organization has a key rotation policy, you may need to update the thumbprint definition when the key is changed.

Managing encryption certificates

There are many tools available for managing certificates but this documentation will focus on creating and distributing certificates using Windows PowerShell.

If other tools are used, the requirements are:

  • a RSA key is used
  • the key is stored in a CNG KeyStorageProvider
  • the certificate is stored in a certificate store for the user running the Engine
Note: Make sure to back up the certificate. You may not be able to open your app if the certificate is lost.

Creating encryption certificates

It is not necessary to use certificates issued by a certificate authority (CA), you might as well issue and sign your own self-signed certificates. Encryption certificates that you create must be stored in a certificate store for the user running the Engine service.

To create the new encryption certificate, use the New-SelfSignedCertificate cmdlet to create a self-signed certificate.

Syntax:  

PS C:\Users\johndoe.ACME> New-SelfSignedCertificate -Subject <Certifcate name> -KeyAlgorithm RSA -KeyLength <Key length, e.g.4096> -Provider "Microsoft Software Key Storage Provider" -KeyExportPolicy ExportableEncrypted -CertStoreLocation "cert:\CurrentUser\My"

New-SelfSignedCertificate cmdlet parameters

The following parameters should at minimal be defined when creating the certificate.

Note: For complete documentation, see the Microsoft New-SelfSignedCertificate documentation.

-Subject

Specifies the string that appears in the subject of the new certificate. This cmdlet prefixes CN= to any value that does not contain an equal sign. For multiple subject relative distinguished names (also known as RDNs), separate each subject relative distinguished name with a comma (,). If the value of the relative distinguished name contains commas, separate each subject relative distinguished name with a semicolon (;).

-Subject <Certifcate name>

-KeyAlgorithm

Specifies the name of the algorithm that creates the asymmetric keys that are associated with the new certificate. Must be RSA.

-KeyAlgorithm RSA

-KeyLength

Specifies the length, in bits, of the key that is associated with the new certificate.

-KeyLength <Key length, e.g.4096>

-Provider

Specifies the name of the KSP or CSP that this cmdlet uses to create the certificate. Should be Microsoft Software Key Storage Provider.

-Provider "Microsoft Software Key Storage Provider"

-KeyExportPolicy

Specifies the policy that governs the export of the private key that is associated with the certificate. The acceptable values for this parameter are:

  • Exportable
  • ExportableEncrypted (default)
  • NonExportable

-KeyExportPolicy ExportableEncrypted

-CertStoreLocation

Specifies the certificate store in which to store the new certificate. If the current path is Cert:\CurrentUser or Cert:\CurrentUser\My, the default store is Cert:\CurrentUser\My. Otherwise, you must specify Cert:\CurrentUser\My for this parameter.

-CertStoreLocation "cert:\CurrentUser\My"

Example: creating a data encryption certificate

In this example, the user called test is creating a self-signed exportable encrypted certificate with the subject MyTestCert and a key length of 4096 bits. The certificate is to be stored in Cert:\CurrentUser\My.

Type the following command in Microsoft PowerShell:

PS C:\Users\test> New-SelfSignedCertificate -Subject MyTestCert -KeyAlgorithm RSA -KeyLength 4096 -Provider "Microsoft Software Key Storage Provider" -KeyExportPolicy ExportableEncrypted -CertStoreLocation "cert:\CurrentUser\My"
PSParentPath: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 563888BB6AEA55EB0D33D9D8B909E0D2EF26FFBD CN=MyTestCert

Exporting encryption certificates

To export a encryption certificate, use the Export-PfxCertificate cmdlet.

Syntax:  

PS C:\Users\johndoe.ACME> Export-PfxCertificate -cert cert:\currentuser\My\<certificate thumbprint> -FilePath <FileName>.pfx -Password $mypwd

Export-PfxCertificate cmdlet parameters

The following parameters should at minimal be defined when exporting the certificate.

Note: For complete documentation, see the Microsoft Export-PfxCertificate documentation.

-cert

Specifies the path to the certificate to be exported.

-cert cert:\currentuser\My\<certificate thumbprint>

-FilePath

Specifies the path for the PFX file to be exported.

-FilePath <FileName>.pfx

-Password

Specifies the password used to protect the exported PFX file. The password should be in the form of secure string. This parameter must be specified, or an error will be displayed.

-Password <Password or variable>

Example: exporting a data encryption certificate

In this example the user called test will export the encryption certificate previously created to a PFX file.

  1. Create a secure string of the plain text password string and store it in the $mypwd variable. For this, use the ConvertTo-SecureString cmdlet.

    Type the following command in Microsoft PowerShell:

    PS C:\Users\test> $mypwd = ConvertTo-SecureString -String "MyPassword" -Force -AsPlainText
  2. Proceed with the actual exporting of the encryption certificate with thumbprint 563888bb6aea55eb0d33d9d8b909e0d2ef26ffbd using the Export-PfxCertificate cmdlet. The password variable created in the previous step is called to protect the exported PFX file.

    Type the following command in Microsoft PowerShell:

    PS C:\Users\test> Export-PfxCertificate -cert cert:\currentuser\My\563888bb6aea55eb0d33d9d8b909e0d2ef26ffbd -Filepath MyTestCert.pfx -Password $mypwd

When the certificate has been exported, the following is displayed in Microsoft PowerShell:

Directory: C:\Users\test Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 11/20/2019 11:21 4294 MyTestCert.pfx

Importing encryption certificates

To import a encryption certificate on for example other machines, use the Import-PfxCertificate cmdlet.

Syntax:  

PS C:\Users\johndoe.ACME> Import-PfxCertificate -CertStoreLocation cert:\currentuser\My -FilePath <FileName>.pfx [-Exportable] -Password $mypwd

Import-PfxCertificate cmdlet parameters

The following parameters should at minimal be defined when importing the certificate.

Note: For complete documentation, see the Microsoft Import-PfxCertificate documentation.

-CertStoreLocation

Specifies the path of the store to which certificates will be imported. If this parameter is not specified, then the current path is used as the destination store.

-CertStoreLocation cert:\currentuser\My

-FilePath

Specifies the path for the PFX file.

-FilePath <FileName>.pfx

-Exportable

Optional.

If specified, the parameter specifies whether the imported private key can be exported. If this parameter is not specified, then the private key cannot be exported.

-Exportable

-Password

Specifies the password for the imported PFX file in the form of a secure string.

-Password $mypwd

Example: importing a data encryption certificate

In this example the user called test2 will import the encryption certificate with thumbprint 563888BB6AEA55EB0D33D9D8B909E0D2EF26FFBD previously exported to a PFX file.

  1. Create a secure string of the plain text password string and store it in the $mypwd variable. For this, use the ConvertTo-SecureString cmdlet.

    Type the following command in Microsoft PowerShell:

    PS C:\Users\test2>  $mypwd = ConvertTo-SecureString -String "MyPassword" -Force -AsPlainText
  2. Proceed with the actual importing of the PFX file using the Import-PfxCertificate cmdlet. The password variable created in the previous step is called to access the PFX file.

    Type the following commands in Microsoft PowerShell:

    PS C:\Users\test2>  Import-PfxCertificate -CertStoreLocation cert:\currentuser\My -FilePath MyTestCert.pfx -Exportable -Password $mypwd

When the certificate has been exported, the following is displayed in Microsoft PowerShell:

PSParentPath: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 563888BB6AEA55EB0D33D9D8B909E0D2EF26FFBD CN=MyTestCert

Did this information help you?

Thanks for letting us know. Is there anything you'd like to tell us about this topic?

Can you tell us why it did not help you and how we can improve it?