Claves de cliente

Todas las solicitudes de cliente en Open Payments se firman con una clave exclusiva que identifica al cliente ante los servidores de autorización y de recursos. Todas las solicitudes, salvo las de nuevas concesiones, incluirán un token de acceso vinculado con la clave.

Registro de claves

Un registro de claves es el conjunto de claves públicas que un cliente utiliza para identificarse en todas las solicitudes de Open Payments y está alojado en el servidor de recursos de Open Payments de la ASE. Las solicitudes de concesión y otras llamadas a la API se realizan a través de múltiples solicitudes HTTP firmadas, por lo que el cliente debe presentar la misma identidad en cada llamada. El servidor de autorización utiliza el registro para verificar que el cliente haya firmado cada solicitud.

El cliente genera un par de claves pública y privada. Conserva la clave privada y firma cada solicitud con esa clave y un keyId. El keyId indica a los servidores qué clave pública del registro utilizar para la verificación.

Para los clientes que se identifican con una wallet address, el registro se publica en WALLET_ADDRESS/jwks.json. Por ejemplo:

https://wallet.example.com/alice/jwks.json

La forma en que los clientes registran las claves con la ASE queda fuera del alcance de Open Payments.

Estructura del registro

El registro de claves debe exponer las claves públicas en formato de conjuntos de claves web en JSON (JWKS). Las claves deben generarse con el algoritmo Ed25519 y el documento JWKS resultante debe contener los siguientes campos y valores.

{
  alg: 'EdDSA',
  kty: 'OKP',
  crv: 'Ed25519'
}

Además, el documento debe incluir los campos x y kid (identificador de clave) para que el cliente pueda identificarse en una firma.

{
  "keys": [
    {
      "kid": "3724c845-829d-425a-9a0d-194d6f12c336",
      "x": "_Eg6UcC8G-O4TY2cxGnZyG_lMn0aWF1rVV-Bqn9NmhE",
      "alg": "EdDSA",
      "kty": "OKP",
      "crv": "Ed25519"
    }
  ]
}

Generación de claves

Para inicializar un SDK de cliente de Open Payments autenticado, debe disponer de un par de claves pública-privada y de un identificador de clave.

El SDK del cliente genera un par de claves con el algoritmo ED25519. El registro de claves del cliente expone la clave pública en formato de JWKS.
La clave pública se proporciona a la entidad que administra la cuenta (account servicing entity, ASE) del cliente. La ASE es responsable de ofrecer a los clientes un medio para cargar claves. La ASE agrega la clave a su servidor de recursos.
Se crea un keyId para identificar el par de claves. Por lo general, la ASE es responsable de la creación del keyId.
El cliente almacena la clave privada para la firma de solicitudes en el futuro. La clave firma el contenido descrito en la sección Método de validación de claves a continuación.

La red de pruebas de Interledger ofrece un ejemplo funcional de obtención de un par de claves y un identificador de clave.

Solicitudes de clientes

Dado que las solicitudes de clientes se realizan en varias solicitudes HTTP firmadas, es importante que el cliente pueda identificarse de manera sistemática en todas esas solicitudes. Por lo tanto, los clientes deben incluir lo siguiente al realizar solicitudes:

Encabezados
- Un encabezado Signature-Input que incluya el keyId asociado al par de claves del cliente. Este encabezado es una lista separada por comas de encabezados que corresponden a valores de los datos firmados.
- Un encabezado signature generado en función de la Signature-Input, usando el algoritmo de firma EdDSA.
Cuerpo
- Una propiedad client que contenga la wallet address del cliente.

La protección de las solicitudes de clientes sigue un perfil definido en la especificación del GNAP.

Open Payments no admite tókenes de portador.

Solicitudes de concesión

Al recibir una solicitud de concesión firmada, el servidor de autorización obtiene el dominio del cliente de la propiedad client. El servidor de autorización vincula el dominio con la concesión para poder usarlo al adquirir el conjunto de claves en solicitudes posteriores.

Luego, el servidor de autorización realiza una solicitud GET al punto final JWKS del cliente en WALLET_ADDRESS/jwks.json. A cambio, el servidor obtiene el registro de claves del cliente. El servidor encuentra la clave pública que contiene el keyId en el encabezado Signature-Input de la solicitud. Luego, el servidor usa esa clave para descifrar y validar la firma de la solicitud. Esto vincula al cliente con la concesión y permite que el servidor continúe con el proceso de solicitud de la concesión.

Método de validación de claves

Firmas de mensajes HTTP

Open Payments usa el método de validación de claves mediante firmas de mensajes HTTP (httpsig).

Este método de validación httpsig debe declararse como parte del material de la clave al usar una clave directamente para solicitar una concesión. El material de claves que se muestra es solo ilustrativo. En Open Payments, se espera que la wallet address se utilice en la solicitud de concesión.

"key": {
    "proof": "httpsig",
    "jwk": {
        "kid": "3724c845-829d-425a-9a0d-194d6f12c336",
        "x": "_Eg6UcC8G-O4TY2cxGnZyG_lMn0aWF1rVV-Bqn9NmhE",
        "alg": "EdDSA",
        "kty": "OKP",
        "crv": "Ed25519"
    }
}

Cuando se usa httpsig, el firmante (el cliente) crea una firma de mensaje HTTP. Los clientes de Open Payments a menudo protegen sus solicitudes a los servidores presentando un token de acceso y la validación de una clave que poseen. La excepción son las llamadas a un servidor de autorización para iniciar una concesión. En ese caso, se utiliza una validación de clave sin token de acceso y se trata de una solicitud firmada no autorizada.

Consulte la página de firmas de mensajes HTTP para obtener más información específica sobre Open Payments. También encontrará información adicional en la especificación de firmas de mensajes HTTP.

Diagrama de secuencia

Se requiere una concesión interactiva para crear un recurso outgoing-payment. Este diagrama muestra la secuencia de llamadas necesarias entre un SDK de cliente de Open Payments y los servidores del lado del emisor para obtener la concesión.

Antes de inicializar el SDK de cliente, debe disponer de un par de claves pública-privada y de un identificador de clave.