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.
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.
HMAC Authentication for Using the XML APIs from the Command Line
- Download and install the Python programming language. Veracode recommends Python 3.5 or later. If you have a recommended version, you can omit this step. Otherwise, refer to the Python Wiki for advice on choosing a Python download.
- Install the Python Authentication Library.
- Download and install the HTTPie command-line tool by following the steps in Using HTTPie with the Python Authentication Library
HMAC Authentication for Python Programming
To use HMAC authentication with Python programs:
HMAC Authentication for Java Programming
To use HMAC authentication with Java programs:
HMAC Authentication for C# Programming
To use HMAC authentication with C# programs, review the HMAC Signing Example in C#.
Troubleshooting TipsIssues 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.