clase ara::crypto::cryp::VerifierPublicCtx

Uso y semántica

El método Cancel() cancela una operación continua en streaming que se inició previamente mediante Start() y que aún no ha concluido [SWS_CRYPT_50023]. Está definido en la cabecera ara/crypto/cryp/verifier_public_ctx.h como método puramente virtual del contexto ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023]. La llamada se realiza de forma síncrona y sin argumentos. Como valor de retorno sirve un ara::core::Result<void>, el cual está vacío en caso de éxito y confirma la cancelación correcta de la operación [SWS_CRYPT_50023].

Manejo de errores

Si el procesamiento de datos aún no ha comenzado mediante la llamada al método Start(), la operación de cancelación falla. En este escenario, la función devuelve un resultado de error con el código de error ara::crypto::CryptoErrc::kProcessingNotStarted garantizando semántica de reversión (rollback) [SWS_CRYPT_50023].

Concurrencia y restricciones

La especificación clasifica el método como seguro para subprocesos (thread-safe) y seguro frente a excepciones (exception safe) con la designación noexcept [SWS_CRYPT_50023]. Interpretación: tras la cancelación correcta, es probable que el contexto vuelva al estado inicial previo al comienzo del procesamiento, de modo que se pueda iniciar un nuevo proceso en streaming. Pregunta Q-d80d09c8a8311bbc (abierta)

Interacción en el módulo crypt

Este patrón de cancelación uniforme con signatura y tratamiento de errores idénticos se aplica de forma coherente a todos los contextos de streaming del módulo crypt:

• MessageAuthnCodeCtx para Message Authentication Codes [SWS_CRYPT_50027],
• SignerPrivateCtx para la generación de firmas digitales [SWS_CRYPT_50041],
• SymmetricCipherCtx para cifrado y descifrado simétrico [SWS_CRYPT_50046],
• HashFunctionCtx para operaciones hash criptográficas [SWS_CRYPT_50058],
• DecryptorPrivateCtx para descifrado asimétrico [SWS_CRYPT_50069],
• AuthCipherCtx para cifrado autenticado [SWS_CRYPT_50077] así como
• EncryptorPublicCtx para cifrado asimétrico [SWS_CRYPT_50089].

El método Finish en ara::crypto::cryp::VerifierPublicCtx finaliza una comprobación de firma y devuelve el resultado de la verificación [SWS_CRYPT_50022]. Recibe a través del búfer de entrada signature (tipo ReadOnlyMemRegion) la firma que se va a comprobar, así como a través de signatureFormat (tipo FormatId) su formato [SWS_CRYPT_50022]. La llamada se realiza de forma sincrónica y, conforme a la especificación, está declarada como thread-safe y exception safe [SWS_CRYPT_50022].

Como valor de retorno sirve un ara::core::Result<bool> [SWS_CRYPT_50022]: si la validación de la firma tiene éxito, el resultado contiene true; si la firma no es válida en cuanto a su contenido, false. Por el contrario, si se produce un error de procesamiento, se devuelve el código de error correspondiente [SWS_CRYPT_50022]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: la operación no se inició previamente con éxito (semántica de reversión) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidInputSize: el tamaño del búfer de signature no es válido (semántica de reversión) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kUnsupportedFormat: el formato indicado signatureFormat no es compatible (semántica de reversión) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidArgument: la firma no se corresponde con el formato especificado (semántica de reversión) [SWS_CRYPT_50022].

En el flujo criptográfico, esta función constituye la contrapartida de la generación de firmas mediante ara::crypto::cryp::SignerPrivateCtx::Finish [SWS_CRYPT_50040], la cual escribe una firma en un búfer de salida. Todos los errores notificados tienen semántica de reversión [SWS_CRYPT_50022], de modo que el estado del contexto permanece consistente en caso de fallo.

El método SetKey configura una instancia de VerifierPublicCtx para el uso de una clave pública concreta destinada a la verificación de firmas ([SWS_CRYPT_24115]). A través del parámetro key se transfiere un puntero de tipo PublicKey::Sptr. La llamada se ejecuta de forma sincrónica y devuelve un ara::core::Result<void>, que en caso de éxito está vacío o bien encapsula un código de error específico.

