clase ara::crypto::cryp::MessageAuthnCodeCtx

El método virtual puro Cancel sirve en la interfaz ara::crypto::cryp::MessageAuthnCodeCtx para cancelar una operación en flujo continua previamente iniciada mediante Start() y aún no finalizada [SWS_CRYPT_50027]. La llamada se efectúa de forma síncrona, no admite parámetros de entrada y devuelve, en caso de éxito, un ara::core::Result<void> vacío que confirma la cancelación satisfactoria de la operación [SWS_CRYPT_50027].

Si el procesamiento de datos no se inició correctamente antes de la llamada mediante el método Start(), la ejecución falla. En este caso, la función devuelve un resultado con el código de error específico ara::crypto::CryptoErrc::kProcessingNotStarted garantizando una semántica de reversión (rollback) [SWS_CRYPT_50027]. En cuanto a la seguridad de ejecución, la interfaz está especificada como segura para hilos (thread-safe) y garantiza seguridad frente a excepciones (exception safe), ya que está declarada como noexcept y no lanza excepciones [SWS_CRYPT_50027].

El comportamiento de cancelación idéntico para procesamientos en flujo aún no finalizados es compartido por todas las interfaces de contexto afines del módulo criptográfico:

• VerifierPublicCtx para la verificación de firmas digitales [SWS_CRYPT_50023],
• SignerPrivateCtx para la generación de firmas digitales [SWS_CRYPT_50041],
• SymmetricCipherCtx para cifrados simétricos [SWS_CRYPT_50046],
• HashFunctionCtx para cálculos de valores hash [SWS_CRYPT_50058],
• DecryptorPrivateCtx para descifrados asimétricos [SWS_CRYPT_50069],
• AuthCipherCtx para cifrados autenticados [SWS_CRYPT_50077], así como
• EncryptorPublicCtx para cifrados asimétricos [SWS_CRYPT_50089].

Interpretación: Al cancelar la operación incompleta, el contexto debería restablecerse a un estado limpio que permita una posterior reinicialización a través de Start(). Pregunta Q-a8fa5cb85c3dab50 (abierta)

usar

El método puramente virtual Compare de la clase ara::crypto::cryp::MessageAuthnCodeCtx sirve para cotejar el tamaño y el contenido de un Message Authentication Code (MAC) calculado con un digest esperado [SWS_CRYPT_50133]. Como parámetro, el digest MAC esperado se transfiere a través de ReadOnlyMemRegion expected. La función devuelve un ara::core::Result<bool> que contiene true si el valor MAC calculado coincide exactamente con el valor esperado, y en caso contrario false [SWS_CRYPT_50133].

Manejo de errores

En caso de error, se devuelve un código de error en el objeto de resultado, aplicándose una semántica de reversión [SWS_CRYPT_50133]:

• ara::crypto::CryptoErrc::kProcessingNotFinished: Se notifica si el cálculo del digest no se ha concluido previamente mediante la llamada al método Finish() [SWS_CRYPT_50133].
• ara::crypto::CryptoErrc::kInvalidInputSize: Ocurre si el tamaño de búfer transferido del digest MAC esperado no es compatible con el contexto [SWS_CRYPT_50133].

Concurrencia y restricciones

El método está declarado como const, así como noexcept, y según la especificación es seguro frente a subprocesos (thread-safe) y seguro frente a excepciones (exception safe) [SWS_CRYPT_50133]. Una condición previa fundamental es el cálculo del digest completado con éxito previamente mediante Finish() [SWS_CRYPT_50133].

Interacción

A diferencia de Compare, que valida la coincidencia completa de todo el digest MAC [SWS_CRYPT_50133], CompareSubspan únicamente compara en el mismo contexto los bits más significativos (most significant bits) con el valor esperado [SWS_CRYPT_50028]. Para funciones hash sin clave existe una función Compare homónima en ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50154].

El método síncrono CompareSubspan de la clase ara::crypto::cryp::MessageAuthnCodeCtx compara los bits más significativos (Most Significant Bits) de un valor MAC calculado con una referencia predeterminada [SWS_CRYPT_50028]. El valor de comparación esperado se pasa mediante el parámetro expected como ReadOnlyMemRegion [SWS_CRYPT_50028]. El resultado se devuelve como ara::core::Result<bool> y contiene true en caso de identidad de los bits más significativos, así como false en caso de discrepancias [SWS_CRYPT_50028].

Tratamiento de errores y condiciones de ejecución

