clase ara::crypto::cryp::KeyAgreementPrivateCtx

La interfaz ara::crypto::cryp::KeyAgreementPrivateCtx sirve para la ejecución de procedimientos criptográficos de acuerdo de claves sobre la base de una clave privada local y la clave pública de un interlocutor [SWS_CRYPT_21312]. Tras la asignación de la clave propia y de parámetros opcionales, el método AgreeKey calcula un secreto compartido y lo devuelve como un objeto de clave simétrica. Una condición de contorno fundamental es la inicialización completa antes de la ejecución, ya que la falta de parámetros o la ausencia de permisos para kAllowKeyAgreement provocan la cancelación con los códigos de error correspondientes [SWS_CRYPT_21312]. Todas las operaciones están diseñadas para ser seguras frente a subprocesos.

más ›

Contexto

La interfaz ara::crypto::cryp::KeyAgreementPrivateCtx sirve en el módulo crypto de Adaptive Platform para la ejecución de procedimientos asimétricos de acuerdo de claves (Key Agreement). Su responsabilidad principal radica en el cálculo de una clave simétrica compartida a partir de una clave privada local y la clave pública de un interlocutor de comunicación [SWS_CRYPT_21312]. Como contexto criptográfico especializado, la clase interactúa con varias abstracciones de claves y de almacenamiento: la clave privada propia puede vincularse directamente como objeto PrivateKey [SWS_CRYPT_21313] o referenciada a través de un KeySlot [SWS_CRYPT_50053]. La contraparte aporta su clave pública en forma de un PublicKey, mientras que el resultado se proporciona como un objeto SymmetricKey independiente [SWS_CRYPT_21312]. Complementariamente, se pueden transferir parámetros de configuración específicos del algoritmo como área de memoria o número entero [SWS_CRYPT_50051], [SWS_CRYPT_50052].

Diagrama de contexto: interacción de KeyAgreementPrivateCtx con claves, ranuras de clave y objeto de resultado. Fuentes: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50053].

Ciclo de vida

El ciclo de vida y las relaciones de propiedad de KeyAgreementPrivateCtx se basan en punteros compartidos; para ello, la especificación proporciona el alias de tipo KeyAgreementPrivateCtx::Sptr [SWS_CRYPT_21301]. Interpretación: es probable que la instanciación se realice a través de una factoría de nivel superior de un CryptoProvider, ya que la clase representa una interfaz puramente virtual sin especificación de constructor. Pregunta Q-22dca518675fba51 (abierta) Tras su creación, la instancia se encuentra en un estado básico no operativo. El contexto solo se inicializa mediante la configuración de una clave privada con SetKey [SWS_CRYPT_21313], [SWS_CRYPT_50053] y la asignación de todos los parámetros necesarios para el esquema seleccionado [SWS_CRYPT_50051], [SWS_CRYPT_50052].

Si se inicia un cálculo de clave antes de concluir estos pasos de configuración, la llamada falla [SWS_CRYPT_21312]. En lo relativo a la concurrencia, todas las funciones miembro están especificadas como seguras frente a subprocesos (thread-safe), así como seguras frente a excepciones (exception safe) [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Dado que la función de ejecución AgreeKey está declarada como const [SWS_CRYPT_21312], el mismo contexto inicializado puede utilizarse en paralelo para acuerdos con diferentes interlocutores.

Ruta de uso

El uso práctico se divide en una secuencia de configuración y cálculo:

• Asignación de clave: en primer lugar, la aplicación vincula su propia clave privada al contexto. Esto se realiza mediante SetKey(PrivateKey::Sptr) [SWS_CRYPT_21313] para un objeto de clave cargado o mediante SetKey(KeySlot::Sptr) [SWS_CRYPT_50053] para una ranura de clave cuyo contenido solo se evalúa en el momento del acuerdo.
• Definición de parámetros: en caso de que el algoritmo de destino requiera datos de inicialización adicionales, estos se transfieren mediante SetParameter como búfer ReadOnlyMemRegion [SWS_CRYPT_50051] o como número entero de 64 bits std::uint64_t [SWS_CRYPT_50052].
• Acuerdo de claves: con AgreeKey se ejecuta el algoritmo criptográfico [SWS_CRYPT_21312]. El componente llamador transfiere la clave pública del interlocutor (otherSideKey), el identificador del algoritmo de destino deseado (targetAlgId), así como los indicadores de uso permitidos (allowedUsage).
• Adopción del resultado: en caso de finalización satisfactoria, AgreeKey devuelve un objeto SymmetricKey que contiene el secreto compartido calculado [SWS_CRYPT_21312].

Diagrama de secuencia: flujo típico del acuerdo de claves desde la asignación de la clave hasta la generación de la clave simétrica. Fuentes: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051].

Escenarios de error

Los métodos de KeyAgreementPrivateCtx devuelven errores a través de ara::core::Result y garantizan la semántica de reversión (rollback) [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Los escenarios de error típicos incluyen:

• CryptoErrc::kUninitializedContext: se produce en AgreeKey si no se ha establecido previamente ninguna clave o si faltan parámetros requeridos [SWS_CRYPT_21312].
• CryptoErrc::kIncompatibleObject: se notifica cuando un PrivateKey o KeySlot transferido no coincide con el tipo del contexto [SWS_CRYPT_21313], [SWS_CRYPT_50053], o cuando la clave del interlocutor otherSideKey es incompatible [SWS_CRYPT_21312].
• CryptoErrc::kUsageViolation: señala que no se ha concedido el permiso kAllowKeyAgreement para la clave privada o para la clave del interlocutor [SWS_CRYPT_21312], [SWS_CRYPT_21313].
• CryptoErrc::kUnsupported: indica que la implementación del contexto solo admite exclusivamente la otra variante de SetKey [SWS_CRYPT_21313], [SWS_CRYPT_50053], o que no se admite un nombre de parámetro solicitado [SWS_CRYPT_50051], [SWS_CRYPT_50052].
• CryptoErrc::kInvalidArgument: se origina ante valores no válidos en SetParameter [SWS_CRYPT_50051], [SWS_CRYPT_50052] o indicadores allowedUsage no permitidos para la clave de destino [SWS_CRYPT_21312].
• CryptoErrc::kUnknownIdentifier: se desencadena si el identificador targetAlgId para el algoritmo de destino es desconocido [SWS_CRYPT_21312].
• CryptoErrc::kEmptyKeySlot y CryptoErrc::kBusyResource: son devueltos por AgreeKey si el KeySlot configurado no contiene ninguna clave en el momento de la ejecución o si un recurso necesario está ocupado [SWS_CRYPT_21312].