Según la especificación, la operación está diseñada para ser segura para hilos y segura frente a excepciones (exception safe) ([SWS_CRYPT_24115]). Si se produce un error durante la vinculación de la clave, se aplica para todos los casos de error una semántica de reversión (rollback), de modo que el contexto permanezca en un estado consistente:

• CryptoErrc::kIncompatibleObject: La clave transferida es incompatible con el contexto de verificación de firma ([SWS_CRYPT_24115]).
• CryptoErrc::kUsageViolation: Los permisos de la clave no permiten la verificación de firmas (ausencia del flag de uso para verificación de firmas) ([SWS_CRYPT_24115]).
• ara::crypto::CryptoErrc::kUnsupported: La implementación del contexto solo admite la vinculación de una clave mediante un KeySlot ([SWS_CRYPT_24115]).

En el flujo de trabajo criptográfico, SetKey constituye la contrapartida pública de SignerPrivateCtx::SetKey ([SWS_CRYPT_23515]). En caso de que un contexto no permita la transferencia directa de claves mediante PublicKey::Sptr o las claves se gestionen en slots protegidos, se encuentra disponible de forma alternativa la sobrecarga mediante KeySlot::Sptr ([SWS_CRYPT_50018]).

usar

El método SetKey de la clase ara::crypto::cryp::VerifierPublicCtx configura el contexto de verificación para el uso de una clave que está almacenada en un KeySlot transferido [SWS_CRYPT_50018]. La clave se consulta en el momento en el que se inicia la comprobación de la firma [SWS_CRYPT_50018].

Como parámetro se utiliza un smart pointer keySlot de tipo KeySlot::Sptr, el cual contiene una clave pública [SWS_CRYPT_50018]. La función opera de forma síncrona y devuelve un ara::core::Result<void> para indicar una finalización exitosa o un error [SWS_CRYPT_50018].

Tratamiento de errores y semántica

La operación está especificada como noexcept y exception safe [SWS_CRYPT_50018]. Si se produce un error, se aplica una semántica de reversión (rollback) [SWS_CRYPT_50018]:

• ara::crypto::CryptoErrc::kIncompatibleObject: El KeySlot proporcionado es incompatible con este contexto [SWS_CRYPT_50018].
• ara::crypto::CryptoErrc::kUnsupported: El contexto admite exclusivamente el establecimiento directo de un PublicKey [SWS_CRYPT_50018].

Concurrencia e interacción

El método está especificado como thread-safe [SWS_CRYPT_50018]. Como alternativa a KeySlot, VerifierPublicCtx ofrece una sobrecarga para establecer directamente un PublicKey [SWS_CRYPT_24115]. Una configuración de clave correspondiente a través de un KeySlot existe de forma análoga también en otros contextos como SignerPrivateCtx [SWS_CRYPT_50036] o MessageAuthnCodeCtx [SWS_CRYPT_50026].

usar

El método síncrono Start() de la interfaz ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_50019]) inicializa el contexto para una nueva comprobación de firma criptográfica en modo streaming. La función no recibe parámetros de transferencia, está declarada como noexcept y devuelve un ara::core::Result<void> que está vacío en caso de éxito.

Tratamiento de errores y rollback

Si se produce un error durante la ejecución, se aplica la semántica de rollback ([SWS_CRYPT_50019]), por lo que el contexto permanece en un estado coherente. Las posibles causas de error son:

• UninitializedContext: no se asignó previamente ninguna clave criptográfica al contexto.
• ara::crypto::CryptoErrc::kUsageViolation: la clave asignada no está habilitada para la comprobación de firma (kAllowSig Verification).
• ara::crypto::CryptoErrc::kEmptyKeySlot: un KeySlot configurado para la verificación está actualmente vacío.
• ara::crypto::CryptoErrc::kUnsupported: el contexto no admite streaming o el procedimiento presupone de forma obligatoria un valor de contexto.
• ara::crypto::CryptoErrc::kBusyResource: un recurso necesario para la operación está actualmente ocupado.

