CreateCredFile utility

This topic describes the credential file, and the CreateCredFile utility that you use to create the credential file.

Overview

Components and applications that require automated access to the Digital Vault use a credential file that contains the user’s Vault username and encrypted logon information.

The credential file contains sensitive logon information, so it’s important to restrict access and usage as much as possible to reduce potential hijacking of the file.

 

Make sure that you are familiar with the user’s Vault authentication details, because you must provide the correct logon credentials to generate the encrypted credential file.

Supported authentication types

Password

For password authentication, the credential file contains a user with CyberArk authentication that authenticates to the Vault using a username and a password. You can also use the following external authentication types along with password authentication.

Asymmetric keys

You can create a credential file that contains a key-pair combination and the CyberArk user for authenticating to the Vault.

Additional protection mechanisms

HSM device

The credential file secret can be encrypted by a HSM device. This can be used for password authentication.

Any PKCS#11 library is supported as long as it meets all of the following criteria:

  • The token must be a hardware token.

  • The token is accessible through the PKCS#11 interface.

  • Access to the token is only possible after supplying a PIN.

  • The token supports RSA 2048-bit key length.

  • The token must be able to perform encryption and key generation on hardware.

  • A 32-bit .dll must be used (64-bit is not supported).

DPAPI

The credential file secret can be encrypted by the Windows DPAPI mechanism, which can be used for both password and key-pair (asymmetric keys) credential files. The DPAPI mechanism can be used with machine and user level protections either separately or together.

Credential file security

The credential file is protected using the following mechanisms:

  • The encrypted password is changed daily, by default.

  • The encrypted secret is encrypted using an AES 256-bit key that contains the following materials:

    • Random salt that is stored in the credential file (512-bit). This randomness assures that each credential file is encrypted with a unique key.

    • Environmental key materials:

      Material type

      Description

      Application-based

      Unique materials that identify the application in the logon process.

      Machine-based

      Unique materials that identify the machine in the logon process.

      Component-based

      Unique materials that identify the component in the logon process.

    • The key is generated by a secure hash (SHA2-512) comprised of the above key materials.

  • You can protect your credential file even more by using the appropriate operating system permissions.

Create a credential file

Use the CreateCredFile utility to create a credential file from a command line prompt. The CreateCredFile utility is located in the component/application installation folder.

You can run the CreateCredFile utility from the same machine where it will be used, or you can copy the credential file to the component or application host machine after it is created.

 

In order to comply with the strongest security guidelines, create the credential file on the same machine where it will be used - not on a remote server.

You must use a valid password for the user when you create the credential file. Before creating the credential file, verify the following:

  • The user must use the CyberArk authentication method.

  • You have the correct username for the user.

  • The user is not currently being used by an active component/application.

  • The user is not suspended on all Vaults (Primary and Satellite Vaults).

  • You have reset the password to a known password.

To create a credential file:

  • Open the command prompt as an Admin user, and run the CreateCredFile utility with the relevant flags set.

    The CreateCredFile utility uses the following syntax:

     

    CreateCredFile <FileName> <command> [command parameters]

    For more information about command usage, see CreateCredFile utility examples.

    The credential file is created and saved in the current folder or the folder that you specified in the command. The following message appears:

    Command ended successfully

 

If you perform any hardware changes on the machine such as adding or replacing a network card, graphic card, disk, or OS license, you must re-create the credential file.

CreateCredFile utility examples