Para una comparación válida, el cálculo del valor de comprobación debe estar concluido. Si no existe una llamada previa al método Finish(), la llamada falla con el código de error ara::crypto::CryptoErrc::kProcessingNotFinished [SWS_CRYPT_50028]. Si el tamaño de búfer del parámetro expected pasado no es admisible para el procedimiento utilizado, el método notifica ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50028]. Ambos tipos de error garantizan la semántica de rollback [SWS_CRYPT_50028].

Concurrencia y contexto de ejecución

La operación está especificada como noexcept (exception-safe) y clasificada como thread-safe [SWS_CRYPT_50028]. Interpretación: la seguridad para subprocesos declarada probablemente se refiera al estado posterior a la finalización de Finish(), de modo que múltiples subprocesos puedan verificar en paralelo el mismo resumen procesado (digest) calculado. Pregunta Q-ac8b7ead6a5b508e (abierta)

El método Finish() finaliza de forma vinculante el cálculo en curso de un Message Authentication Code (MAC) dentro de la interfaz MessageAuthnCodeCtx [SWS_CRYPT_22115]. La llamada se realiza de forma síncrona, no toma parámetros y devuelve ara::core::Result<void>, lo que en el caso regular de éxito representa un resultado vacío [SWS_CRYPT_22115].

En caso de error, la función devuelve el código de error ara::crypto::CryptoErrc::kProcessingNotStarted si el cálculo del MAC no se ha iniciado con éxito antes de la llamada; en tal caso, se aplica una semántica de reversión (rollback) [SWS_CRYPT_22115]. La operación está declarada como noexcept y, según la especificación, está especificada tanto a prueba de excepciones (exception safe) como segura para subprocesos (thread-safe) [SWS_CRYPT_22115].

En el flujo de procesamiento, Finish() constituye el enlace entre el procesamiento de datos y la evaluación: tras la llamada, el digest de MAC generado se puede transferir a un búfer provisto mediante GetDigest() [SWS_CRYPT_22116] o verificarse directamente contra un valor de referencia con CompareSubspan() [SWS_CRYPT_50028]. Mientras que GetMaximumChunkSize() [SWS_CRYPT_50033] describe de forma genérica tamaños de búfer para Update() o Finish(), Finish() aquí no procesa datos directamente; su mención en el requisito probablemente refleje un patrón uniforme en todos los contextos criptográficos. Pregunta Q-79b4f4ecf3998e48 (abierta)

La función miembro sincrónica Generate de la clase ara::crypto::cryp::MessageAuthnCodeCtx sirve, según [SWS_CRYPT_50029], para el cálculo de un Message Authentication Code (MAC) en un único paso y escribe el resumen calculado en el búfer de salida proporcionado.

Para la llamada se pasan los siguientes parámetros:

• data: datos de entrada para el cálculo del MAC como ReadOnlyMemRegion.
• digest: área de memoria de destino de tipo ReadWriteMemRegion en la que se escribe el resumen.
• iv: un vector de inicialización opcional como ara::core::Optional<ReadOnlyMemRegion>.

En caso de éxito, la función devuelve un ara::core::Result<std::size_t> que contiene el tamaño en bytes del resumen MAC escrito [SWS_CRYPT_50029].

Si se produce un error, se devuelve un código de error con semántica de reversión [SWS_CRYPT_50029]:

• UninitializedContext: el contexto todavía no se ha inicializado mediante la asignación de una clave.
• ara::crypto::CryptoErrc::kUsageViolation: la clave utilizada no posee el indicador de uso requerido kAllowMac. Interpretación: presumiblemente, se generará y configurará previamente una clave simétrica adecuada mediante GenerateSymmetricKey [SWS_CRYPT_20721]. Pregunta Q-d22f397bbc02487b (abierta)
• ara::crypto::CryptoErrc::kEmptyKeySlot: Un KeySlot configurado está actualmente vacío.
• ara::crypto::CryptoErrc::kUnsupported: no se admite el procesamiento mediante llamada única o la especificación del vector de inicialización no cumple los requisitos del algoritmo (VI ausente o indicado de forma no permitida).
• ara::crypto::CryptoErrc::kInvalidInputSize: no se admite el tamaño del búfer de los datos de entrada o del VI.
• ara::crypto::CryptoErrc::kInsufficientCapacity: el búfer de destino digest es demasiado pequeño para el resumen MAC.
• ara::crypto::CryptoErrc::kBusyResource: un recurso del sistema requerido está ocupado.

En lo relativo a la concurrencia, el método está especificado como thread-safe y exception safe [SWS_CRYPT_50029]. Está declarado como const noexcept y no modifica el estado del contexto durante su ejecución.

