Generate an application hash value

This topic describes how to generate an application hash value using the GetAppInfo utilities.

GetAppInfo utilities

The GetAppInfo utilities calculate the unique hash value of an application/script, which can then be used to authenticate an application to the Credential Provider.

The main benefit of this type of authentication is to protect the application/script from any malicious code changes.

The hash value of an application/script is calculated using the file’s content. This value is specified for an application ID in the Vault and is compared to the runtime hash values of requesting applications.

After the code is finalized, update the hash value of an application in the Vault by running the utility on the machine where the application resides. Then use the returned value to update the hash value in the Vault.

Whenever your application file is modified, you must repeat this process.
If, after running this utility on a Windows machine, the application or script is deployed on a UNIX machine and goes through a DOS2UNIX process, this may result in a code change. The hash value taken from the Windows machine may therefore not be valid anymore and you must generate a new one.

Credential Providers includes the following GetAppInfo utilities:

Utility	Description
AIMGetAppInfo	Calculates a unique hash value of scripts for the CLI Application Password SDK. During installation, this utility is copied to the following folders: Windows – This utility is copied to the ApplicationPasswordProvider\Utils folder. UNIX – This utility is copied to the /opt/CARKaim/bin folder.
NetCoreAAMGetAppInfo	Calculates a unique hash value of .NET Core applications.
NetAIMGetAppInfo	Calculates a unique hash value of .NET Framework applications.
JavaAIMGetAppInfo	Calculates a unique hash value of Java applications. Windows – The JavaAIMGetAppInfo.jar utility for Windows is copied to the ApplicationPasswordProvider\Utils folder. UNIX – The javaaimgetappinfo.jar utility for UNIX is copied to the /opt/CARKaim/bin folder.

You need the following permissions to run this utility

‘Execute’ permission on the utility file
‘Read’ permission on all the application/script files for which the utility will calculate the hash value

AIMGetAppInfo

Syntax

AIMGetAppInfo <command> [command parameters]

The command and the parameter must be specified. If a command parameter is not specified, the user will be prompted for it.

This utility has the following command and command parameters:

GetHash - Calculates the hash value of an application file.
File Path
Windows command	/FilePath
UNIX command	-FilePath
Description	A pattern that describes the full path of the .NET application files. When this parameter specifies a folder, do not specify a path delimiter (slash or backslash) after the folder name.
Acceptable Values	Full path or pattern
Default Value	(no default value)
Mandatory	Yes
Usage
Windows command	/?
UNIX command	-?

NetCoreAAMGetAppInfo

Requirements

.NET 6.0 – This must be installed on the machine where the utility will be run.

Files – During installation, the NETCoreAAMGetAppInfo.dll is copied to the following folders:

Windows	ApplicationPasswordProvider\Utils\NetCore
Unix	.NET 6.0: /opt/CARKaim/bin/net6.0

To run the utility, copy NetStandardPasswordSDK.dll to the same folder.

If you move the utility file to a different location, before you run the utility make sure to copy NetPasswordSDK.dll to the same location.

The .NetCoreAAMGetAppInfo utility has the following syntax:

dotnet NetCoreAAMGetAppInfo.dll <command> [command parameters]

Command parameters and their values can be separated by ‘=’ or a space.

Syntax

This utility has the following command and command parameters:

GetHash - Calculates the hash value of a .NET Core application file
AppExecutablesPattern
Description	A pattern that describes the full path of the .NET Core application files. When this parameter specifies a folder, do not specify a path delimiter (slash or backslash) after the folder name.
Mandatory	Yes
Acceptable Values	Full path, pattern or UNC
Default Value	(no default value)
Usage	Windows: /AppExecutablesPattern
Usage	Unix: -AppExecutablesPattern
OnlyExecutablesWithAAMAttribute
Description	When set to Yes, a hash value is calculated only for files that match the specified pattern and whose class contains the CyberArk custom attribute. When an archive type file is provided, such as an .exe or .dll file, to calculate the hash value of the file the attribute needs to be applied to one of its classes only . If neither file type contains an attribute, a hash value is not calculated. The attribute can be used on class level only. The name of the CyberArk custom attribute is: CyberArkGetPassword ([assembly: CyberArk. AAM.NetStandardPasswordSDK]). When set to No, a hash value is calculated regardless of whether the file contains the CyberArk custom attribute.
Mandatory	No
Acceptable Values	Yes/No
Default Value	No
Usage	Windows: /OnlyExecutablesWithAAMAttribute
Usage	Unix: -OnlyExecutablesWithAAMAttribute
IncludeSubFolders
Description	Whether or not the utility searches for application files in subfolders of the folders that match the specified pattern.
Mandatory	No
Acceptable Values	Yes/No
Default Value	No
Usage	Windows: /IncludeSubFolders
Usage	Unix: -IncludeSubFolders
OutputDelimiter
Description	Determines whether hash values are displayed on separate lines or on the same line separated by a semicolon. The semicolon option is suitable for Bulk functions. This output also displays the total number of hash values.
Mandatory	No
Acceptable Values	NewLine or ‘;’ (semicolon)
Default Value	NewLine
Usage	Windows: /OutputDelimiter
Usage	Unix: -OutputDelimiter
?
Description	Displays the utility usage.
Usage	Windows: /?
Usage	Unix: -?

The following examples show typical usages of the NETCoreAAMGetAppInfo utility:

Example 1: In this example, a hash value is calculated for each .NET DLL file stored directly in the App1 directory. The hash value is calculated for both files with an Secrets Manager attribute and for files without, and files in subfolders of the App1 directory are overlooked. The output hash values are separated by a semicolon (;).

Windows:

dotnet NetCoreAAMGetAppInfo.dll GetHash /AppExecutablesPattern="C:\App1\*.dll" /OnlyExecutablesWithAAMAttribute no /IncludeSubFolders no /OutputDelimiter ";"

Unix:

dotnet NetCoreAAMGetAppInfo.dll GetHash -AppExecutablesPattern="/home/App1/*.dll" -OnlyExecutablesWithAAMAttribute no -IncludeSubFolders no -OutputDelimiter ";"

Example 2: In this example, a hash value is calculated for each .NET DLL/EXE file stored in the App1 directory or one of its subfolders. The hash value is only calculated for files with an Secrets Manager attribute and, in the output, each hash value appears on a new line.

Windows:

dotnet NetCoreAAMGetAppInfo.dll GetHash /AppExecutablesPattern="C:\App1" /OnlyExecutablesWithAAMAttribute yes /IncludeSubFolders yes /OutputDelimiter NewLine

Unix:

dotnet NetCoreAAMGetAppInfo.dll GetHash -AppExecutablesPattern="/home/App1" -OnlyExecutablesWithAAMAttribute yes -IncludeSubFolders yes -OutputDelimiter NewLine

NetAIMGetAppInfo

Requirements

.NET Framework 4.8 and later– This must be installed on the machine where the utility will be run.

Files – During installation, the following file is copied to the ApplicationPasswordProvider\Utils folder for this utility:

NETAIMGetAppInfo.exe

To run the utility, copy NetPasswordSDK.dll to the same folder.

If you copy NetPasswordSDK.dll to the utility folder using a Credential Provider version earlier than 12.0 and then upgrade Credential Provider, the old version of NetPasswordSDK.dll remains in the utility folder. You must delete this file and copy the new version of NetPasswordSDK.dll to the utility folder.

If you move the utility file to a different location, before you run the utility make sure to copy NetPasswordSDK.dll to the same location.

The .NetAIMGetAppInfo utility has the following syntax:

NetAIMGetAppInfo <command> [command parameters]

Command parameters and their values can be separated by ‘=’ or a space.

Syntax

This utility has the following command and command parameters:

