clase ara::crypto::cryp::HashFunctionCtx

El método CalculateHashDigest realiza un cálculo one-shot síncrono de un valor hash criptográfico y escribe el resultado en el búfer de salida proporcionado [SWS_CRYPT_50060]. Se pasan como parámetros el mensaje de entrada a procesar data, el búfer de destino digest y, opcionalmente, un vector de inicialización iv. En caso de ejecución correcta, la función devuelve a través del objeto de resultado ara::core::Result<std::size_t> el número real de bytes de digest escritos [SWS_CRYPT_50060].

Manejo de errores

Si el cálculo falla, la interfaz garantiza una semántica de reversión [SWS_CRYPT_50060]. El resultado puede contener los siguientes códigos de error:

• ara::crypto::CryptoErrc::kInvalidInputSize: El tamaño de los datos pasados o del vector de inicialización no es compatible [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported: El contexto no admite el cálculo mediante llamada única (single-call), o la transferencia del vector de inicialización no coincide con la configuración del contexto (IV requerido pero ausente, o bien IV transferido aunque no es compatible) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity: La capacidad del búfer de salida digest no es suficiente para el digest calculado [SWS_CRYPT_50060].

Concurrencia e interacción

La función está declarada como segura frente a excepciones (exception safe) y segura frente a hilos (thread-safe) [SWS_CRYPT_50060]. Para evitar de antemano errores relativos a longitudes de entrada no permitidas, el tamaño de búfer máximo permitido del contexto para una única llamada puede determinarse a través de GetMaximumChunkSize [SWS_CRYPT_50062].

usar

El método Cancel() sirve para la cancelación selectiva de una operación de streaming en curso que se inició previamente mediante el método Start() y aún no ha concluido con normalidad [SWS_CRYPT_50058]. La llamada se realiza de forma sincrónica y sin parámetros en una instancia de ara::crypto::cryp::HashFunctionCtx del archivo de cabecera ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. Si se ejecuta con éxito, la operación devuelve un ara::core::Result<void> vacío [SWS_CRYPT_50058].

Manejo de errores

Si surge un problema durante la ejecución, el ara::core::Result devuelto contiene un valor de error correspondiente [SWS_CRYPT_50058]. Si el procesamiento no se inició mediante Start() antes de la llamada a Cancel(), la cancelación falla y devuelve el código de error específico ara::crypto::CryptoErrc::kProcessingNotStarted con semántica de reversión [SWS_CRYPT_50058].

Concurrencia y restricciones

La interfaz está definida como thread-safe y exception safe, y está declarada con noexcept [SWS_CRYPT_50058]. Como condición previa funcional esencial, el procesamiento de datos debe encontrarse en un estado activo generado por una llamada previa a Start() [SWS_CRYPT_50058].

Interacción

El patrón implementado por Cancel() está estandarizado en diversos contextos de streaming de la pila criptográfica. Los contextos VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] y EncryptorPublicCtx [SWS_CRYPT_50089] también presentan una semántica y una señalización de errores exactamente coincidentes.

El método Compare de la clase ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) compara de forma síncrona el tamaño y el contenido de un digest hash calculado previamente con un valor de referencia esperado. El valor nominal se transfiere a través del parámetro expected del tipo ReadOnlyMemRegion. En caso de éxito, la función devuelve un ara::core::Result<bool> que contiene true si y solo si la secuencia de bytes esperada es idéntica al digest calculado.

El requisito previo para la llamada es que el cálculo del digest se haya concluido previamente con el método Finish(). Si este no es el caso, la llamada falla y devuelve el error ara::crypto::CryptoErrc::kProcessingNotFinished con semántica de reversión ([SWS_CRYPT_50154]). Interpretación: Es de suponer que una longitud discrepante o un contenido no coincidente de expected no dé lugar a un código de error, sino a un false regular en el objeto de resultado. Pregunta Q-fdd0ecaec22f6985 (abierta)

