Burp Client Authentication

Authentication is performed for the Burp API via signing. By leveraging this technique, it is possible to guarantee the identity of the sender, data integrity, and replay attack prevention.

Authorization

Components

Authorization is requested by including the following parameters in an 'Authorization' http header, or as query string parameters:

• date
  • The date of the request in the format: 'YYYYMMDDTHHmmssZ' (example: '20160102T030405Z').
• credential
  • A combination of the following values in strict order, joined by a single '/'.
  • API Key ID
  • Request Date in format 'YYYYMMDD'
  • Request scope
  • Service Name
• headers
  • A (sorted, lowercased) list of the HTTP headers used in generating the signature.
• signature
  • The generated signature that should be used to validate the request. When used in a query string, this value must always be the final parameter in the query string.
• expire (optional)
  • The datetime at which the request should no longer be considered valid.
  • Format: 'YYYYMMDDTHHmmssZ'

Process

Signatures are generated using the following rules:

1. Parse+Validate the 'credentials' authorization parameter.
2. Ensure the requested scope is in both the user-assigned scopes, as well as the requested route's scopes.
3. Create a "normalized headers" string by looping over the 'headers' authorization parameter, and for each header appending to the string using the format: lowercased-header-name:cleaned-header-value\n. The cleaned header value should consist of the assigned value, with leading and trailing whitespace removed. Any whitespace inside the value should additionally be replaced with a single space.
4. Retrieve the API Secret Key assigned to the specified API Key Identifier
5. Derive a signing key by executing a SHA256 HMAC consecutively on each of the following properties. The hex-encoded output of each function should be used as the input for the next in the series:
   
6. a = HMAC(secret, credential.date)
7. b = HMAC(a, credential.scope)

8. c = HMAC(b, credential.service)

9. Generate the signing text by SHA256 hashing the following properties in strict order, separated by newline characters:

10. Request method - GET, POST, PUT, etc
11. Request path - /collection/f4c96634-0ce3-47cb-975d-0c9ab5df6199
12. Request query string excluding signature - ?name=foo&value=bar
13. Normalized headers

14. The list of header names used to generate the normalized headers

15. Sign the following information using a SHA256 HMAC function on the following values in strict order, separated by newlines characters.

16. Request date parameter string
17. Request credential parameter string
18. Request expiration parameter string, or an empty string if it wasn't included

19. Signing text SHA256 hex output generated in step 6.

20. Compare the hex output of step 7 with the signature request parameter string. If they match, consider the request authorized. If they do not match, reject the request.