Registering the Policy Agent from the Windows Command Line

Before You Begin 

Make sure that you know:

  • The VM Encryption vault details. This is the vault you configured during the initial set up. See the Administration Guide.

  • The IP addresses of the Cryptographic Security Platform Vault for VM Encryption node with which you want to register the Policy Agent.

  • The login credentials for a Cryptographic Security Platform Vault for VM Encryption account with Cloud Admin privileges.
  • The name of the Cryptographic Security Platform Vault for VM Encryption Cloud VM Set with which you want to associate the VM. You cannot encrypt the drive until it has been associated with a Cloud VM Set in Cryptographic Security Platform Vault for VM Encryption. For details, see the Administration Guide.

Procedure 

  1. When you register the VM, you can either specify the Cloud VM Set you want to use interactively during the registration process or you can create a certificate for that Cloud VM Set in the Cryptographic Security Platform Vault for VM Encryption webGUI and then use that certificate during the registration process.

    To create the Cloud VM Set certificate:

    1. Log into the Cryptographic Security Platform Vault for VM Encryption using an account with Cloud Admin privileges.
    2. In the top menu bar, click Workloads.
    3. On the VM Sets tab, select the Cloud VM Set with which you want to associate the VM.
    4. Click Actions > Create New Certificate.
    5. If desired, enter a passphrase for the certificate. If you enter a passphrase here, you will need to enter that passphrase when you use the certificate on the VM.
    6. Enter a date on which this certificate should expire.

    7. Click Create. The Cryptographic Security Platform Vault for VM Encryption downloads a .cert file to the default download location.

      Important: Do not rename the downloaded certificate. The name of the certificate has additional information, and a renamed certificate will fail.

    8. If necessary, copy the .cert file to the Windows VM.
  2. Log into the VM using an account with Administrator privileges.
  3. Open a Windows Command prompt and navigate to the directory in which you placed the .cert file. If you do not have a .cert file, you can register the VM from the any directory.

  4. Register the VM with Cryptographic Security Platform Vault for VM Encryption using the following command:

    hcl register [-a] [-h vm-name] [-d "vm-description"] [-p cert-passphrase] [-o one-time-passphrase] [-z cvm-set] [-v vault_id] [-n mapping-name] [-N] kc-hostname[:port],kc-hostname2[:port],... [cert-file.cert]

    where:

    • -a — Indicates that you want to authenticate the VM through the command line or the script instead of through a certificate file. Use this option if you are using Simplified or Automated Authentication. If you created a certificate in Cryptographic Security Platform Vault, omit this option and specify the certificate name in cert-file.cert.
    • -h—The name of the VM that will be displayed in the Cryptographic Security Platform Vault for VM Encryption (Default: hostname).
    • -d—A description of the VM that will be displayed in the Cryptographic Security Platform Vault for VM Encryption.
    • -p—The passphrase assigned to the certificate when it was created. If you do not specify this parameter and the certificate has an associated passphrase, the registration process prompts you for the passphrase. Applies to Standard Authentication only.

    • -v (optional)—The Vault ID of the Vault that will be displayed in Vault Management. If you do not specify vault_id, you will be asked whether you want to enter vault_id or not.

    • -o—The one-time passphrase that will be used to encrypt the initial communication between this VM and the existing Cryptographic Security Platform Vault for VM Encryption cluster. If you do not specify this parameter, the registration process prompts you for the one-time passphrase. Applies to Standard Authentication only.

      Note: The passphrase is valid for 15 minutes from the time it is created. Make sure you authenticate the VM in Cryptographic Security Platform Vault during this time. Authentication will fail after the passphrase has expired.

    • -z—The name of the Cloud VM Set defined in the Cryptographic Security Platform Vault for VM Encryption cluster to which you want to assign this VM. Applies to Simplified or Automated Authentication only (the -a option must be specified on the hcl register command).
    • -n — The name of the Cluster Node Mapping that you want to associate with this VM. If you do not specify this option and one or more Cluster Node Mappings have been configured, the Policy Agent prompts you to select a Node Mapping from the list. If you do not want to use a Node Mapping, you must manually respond to this prompt. This option is mutually exclusive with the -N option, described below, and it requires that the -a option must be specified on the hcl register command.
    • -N—Tells the Policy Agent that you do not want to use a Cluster Node Mapping, even if one is available. If you specify both -N and -n, the Policy Agent ignores the -n option and does not assign a Node Mapping to the VM. Applies to Simplified or Automated Authentication only (the -a option must be specified on the hcl register command).

    • kc-hostname[:port],kc-hostname2[:port],... (required)—The list of IP addresses or hostnames for the Cryptographic Security Platform Vault nodes with which you want to register the VM. You must specify at least one Cryptographic Security Platform Vault node in this list. You must also specify a port if the Cryptographic Security Platform Vault nodes use anything other than the default port (443).

      If you are using the -n option to specify a Cluster Node Mapping, this IP address will be the Cryptographic Security Platform Vault for VM Encryption node that the VM contacts to retrieve the Node Mapping information. After the Node Mapping has been retrieved, the Policy Agent ignores any other IP addresses in this list and only registers the VM with the Cryptographic Security Platform Vault for VM Encryption nodes in the contained in the Node Mapping.

    • cert-file.cert—The name of the certificate file you copied to the target system if you are using Standard Authentication. If you are running the hcl register command from a directory other than the one where the .cert file resides, specify the full path to the .cert file as part of this option. If you did not create a certificate file in Cryptographic Security Platform Vault for VM Encryption, omit this option and use the -a option instead.