The examples used in these instructions run the utility from the CreateCredFile subfolder, and create a credential file called user.cred.

  1. Open the command prompt as an admin user.

  2. Run the CreateCredFile.exe utility with all the relevant flags set.

    • Windows syntax:

      • Human user syntax with HSM device (recommended):

         

        CreateCredFile.exe user.cred Password /username <username> /password <password> /ExePath <path> /IpAddress /Hostname /OSUsername <domain\user> /EntropyFile /DpapiMachineProtection /HSMProtection /DLLpath <path\pkcs11-provider.dll> /PIN <pin code> /InitToken

      • Human user syntax:

         

        CreateCredFile.exe user.cred Password /username <username> /password <password> /ExePath <path> /IpAddress /Hostname /OSUsername <domain\user> /EntropyFile /DpapiMachineProtection /DpapiUserProtection

      • Component or application user syntax with HSM device (recommended):

         

        CreateCredFile.exe user.cred Password /username <username> /password <password> /ExePath <path> /IpAddress /ClientHostname /OSUsername <domain\user> /AppType <Application ID> /HSMProtection /DLLpath <path\pkcs11-provider.dll> /PIN <pin code> /InitToken

      • Component or application user syntax:

         

        CreateCredFile.exe user.cred Password /username <username> /password <password> /ExePath <path> /IpAddress /Hostname /OSUsername <domain\user> /AppType <Application ID /EntropyFile /DpapiMachineProtection /DpapiUserProtection

      • Human user syntax on a remote server:

         

        This method is less secure, and shouldn't be used in a production environment.
         

        CreateCredFile.exe user.cred Password /username <username> /password <password> /OSUsername <domain\user> /NotSecure

      • Component or application user syntax on a remote server:

         

        This method is less secure, and shouldn't be used in a production environment.
         

        CreateCredFile.exe user.cred Password /username <username> /password <password> /OSUsername <domain\user> /AppType <Application ID> /NotSecure

    • *NIX syntax:

      • Human user syntax:

         

        ./CreateCredFile user.cred password -username <username> -password <password> -exepath <path> -hostname -osusername <domain\user> -entropyfile

      • Component or application user syntax:

         

        ./CreateCredFile user.cred password -username <username> -password <password> -exepath <path> -hostname -osusername <domain\user> -entropyfile -apptype <Application ID>

      • Human user syntax on a remote server:

         

        This method is less secure, and shouldn't be used in a production environment.
          CreateCredFile user.cred password -username <username> -password <password> -osusername <user> -notsecure

      • Component or application user syntax on a remote server:

         

        This method is less secure, and shouldn't be used in a production environment.
          CreateCredFile user.cred password -username <username> -password <password> - osusername <user> -apptype <Application ID> -notsecure

         

 

To apply LDAP or RADIUS authentication or other configurations, see CreateCredFile parameters for more details.
 

Only use this option if instructed by CyberArk.

  1. At the command line prompt, run the CreateCredFile.exe utility.

     

    CreateCredFile.exe user.cred KeyPair /username <username> /ExePath <path> /IpAddress /Hostname /OSUsername <domain\user> /EntropyFile /DpapiMachineProtection /DpapiUserProtection

The above example creates a credential file with a generated encrypted private key.

 

Only use this option if instructed by CyberArk.

Using the Convert option allows you to upgrade the credential file version to the latest one but does not improve security. To improve security, you must create a new credential file.

After you upgrade to version 12.2 or later, if you log on using the existing credential file, the credential file will be automatically converted to the latest version (version 3).

To manually convert a credential file to the latest version, run the following command:

  1. At the command line prompt, run the CreateCredFile.exe utility.

     

    CreateCredFile.exe user.cred Convert /AppType <ApplicationID>/ExePath <path> /OSUsername <domain\user>
 

You must specify one or more of the following flags with the same values given in the original credential file:

  • /AppType

  • /OSUsername

  • /ExePath

The above example converts the user.cred file to the latest version, and renames the previous file to user.cred.old.

Specify applications

You can specify the CyberArk applications or utilities in a credential file.

Component

Application user

Application ID

CPM

Central Policy Manager

CPM

PVWA

Password Vault Web Access gateway user

PVWAApp

Password Vault Web Access application user

PVWAApp

OPM

OPM application user

AppPrv

PSM

Privileged Session Manager application user

PSMApp

Privileged Session Manager gateway user

PSMGWApp

PSMP

 

 

AD Bridge application user

PSMPApp

PSMP application user

 PSMPApp

PSMP gateway user

 PSMPApp

Digital Vault

 

Disaster Recovery Application user

