Descripción general

La API de Digital Credentials Provisioning se organiza en tres modelos de recursos principales:

Recurso	Descripción
Dispositivo	Es una instancia única de un dispositivo físico y una clave de identidad.
Pruebas	Proceso para demostrar la identidad de un usuario antes de emitir una credencial.
Credentials	El DC en sí.

Como emisor, eres responsable de crear y administrar estos recursos durante todo el ciclo de vida de un DC.

Suposiciones

La principal suposición que hace esta API es el uso de la API de Android Identity Credential por parte del dispositivo para almacenar las DC definidas por ISO/IEC 18013-5.

Modelos de recursos

Dispositivo

En el modelo de la API de Digital Credentials Provisioning, un dispositivo no solo representa un dispositivo con Android en el que un usuario administra sus DC con la app de la Billetera de Google, sino que se representa como una combinación de los siguientes elementos:

Es el dispositivo físico con Android.
Un par de claves pública/privada (denominado “clave de identidad”).
- La entidad emisora usa la clave pública para verificar la identidad de un dispositivo.
- La clave privada se almacena en el almacenamiento seguro del dispositivo.

Cuando se realizan llamadas a la API, una combinación de dispositivo y credencial se identifica con un ID de referencia del dispositivo (la propiedad deviceReferenceId).

La primera vez que un dispositivo se comunica con un emisor, se le otorga un nonce único (para evitar ataques de reproducción y garantizar la actualización). El nonce se firma con la clave de identidad del dispositivo y se incorpora en el certificado que contiene la clave de identidad. En el futuro, el certificado se podrá usar para verificar el dispositivo con la entidad emisora.

Para obtener más información sobre el certificado, consulta la documentación de IdentityCredential de Android.

Si modelas este recurso como una tabla de base de datos, se verá similar a lo siguiente. Ten en cuenta que la propiedad identityKey sería el valor de la clave pública.

Ejemplo de una tabla de base de datos para un recurso de dispositivo.

Pruebas

Una prueba representa la combinación de los siguientes elementos:

La evidencia que proporciona un usuario para demostrar su identidad
Es la decisión que tomó la entidad emisora en función de las pruebas proporcionadas.

La verificación es específica para el tipo de credencial que solicita el usuario. Cuando se aprovisiona un DC, el usuario proporciona fotografías de su documento de identidad físico y un video de su perfil. Google usa el video para calcular la probabilidad de que se trate de una persona real. El resultado que Google proporciona a los emisores se denomina "puntuación de vitalidad". Se agregarán métodos de verificación adicionales a medida que se admitan nuevos tipos de credenciales.

En la siguiente tabla, se indican los estados posibles de una prueba.

Estado	Descripción	Estado final
Pendiente	El emisor aún no tomó una decisión.	No
Aceptado	La entidad emisora decidió que la evidencia es satisfactoria.	No
Rechazado	El emisor decidió que la evidencia no era satisfactoria.	Sí*
Con dificultades	El emisor necesita más información para tomar una decisión.	No
Cancelado	El usuario canceló la revisión.	Sí
Revocado	La entidad emisora revocó la verificación.	Sí*
Vencido	El usuario no completó el desafío a tiempo.	Sí

Los estados marcados con un asterisco (*) pueden no ser definitivos en los casos en que un revisor humano comete un error y actualiza el estado de forma manual.

En el siguiente diagrama de estado, se describen los posibles flujos de estado:

En algunos casos, es posible que los emisores no puedan tomar una decisión con la evidencia inicial. Para ayudar a tomar la decisión, se puede solicitar a los usuarios que proporcionen información o evidencia adicional al emisor. Entre los ejemplos de desafíos, se incluyen responder cartas por correo, visitar el sitio web de un emisor o enviar evidencia adicional.

Si modelas este recurso como una tabla de base de datos, se verá similar a lo siguiente.

Tabla de base de datos de ejemplo para un recurso de revisión.

Credencial

Una credencial representa la versión virtual de la credencial física para un dispositivo específico. Cada vez que se aprovisiona una credencial virtual en un dispositivo físico, se le asigna un ID de credencial. Si la misma credencial física se aprovisiona en diferentes dispositivos, tendrá un ID de credencial diferente cada vez. Del mismo modo, si se aprovisiona una credencial en un dispositivo, se borra y se vuelve a aprovisionar en el mismo dispositivo, tendrá un ID de credencial diferente.

Cuando cambian los detalles de las credenciales de un usuario (por ejemplo, un cambio de dirección en un documento de identidad), estos detalles deben actualizarse para todas las credenciales virtuales asociadas. Una sola credencial puede tener diferentes versiones que corresponden a esos cambios. La versión actual se rastrea con un ID de versión de credencial.

Para presentar una credencial a una entidad verificadora, el dispositivo primero debe recuperar objetos de seguridad para dispositivos móviles (MSO) del emisor. Un MSO contiene resúmenes de la credencial que fueron firmados por el emisor. Se crea un MSO a partir de una clave de autorización, una clave pública generada y firmada por la clave de identidad del dispositivo. La clave de autorización vincula de manera efectiva al MSO con el dispositivo. La combinación del MSO y la credencial demuestra a las partes que confían que la credencial proviene del emisor.

Una vez que se aprovisiona una credencial en un dispositivo, este debe enviar un objeto ProofOfProvisioning al emisor. Esto notifica al emisor que la credencial se aprovisionó correctamente en el dispositivo y se almacenó en el almacenamiento seguro del dispositivo.

Una credencial puede tener los siguientes estados:

Estado	Descripción
ProvisionPending	La credencial se lanzó a la Billetera de Google, pero no se devolvió la prueba de aprovisionamiento al emisor. Las credenciales se mueven a este estado cada vez que cambia el ID de versión de la credencial. No se lanzarán MSO para esta credencial.
Activo	La credencial se lanzó a la Billetera de Google y se devolvió la prueba de aprovisionamiento al emisor. Los MSO están disponibles para la credencial.
Revocado	La entidad emisora revocó la credencial de forma permanente. No se lanzarán MSO para esta credencial. En este estado, la Billetera de Google no presentará una credencial.
Borrado	El usuario o la Billetera de Google borraron de forma permanente la credencial del dispositivo. No se lanzarán MSO para esta credencial. En este estado, la Billetera de Google no presentará una credencial.