clase ara::crypto::cryp::KeyDecapsulatorPrivateCtx

La interfaz ara::crypto::cryp::KeyDecapsulatorPrivateCtx sirve para el desencapsulado asimétrico de datos de clave (Key Encapsulation Mechanism, KEM) a fin de generar claves simétricas de destino [SWS_CRYPT_21412]. Antes del desencapsulado, el contexto debe inicializarse obligatoriamente mediante SetKey con una clave privada o un espacio de almacenamiento de claves adecuado [SWS_CRYPT_21413]. Posteriormente, el método Decapsulate transforma los datos encapsulados de forma segura para subprocesos y frente a excepciones en una nueva instancia de clave simétrica [SWS_CRYPT_21412]. Todas las llamadas a la interfaz garantizan una estricta semántica de reversión en caso de error.

más ›

Contexto

La clase ara::crypto::cryp::KeyDecapsulatorPrivateCtx constituye la interfaz estandarizada para mecanismos de desencapsulado de claves asimétricas (Key Encapsulation Mechanism, KEM) basados en claves privadas. Como contexto criptográfico especializado, hereda de CryptoContext y sirve para desencapsular datos de clave encapsulados previamente transmitidos utilizando una clave privada asimétrica y transformarlos en un nuevo objeto de clave simétrica (SymmetricKey) [SWS_CRYPT_21412].

En la operación de desencapsulado intervienen al menos tres componentes: la aplicación solicitante, el propio contexto de desencapsulado y las fuentes de clave en forma de un PrivateKey [SWS_CRYPT_21413] o una ranura de memoria referenciada a través de KeySlot [SWS_CRYPT_50083]. Tras un desencapsulado correcto, el contexto proporciona el objeto de clave simétrica generado como puntero inteligente [SWS_CRYPT_21412].

Diagrama de contexto: Integración del contexto de desencapsulado entre la provisión de claves y la generación de la clave de destino. Fuentes: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Ciclo de vida

El contexto se referencia y comparte típicamente mediante el alias de tipo KeyDecapsulatorPrivateCtx::Sptr como std::shared_ptr [SWS_CRYPT_21401]. Dado que la interfaz define funciones miembro puramente virtuales, la instanciación del objeto concreto se realiza presumiblemente a través de una fábrica criptográfica de nivel superior (interpretación). Pregunta Q-870e12aabbad8472 (abierta) La destrucción y la limpieza de recursos quedan vinculadas al ciclo de vida del puntero inteligente.

Al principio, el contexto se encuentra en un estado no inicializado en el que todavía no se ha asignado ninguna clave de desencapsulamiento. Una llamada directa a Decapsulate falla en este estado con el error UninitializedContext [SWS_CRYPT_21412]. Solo tras la llamada correcta a uno de los dos métodos sobrecargados SetKey, el contexto pasa al estado operativo [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Si se asigna un KeySlot, la clave privada contenida en él se consulta de forma dinámica solo en el momento del desencapsulamiento efectivo; por lo tanto, es de suponer que las modificaciones en el contenido del slot afectan de inmediato a futuras llamadas de desencapsulamiento (interpretación). Pregunta Q-0b0dfc1fd3ebbc6f (abierta)

En lo que respecta a la concurrencia y a la tolerancia a fallos, todos los métodos están especificados como seguros para subprocesos (thread-safe) y seguros frente a excepciones (exception safe) [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Dado que el método de transformación Decapsulate está declarado como const, varios subprocesos pueden iniciar desencapsulamientos en paralelo sobre el mismo contexto configurado [SWS_CRYPT_21412].

Ruta de uso

El flujo regular para el desencapsulamiento de una clave de sesión se divide en dos fases sucesivas:

1. Configuración de la clave de desencapsulamiento: la aplicación configura el contexto a través de SetKey, ya sea pasando un PrivateKey::Sptr [SWS_CRYPT_21413] o depositando un KeySlot::Sptr [SWS_CRYPT_50083]. El resultado es un ara::core::Result<void>, cuyo estado debe comprobarse antes del siguiente paso.
2. Ejecución del desencapsulamiento: la aplicación llama a Decapsulate y pasa los datos del búfer de la clave encapsulada (ReadOnlyMemRegion encapsulatedKey), el identificador de algoritmo de la clave de destino (AlgId algId), así como sus usos permitidos (AllowedUsageFlags allowedUsage) [SWS_CRYPT_21412].
3. Procesamiento del resultado: en caso de transformación correcta, la función devuelve un ara::core::Result<SymmetricKey::Sptr> a través del cual la nueva clave simétrica se puede utilizar de forma inmediata para operaciones criptográficas subsiguientes [SWS_CRYPT_21412].

Diagrama de secuencia: flujo típico de configuración de clave y desencapsulamiento de una clave de destino. Fuentes: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Escenarios de error

Todas las operaciones devuelven estados de error a través de ara::core::Result y garantizan una semántica estricta de reversión (rollback_semantics), gracias a lo cual el contexto permanece en un estado válido en caso de fallos [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083].

En el marco de la configuración de claves mediante SetKey pueden producirse los siguientes errores:

• CryptoErrc::kIncompatibleObject: el objeto PrivateKey pasado o el KeySlot es incompatible con el contexto [SWS_CRYPT_21413], [SWS_CRYPT_50083].
• CryptoErrc::kUsageViolation: los flags de permisos de la clave privada no contienen el derecho de desempaquetado (kAllowKeyUnwrapping) [SWS_CRYPT_21413].
• CryptoErrc::kUnsupported: la implementación del contexto solo admite la otra variante de configuración respectiva (p. ej., vinculación exclusiva a través de KeySlot o exclusivamente a través de PrivateKey) [SWS_CRYPT_21413], [SWS_CRYPT_50083].

Al llamar a Decapsulate se especifican las siguientes causas de error:

• UninitializedContext: no se había asignado previamente ninguna clave al contexto [SWS_CRYPT_21412].
• CryptoErrc::kInvalidArgument: el formato de datos del búfer encapsulatedKey pasado no es válido [SWS_CRYPT_21412].
• CryptoErrc::kUnknownIdentifier: el identificador algId pasado no es compatible [SWS_CRYPT_21412].
• CryptoErrc::kIncompatibleArguments: o bien los permisos de destino allowedUsage no se corresponden con algId o con el tipo de clave, o bien algId es incompatible con los datos KEM en encapsulatedKey [SWS_CRYPT_21412].
• CryptoErrc::kUsageViolation: las reglas de uso de la clave configurada no permiten el desempaquetado (falta kAllowKeyUnwrapping) [SWS_CRYPT_21412].
• CryptoErrc::kEmptyKeySlot: un KeySlot vinculado previamente a través de SetKey no contiene ninguna clave en el momento de la ejecución [SWS_CRYPT_21412].
• CryptoErrc::kBusyResource: un recurso del sistema necesario para el cálculo criptográfico está ocupado temporalmente [SWS_CRYPT_21412].