GetHash - Calculates the hash value of a .NET application file.
/AppExecutablesPattern
Description	A pattern that describes the full path of the .NET application files. When this parameter specifies a folder, do not specify a path delimiter (slash or backslash) after the folder name.
Acceptable Values	Full path or pattern
Default Value	(no default value)
Mandatory	Yes
/OnlyExecutablesWithAIMAttribute
Description	When set to Yes, a hash value is calculated only for files that match the specified pattern and whose class contains the CyberArk custom attribute. When an archive type file is provided, such as an .exe or .dll file, to calculate the hash value of the file the attribute needs to be applied to one of its classes only . If neither file type contains an attribute, a hash value is not calculated. The attribute can be used on class level only. The name of the CyberArk custom attribute is: CyberArkGetPassword ([assembly: CyberArk. AIM.NetPasswordSDK.CyberArkGetPassword]) When set to No, a hash value is calculated regardless as to whether or not the file contains the CyberArk custom attribute.
Acceptable Values	Yes/No
Default Value	No
Mandatory	No
/IncludeSubFolders
Description	Whether or not the utility will search for application files in subfolders of the folders that match the specified pattern.
Acceptable Values	Yes/No
Default Value	No
Mandatory	No
/OutputDelimiter
Description	Determines whether hash values are displayed on separate lines or on the same line separated by a semicolon. The semicolon option is suitable for Bulk functions. This output also displays the total number of hash values.
Acceptable Values	NewLine or ‘;’ (semicolon)
Default Value	NewLine
Mandatory	No
/?
Description	Displays the utility usage.

The following examples show typical usages of the NETAIMGetAppInfo utility:

NETAIMGetAppInfo.exe GetHash /AppExecutablesPattern="C:\App1\*.dll" /OnlyExecutablesWithAIMAttribute no /IncludeSubFolders no /OutputDelimiter ";"

In the above example, a hash value is calculated for each .NET DLL file stored directly in the C:\App1 directory. The hash value is calculated for both files with an Secrets Manager attribute and for files without, and files in subfolders of the C:\App1 directory are overlooked. The output hash values are separated by a semicolon (;).

NETAIMGetAppInfo.exe GetHash /AppExecutablesPattern="C:\App1" /OnlyExecutablesWithAIMAttribute yes /IncludeSubFolders yes /OutputDelimiter NewLine

In the above example, a hash value is calculated for each .NET DLL/EXE file stored in the C:\App1 directory or one of its subfolders. The hash value is only calculated for files with an Secrets Manager attribute and, in the output, each hash value appears on a new line.

JavaAIMGetAppInfo

Requirements

Java 8 (1.8.x or later) must be installed on the machine where the utility will be run.

The JavaAIMGetAppInfo utility has the following syntax:

JavaAIMGetAppInfo.jar <command> [command parameters]

Command parameters are prefixed with ‘/’ in Windows and ‘-‘ in UNIX.
Command parameters and their values can be separated by ‘=’.

This utility has the following command and command parameters:

GetHash - Calculates the hash value of a Java application file.
AppExecutablesPattern
Description		A pattern that describes the full path of the Java application files. This command parameter is mandatory. Use the following recommended patterns: Specific war file – The hash will be calculated on all the classes and jar files in the war file. For example: C:\App1\CalcApp.war. Specific ear file – The hash will be calculated on all the classes and jar files inside the ear file, including classes\jar files inside the war file(s) that are inside the ear file. For example: C:\App1\CalcApp.ear. Directory – The hash will be calculated on all classes\jars in the specified directory. This must be the root directory of the application, i.e., the directory from where the application is run. For example: C:\StandAloneApps\App1. Multiple jar files – Specify a wildcard to calculate hash values for all the jar files in the specified directory. For example: C:\App1\*.jar. Open war directory (exploded war) – The hash will be calculated on all classes/jar files in the directory. The specified directory must be the root directory of Web application, meaning the directory that directly contains the WEB-INF and META-INF directories. Open ear directory (exploded ear) – The hash will be calculated on all classes/jar files in the directory, include the classes/jar files inside the war file/s inside the ear file. The specified directory must be the root directory of the Enterprise Web application, meaning the directory which directly contains the META-INF directory. When this parameter specifies a folder, do not specify a path delimiter (slash or backslash) after the folder name.
Acceptable Values		Full path or pattern
Default Value		(no default value)
Mandatory		Yes
ClassPath
Description	A list of directory paths separated with a colon ':' for UNIX systems and ';' in Windows. This command parameter is not mandatory. If a hash value will be calculated for a class that inherits from a parent class or implements a interface that is not included in the application directory/file (specified by the AppExecutablesPattern), the path of the parent class or/and interface must be included in this list of paths. This is relevant for the direct parent/interface as well as for the entire inheritance tree.
Acceptable Values	Yes/No
Default Value	(no default value)
Mandatory	No
OnlyExecutablesWithAIMAnnotation
Description		When set to Yes, a hash value is calculated only for files that match the specified pattern and whose class contains the CyberArk custom annotation. When an archive type file is provided, such as a .jar or .war file, to calculate the hash value of the file the attribute needs to be applied to one of its classes only . When a class type file is provided, the hash value is only calculated if the class contains the attribute. If neither file type contains an annotation, a hash value is not be calculated. The annotation can be used on class level only. The name of the CyberArk custom annotation is: CyberArkGetPassword. When set to No, a hash value is calculated regardless as to whether or not the file contains the CyberArk custom annotation.
Acceptable Values		Yes/No
Default Value		Yes
Mandatory		No
IncludeSubFolders
Description		Whether or not the utility will search for application files in subfolders of the folders that match the specified pattern.
Acceptable Values		Yes/No
Default Value		Yes
Mandatory		No
OutputDelimiter
Description		Determines whether hash values are displayed on separate lines or on the same line separated by a semicolon. The semicolon option is suitable for Bulk functions. This output also displays the total number of hash values.
Acceptable Values		NewLine or ‘;’ (semicolon)
Default Value		NewLine
Mandatory		No
LogFileDirectory
Description		Specifies the directory where the utility log file will be created. If a directory is not specified, a log file will not be created.
Acceptable Values		Existing directory
Default Value		(no default value)
Mandatory		No
/?
Description		Displays the utility usage.

The following example shows a typical usage of the JavaAIMGetAppInfo utility for Windows:

java -jar JavaAIMGetAppInfo.jar GetHash /AppExecutablesPattern="C:\Apps\*.war" /ClassPath="K:\jboss-4.2.2.GA\server\default\lib" /OnlyExecutablesWithAIMAnnotation=yes /LogFileDirectory="K:\temp"

In the above example, a hash value will be calculated for all the classes and jars in every .war file in C:\Apps and all its subfolders that contain the CyberArkGetPassword annotation. The subfolders will be included as, by default, the utility will search for application files in subfolders of specified folders. The parent class and/or interface of all the classes whose hash value will be inherited but are not included in C:\Apps will be included in K:\jboss-4.2.2.GA\server\default\lib. A log file for this hash calculation will be stored in K:\temp.

The following example shows a typical usage of the javaaimgetappinfo utility for UNIX:

java -jar javaaimgetappinfo.jar GetHash -AppExecutablesPattern="/machine1/apps/app1" -ClassPath="/machine/lib/" -OnlyExecutablesWithAIMAnnotation=no -IncludeSubFolders=yes ‑OutputDelimiter=";" -LogFileDirectory="/tmp"

In the above example, a hash value will be calculated for the classes and jars in /machine1/apps/app1, including classes and jars in subfolders and classes and jars that do not contain the CyberArkGetPassword annotation. The parent class and/or interface of all the classes whose hash value will be inherited but are not included in /machine1/apps/app1 will be included in /machine/lib/. The generated list of hash values will be separated by a semicolon. A log file for this hash calculation will be stored in /tmp.