Authenticate with a hash value

The Credential Provider can authenticate a list of valid hash values of an application.

Overview

The Credential Provider calculates the calling application hash value and compares it with the hash values specified for the application ID in the Vault. The main benefit of authenticating an application based on its hash is to protect it from any malicious code changes.

The hash value in the Vault can be calculated using the AIMGetAppInfo utilities. The Credential Provider verifies the full path of the application or script file based on similar concepts mentioned in Application path authentication and calculates the hash value for this path. For more information about the AIMGetAppInfo utilities, see GetAppInfo utilities.

This authentication method can be used in all the SDKs. For details about each SDK, see the relevant section below.

Java password SDK

In Java applications, developers can mark the classes they want to check for tampering using a specific Java annotation. During a password request, the Credential Provider investigates the classes in the calling stack for a class with a Java annotation named CyberArkGetPassword.

The Credential Provider calculates the hash of either a class or related JAR file as follows:

To summarize, in order to authenticate specific applications using hash authentication, relevant classes must be marked with the CyberArk annotation, as shown in the following example:

@CyberArkGetPassword
public class MyClassMyClass 
{ code of the TryAnno class..}

To authenticate all applications using hash authentication, do not mark any class so that the hash is calculated on the entire call stack.

Work in a JAVA application server environment

The methods described above are also relevant for Java application servers, meaning that users must register the hash of classes/JARs within WAR/EAR files.

This section describes some of the behaviors that are unique to these environments and should be considered when deploying applications using the Credential Provider hash authentication.

• As mentioned above, when working with application servers, the CyberArk Java annotation must be used to mark class files for hash authentication.

• When deploying a WAR/EAR file, some application servers manipulate the classes/JARs within the WAR/EAR when unpacking them. For example:

  • WebLogic – When deploying an EAR/WAR file, WebLogic creates a JAR file, named "_wl_cls_gen.jar" from all the classes that reside under “web-in/classes”. To authenticate any of these class files, register the hash of the relevant class(es). This is an exceptional scenario in which the Credential Provider calculates the hash of the relevant class(es) during runtime, even though they reside within a JAR file.

  • For the above reasons, the hash value for WebLogic applications must be calculated before deployment, unless they are deployed in an exploded manner.

  • Other applications servers that are not mentioned above (JBoss, Tomcat, WebSphere) do not perform any manipulations on the unpacked files that are relevant to the hash authentication method.

CLI Password SDK

The registered hash is compared to the calculated hash of the calling script. If the verification fails, the hash is validated against the calculated hash of the parent script file.

The following example shows how to call a script in Windows so the Credential Provider can successfully identify it:

cmd /c c:\MyScripts\scriptname.cmd

The following example shows how to call a script in UNIX so the Credential Provider can successfully identify it:

bash /home/scripts/scriptname.sh

Use an SDK wrapper

If your scripts do not call the CLI Password SDK directly, but through a wrapper script, you can ensure that both the hash of the wrapper as well as the hash of the calling script are validated, while registering the hash of trusted wrapper scripts only once in the Credential Provider configuration instead of for each Application ID.

To specify hash values for SDK wrappers:

1. In the Credential Provider main configuration file, main_appprovider.conf.<platform>.<version>, add a new section called TrustedCLIWrappers.

2. For each hash value of a wrapper script used by applications running from Credential Providers that use this configuration file, add a new HASH# parameter and value, as shown in the following example. You can add up to 200 hash values.

   [TrustedCLIWrappers] HASH1=4A5962A67D73D912D6A86DE9C1A4829B67804E370F2A8AC731C0C01ED24B43D80CC4875731B711829B0D424A60A8C239A727751EA3E2388FDAE3AD616251D7D1 HASH2=AF465FC444959D25701E2E5C60DA94F4DC876BE83915427C4CFF9CE3720BA744CFF850DFDC3D90C00776A8EAA1BEB71F4C5CA2259C006E42AA3B40A86F0B8482 ..

3. You can add additional information in a comment after each hash value specified for an application by specifying ‘#’ after the hash value, followed by the comment.

   For example,

   2E226BB7F6ADDBC1686A8562F05E5D03F6DF6955B36658464259D31DC783FA7CD7570D45C1C375CA35398CF138BEB47E797B10FFC1F12EA6FB4382A962C53009 # app2

   The comment must not include a colon or a semicolon.

C/C++ Password SDK

The registered hash is compared to the calculated hash of the calling executable even if the SDK is used from an ‘so’.

• Allow internal scripts to request credentials – Cannot be used for this SDK. Independently, if the SDK is called directly from the executable or from an ‘so’, the Credential Provider checks the path of the main executable that matches the registered application path.

.NET Password SDK

In .NET applications, developers can mark the assemblies they want to check for tampering using a specific .NET attribute. During a password request, the Credential Provider investigates the assemblies in the calling stack for an assembly with a .NET attribute named “CyberArkGetPasswordAttribute” (this should be an assembly-level attribute).

In addition, in order for the NetCoreAAMGetAppInfo or NETAIMGetAppInfo utility to successfully identify Secrets Manager attributes, it must be exactly the same version as the .NET Password SDK used by the application.