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.
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.
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
- 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.
- 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.