DR

Event Notification Engine

ENE

PrivateArk Client

PrivateArk Client application user

WINCLIENT

GUI

Secrets Manager

Credential Provider

AIMProvider

Synchronizer

AIMProvider

Telemetry

Telemetry

Telemetry

PTA

Privileged Threat Analytics

PTAAPP

Utility

Application user

Application ID

Replicate

CyberArk Backup and Restore application user

CABACKUP

CyberArk SDK

CyberArk CLI application user

PACLI

Export Vault Data

Export Vault Data application user

EVD

AccountUploader

Add accounts with SSH Keys

PACLI

CreateCredFile parameters

The following table contains credential file parameters for Windows.

Command

Parameter

Description

Mandatory

Filename

The name of the user credential file to create or update, specifically user.cred.

Yes

Password

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Indicates that the credential file is created with password authentication details.

Optional

/Username

Sets the username in the credential file.

Yes

/Password

The password that is encrypted and stored in the credential file.

Yes

/DisableSyncPassword
ToDR

Whether or not passwords in user credential files are replicated to all DR sites before they are replaced.
By default, this parameter is set to No, which makes sure that user credential files on all DR sites (if they exist) are synchronized with the Production Vault, and that users will be able to continue working with the Vault seamlessly after a failover. If this parameter is changed to Yes, passwords are replaced in credential files regardless of whether or not they have been replicated to all DR sites.

No

/ExternalAuth

The type of external authentication that is used to authenticate users to the Vault.

Valid values:

  • Radius: Creates a credential file for use with RADIUS server.

  • LDAP: Creates a credential file for use with an LDAP directory.

  • None: This credential file is not used with either a RADIUS server or an LDAP directory.

Default value: None

No

/AppType

A unique application ID that specifies the application that is able use this file. For a list of accepted values, see Specify applications above.

No

/ExePath

The full path of the executable that is able to use this file. Specify the full path.

No

/IpAddress

Specify this parameter to require the IP address of the current machine for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/Hostname

Specify this parameter to require the hostname of the current machine for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/OSUsername

The name of the operating system user who can use this file.

Specify the username in “domain_name\username” format.

When the application is executed as a Windows service that uses local system permissions, specify “nt authority\system”.

 

This parameter cannot be used in a Cluster environment.
 

The quotation marks are required because of the space in “nt authority”.

No

/MachineGUID

Specify this parameter to require the identifier of the current machine for user authentication.

 

This parameter cannot be used in a Cluster environment.
No

/DiskSignature

Specify this parameter to require the data storage device ID of the current machine for user authentication.

 

  • This parameter cannot be used in a Cluster environment.

  • Verify that this parameter works with your operating system before using it.

No

/EntropyFile

Specify this parameter to require the entropy file for user authentication. The Entropy file is created in the same directory as the credential file when you run the CreateCredFile utility.

No

/HSMProtection

Use HSM protection for user authentication.

 

This parameter is optional. If you use this parameter, you must include the mandatory sub-parameters.
  • /dllpath: Specifies the 32-bit .dll path used by the HSM client (mandatory)

  • /pin: Specifies the HSM pin code (mandatory)

  • /inittoken: Specify this parameter the first time HSM protection is used

No

/DPAPIMachineProtection

Uses the operating system DPAPI machine protection for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/DPAPIUserProtection

Uses the operating system DPAPI user protection for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/NotSecure

Indicates that the newly created credential file is not secure according to CyberArk best practices.

 

Use only when creating credential files on a remote server (not recommended).

 

Convert

 

 

 

Optional

/AppType

A unique application ID that specifies the application that can use this file. For a list of accepted values, see Specify applications above.

No

/ExePath

The full path of the executable that is able to use this file. Specify the complete path.

No

/OSUsername

The name of the operating system user who can use this file. Specify the username in “domain_name\username” format.

When the application is executed as a Windows service that uses local system permissions, specify “nt authority\system”.

 

This parameter cannot be used in a Cluster environment.
 

