Enabling HMAC Authentication

Veracode APIs

The Veracode integrations and APIs use HMAC authentication when accessing API resources.

About HMAC Authentication

Veracode API authentication uses Veracode API credentials. You can use these credentials with both user accounts and API service accounts. You can also use these credentials for both username/password and SAML login methods. The API ID and key digitally sign the HTTP header accompanying an API request with Hash-based Message Authentication Code (HMAC). This process provides added security:

  • Credentials are not sent in the clear as plain text. The API key is never transmitted, but encrypts the HMAC from the sender-side and decrypts it from the server-side.
  • The HMAC signature validates that the message was not tampered with or altered in transit. Any change to the message invalidates the HMAC.
  • The HMAC signature includes a nonce (one-time code) that prevents replay attacks.
  • You can revoke and regenerate the Veracode API credentials to respond to an accidental credentials leak.

Prerequisites

Ensure you have followed the steps in:

HMAC Authentication for the API Wrappers

The API wrappers provide the easiest way for occasional users to achieve secure API functionality.

After you generate and store your Veracode API credentials, the Java and C# API wrappers are enabled for HMAC authentication and ready for use from the command line and in your code.

To configure HMAC authentication, incorporate the Java or C# wrapper into your automation. You can use the wrappers as a command-line tool and supply the Veracode API credentials or store the credentials in a Veracode API credentials file.

See Using the API Wrappers as a Library for information about using the API wrappers in plugins.

The API wrappers are also the best way to troubleshoot your Veracode environment.

The HMAC signing example programs for Java and C# use the Java and C# API wrappers.

Note: If you use the API wrappers, ensure that you always run the latest version.

HMAC Authentication for Using the REST APIs with Java

You can use any of these methods:

  • Perform the external signing step on the command line using either the Java or Python tool or the Veracode Java or C# API wrappers.
  • Use one of the community-provided HMAC implementations listed in HMAC Signing Example in C#.
  • Enable HMAC signing within your C# application.

HMAC Authentication for Using the XML APIs from the Command Line

The cURL command-line tool does not support HMAC authentication, therefore Veracode provides support for the HTTPie command-line tool. To use HTTPie and HMAC authentication with the XML APIs:

HMAC Authentication for Python Programming

To use HMAC authentication with Python programs:

  1. Install the Python Authentication Library.
  2. Review the HMAC Signing Example in Python.

HMAC Authentication for Java Programming

To use HMAC authentication with Java programs:

  1. Install the Java Authentication Library.
  2. Review the HMAC Signing Example in Java.

HMAC Authentication for C# Programming

To use HMAC authentication with C# programs, review the HMAC Signing Example in C#.

Troubleshooting Tips

Issues that prevent HMAC from working correctly, or make it appear that HMAC is not working at all, include:
  • Incorrect credentials. The most frequent problem encountered after setting up HMAC authentication is incorrect API ID and key. For example, you may have multiple accounts and associate the wrong set of credentials with the account you are setting up. Ensure credential sets are current and secure. If your system is not working, try revoking the existing credentials, creating new credentials, and retrying.
  • Incorrect account type or user roles. Each API specifies the required account type (user account or API service account) and user roles to call it. A role or account error can sometimes be misunderstood as a larger problem with authentication.
  • Problems connecting to the Veracode Platform. As a test, run the getmaintenancescheduleinfo.do XML API from the command line. An API service account requires the Admin API role to use this call. A user account requires the Administrator role to use this call.
    http --auth-type=veracode_hmac "https://analysiscenter.veracode.com/api/3.0/getmaintenancescheduleinfo.do"
    You should quickly get a short response.
  • Inaccurate system time. Although infrequent, HMAC authentication fails if the system time of the client and server are substantially out-of-sync. Compare your system time with actual time at time.is to ensure your system time is close to actual time.
For more help with HMAC authentication issues, contact Veracode Technical Support at [email protected].