En cuanto a la concurrencia, el método está especificado como thread-safe y exception safe ([SWS_CRYPT_50154]). Debido a su declaración como noexcept, no lanza excepciones de C++.

En contextos criptográficos relacionados se utiliza el mismo patrón de comprobación: para Message Authentication Codes, ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) compara el tamaño y el contenido del valor MAC calculado, mientras que CompareSubspan ([SWS_CRYPT_50028]) comprueba los bits más significativos. Ambos métodos exigen por igual un cálculo finalizado previamente.

El método [SWS_CRYPT_50064] de la clase ara::crypto::cryp::HashFunctionCtx escribe de forma síncrona el estado actual de un contexto de hash en el búfer de salida pasado contextState de tipo ReadWriteMem Region. Esto permite a las aplicaciones interrumpir una operación de hash criptográfica en curso y reanudarla en un momento posterior. En caso de ejecución correcta, la llamada devuelve un ara::core::Result<void> vacío.

Interacción y dimensionamiento del búfer

Para evitar errores de memoria, el tamaño de búfer en bytes estrictamente necesario debe consultarse de antemano a través de la función [SWS_CRYPT_50063]. El estado exportado puede reimportarse posteriormente en un contexto de hash mediante [SWS_CRYPT_50065]. El requisito para ello es que el contexto de destino presente la misma AlgorithmId y sea proporcionado por el mismo Crypto Provider que el contexto de origen. Al realizar la importación, cualquier estado de cálculo existente se sobrescribe por completo.

Manejo de errores

Si la operación falla, se devuelve un error en el ara::core::Result. Se especifican los siguientes códigos de error de ara::crypto::CryptoErrc:

• ara::crypto::CryptoErrc::kUnsupported: El contexto concreto no admite la exportación o importación de estados.
• ara::crypto::CryptoErrc::kInsufficientCapacity: La capacidad del búfer pasado contextState no es suficiente para albergar el estado.

Para ambos casos de error se define una semántica de reversión, de modo que el estado del objeto permanece inalterado.

Concurrencia y seguridad de ejecución

La interfaz está declarada como const y noexcept. Según la especificación, la llamada es tanto thread-safe como exception-safe.

usar

El método síncrono Finish() finaliza el cálculo de un valor hash en ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_21115]. La llamada sin parámetros devuelve un ara::core::Result<void> que señala la finalización correcta o encapsula un error [SWS_CRYPT_21115]. La interfaz está declarada como noexcept y especificada como segura frente a excepciones (exception safe) y segura para hilos (thread-safe) [SWS_CRYPT_21115].

Tratamiento de errores y concurrencia

Si el cálculo de hash no se inició correctamente antes de la llamada, el método falla con el error ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_21115]. Para este caso de error se define una semántica de reversión, de modo que los llamantes deben asegurarse obligatoriamente de contar con un contexto debidamente iniciado antes de la finalización [SWS_CRYPT_21115].

Interacción

Tras una llamada correcta a Finish(), el digest hash calculado se transfiere típicamente con GetDigest() a un búfer provisto [SWS_CRYPT_21116], [SWS_CRYPT_50059]. Como diferenciación sirve GetIntermediateDigest(): esta función proporciona el mismo valor hash que la secuencia de Finish() y GetDigest(), pero permite a continuación el paso de más datos [SWS_CRYPT_50059]. Interpretación: Tras la llamada a Finish(), es de esperar que el cálculo haya finalizado definitivamente y que el contexto ya no acepte datos adicionales. Pregunta Q-f4daf29364f45fd5 (abierta) Los tamaños de búfer admisibles para los pasos de procesamiento en el contexto pueden consultarse mediante GetMaximumChunkSize() [SWS_CRYPT_50062].

