API Auth

This document will explain in the detail how the authentication work for node administration endpoints.

• Scope

  The authorization string is passed to the node using the grpc metadata. It is only used to validate owner of node to adminstrate the node they own, non-protected service (GetBlocks, GetTransactions, etc) won't need the authorization metadata to access.

• Auth String

  The authorization string is provided in the RPC request metadata.

  No	key	type	description
  1	authorization	string (base64)	base64 string representation of the signed bytes including the signature at the end

  The payload of the request that are signed (in order):

  No	field	type	length
  1	Timestamp	uint64	8 bytes
  2	RequestType	int32 (model.Auth.RequestType)	4 bytes

  The authorization string is build by writing the above bytes in order and signed by the account (owner) private key. The resulting signature from signing process appended with its type (see: signature) will be appended to the end of the payload.

  payload = [timestampBytes, requestTypeBytes]
  signature = sign(payload, ownerPrivateKey)
  authorizationBytes = [payload..., signature]
  authorization = base64.StdEncoding.EncodeToString(authorizationBytes)
  

• Server validation

  • server will validate the request signature in the following step:

  LastTimestamp = 0 // default 0, update each time admin request successfull
  ...
    decodedAuthBytes = decode(metadata.authorization)
    payload, signature = separatePayloadAndSignature(decodedAuthBytes)
  
    if payload.Timestamp <= LastTimestamp {
        InvalidRequest
    }
    if payload.RequestType != currentService.RequestType {
        InvalidRequest
    }
    if !VerifySignature(payload, signature) {
        InvalidRequest
    }
    LastTimestamp = paylaod.timestamp
    ValidRequest
  

  Everytime the auth timestamp fullfill the condition, the LastTimestamp will be updated, resulting the signed request cannot be replayed anymore, and user will be required to sign another auth message to post another request