Concurrencia e interacción

Aunque la especificación designa el método como seguro para subprocesos ([SWS_CRYPT_50019]), es de suponer que una llamada paralela en la misma instancia de contexto durante una verificación en curso restablezca la operación existente o falle debido a recursos ocupados. Pregunta Q-af5e08ff9d905a29 (abierta)

Tras una inicialización exitosa, las partes del mensaje se pasan secuencialmente mediante Update() ([SWS_CRYPT_50021]). Una operación de streaming en curso se puede cancelar prematuramente con Cancel() ([SWS_CRYPT_50023]) en caso necesario. Si el algoritmo exige imperativamente un valor de contexto, debe llamarse en su lugar a la función sobrecargada Start(ReadOnlyMemRegion context) ([SWS_CRYPT_50020]).

usar

La función Start inicializa, conforme a [SWS_CRYPT_50020], un contexto de verificación de la clase ara::crypto::cryp::VerifierPublicCtx para una nueva verificación de firma. Como parámetro de entrada recibe context del tipo ReadOnlyMemRegion, que proporciona un valor de contexto específico de la aplicación. Como alternativa sin datos de contexto existe la sobrecarga [SWS_CRYPT_50019]. El valor de retorno es ara::core::Result<void>; interpretación: dado que no se definen retrollamadas ni objetos de futuro, es probable que la llamada se procese de forma puramente síncrona. Pregunta Q-4e10cdb1a4343a3a (abierta)

Manejo de errores

En caso de error, la función devuelve un ara::core::Result con un código de error adecuado de ara::crypto::CryptoErrc, estando especificada una semántica de reversión [SWS_CRYPT_50020]:

• kUninitializedContext: El contexto todavía no se ha inicializado mediante la asignación de una clave.
• kEmptyKeySlot: Un KeySlot configurado está actualmente vacío.
• kUsageViolation: El uso permitido de la clave asignada no incluye kAllowSigVerification.
• kInvalidInputSize: El tamaño del búfer del valor de contexto proporcionado no es válido para el algoritmo.
• kUnsupported: El contexto no admite streaming o el algoritmo no admite el establecimiento de un valor de contexto.
• kBusyResource: Un recurso requerido está ocupado.

Concurrencia y restricciones

Según [SWS_CRYPT_50020], el método está clasificado como thread-safe y exception-safe. No lanza excepciones (noexcept).

Interacción

Tras la ejecución con éxito de Start, el mensaje de entrada puede transmitirse paso a paso mediante llamadas repetidas a Update [SWS_CRYPT_50021]. Un proceso de streaming en curso que haya sido iniciado por Start puede cancelarse prematuramente mediante Cancel si es necesario [SWS_CRYPT_50023].

usar

El método Update() sirve para actualizar paso a paso el contexto de verificación de firma con una parte adicional del mensaje de entrada [SWS_CRYPT_50021]. Como parámetro se pasa un área de memoria data del tipo ReadOnlyMemRegion. La función devuelve un ara::core::Result<void>; interpretación: debido a este tipo de retorno, es probable que el procesamiento se realice de forma síncrona. Pregunta Q-f98391030b3b4684 (abierta)

Manejo de errores

En caso de error se devuelve el código de error correspondiente con semántica de reversión [SWS_CRYPT_50021]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: La verificación de firma no se inició previamente mediante la llamada al método Start() [SWS_CRYPT_50021].
• ara::crypto::CryptoErrc::kInvalidInputSize: El tamaño de los datos proporcionados en data no es compatible [SWS_CRYPT_50021].

Concurrencia e interacción

