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.
-
Open the command prompt as an admin user.
-
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. |
-
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:
-
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:
|
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 applicative user |
PSMPApp |
PSMP applicative 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 |
Whether or not passwords in user credential files are replicated to all DR sites before they are replaced. |
No |
||
/ExternalAuth |
The type of external authentication that is used to authenticate users to the Vault. Valid values:
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. |
No |
||
/Hostname |
Specify this parameter to require the hostname of the current machine for user authentication. |
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”.
|
No |
||
/MachineGUID |
Specify this parameter to require the identifier of the current machine for user authentication. |
No | ||
/DiskSignature |
Specify this parameter to require the data storage device ID of the current machine for user authentication. |
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.
|
No |
||
/DPAPIMachineProtection |
Uses the operating system DPAPI machine protection for user authentication. |
No |
||
/DPAPIUserProtection |
Uses the operating system DPAPI user protection for user authentication. |
No |
||
/NotSecure |
Indicates that the newly created credential file is not secure according to CyberArk best practices.
|
|
||
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”.
|
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”.
|
No |
||
/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. |
No |
||
/MachineGUID |
Specify this parameter to require the identifier of the current machine for user authentication. |
No | ||
/DiskSignature |
Specify this parameter to require the data storage device ID of the current machine for user authentication. |
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. |
No |
||
/DPAPIUserProtection |
Uses the operating system DPAPI user protection for user authentication. |
No |
||
/NotSecure |
Indicates that the newly created credential file is not secure according to CyberArk best practices.
|
|
||
/? |
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 |
Whether or not passwords in user credential files are replicated to all DR sites before they are replaced. |
No |
||
-externalauth |
The type of external authentication that is used to authenticate users to the Vault. Valid values:
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. For the specific paths for each application user, see CreateCredFile utility. |
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.
|
No |
||
-notsecure |
Indicates that the newly created credential file is not secure according to CyberArk best practices.
|
|
||
-? |
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 Vault, the credential file may not be synchronized with the Vault.
-
Log on to the Primary Vault with the Vault admin user.
-
Change the relevant user's password.
-
Create a credential file with the new password.
-
Replace the existing credential file with the new one that you created.
FAQs
-
When integrating with HSM, what is the required connectivity?
Connectivity is required when creating the credential file and during regular operations.