Registration Examples with Standard Authentication

If the VM name is "hq-vm-3", the description is "HQ Windows 2022 Server", and you want to register it using Standard Authentication with a Cryptographic Security Platform Vault for VM Encryption node at 10.238.32.74, you would enter:

C:\> hcl register -h hq-vm-3 -d "HQ Windows 2022 Server" 10.238.32.74 \F
      ad85837b-9862-11e1-afd5-000c29de5d41_120507163538.cert
You need to specify a passphrase that will be used for authentication with KeyControl
Enter passphrase (min 16 characters): passphrase16chars
			
Registered as hq-vm-3 with KeyControl node(s) 10.238.32.74
Please login to the KeyControl node to complete the authentication of this node

To register the VM in a single command where the .cert file resides in the directory /install/entrust/cert, you would enter:

C:\> hcl register -h hq-vm-3 -d "HQ Linux Server Alpha" -p certpassphrase \ 
      -o onetimepassword16chrsmin 10.238.32.74 \
      ./install/entrust/cert/ad85837b-9862-11e1-afd5-000c29de5d41_120507163538.cert

Registered as hq-vm-3 with KeyControl node(s) 10.238.32.74
Please login to the KeyControl node to complete the authentication of this node

Registration Examples with Simplified Authentication

In this example, the VM name is "hq-vm-3", the description is "HQ Windows 2022 Server", and the Cryptographic Security Platform Vault for VM Encryption node you want to use is at 10.238.66.250. You want to be prompted for the Cryptographic Security Platform Vault for VM Encryption Cloud Admin account information, the Cloud VM Set, and the Cluster Node Mapping.

In this case, you would enter:

C:\> hcl register -a -h hq-vm-3 -d "HQ Windows 2022 Server" 10.238.66.250

Do you want to register into a Vault?  (y/n) y
Please provide the vaultID
vaultid: d84243e7-d359-4179-9530-3497434e3192
Please provide the login details
username: CloudAdmin
password: 

Available Cloud VM Sets
--------------------------------------------------------------------------------
SF-Datacenter
--------------------------------------------------------------------------------

Please specify Cloud VM Set to which this VM should be added: SF-Datacenter
Registered as hq-vm-3 with KeyControl node(s) 10.238.66.250

Completing authentication for hq-vm-3 on KeyControl node(s) 10.238.66.250

Authentication complete, machine ready to use
Getting KeyControl Mapping information


This VM can be added to one of the following KeyControl Mappings
--------------------------------------------------------------------------------
1 : SF-Datacenter-Map
2 : West-Coast-Map
--------------------------------------------------------------------------------

Please select a numeric KeyControl Mapping ID (0 to skip): 1
KeyControl Mapping: SF-Datacenter-Map
server description First Node, ip 10.238.66.250, port 443
server description Second Node, ip 10.238.66.251, port 443
Updated KeyControl list with KeyControl nodes 10.238.66.250:443,10.238.66.251:443

To specify the name, description, Cloud VM Set and Cluster Node Mapping in a single command, you would enter:

C:\> hcl register -a -h hq-vm-3 -v d84243e7-d359-4179-9530-3497434e3192 -d "HQ Linux Server Alpha" -z SF-Datacenter -n SF-Datacenter-Map 10.238.66.250

Please provide the KeyControl login details
username: CloudAdmin
password: 
Registered as hq-vm-3 with KeyControl node(s) 10.238.66.250

Completing authentication for hq-vm-3 on KeyControl node(s) 10.238.66.250

Authentication complete, machine ready to use
Getting KeyControl Mapping information

KeyControl Mapping: SF-Datacenter-Map
server description First Node, ip 10.238.66.250, port 443
server description Second Node, ip 10.238.66.251, port 443
Updated KeyControl list with KeyControl nodes 10.238.66.250:443,10.238.66.251:443

Registration Example with Automated Authentication

If the VM name is "hq-vm-3", the description is "HQ Windows 2022 Server", and you want to register it using Automated Authentication with a Cryptographic Security Platform Vault node at 10.238.32.74, you would create a registration script containing the following command:

C:\> hcl register -a -h hq-vm-3 -v d84243e7-d359-4179-9530-3497434e3192 -d "HQ Windows 2022 Server" -u htcloudadmin -s 'DogDays123!' \
      10.238.32.74
Certificate passphrase might be required
Certificate successfully unpacked

Registered as hq-vm-4 with KeyControl node(s) 10.238.32.74
Completing authentication for hq-vm-4 on KeyControl node(s) 10.238.32.74
Authentication complete, machine ready to use

What to Do Next 

If you used Standard Authentication, authenticate the VM with Cryptographic Security Platform Vault for VM Encryption as described in Authenticating a New VM. If you used Simplified or Automated Authentication, encrypt the drive as described in Data Encryption Overview.