El método ImportContextState de la clase ara::crypto::cryp::HashFunctionCtx (definido en ara/crypto/cryp/hash_function_ctx.h) sirve para restaurar el estado interno de un contexto de hash a partir de un búfer pasado y continuar así una operación de hash interrumpida previamente [SWS_CRYPT_50065]. Cualquier estado de cálculo en curso del contexto actual se sustituye completamente por el estado importado [SWS_CRYPT_50065].

Llamada y condiciones previas

La llamada síncrona se realiza a través de la firma ImportContextState(ReadOnlyMem Region contextState) noexcept y devuelve un ara::core::Result<void> [SWS_CRYPT_50065]. Para el parámetro contextState se aplican los siguientes requisitos obligatorios:

• El búfer de datos debe haber sido exportado previamente con el método ExportContextState() desde una instancia de HashFunctionCtx [SWS_CRYPT_50065].
• El contexto de origen debe haber tenido la misma AlgorithmId y haber sido proporcionado por el mismo Crypto Provider que el contexto de destino [SWS_CRYPT_50065].

Tratamiento de errores y concurrencia

En caso de error, se devuelve un código de error con semántica de reversión, de modo que el estado existente del contexto permanezca inalterado ante un fallo [SWS_CRYPT_50065]:

• ara::crypto::CryptoErrc::kInvalidArgument: El argumento contextState contiene datos no válidos [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported: El contexto específico no soporta la exportación e importación de estados de contexto [SWS_CRYPT_50065].

La operación está especificada como thread-safe y exception safe [SWS_CRYPT_50065].

El método Start() de la interfaz ara::crypto::cryp::HashFunctionCtx inicializa el contexto para el cálculo paso a paso de un valor hash sin vector de inicialización (IV) [SWS_CRYPT_50152]. Una nueva llamada cancela un cálculo de hash que posiblemente ya esté en curso y configura el contexto para un nuevo cálculo [SWS_CRYPT_50152].

La función es síncrona, no recibe parámetros y devuelve un ara::core::Result<void> [SWS_CRYPT_50152]. Si se produce un error durante la inicialización, se aplica la semántica de reversión con los siguientes códigos de error específicos [SWS_CRYPT_50152]:

• ara::crypto::CryptoErrc::kUnsupported: la función hash utilizada requiere obligatoriamente un vector de inicialización [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource: un recurso interno imprescindible para la operación está ocupado [SWS_CRYPT_50152].

En cuanto a la concurrencia, el método está especificado como thread-safe y exception safe, y está declarado como noexcept [SWS_CRYPT_50152]. Tras una inicialización correcta, las partes del mensaje se pueden suministrar secuencialmente a través del método Update() del contexto [SWS_CRYPT_21113]. Dado que la llamada cancela los cálculos en curso, en la práctica la función probablemente también sirve como mecanismo de restablecimiento antes de un reinicio. Pregunta Q-9c369489a6c6e8cb (abierta)

usar

La función Start de la interfaz ara::crypto::cryp::HashFunctionCtx inicializa el contexto para el cálculo de un resumen de hash utilizando un vector de inicialización (IV) [SWS_CRYPT_50153]. Como parámetro, el vector de inicialización iv se transfiere a través de un ReadOnlyMemRegion [SWS_CRYPT_50153]. La llamada síncrona devuelve un ara::core::Result<void>, que en caso de éxito no contiene ningún valor de retorno [SWS_CRYPT_50153]. Una llamada cancela además un cálculo de hash que posiblemente ya esté en curso en este contexto [SWS_CRYPT_50153].

Manejo de errores

Si se produce un error durante la inicialización, se devuelve un código de error correspondiente, garantizándose una semántica de reversión para todos los casos de error [SWS_CRYPT_50153]:

• ara::crypto::CryptoErrc::kInvalidInputSize: el tamaño del vector de inicialización proporcionado no es compatible [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported: la función hash subyacente no utiliza ningún vector de inicialización [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource: un recurso necesario para la inicialización está ocupado [SWS_CRYPT_50153].

Concurrencia e interacción

La interfaz está declarada como noexcept y especificada como segura para subprocesos (thread-safe) y segura frente a excepciones (exception safe) [SWS_CRYPT_50153]. En el flujo típico, la llamada constituye la condición previa para el posterior procesamiento secuencial del mensaje de entrada a través del método Update [SWS_CRYPT_21113].

El método síncrono Update sirve en [SWS_CRYPT_21113] para la actualización incremental de un contexto de cálculo de hash en curso (ara::crypto::cryp::HashFunctionCtx). A través del parámetro data (ReadOnlyMemRegion) se transmite una parte del mensaje de entrada que se va a procesar. La función devuelve un ara::core::Result<void> que está vacío en caso de éxito o encapsula un código de error correspondiente.

En lo relativo al comportamiento ante errores, el método ofrece semántica de reversión en dos estados de error específicos:

• ara::crypto::CryptoErrc::kProcessingNotStarted: el cálculo no se inició previamente mediante una llamada al método Start() [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize: el tamaño de los datos transmitidos no es admitido por el contexto [SWS_CRYPT_21113].

Para el contexto de llamada rigen condiciones claras de orden y tamaño: antes de la transferencia de datos, la operación de hash debe haberse inicializado [SWS_CRYPT_21113]. Para evitar kInvalidInputSize, el tamaño de bloque máximo permitido para una única llamada a Update se puede determinar previamente mediante GetMaximumChunkSize [SWS_CRYPT_50062]. Conforme a la especificación, la función está declarada como segura frente a excepciones (exception safe) y segura para subprocesos (thread-safe) [SWS_CRYPT_21113].

En la interacción con otras interfaces, dentro de HashFunctionCtx existe una sobrecarga para transferir objetos de clave mediante Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. Tras el suministro de todos los bloques de datos, la finalización del valor de comprobación presumiblemente debería realizarse mediante Finish() [SWS_CRYPT_50062]. Pregunta Q-dcac20f353ca55f4 (abierta)

El método síncrono Update sirve en [SWS_CRYPT_50057] para ampliar paso a paso el contexto de un cálculo de valor hash en ara::crypto::cryp::HashFunctionCtx con un nuevo segmento de mensaje en forma de objeto de clave. Como parámetro se pasa un puntero inteligente al objeto de clave (CryptoObject::Sptr key). La llamada devuelve como valor de retorno un ara::core::Result<void> que, en caso de procesamiento correcto, está vacío o, en caso de error, encapsula un código de error correspondiente [SWS_CRYPT_50057].

Como condición de secuencia se aplica que el cálculo debe haberse iniciado previamente de forma obligatoria mediante la llamada a Start(); de lo contrario, se notifica el error ProcessingNotStarted [SWS_CRYPT_50057]. Otros casos de error específicos incluyen (cada uno con semántica de reversión) [SWS_CRYPT_50057]:

• ara::crypto::CryptoErrc::kUnsupported, si el contexto de hash no soporta en general el cálculo de hash de claves,
• ara::crypto::CryptoErrc::kIncompatibleObject, si el objeto de clave pasado no es compatible con el contexto,
• ara::crypto::CryptoErrc::kUsageViolation, siempre que el uso permitido de la clave no incluya kAllowHash Calculation,
• ara::crypto::CryptoErrc::kInvalidInputSize, si el tamaño de datos de la clave pasada no está soportado.

El método está declarado como thread-safe así como exception safe (noexcept) [SWS_CRYPT_50057]. En interacción con otras interfaces del módulo, el tamaño de búfer máximo admisible para llamadas individuales a Update se puede determinar a través de GetMaximumChunkSize() [SWS_CRYPT_50062]. Para partes regulares del mensaje sin objeto de clave, existe en paralelo en HashFunctionCtx la sobrecarga Update(ReadOnlyMemRegion data) [SWS_CRYPT_21113].