¿Qué es el algoritmo de autenticación para endpoints privados?

 

La autenticación de API es necesaria cuando una llamada a la API accede a una cuenta a través de uno de los métodos privados de la API.

Por ejemplo, los métodos de gestión de cuenta como Balance, TradeBalance, y OpenOrders; los métodos para trading AddOrder y CancelOrder; y los métodos de depósitos y retiros como DepositAddresses y WithdrawInfo, todos son métodos privados de la API que necesitan autenticación de API.

Claves API y firmas criptográficas

La autenticación de la API se basa en un par de claves pública/privada (en conjunto se conoce como clave API), y una firma criptográfica utilizando algoritmos hash como SHA256 y HMAC SHA512.

Un ejemplo de clave API consistiría en una clave pública y una privada similar a los siguientes:

  • Clave Pública: CJbfPw4tnbf/9en/ZmpewCTKEwmmzO18LXZcHQcu7HPLWre4l8+V9I3y
  • Clave Privada: FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==

Tenga en cuenta que estos ejemplos no se pueden utilizar ya que no están asociados con ninguna cuenta Kraken.

Las firmas criptográficas se crean en tiempo real mediante el código API del cliente. Los datos para la llamada API se pasan a través de una series de hashes y algoritmos de autenticación de mensajes que firman los datos de forma segura utilizando la clave API privada (la parte secreta de la clave API).

Cabeceras HTTP

La clave y firma API se proporcionan a la API a través de cabeceras HTTP personalizadasAPI-Key y la API-Sign.

La clave API se utiliza para identificar qué cuenta se está accediendo, por lo tanto el valor de la clave es el mismo para cada llamada. La firma criptográfica se utiliza para autenticar la llamada API y se calcula utilizando valores variables (como el nonce), por lo tanto el valor de la firma es diferente en cada llamada.

A continuación se muestran algunos ejemplos de las cabeceras HTTP para API-Key y la API-Sign:

  • API-Key: CJbfPw4tnbf/9en/ZmpewCTKEwmmzO18LXZcHQcu7HPLWre4l8+V9I3y
  • API-Sign: vcDrflw2QAYr0x7zT6HFNhyDYz2Jqex0xSN7htHoY0ggvEkyNsgSXBEgXuYEU9Gy90IFXtES9OGknI0yo1cl9Q==

Tenga en cuenta que el valor de la clave API es exactamente el mismo que la clave pública mostrada con anterioridad, pero que el valor de API-Sign (la firma) es diferente a la clave privada mostrada anteriormente, y obtendrá un valor nuevo con cada llamada API.

Pseudo código de firma

Nuestra documentación de API indica que el valor de API-Sign es un "mensaje firmado utilizando HMAC-SHA512 de (la ruta URI + SHA256(nonce + datos POST)) y la clave secreta API descodificada en base64", la cual se puede separar en varias partes como sigue:

Variables

  • Ruta URI = URL de la llamada API sin https://api.kraken.com
  • nonce = identificador único que debe incrementar su valor con cada llamada API (usualmente es una marca de tiempo UNIX, que es el tiempo actual en segundos (o milisegundos para mayor resolución) transcurridos desde el 1 de Enero de 1970)
  • Datos POST = Los pares de nombre/valor codificados del formulario del nonce y los parámetros del método API

A continuación, algunos ejemplos de las variables para una llamada al método TradeBalance (tenga en cuenta que todos los valores son string independientemente de lo que representen los mismos):

  • Ruta URI = "/0/private/TradeBalance"
  • nonce = "1540973848000"
  • Datos POST = "nonce=1540973848000&asset=xxbt"

Algoritmo

  • Calcula el valor SHA256 del nonce y los datos POST
  • Descodifica la clave privada API (la parte secreta de la clave API) de base64
  • Calcula el HMAC de la ruta URI y el SHA256, utilizando SHA512 como el hash HMAC y la clave secreta API descodificada como la clave HMAC
  • Codifica la HMAC en base64

A continuación, se muestra un ejemplo del algoritmo utilizando las variables mostradas anteriormente:

  • Base64Encode(HMAC-SHA512 de ("/0/private/TradeBalance" + SHA256("1540973848000nonce=1540973848000&asset=xxbt")) utilizando Base64Decode("FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==") como la clave HMAC

El resultado es el valor de API-Sign.

Código de ejemplo

Python

Un ejemplo minimalista (sin comprobación de errores) pero totalmente funcional de cómo generar una firma de autenticación API para el endpoint TradeBalance se muestra a continuación:


        #Importar librerías Python necesarias
        import time
        import base64
        import hashlib
        import hmac
            
        # Decode API private key from base64 format displayed in account management
        api_secret = base64.b64decode("FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==")
            
        # Variables (API method, nonce, and POST data)
        api_path = "/0/private/TradeBalance"
        api_nonce = str(int(time.time()*1000))
        api_post = "nonce=" + api_nonce + "&asset=xbt"
            
        # Cryptographic hash algorithms
        api_sha256 = hashlib.sha256(api_nonce + api_post).digest()
        api_hmac = hmac.new(api_secret, api_path + api_sha256, hashlib.sha512)
            
        # Encode signature into base64 format used in API-Sign value
        api_signature = base64.b64encode(api_hmac.digest())
            
        # API authentication signature for use in API-Sign HTTP header
        print(api_signature)