Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Microsoft SQL Server Extensible Key Management (EKM)

Advanced Topics

search

Advanced Topics

This section describes the following topics:

Securing Passphrase

A passphrase can be secured in the following three ways:

Obfuscated Passphrase

To obfuscate the passphrase and store the obfuscated value in the Passphrase parameter:

  1. Enable the passphrase obfuscation (i.e. set Passphrase_Encrypted=yes).

  2. Run the command line utility (PassPhraseSecure) from the command line, as shown below:

    <Installation_Directory>\utilities>PassPhraseSecure.exe
Please enter password :
0A24B7E51A0B1DF37979359FE5730CBC

The obfuscated value (0A24B7E51A0B1DF37979359FE5730CBC) gets stored in the Passphrase parameter.

The parameters with PassPhraseSecure Utility allows the user to give different inputs to the utility. Following are the parameters used:

  • PassPhraseSecure -txt <TextToBeObfuscated>: This parameter allows the user to provide input as text and display the obfuscated value.

    If the text to (be obfuscated) contains whitespaces then it must be provided within double quotes (" ").

    For example:

    <Installation_Directory>\utilities>PassPhraseSecure.exe -txt "hello, input to passpharase" 41058116C2572937869274FC1BD81EDB75AF95182F62870815220A3890B3BD6C

    The length of the text to be obfuscated must be <=1023 characters, excluding leading and trailing whitespaces. Any leading and trailing whitespaces are removed from the text before obfuscation.

  • PassPhraseSecure -file <FileName>: This parameter allows the user to provide input from a file and display the obfuscated value. The FileName could be the name and path of the file from which the text is to be obfuscated. For example:

    <Installation_Directory>\utilities>PassPhraseSecure.exe -file test.txt
66A09CF4974DB15B1E3C22F89912338E

    There exists no restriction on length of the file. However, only first line from the file is obfuscated irrespective of the file length.

  • PassPhraseSecure -help: This parameter displays the help, to use this utility, on the console. For example:

    <Installation_Directory>\utilities>PassPhraseSecure.exe -help
Usage :
Passphrase -help -- To print this help
Passphrase -txt <TextToBeObfuscated> -- Obfuscates the provided text
Passphrase -file <FileName> -- Obfuscates first line of the file provided in file name

    If user does not provide any parameter with the utility, the same -help parameter output is displayed.

Secured Passphrase

You can use the I_C_SetPassPhraseCallback() function to secure the passphrase. This function can be used to get the passphrase using a user-specified callback function.

The I_C_SetPassPhraseCallback() function can only be used when Passphrase_Encrypted=no. When the I_C_SetPassPhraseCallback() function is called, it sets the callback function to get the passphrase. In this case, the plaintext passphrase stored in the Passphrase parameter is ignored.

For Example: The following is an example of using secured passphrase functionality:

