api/signature

↓ Members.

↓ Methods.

module:api/signature

Description:

  • Authentication signature implementation

    All 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:

Members

(static) header :string

Description:

  • header name to keep signature

Source:
Default Value:
  • >bk-signature

Methods

(static) create(login, secret, optionsopt) → {object}

Description:

  • Create secure signature for an HTTP request. Returns an object with HTTP headers to be sent in the response.

Source:
Parameters:
Name Type Attributes Description
login string
secret string
options object <optional>
Properties
Name Type Attributes Description
host string <optional>

request host
hostname string <optional>

request host
url string <optional>

path and query params as full URL
path string <optional>

request path
method string <optional>

GET, POST, ...
expires string <optional>

is absolute time in milliseconds when this request will expire, default is 30 seconds from now
version string <optional>

a version number defining how the signature will be signed
type string <optional>

content-type header, may be omitted
contentType string <optional>

content-type header, may be omitted
tag string <optional>

a custom tag, vendor specific, opaque to the bkjs, can be used for passing additional user or session information
checksum string <optional>

SHA1 digest of the whole content body, may be omitted
query string <optional>

on object with query parameters to use instead of parameters in the uri
Returns:
Type Description
object

in format:

  • value - signature string to be returned
  • header - HTTP header or cookie name to be used

(static) fromRequest(req, optionsopt) → {object}

Description:

  • Returns a new signature object with all required properties filled form the request object

Source:
Parameters:
Name Type Attributes Description
req object
options object <optional>

properties to put in the signature object
Returns:
Type Description
object

(static) get(req) → {object}

Description:

  • Parse incoming request for signature and return all pieces wrapped in an object, this object will be used by verifySignature function.

    If the signature successfully recognized it is saved in the request as req.signature, it always returns a signature object, a new one or existing

Source:
Parameters:
Name Type Description
req Request

HTTP incoming request
Returns:
Type Description
object

(static) verify(req, sig, user, callback)

Description:

  • Returns non-empty signature if sig matches given user secret. user object must be a bk_user record.

Source:
Parameters:
Name Type Description
req Request

HTTP incoming request
sig object

parsed signature to verify
user object

a user record with hashed password
callback function

function(signature)