La operación está clasificada en la especificación como thread-safe y exception safe [SWS_CRYPT_50021]. Antes de la llamada debe haberse realizado obligatoriamente la inicialización a través de Start() [SWS_CRYPT_50021]. Para evitar que se produzca kInvalidInputSize, el tamaño máximo de búfer admisible para llamadas individuales se puede consultar mediante el método GetMaximumChunkSize() del mismo contexto [SWS_CRYPT_50025]. La contraparte complementaria para la generación de firmas por mensajes la representa Update() en SignerPrivateCtx [SWS_CRYPT_50039].

usar

El método Verify del contexto ara::crypto::cryp::VerifierPublicCtx sirve para verificar la firma de un mensaje suministrado en una única llamada [SWS_CRYPT_24112]. Como parámetros se pasan el búfer de mensajes message, la firma signature y el formato signatureFormat [SWS_CRYPT_24112]. El valor de retorno ara::core::Result<bool> contiene true en caso de comprobación exitosa, false en caso de no coincidencia o un código de error [SWS_CRYPT_24112]. Interpretación: debido al tipo de resultado síncrono, es probable que el proceso de comprobación se ejecute de forma bloqueante en el subproceso llamador. Pregunta Q-671054c6e2b581c6 (abierta)

Tratamiento de errores y concurrencia

La función está especificada como exception safe y thread-safe [SWS_CRYPT_24112]. En caso de error, se aplica una semántica de rollback para los códigos de error [SWS_CRYPT_24112]. Las posibles causas de error comprenden:

• UninitializedContext, si el contexto no se inicializó con una clave [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kEmptyKeySlot en caso de ranura de clave vacía o kUsageViolation si la clave carece del permiso kAllowSig Verification [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kInvalidInputSize en caso de tamaño de búfer no permitido [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kUnsupportedFormat o kInvalidArgument en caso de formato de firma defectuoso o incompatible [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kBusyResource, si los recursos requeridos están ocupados [SWS_CRYPT_24112].

Interacción

El tamaño de búfer máximo para llamadas individuales se puede consultar mediante GetMaximumChunkSize() [SWS_CRYPT_50025]. Si el algoritmo exige imperativamente un valor de contexto, se devuelve ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_24112]; en este caso, debe elegirse la sobrecarga con el parámetro context adicional [SWS_CRYPT_50024]. A modo de delimitación, para comprobaciones de Message Authentication Codes existe ara::crypto::cryp::MessageAuthnCodeCtx::Verify [SWS_CRYPT_50031].

El método síncrono Verify verifica la firma digital de un mensaje proporcionado teniendo en cuenta un valor de contexto definido por el usuario en una sola llamada ([SWS_CRYPT_50024]). Como parámetros de entrada, el método espera los búferes message, context y signature, cada uno como ReadOnlyMemRegion, así como el formato de la firma mediante signatureFormat ([SWS_CRYPT_50024]). El valor de retorno es un ara::core::Result<bool>: contiene true en caso de verificación correcta, false en caso de firma errónea o un código de error correspondiente ([SWS_CRYPT_50024]).

En caso de error se aplica una semántica de reversión ([SWS_CRYPT_50024]). Los códigos de error específicos incluyen, entre otros:

• UninitializedContext, si el contexto de verificación todavía no se ha inicializado con un valor de clave ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kInvalidInputSize en caso de tamaño de búfer no permitido ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupported, si el algoritmo de firma seleccionado no admite la especificación de un valor de contexto ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupportedFormat o ara::crypto::CryptoErrc::kInvalidArgument, si el formato de firma especificado no es compatible o la firma no se corresponde con el formato ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUsageViolation, si el uso permitido de la clave no incluye kAllowSigVerification, así como ara::crypto::CryptoErrc::kEmptyKeySlot y ara::crypto::CryptoErrc::kBusyResource ([SWS_CRYPT_50024]).

El método está declarado como const noexcept, se considera seguro frente a excepciones y está especificado como thread-safe ([SWS_CRYPT_50024]). En interacción con el contexto, el tamaño máximo de búfer para llamadas individuales puede determinarse a través de GetMaximumChunkSize ([SWS_CRYPT_50025]). Para verificaciones sin contexto, está disponible la sobrecarga alternativa de Verify ([SWS_CRYPT_24112]).