char str[100] = {0,};
char * getstring (void *arg)
{
printf("\nPlease enter password for private key [%s] : ",(char*)arg);
scanf("%s",str); // Some other way can be used to read secure password from User Interface
return str;
} // Before calling I_C_OpenSession, the following function should be called to set a
callback
for passphrase.
rc = I_C_SetPassPhraseCallback(getstring);
if (rc != I_E_OK)
{ fprintf(stderr, "
I_C_SetPassPhraseCallback error: %
s\n", I_C_GetErrorString(rc));
return rc;
}

This causes the password to be dynamically collected when reading Key_File while establishing SSL connection with the server. Here, getstring is the user-specified function that provides the user with a customized approach to secure/get the passphrase.

Plaintext Passphrase

When Passphrase_Encrypted is set to no, and the callback function is not used, the Passphrase parameter stores the password in plaintext for the private key. Storing the password in plaintext on the system is against a good security practice, as it might compromise the security of the private key.

It is strongly recommended to use secured or obfuscated passphrase.

Setting up SSL/TLS

CipherTrust Manager comes with pre-configured SSL settings. However, you can also configure the settings in accordance with your organizational needs.

Configuring SSL with CipherTrust Manager

Standard SSL communication requires a certificate that identifies the server. This certificate is signed by a certificate authority (CA) known to both the server and the client. During the SSL handshake, the server certificate is passed to the client. The client uses a copy of the CA certificate to validate the server certificate, thus authenticating the server.

It is recommended that you increase security only after confirming network connectivity. You should establish a TCP connection before enabling SSL. Otherwise, an unrelated network connection mistake could interfere with your SSL setup and complicate the troubleshooting process.

While the CA can be a third-party CA or your corporate CA, you will most likely use a local CA on the CipherTrust Manager appliance. If you are not using a local CA, consult your CA documentation for instructions on signing requests and exporting certificates.

To use an SSL connection when communicating with the CipherTrust Manager appliance, configure the server and the client.

To configure the server:

  1. Create a server certificate. (If you are using a cluster, each member must have its own, unique certificate). To create a server certificate, follow these steps:

    1. Creating a Local CA

    2. Creating a CSR on the console

    3. Signing a Certificate Request with a Local CA

  2. Make the certificate active. Refer to Activating the Server Certificate.

  3. Enabling SSL connection.

    1. Log on to the console as an administrator with Certificate Authorities access control.

    2. Navigate to Settings > Interfaces.

    3. Under Interface Configurations, edit NAE interface and select a TLS option in the Mode field. Available options are:

      1. TLS, allow anonymous logins, ignore client cert

      2. TLS, user must supply password, ignore client cert

      3. TLS, allow anonymous logins, verify client cert

      4. TLS, user must supply password, verify client cert

      5. Verify client cert, username taken from client cert, auth request is optional

      6. Verify client cert, password is needed, username in cert must match username in authentication request

Without TLS, any secret or message transmitted to and from the CipherTrust Manager through this interface could be compromised. Restart the CipherTrust Manager for these configuration changes to come into effect.

To configure the client, you must:

  1. Place a copy of the CA certificate on your client. Refer to Downloading a Local CA Certificate.

  2. Update the IngrianNAE.properties file as follows:

    Protocol=ssl
CA_File=<location and name of the CA certificate file>‌‌

Authenticating Server Certificate on CipherTrust Manager

This section describes the procedure to configure SSL for server certificate authentication.

Creating a Local CA‌‌

To create a local CA:

  1. Log on to the console as an administrator with Certificate Authorities access control.

  2. Click CA > Local CA.

  3. Under the Local Certificate Authorities section, click Local CA.

  4. On the Local CA window, enter the fields as needed.

  5. Click Create Local CA. It is added in the Pending CAs.

  6. From the Pending CAs list, click the local CA that you want to create. A window containing property and value of the CA displays.

  7. You can either self-sign Certificate Signing Request (CSR) or upload a certificate signed by an external CA.

    For uploading a certificate signed by an external CA, you must have installed the external CA certificate.

    Once the CA is verified, it is listed under the Local Certificate Authorities section.

    In the Local Certificate Authorities list, you can view Subject, Serial#, Activation, Expiration, and State.

    You can also delete, view certificate details, and download the local certificate.

    Only a local CA can sign certificate requests on CipherTrust Manager appliance. If you are using a CA that does not reside on CipherTrust Manager appliance you cannot use the console to sign certificate requests.

Downloading a Local CA Certificate‌‌

To download a local CA certificate from CipherTrust Manager appliance:

  1. Log in to the console as an administrator with Certificate Authorities access controls.

  2. Navigate to CA > Local Certificate Authorities, click the ellipsis icon, and select Download to download a local CA. You should place the CA certificate in a secure location and modify access appropriately.

    Update the following parameters in your IngrianNAE.properties file:

    Protocol=ssl
CA_File=<path to CA cert>\localca.crt

    • Use the CA_File parameter in the IngrianNAE.properties file to indicate the name and location of the CA certificate.
    ‌‌ • Use the CA_File parameter in the IngrianNAE.properties file to indicate the name and location of the CA certificate.

Creating a CSR on the Console‌‌

To create a certificate signing request on the console:

  1. Log on to the console as an administrator with Certificates access control.

  2. Click CA.

  3. Under the CSR Tool section, click Create CSR.

  4. On the Create CSR window, enter the fields as needed (Common Name is mandatory).

  5. Click Create. You'll be prompted with two options: save csr and save private key.

    1. Click save csr to save the CSR in the .pem format.

      You must save the Private Key to continue.

    2. Click save private key to save the private key in .pem format.

      For generation of public/private key pairs for server certificates only RSA algorithm is supported.

Signing a Certificate Request with a Local CA‌‌

To sign a certificate request with a local CA:

  1. Log in to the console as an administrator with Certificates access control.

  2. Navigate to CA > Local Certificate Authorities and click on the local CA from which you want to sign the CSR.

  3. Click Upload CSR.

  4. Copy the saved CSR in the previous section and paste it on the Upload Externally Generated CSR window. The copied text must include the header (-----BEGIN CERTIFICATE REQUEST-----) and footer (-----END CERTIFICATE REQUEST-----).

  5. From the Certificate Purpose list, select server.

  6. In the Duration in days field, enter the life span of the certificate. Enter minimum 365 days.

  7. Click Issue Certificate.

    The newly created certificate is listed under Parent Issuer. This certificate can be used as the server certificate for the NAE Server.

  8. Once the certificate has been issued, click the ellipsis icon, and select Download to download the certificate.

Activating the Server Certificate‌‌

To activate the server certificate:

  1. Log on to the Management Console as an administrator.

  2. Navigate to Settings > Interfaces.

  3. For NAE interface, click icon in the Action column.

  4. In the Local CA for Automatic Server Certificate Generation field, select Turn off auto generation from a local CA.

    In the Local CA for Automatic Server Certificate Generation field, if you select any CA then just click Update. It will automatically generate a server certificate and make it active.

  5. Expand Upload Certificate.

  6. In the Certificate text box, paste the server certificate, CA certificate, and key in the PEM format or base64 encoded PKCS#12 format.

    The list of certificates must be added from server cert to root ca in the ascending order. If there are any intermediate CAs, they can be added. The key can be anywhere. Maintaining this order is important: <server cert> <ca cert> <key>

  7. Select Format.

  8. Click Upload New Certificate and then click Update. Restart the application after uploading the certificate.

Authenticating Client Certificate on CipherTrust Manager

This SSL configuration requires that both the server and the client provide certificates. Each certificate is signed by a trusted CA known to both the server and the client. Most likely, you will use one CA to sign both the certificates. During the SSL handshake, the certificates are exchanged. Both the client and the server use the CA certificate to validate each others' certificate, thus authenticating the other party.

To enable client certificate authentication, you must first successfully configure SSL. Then, you must make additional configuration changes to the client and the server.

It is recommended that you increase security only after confirming network connectivity. You should establish a TCP connection before enabling SSL. Otherwise, an unrelated network connection mistake could interfere with your SSL setup and complicate the troubleshooting process.

To configure the client:

  1. Create a client certificate. This involves two steps:

    1. Generating a Client Certificate Request with OpenSSL

    2. Signing a Certificate Request and Downloading the Certificate

      You can create a certificate request using OpenSSL. You can then sign the request with the local CA on the CipherTrust Manager appliance. Once signed, the certificate request becomes a valid certificate.

      If you are not using a local CA, consult your CA documentation for instructions on signing requests and exporting certificates.

  2. Update the IngrianNAE.properties file as follows:

    Cert_File=<location and name of the client certificate> Key_File=<location and name of the client’s key file> Passphrase=<the passphrase used to unlock the client’s key file>

To configure the server, you must upload a CA certificate on the server.

Generating a Client Certificate Request with OpenSSL‌‌

To generate a client certificate request:

  1. Open the command window.

  2. If you are using OpenSSL, run the following command:

    openssl req -out clientreq -newkey rsa:2048 -keyout clientkey

    By default, both the certificate request and private key will be created in the working directory. You can generate them in another directory by including a location in the certificate request and key name.
    For example, to create them in the C:\client_certs directory, use the following command:
    openssl req -out C:\client_certs\clientreq -newkey rsa:2048 - keyout C:\client_certs\clientkey.

    The certificate request generation process will then request the following details:

    • A PEM passphrase to encode the private key: The passphrase that encodes the private key is the first passphrase you provide after issuing the above command. This will be the Passphrase parameter in the IngrianNAE.properties file.

    • The distinguished name: The distinguished name is a series of fields whose values are incorporated into the certificate request. These fields include country name, state or province name, locality name, organization name, organizational unit name, common name, and email address.

    • A challenge password: This challenge password is NOT used in the CipherTrust Manager environment.

    • An optional company name.

Signing a Certificate Request and Downloading the Certificate‌‌

This section describes how to sign a certificate request with a local CA and then download the certificate. You must download the certificate immediately after it is signed by the CA.

To sign a certificate request with a local CA:

  1. Log on to the console as an administrator with Certificate Authorities access controls.

  2. Navigate to CA > Local Certificate Authorities and click the local CA by which you want to sign the CSR.

  3. Click Upload CSR.

  4. Copy the CSR and paste it on the Upload Externally Generated CSR window. The copied text must include the header (-----BEGIN CERTIFICATE REQUEST-----) and footer (-----END CERTIFICATE REQUEST-----).

  5. From the Certificate Purpose list, select client.

  6. In the Duration in days field, enter the life span of the certificate. Enter minimum 365 days.

  7. Click Issue Certificate. The newly created certificate is listed under Parent Issuer.

  8. Click the image button to save the certificate on your local machine.

    You should place the certificate in a secure location and modify access appropriately.

  9. Update the following parameters in the IngrianNAE.properties file:

    Cert_File=<path to client cert>\client.crt Key_File=<path to client key>\clientkey
Passphrase=<the passphrase used to unlock the client's key file>

    Restart the database after updating the properties file for the changes to take effect.
    Use the Cert_File parameter in the IngrianNAE.properties file to indicate the name and location of the client certificate.

Using Versioned Keys

A versioned key maintains the same key metadata (key name, owner, algorithm, key size, etc.), but has a unique set of bytes for each version. Thus, each version is different enough for encryption purposes, but similar enough to allow for easy management.

A key can have a maximum of 4000 versions.

Each key version has its own key bytes, default IV, state, and creation date. The state determines which operations are available for a key version. Possible states are: active, restricted, and retired.

Versioned keys do not apply to KMIP.

  • Active: encryption and decryption and all key management options are allowed.

  • Restricted: only decryption operations are allowed.

  • Retired: no crypto operations are allowed. The key's state and group permissions determine how the key version can be used. Ultimately, a key version can only be used when the following are true:

  • The key version's state permits the operation.

  • The key's group permissions permit the operation.
  • The request comes from a member of the permitted group.

In remote mode, the key information for a key is fetched only once per session from the key manager.

Creating a Versioned Key

To create a global versioned key:

  1. Create an NAEParameterSpec object. To create a versioned key, the constructor needs the following parameters: name (String), exportable (boolean), deletable (boolean, versioned (boolean), length (int), attrs (CustomAttributes), session (NAESession).

    The only difference between creating a key and versioned key is that you must call the constructor that includes the versioned parameter. (And set it to true) Notice that this constructor also requires CustomAttributes and NAESession. You can set those to null if needed.

  2. Obtain an instance of KeyGenerator. Pass the key algorithm and provider name (IngrianProvider) as arguments.

  3. Initialize the cipher for encryption.

  4. Call the generateKey method of the KeyGenerator object to create the key.

    The following code sample generates a global AES key named "mykey".

    NAEParameterSpec spec = new NAEParameterSpec("mykey", true, true, true, 256, attrs, session);
KeyGenerator keygen = KeyGenerator.getInstance("AES", "IngrianProvider");
keygen.init(spec);
SecretKey aesKey = keygen.generateKey();

The first version of the key is automatically created.

Creating a New Version

To create a new key version:

  1. Create a new NAEKey object and call the getSecretKey method to get a key from the Key Manager. This must be a versioned key, otherwise the next step will fail with an NAEException.

  2. Call the generateVersion method of the NAEKey. This method returns an integer indicating the version number. You may want to capture that information. The new version is automatically put in the Active state. There can be no more than 4000 versions.

    NAEKey key = NAEKey.getSecretKey(keyName, session);
int newVersion = key.generateVersion();

The most active version of a key is always the default version.

Altering State of a Key Version

To change the state of a key version, call the modifyVersion method of the SecretKey. Pass the key version number and the new state as arguments.

// This line activates version of a key. Active version of a key can be used for encryption
// decryption, signing, sign verification, mac, and mac verification.aesKey.modifyVersion(4, "Active")
// This line restricts version of a key. Restricted version of a key can be used for decryption,
// sign verification, and macverification.
aesKey.modifyVersion(2, "Restricted")
// This line retires version of a key. Retired version of a key cannot be used for any crypto operation.
aesKey.modifyVersion(7, "Retired")

Using a Versioned Key to Encrypt, Sign, and MAC

To encrypt, sign, and generate MACs, your code must create an instance of a key. When using a versioned key, you can create an instance of the default version, a specific version, or all versions. The code is similar for each.

To access the default version of a versioned key, call the method the same way you access a non-versioned key. The Key Manager will return the latest active version.

// for encryption and MAC
NAEKey defaultVersion = NAEKey.getSecretKey(keyname, session);
// for sign
NAEPrivateKey defaultVersion = NAEKey.getPrivateKey(RSAkey, session);

To create an instance of a specific key version, you must append a # plus the version number. These statements will return version two of the key:

// for encryption and MAC
NAEKey secondVersion = NAEKey.getSecretKey(keyname+"#2", session);
// for sign
NAEPrivateKey secondVersion = NAEKey.getPrivateKey(RSAkey+"#2", session);

You can also create an instance of the key that contains all key versions:

// for encryption and MAC
NAEKey allVersions = NAEKey.getSecretKey(keyname+"#all", session);
// for sign
NAEPrivateKey allVersions = NAEKey.getPrivateKey(RSAkey+"#all", session);

This feature works for symmetric keys.

Using a Versioned Key to Decrypt, SignV, and MACV

When data is encrypted, signed, or MACed using a versioned key, the resulting ciphertext contains information in its header indicating which version of the key was used. This header is 3 bytes long. During decryption or verification, the Key Manager parses this information and applies the correct key version. There is no need to specify the key version.

If the data requires a retired key version, you will get an exception.

Exporting a Versioned Key

You can export the default version, a specific version, or all key versions. You cannot export retired versions of a versioned key.

To export the default version, simply call the NAEkey.export method for that key.

NAEKey key = NAEKey.getSecretKey(keyname, session);
KeyExportData keyData = key.export();

To export a specific version, you must append a # plus the version number. This statement will return version two of the key. The export method exports that version only.

NAEKey key = NAEKey.getSecretKey(keyname+"#2", session);
KeyExportData keyData = key.export();

To export all versions, call the NAEKey.export method and pass the boolean true. Place the values in an array.

NAEKey key = NAEKey.getSecretKey(keyname, session);
KeyExportData[] keyData = key.export(true);

On this page