The quotation marks are required because of the space in “nt authority”.

No

KeyPair

Optional

/Username

Sets the username in the credential file.

Yes

/DisableSyncKeyToDR

Whether or not passwords in user credential files are replicated to all DR sites before they are replaced.

By default, this parameter is set to No, which makes sure that user credential files on all DR sites (if they exist) are synchronized with the Production Vault, and that users will be able to continue working with the Vault seamlessly after a failover. If this parameter is changed to Yes, passwords are replaced in credential files regardless of whether or not they have been replicated to all DR sites.

No

/ExePath

The full path of the executable that is able to use this file. Specify the full path.

No

/OSUsername

The name of the operating system user who can use this file. Specify the username in “domain_name\username” format.

When the application is executed as a Windows service that uses local system permissions, specify “nt authority\system”.

 

This parameter cannot be used in a Cluster environment.
 

The quotation marks are required because of the space in “nt authority”.

No

/IpAddress

Specify this parameter to require the IP address of the current machine for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/Hostname

Specify this parameter to require the hostname of the current machine for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/MachineGUID

Specify this parameter to require the identifier of the current machine for user authentication.

 

This parameter cannot be used in a Cluster environment.
No

/DiskSignature

Specify this parameter to require the data storage device ID of the current machine for user authentication.

 

  • This parameter cannot be used in a Cluster environment.

  • Verify that this parameter works with your operating system before using it.

No

/EntropyFile

Specify this parameter to require the entropy file for user authentication. The Entropy file is created in the same directory as the credential file when you run the CreateCredFile utility.

No

/DPAPIMachineProtection

Uses the operating system DPAPI machine protection for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/DPAPIUserProtection

Uses the operating system DPAPI user protection for user authentication.

 

This parameter cannot be used in a Cluster environment.

No

/NotSecure

Indicates that the newly created credential file is not secure according to CyberArk best practices.

 

Use only when creating credential files on a remote server (not recommended).

 

/?

Lists the available options.

Optional

The following table contains credential file parameters for *NIX.

Command

Parameter

Description

Mandatory

Filename

The name of the credential file to create or update, specifically user.cred.

Yes

Password

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Indicates that the credential file is created with password authentication details.

Yes

-username

Sets the username in the credential file.

Yes

-password

The password that is encrypted in the credential file.

Yes

-DisableSyncPassword
ToDR

Whether or not passwords in user credential files are replicated to all DR sites before they are replaced.
By default, this parameter is set to No, which ensures that user credential files on all DR sites (if they exist) are synchronized with the Production Vault, and that users can continue working with the Vault seamlessly after a failover. If this parameter is changed to Yes, passwords are replaced in credential files regardless of whether or not they have been replicated to all DR sites.

No

-externalauth

The type of external authentication that is used to authenticate users to the Vault.

Valid values:

  • -radius: Creates a credential file for use with RADIUS server.

  • -ldap: Creates a credential file for use with an LDAP directory.

  • -none: This credential file is not used with either a RADIUS server or an LDAP directory.

Default value: -none

No

-apptype

A unique application ID that specifies the application that can use this file. For a list of accepted values, see Specify applications above.

Yes

Note: For the cred file used for the installation of PSM for SSH and OPM, apptype is not used.

-exepath

The full path of the executable that can use this file. If the executable is executed from the PATH you can specify only the name of the executable. Otherwise, specify the complete path.

Yes

Note: For the cred file used for the installation of PSM for SSH and OPM, exepath is not used.

-ipaddress

Specify this parameter to require the IP address of the current machine for user authentication.

No

-hostname

Specify this parameter to require the hostname of the current machine for user authentication.

When this parameter is defined, the credential file specifies the hostname of the current machine and only authenticates the user to the Vault from a machine with the specified hostname.

No

-osusername

The name of the operating system user who can use this file. Specify only the username.

Yes

Note: For the cred file used for the installation of PSM for SSH and OPM, osusername is not used.

-machineguid

Specify this parameter to require the identifier of the current machine for user authentication.

No