El método GenerateSubspan de la clase ara::crypto::cryp::MessageAuthnCodeCtx calcula en un único paso un Message Authentication Code (MAC) para los datos de entrada data y escribe el inicio (los bytes más significativos, MSB) del digest calculado en el búfer de salida truncatedDigest [SWS_CRYPT_50030]. Mediante el parámetro opcional iv se puede pasar un vector de inicialización si es necesario [SWS_CRYPT_50030]. El retorno directo de ara::core::Result<std::size_t> probablemente indique una ejecución síncrona; si el proceso se completa con éxito, se devuelve el número de bytes escritos del digest de MAC [SWS_CRYPT_50030]. Pregunta Q-167c6d44b9f39fed (abierta)

Para el caso de error, la especificación define una semántica de reversión y prevé los siguientes códigos de error [SWS_CRYPT_50030]:

• UninitializedContext: El contexto no se inicializó previamente mediante la asignación de una clave [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Un KeySlot configurado está actualmente vacío [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUsageViolation: El uso permitido de la clave no incluye kAllowMac [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUnsupported: No se admite el procesamiento en un único paso, o bien la configuración del IV no concuerda con el contexto (falta el IV requerido o se ha suministrado un IV no permitido) [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kInvalidInputSize: No se admite el tamaño de los datos pasados data o del iv [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kBusyResource: un recurso necesario está ocupado [SWS_CRYPT_50030].

En lo que respecta al entorno de ejecución, el método está especificado como thread-safe y ofrece seguridad frente a excepciones (noexcept) [SWS_CRYPT_50030]. Para una llamada sin fallos se requiere la provisión previa en el contexto de una clave con la autorización correspondiente [SWS_CRYPT_50030].

El método SetKey configura una instancia de ara::crypto::cryp::MessageAuthnCodeCtx para el cálculo posterior de MAC con una clave simétrica proporcionada [SWS_CRYPT_22118]. La llamada se realiza de forma síncrona y recibe el objeto de clave como puntero inteligente SymmetricKey::Sptr. Como resultado, la función devuelve un ara::core::Result<void> que está vacío en caso de éxito o encapsula un código de error específico en caso de error [SWS_CRYPT_22118].

Si la asignación falla, se aplica una semántica de reversión que preserva el estado anterior del contexto [SWS_CRYPT_22118]. Se especifican los siguientes estados de error de ara::crypto::CryptoErrc:

• kUnsupported: El contexto admite exclusivamente la vinculación mediante un KeySlot en lugar de a través de objetos de clave directos [SWS_CRYPT_22118].
• kIncompatibleObject: El objeto de clave simétrica pasado es incompatible con el contexto de destino [SWS_CRYPT_22118].
• kUsageViolation: Los indicadores de autorización de la clave no contienen el uso obligatorio kAllowMac [SWS_CRYPT_22118].

En cuanto a la seguridad de ejecución, la interfaz está definida como thread-safe y exception safe (con noexcept) [SWS_CRYPT_22118]. En interacción con la gestión de claves, representa la contraparte directa de la asignación basada en ranuras: si una implementación o un caso de uso admite la utilización de ranuras persistidas, se utiliza en su lugar la sobrecarga para KeySlot::Sptr [SWS_CRYPT_50026].

usar

La función miembro virtual SetKey de la interfaz ara::crypto::cryp::MessageAuthnCodeCtx del archivo de cabecera ara/crypto/cryp/message_authn_code_ctx.h configura el contexto para el cálculo o la verificación de un Message Authentication Code (MAC) [SWS_CRYPT_50026]. Como parámetro, el método sincrónico recibe un puntero inteligente keySlot de tipo KeySlot::Sptr que contiene una clave simétrica, y devuelve un ara::core::Result<void> [SWS_CRYPT_50026]. La vinculación de la clave es semánticamente diferida: la clave almacenada en el slot solo se utiliza en el momento en que se inicia efectivamente el cálculo del MAC [SWS_CRYPT_50026]. Interpretación: Las actualizaciones posteriores del contenido del slot hasta el inicio del cálculo deberían, por tanto, surtir efecto. Pregunta Q-d1886811d8af71e3 (abierta)

Concurrencia y seguridad de ejecución

La interfaz está definida como noexcept, garantiza seguridad frente a excepciones (exception safe) y está especificada explícitamente para la invocación concurrente (thread-safe) [SWS_CRYPT_50026].

Tratamiento de errores e interacción

En caso de error, el método garantiza una estricta semántica de reversión, de modo que el estado anterior del contexto se conserva por completo [SWS_CRYPT_50026]. En el objeto de resultado pueden presentarse los siguientes códigos de error:

• ara::crypto::CryptoErrc::kIncompatibleObject: El KeySlot transferido es incompatible con este contexto de clave simétrica [SWS_CRYPT_50026].
• ara::crypto::CryptoErrc::kUnsupported: La implementación concreta del contexto no admite el establecimiento mediante KeySlot [SWS_CRYPT_50026]. En este caso, debe utilizarse alternativamente la sobrecarga SetKey(SymmetricKey::Sptr) para la transferencia directa de una clave [SWS_CRYPT_22118].

El método Start de ara::crypto::cryp::MessageAuthnCodeCtx inicializa el contexto para un nuevo cálculo de MAC y establece en ello un vector de inicialización o valor nonce a través del parámetro iv ([SWS_CRYPT_22110]). Esto se utiliza, por ejemplo, en algoritmos como GMAC ([SWS_CRYPT_22110]). Para cálculos sin vector de inicialización explícito está disponible alternativamente la sobrecarga sin parámetros Start() ([SWS_CRYPT_22111]).

Uso y concurrencia

La llamada se realiza de forma síncrona y está especificada como thread-safe y exception safe ([SWS_CRYPT_22110]). Tras una llamada correcta, se pueden transferir partes sucesivas del mensaje al contexto mediante Update ([SWS_CRYPT_22113]). Una operación de transmisión continua (streaming) en curso aún no finalizada puede cancelarse en caso necesario mediante Cancel ([SWS_CRYPT_50027]).

Manejo de errores

El método devuelve un ara::core::Result<void> que posee semántica de reversión en caso de error ([SWS_CRYPT_22110]). Los posibles estados de error son:

• UninitializedContext: No se asignó previamente ninguna clave al contexto ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: Un KeySlot configurado está vacío ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUsageViolation: Los permisos de la clave no contienen kAllowMac ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kInvalidInputSize: El tamaño de IV proporcionado no es compatible ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUnsupported: El algoritmo o el contexto no admiten el streaming ni el establecimiento de un IV ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kBusyResource: Un recurso necesario está ocupado ([SWS_CRYPT_22110]).

usar

El método Start() inicializa una instancia de ara::crypto::cryp::MessageAuthnCodeCtx para un nuevo cálculo de MAC [SWS_CRYPT_22111]. La llamada no acepta parámetros y devuelve un ara::core::Result<void> [SWS_CRYPT_22111]. Es de suponer que la ejecución se realiza de forma síncrona, ya que se proporciona directamente un objeto de resultado. Pregunta Q-1e6e36f4ed1176d3 (abierta)

Tratamiento de errores y concurrencia

Si se produce un error durante la inicialización, se aplica la semántica de reversión y se devuelve uno de los siguientes códigos de error [SWS_CRYPT_22111]:

• UninitializedContext: no se ha asignado previamente ninguna clave al contexto [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUnsupported: el contexto no admite streaming o el algoritmo requiere obligatoriamente un vector de inicialización (IV) [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kBusyResource: un recurso necesario está ocupado [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kEmptyKeySlot: un KeySlot configurado está vacío [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUsageViolation: la clave no permite el cálculo de MAC sin haber establecido kAllowMac [SWS_CRYPT_22111].

La función está especificada como segura para subprocesos y segura frente a excepciones (exception safe) [SWS_CRYPT_22111].

Interacción en el flujo de streaming

Si el algoritmo requiere un IV (p. ej., GMAC), se debe utilizar en su lugar la sobrecarga Start(ReadOnlyMemRegion iv) [SWS_CRYPT_22110]. Tras una llamada correcta, los datos del mensaje se pueden pasar progresivamente a través de Update() [SWS_CRYPT_22113]. Una operación de streaming que aún no haya concluido se puede descartar mediante Cancel() [SWS_CRYPT_50027].

usar

El método síncrono Update del contexto ara::crypto::cryp::MessageAuthnCodeCtx sirve para complementar el cálculo en curso de un Message Authentication Code (MAC) con un fragmento adicional del mensaje de entrada [SWS_CRYPT_22113]. La sección de datos que se va a procesar se pasa mediante el parámetro data en forma de ReadOnlyMemRegion. Como valor de retorno, la función proporciona un ara::core::Result<void> que confirma el paso intermedio exitoso o, en caso de error, informa sobre la causa del error [SWS_CRYPT_22113].

Tratamiento de errores y concurrencia

En caso de error, se garantiza una semántica de rollback, de modo que el estado de cálculo previo permanece inalterado [SWS_CRYPT_22113]. Las posibles causas de error son:

• ara::crypto::CryptoErrc::kProcessingNotStarted: el cálculo no se inició previamente mediante la llamada al método Start() [SWS_CRYPT_22113].
• ara::crypto::CryptoErrc::kInvalidInputSize: el contexto no admite el tamaño del bloque de datos proporcionado [SWS_CRYPT_22113].

El método está declarado como noexcept y especificado como seguro para subprocesos (thread-safe) y seguro frente a excepciones (exception safe) [SWS_CRYPT_22113].

Interacción

Para evitar errores de búfer con ara::crypto::CryptoErrc::kInvalidInputSize, el tamaño de entrada máximo permitido para llamadas individuales se puede consultar previamente a través del método GetMaximumChunkSize() [SWS_CRYPT_50033]. Tras procesar sucesivamente todas las partes del mensaje, según la interpretación, el cálculo de la etiqueta MAC concluiría típicamente a través del método Finish() [SWS_CRYPT_50033]. Pregunta Q-7f8eaf8ebbf30d55 (abierta)

usar

El método Verify en ara::crypto::cryp::MessageAuthnCodeCtx ([SWS_CRYPT_50031]) sirve para el cálculo sincrónico de un resumen MAC sobre el búfer de entrada data y su comparación directa con el valor esperado expected. De forma opcional, se puede pasar un vector de inicialización a través de iv. Como resultado, la función devuelve un ara::core::Result<bool> que contiene true si el MAC calculado coincide con la secuencia de bytes esperada; en caso contrario, false.

Manejo de errores

Si la verificación falla por razones sistémicas o criptográficas, el método devuelve un ara::core::Result con el código de error correspondiente ([SWS_CRYPT_50031]):

• UninitializedContext: si el contexto no se ha inicializado previamente mediante la asignación de una clave.
• ara::crypto::CryptoErrc::kEmptyKeySlot: si el KeySlot configurado está vacío.
• ara::crypto::CryptoErrc::kUsageViolation: si el uso permitido de la clave no incluye kAllowMac.
• ara::crypto::CryptoErrc::kInvalidInputSize: si el tamaño del búfer de data, expected o iv no es válido.
• ara::crypto::CryptoErrc::kUnsupported: si no se admite la ejecución mediante llamada única o la provisión del iv no se corresponde con las exigencias del algoritmo.
• ara::crypto::CryptoErrc::kBusyResource: en caso de conflictos de recursos.

Concurrencia e interacción

El método está especificado como thread-safe y exception safe ([SWS_CRYPT_50031]). En caso de error, se aplica una semántica de reversión. A diferencia de las comprobaciones de firma asimétrica en ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_24112], [SWS_CRYPT_50024]), Verify opera sobre contextos MAC simétricos. El tamaño de búfer máximo procesable en una llamada única probablemente esté limitado —de forma análoga a la consulta de búfer en los verificadores de firma ([SWS_CRYPT_50025])— por la implementación del contexto. Pregunta Q-51e7427e4e082881 (abierta)

El método VerifySubspan de la clase ara::crypto::cryp::MessageAuthnCodeCtx sirve para calcular de forma síncrona un digest de MAC y comparar a continuación sus bits más significativos con una secuencia de bytes esperada [SWS_CRYPT_50032]. Procesa datos de entrada a través de data, los bits iniciales esperados a través de expected, así como un vector de inicialización opcional a través de iv [SWS_CRYPT_50032]. El resultado se devuelve como ara::core::Result<bool> y, en caso de coincidencia exitosa, indica true, o de lo contrario false [SWS_CRYPT_50032].

La interfaz está especificada como noexcept, es exception safe así como thread-safe y aplica una semántica de reversión en caso de error [SWS_CRYPT_50032]. Las llamadas fallidas entregan códigos de error específicos en el valor de retorno [SWS_CRYPT_50032]:

• UninitializedContext: El contexto no se inicializó previamente mediante la asignación de una clave [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUsageViolation: el uso permitido de la clave no incluye kAllowMac [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Un KeySlot configurado está actualmente vacío [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kInvalidInputSize: No se admite el tamaño de los datos pasados, del valor de comprobación esperado o del IV [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUnsupported: No se admite la operación de llamada única (single-call) o el suministro del IV contradice los requisitos del contexto [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kBusyResource: un recurso necesario está ocupado [SWS_CRYPT_50032].