Secure json middleware

sjson.md

Secure Json

Objetivo

El objetivo de secure json es proveer un mecanismo de seguridad e integridad de los objetos json devueltos por nuestras apis con enfasís en el acceso público. Cada petición o respuesta SJSON debe ser declarada en la definición SWAGGER de la api publicada.

Hay varios casos de uso en donde SJSON se puede utilizar:

1. Mantener la seguridad y la integridad de los datos en una transacción "monetaria" pública.
2. Asegurar que las peticiones y respuestas REST no sean manipuladas por un atacante.

Conceptos

• Middleware: Es el artefacto de software encargado de firmar y validar los peticiones y respuestas públicas de nuestras apis de forma transparente para las aplicaciones.
• CDN: Es el artefacto que nos permite desplegar y regionalizar el "Middleware" en la entrada pública de nuestras apis.
• Swagger Definition: Esquema declarativo de los objetos SJSON en un determinado servicio de api publicado.

Implementación

Middleware

El Middleware es el servicio encargado de firmar y verificar los objetos json que desean segurizarse. Cada objeto que se desee segurizar para determinado servicio deberá estar declarado en la específicación swagger de cada api. Este middleware tiene todas las especificaciones de los servicios para poder entender que objetos deberá validar en las peticiones o firmar en las respuestas.

Por ejemplo, cuando se desee validar que el campo transaction_amount que recibe el api de plan de pagos sea el originado por el api de offerings, el middleware firmara cada objeto anidado (incluyendo el root) en la respuesta del servicio de offerings. Luego, es responsabilidad del llamante al api de plan de pagos mandar el objeto asociado firmado previamente.

Ejemplo para firmar un objeto

const signedObj = sjson.sign({
  a: 'a',
  b: {
    foo: 'bar'
  }
});

Ejemplo del objeto firmado

{
  a: 'a',
  b: {
    foo: 'bar',
    _signature: 'ab4df6827e01b223f8b1be6f3a14ab1d966366aff37429c6bf2e9964090b8f58a350154e9348361b0531277d4fd642d044b4c2aaf40117a6d98dc7a51b0c9a73'
  },
  _signature: '249e62e11ba0ebb85f3a134ac4867957f363aef490914b51563f998cbb0d4399b8622519f1352e233016c8f4f2032a5df176e4144315f0d5cea76307e405d026'
}

Ejemplo para verificar la firma del objeto

console.log(sjson.check(signedObj));

CDN

Es el artefacto de infraestructura que nos permitira desplegar el middleware en todos los accesos públicos a nuestra api.

Este servicio nos permite interceptar las peticiones que tienen como destino nuestra api pública. Aqui se llamará al middleware para comenzar el proceso de validación si el servicio llamado lo requiere en su especificación. También nos va a permitir interceptar las respuestas pública de nuestra api para poder comenzar el proceso de firmado si así lo requiere el servicio que responde en su especificación.

Swagger definition

Para declarar que un objeto es del tipo SJSON se deberá especificar en el campo "definitions" del swagger cada objecto que deberá ser validado ( u objeto anidado ) si interviene en una petición, o si deberá ser firmado si interviene en una respuesta de un servicio.

Ejemplo básico de un objeto SJSON en los esquemas de swagger

"definitions" : {
  "Message" : {
     "type" : "object",
     "format" : "sjson",
     "properties" : {
        "code" : {
          "type" : "integer"
        },
        "text" : {
          "type" : "string"
        }
     }
  }
}

Mataría que no usemos description para eso sino que usemos format, onda:

"definitions" : {
  "Message" : {
     "type" : "object",
     "format" : "sjson",
     "properties" : {
        "code" : {
          "type" : "integer"
        },
        "text" : {
          "type" : "string"
        }
     }
  }
}