Note: For the cred file used for the installation of PSM for SSH and OPM, machineguid is not used.

-entropyfile

Specify this parameter to require the entropy file for user authentication. The Entropy file is created in the same directory as the credential file when you run the CreateCredFile utility.

Yes

-hsmprotection

Use HSM protection for user authentication.

 

This parameter is optional. If you use this parameter, you must include the mandatory sub-parameters.

  • -dllpath: Specifies the path used by the HSM client files (mandatory)

  • -pin: Specifies the HSM pin code (mandatory)

  • -inittoken: Specify this parameter the first time HSM protection is used

No

-notsecure

Indicates that the newly created credential file is not secure according to CyberArk best practices.

 

Use only when creating credential files on a remote server (not recommended).

 

-?

Lists the available options.

No

Troubleshoot the CreateCredFile utility and file

Troubleshoot the CreateCredFile utility

CASCF001E Failed to write credential file [cred file name]. Reason: Security Error: Authentication flags are not sufficient. For more information, see the CyberArk docs.

The current number of authentication flags are not enough for securing the credential file. You must specify additional authentication flags.

CASCF001E Failed to write credential file [<filepath>]. Reason: CASPR001E Error parsing parameters file (Location:CCAGParmsStreamFile.cpp:178), Reason: Parms file [<filepath>] open for write failed.

Verify that the path for the credential file exists.

CLP001S: The option </some option> is unknown

One of the options specified in the command does not exist. Use the CreateCredFile.exe /? command to list the available options.

CASCF005E Cannot encrypt password. Rc = -1, Reason:

Verify that you are using valid authentication flags for this command, and that the specified paths exist.

CASCF005E Cannot encrypt password. Rc = 1100, Reason: CASGN003E PKCS11 error 110

This error indicates that the command failed due to an issue with HSM. Verify the following:

  • The HSM client was configured correctly

  • All HSM parameters were specified

  • The path to PKCS dll and PIN are correct

CASCF011W Executable specified [<path>] not found.

This is a warning. The credential file was created, however, the executable that was specified does not exist. An attempt to log on using this credential file will fail.

CASGE007E Cryptography error: Failed to decrypt buffer (code -1, reason: Failed to unseal data, diagnostics: 16)

CASGS054E Failed to serialize Secret File, Code(<code>).

If no other errors appear, please contact CyberArk support.

CASTM071E Credential file version is not supported or missing version number in file [<version number>]

Verify that the secret file is valid, and that it has the SecretfileVersion and SecretFileType fields.

Troubleshoot the credential file

CASTM071E Credential file version is not supported or missing version number in file [<file>]

There are missing mandatory fields in the file. Recreate the file manually. See the relevant documentation for the specific client or component for more information.

CASTM073E Failed to convert the credential file. The secret file not the most updated format, and the conversion to the most updated format version has failed.

To find out more information about this error, in the application log, check the messages that appear before this error.

CASTM074E Cannot rename old credential file before converting to new format.

The secret file not the most updated format.

Before conversion to the most updated format version has failed - the file is renamed with .old suffix. this rename has failed.

Check the file system authorization in the folder of the secret file.

CASTM075I Converting the credential file to version 3.

This informational message indicates that the secret file is not in the latest format, and will be converted to the version 3 format.

No action item is needed.

CASTM076I Successfully converted the credential file.

This informational message indicates that the secret file was not in the latest format, and has been successfully converted.

No action item is needed.

CASGS055E The contents of the secret file has been updated. Please create a new secret file (code %d).

This message appears when a user is using a credentials file that contains updated WMI material, and the secrets file contains old WMI material.

Failed to log on with the credential file

If the user cannot log on to the Primary the Vault, the credential file may not be synchronized with the Vault.

  1. Log on to the Primary Vault with the Vault admin user.

  2. Change the relevant user's password.

  3. Create a credential file with the new password.

  4. Replace the existing credential file with the new one that you created.

FAQs

  1. No.

  2. Connectivity is required when creating the credential file and during regular operations.