api/signature

module:api/signature

Description:

• Authentication signature implementation

  All secured requests to the API server must be signed with user login/secret pair. The algorithm how to sign HTTP requests (Version 1, 2):

  • Split url to path and query parameters with "?"
  • Split query parameters with "&"
  • ignore parameters with empty names
  • Sort list of parameters alphabetically
  • Join sorted list of parameters with "&"
    • Make sure all + are encoded as "%2B"
  • Form canonical string to be signed as the following:
    • Line1: The signature version
    • Line2: The application tag or other opaque data
    • Line3: The login name
    • Line4: The HTTP method(GET), followed by a newline.
    • Line5: The host name, lowercase, followed by a newline.
    • Line6: The request URI (/), followed by a newline.
    • Line7: The sorted and joined query parameters as one string, followed by a newline.
    • Line8: The expiration value in milliseconds, required, followed by a newline
    • Line9: The Content-Type HTTP header, lowercase, optional, followed by a newline
    • Line10: The SHA1 checksum of the body content, optional, for JSON and other forms of requests not supported by query parameters
  • Computed HMAC-SHA1 digest from the canonical string and encode it as BASE64 string, preserve trailing = if any
  • Form the signature HTTP header as the following:
    • The header string consist of multiple fields separated by pipe |
      • Field1: Signature version:
        • version 1, obsolete, do not use first 3 lines in the canonical string
        • version 2,3 to be used in session cookies only
        • version 4
      • Field2: Application tag or other app specific data
      • Field3: user login or whatever it might be in the login column
      • Field4: HMAC-SHA digest from the canonical string, version 1 uses SHA1, other SHA256
      • Field5: expiration value in milliseconds, same as in the canonical string
      • Field6: SHA1 checksum of the body content, optional, for JSON and other forms of requests not supported by query parameters
      • Field7: empty, reserved for future use The resulting signature is sent as HTTP header bk-signature in in the query.

Source:

• api/signature.js, line 59