Enabling HMAC Authentication

APIs

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

About HMAC Authentication

Veracode API authentication uses an API ID and key that you can generate for any Veracode user account, regardless of type (human or API user) and login method (username/password or SAML). 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 API ID and key 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.

As a first step in using HMAC authentication, incorporate the Java or C# wrapper into your automation. You can use the wrappers as a command-line tool and supply the API ID and key, or store them in a credentials file. The other HMAC steps are then automatic.

See Using the API Wrappers as a Library or a Command-Line Application 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 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. Check the specific API call reference page in the Veracode Help Center for required account and role information.
  • 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 support@veracode.com.