clase ara::crypto::cryp::SignerPrivateCtx

El método Cancel() sirve para la cancelación sincrónica de una operación de streaming en curso y aún no finalizada dentro de la clase ara::crypto::cryp::SignerPrivateCtx, la cual se inició previamente mediante una llamada a Start() [SWS_CRYPT_50041]. La interfaz puramente virtual virtual ara::core::Result<void> Cancel() noexcept = 0; está declarada en la cabecera ara/crypto/cryp/signer_private_ctx.h, no recibe parámetros de entrada y señala la cancelación correcta a través de un ara::core::Result<void> vacío [SWS_CRYPT_50041]. Para el llamador, el método está especificado como seguro frente a excepciones (exception safe) y seguro para subprocesos concurrentes (thread-safe) [SWS_CRYPT_50041].

Con respecto al orden de llamada y al tratamiento de errores, Cancel() requiere obligatoriamente un procesamiento activo: si el procesamiento de datos no se inició previamente mediante una llamada al método Start(), la cancelación falla y devuelve el código de error ara::crypto::CryptoErrc::kProcessingNotStarted con semántica de reversión definida [SWS_CRYPT_50041]. Interpretación: tras una llamada exitosa a Cancel(), es probable que el contexto vuelva a un estado básico no iniciado, de modo que se pueda comenzar un nuevo proceso de firma o de streaming. Pregunta Q-348fb3ae43e424c9 (abierta)

El diseño sigue un principio uniforme para todas las operaciones de streaming en el módulo criptográfico. Existen firmas y semánticas de error completamente idénticas para contextos afines como VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SymmetricCipherCtx [SWS_CRYPT_50046], HashFunctionCtx [SWS_CRYPT_50058], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] y EncryptorPublicCtx [SWS_CRYPT_50089].

usar

El método ara::crypto::cryp::SignerPrivateCtx::Finish finaliza la generación de firmas de forma sincrónica y escribe la firma calculada directamente en el búfer de salida proporcionado signature [SWS_CRYPT_50040]. La función espera como parámetros de entrada el área de memoria modificable signature (tipo ReadWriteMemRegion) y el formato deseado signatureFormat (tipo FormatId) [SWS_CRYPT_50040]. Como valor de retorno, ara::core::Result<size_t> devuelve el tamaño real en bytes de los datos de firma escritos; esta cantidad de datos puede ser menor que la capacidad del búfer de destino [SWS_CRYPT_50040].

Manejo de errores

Para todos los casos de error que se produzcan está especificada una semántica de reversión [SWS_CRYPT_50040]. A través del resultado pueden devolverse los siguientes códigos de error:

• ara::crypto::CryptoErrc::kProcessingNotStarted: la generación de firma no se inició previamente con éxito [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kInsufficientCapacity: la capacidad del búfer de salida signature pasado es insuficiente [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kUnsupportedFormat: el valor de signatureFormat es desconocido o no es compatible [SWS_CRYPT_50040].

Concurrencia y restricciones

El método está especificado como thread-safe y exception safe y no debe lanzar excepciones (noexcept) [SWS_CRYPT_50040]. Una llamada válida presupone imperativamente que el proceso de generación se haya iniciado previamente con éxito en el contexto [SWS_CRYPT_50040].

Interacción

La contrapartida funcional directa para la verificación de la firma generada la constituye el método ara::crypto::cryp::VerifierPublicCtx::Finish [SWS_CRYPT_50022]. En comparación con los contextos para cálculos hash o MAC, en los que Finish() solo finaliza el cálculo y el resultado intermedio o final se recupera por separado [SWS_CRYPT_21115] [SWS_CRYPT_21116], SignerPrivateCtx::Finish escribe la firma directamente en el búfer [SWS_CRYPT_50040].

usar

El método virtual SetKey de la clase ara::crypto::cryp::SignerPrivateCtx (#include "ara/crypto/cryp/signer_private_ctx.h") configura el contexto de firma para el uso de una clave privada proporcionada [SWS_CRYPT_23515]. Como parámetro, se transfiere key de tipo PrivateKey::Sptr como objeto de clave de origen [SWS_CRYPT_23515]. El método se ejecuta de forma sincrónica y devuelve un ara::core::Result<void>, el cual está vacío en caso de éxito o transmite el código de error ocurrido en caso de error [SWS_CRYPT_23515].

Manejo de errores

Si se produce un error durante la configuración, se aplica una semántica de reversión (rollback) [SWS_CRYPT_23515]. Se especifican los siguientes códigos de error:

• ara::crypto::CryptoErrc::kIncompatibleObject: el objeto de clave transferido es incompatible con el contexto actual [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUsageViolation: el uso permitido de la clave no comprende la generación de firmas (kAllowSig Generation) [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUnsupported: el contexto específico solo admite el establecimiento mediante un KeySlot [SWS_CRYPT_23515].

Concurrencia y restricciones

La interfaz está declarada como noexcept y, según la especificación, está clasificada tanto segura frente a excepciones («exception safe») como segura para subprocesos («thread-safe») [SWS_CRYPT_23515].

Interacción

En SignerPrivateCtx existe alternativamente la sobrecarga SetKey(KeySlot::Sptr), la cual configura el contexto de tal modo que la clave almacenada en un KeySlot no se utiliza hasta el momento de inicio del cálculo de la firma [SWS_CRYPT_50036]. Para la comprobación de firmas sirve, en la parte de verificación, la contrapartida funcional SetKey con PublicKey::Sptr dentro de ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_24115].

usar

El método SetKey configura el contexto de firma [SWS_CRYPT_50036] para el uso de una clave que se encuentra en el KeySlot::Sptr pasado. La clave se utiliza únicamente en el momento en que se inicia el cálculo real de la firma [SWS_CRYPT_50036]. La llamada se realiza de forma síncrona, está declarada como noexcept y devuelve un ara::core::Result<void> [SWS_CRYPT_50036].

Manejo de errores

Si la configuración falla, se transmite un error en el objeto de retorno, aplicándose la semántica de reversión (rollback) [SWS_CRYPT_50036]:

• ara::crypto::CryptoErrc::kIncompatibleObject: se produce cuando el keySlot proporcionado no es compatible con este contexto de firma [SWS_CRYPT_50036].
• ara::crypto::CryptoErrc::kUnsupported: se notifica si el contexto admite exclusivamente el establecimiento directo de un PrivateKey [SWS_CRYPT_50036].

Concurrencia e interacción

La interfaz pertenece a la clase ara::crypto::cryp::SignerPrivateCtx y está especificada como segura para subprocesos (thread-safe), así como segura frente a excepciones (exception-safe) [SWS_CRYPT_50036]. Además de esta variante basada en slots, SignerPrivateCtx también proporciona una sobrecarga que acepta directamente un objeto PrivateKey::Sptr [SWS_CRYPT_23515]. Existen vinculaciones de slots análogas para otros contextos criptográficos, por ejemplo para la verificación de firmas con KeySlot en VerifierPublicCtx [SWS_CRYPT_50018] o para la derivación de claves en KeyDerivationFunctionCtx [SWS_CRYPT_50010].

El método Sign firma un mensaje de forma síncrona en un único paso según [SWS_CRYPT_23512]. Acepta el mensaje de entrada que se va a firmar (message), el búfer de destino (signature), el formato de firma deseado (signatureFormat) así como opcionalmente un valor de contexto (context). En caso de éxito, la función devuelve a través de ara::core::Result<std::size_t> el tamaño real en bytes de la firma generada, el cual puede ser inferior a la capacidad del búfer de destino [SWS_CRYPT_23512].

En cuanto a concurrencia y seguridad frente a excepciones, el método está declarado como noexcept, se considera exception safe y está especificado explícitamente como thread-safe [SWS_CRYPT_23512].

Antes de la llamada, el contexto debe estar debidamente inicializado con un valor de clave; de lo contrario, se notifica UninitializedContext [SWS_CRYPT_23512]. Respecto a la longitud de entrada, Sign interactúa con [SWS_CRYPT_50042]: a través de GetMaximumChunkSize se puede determinar el tamaño de búfer máximo admitido para el procesamiento en un único paso, con el fin de prevenir errores como ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_23512] [SWS_CRYPT_50042].

El tratamiento de errores prevé semánticas de reversión (rollback) para códigos de error específicos [SWS_CRYPT_23512]:

• ara::crypto::CryptoErrc::kInsufficientCapacity: El búfer de salida signature es demasiado pequeño.
• ara::crypto::CryptoErrc::kUnsupported: No se admite el procesamiento en un único paso o la especificación del contexto context no se ajusta a las prescripciones.
• ara::crypto::CryptoErrc::kUnsupportedFormat: El FormatId especificado es desconocido o no se admite.
• ara::crypto::CryptoErrc::kUsageViolation: El uso de clave permitido no incluye kAllowSig Generation.
• ara::crypto::CryptoErrc::kEmptyKeySlot o ara::crypto::CryptoErrc::kBusyResource: El KeySlot configurado está vacío o bien un recurso requerido está ocupado.

El método sin parámetros Start inicializa un contexto de la clase ara::crypto::cryp::SignerPrivateCtx para una nueva generación de firma [SWS_CRYPT_50037]. La llamada se realiza de forma síncrona, está declarada como noexcept y devuelve un ara::core::Result<void> vacío en caso de inicialización correcta o un código de error en caso de fallo [SWS_CRYPT_50037].

En caso de error, la operación admite la semántica de reversión (rollback) [SWS_CRYPT_50037]. Entre las causas de error definidas a partir de ara::crypto::CryptoErrc se incluyen:

• kUninitializedContext: el contexto no se inicializó previamente mediante la provisión de una clave [SWS_CRYPT_50037].
• kEmptyKeySlot: un key-slot configurado está actualmente vacío [SWS_CRYPT_50037].
• kUsageViolation: los permisos de la clave asignada no incluyen kAllowSigGeneration [SWS_CRYPT_50037].
• kBusyResource: un recurso necesario para la operación está ocupado [SWS_CRYPT_50037].
• kUnsupported: el contexto no admite streaming o el algoritmo de firma requiere obligatoriamente la indicación de un valor de contexto [SWS_CRYPT_50037].

Según la especificación, la función es segura para subprocesos (thread-safe), así como segura frente a excepciones (exception safe) [SWS_CRYPT_50037]. Si el algoritmo requiere un valor de contexto específico, debe utilizarse alternativamente la variante sobrecargada Start(ReadOnlyMemRegion context) [SWS_CRYPT_50038]. Tras una llamada correcta a Start, las partes del mensaje que se van a firmar pueden procesarse de forma continua mediante Update [SWS_CRYPT_50039].

El método Start sirve para la inicialización sincrónica del contexto ara::crypto::cryp::SignerPrivateCtx para una nueva generación de firma proporcionando un valor de contexto ([SWS_CRYPT_50038]). Recibe el parámetro context de tipo ReadOnlyMemRegion y devuelve un ara::core::Result<void>. La función está especificada como noexcept=0, declarada como exception-safe y segura para subprocesos ([SWS_CRYPT_50038]).

En caso de error, el estado del contexto se deja inalterado mediante una semántica de reversión ([SWS_CRYPT_50038]). Las causas de error especificadas son:

• UninitializedContext: si el contexto no se ha inicializado previamente mediante el suministro de una clave.
• ara::crypto::CryptoErrc::kUnsupported: si el contexto no admite streaming o el algoritmo no permite un valor de contexto.
• ara::crypto::CryptoErrc::kInvalidInputSize: si el tamaño de búfer del valor de contexto pasado no es válido.
• ara::crypto::CryptoErrc::kEmptyKeySlot: si una ranura de clave configurada está actualmente vacía.
• ara::crypto::CryptoErrc::kUsageViolation: si el uso permitido de la clave no incluye la generación de firmas (kAllowSig Generation).
• ara::crypto::CryptoErrc::kBusyResource: si un recurso necesario está ocupado.

En el flujo de procesamiento habitual, presumiblemente los datos que se van a firmar se pasarán sucesivamente a través de Update ([SWS_CRYPT_50039]) tras un inicio exitoso. Pregunta Q-7b821391730c9d38 (abierta) Si el procedimiento criptográfico no requiere ningún valor de contexto, alternativamente está disponible la sobrecarga sin parámetros Start() ([SWS_CRYPT_50037]).

El método Update sirve en [SWS_CRYPT_50039] para ampliar de forma continua el estado interno de un cálculo de firma con una sección adicional del mensaje. La llamada se realiza de forma síncrona y procesa el área de memoria transferida data de tipo ReadOnlyMemRegion. Como resultado, la función devuelve un ara::core::Result<void> que no contiene ningún valor si el procesamiento es correcto o, en caso contrario, encapsula un código de error [SWS_CRYPT_50039].

En caso de error, los valores de retorno poseen semántica de reversión (rollback) [SWS_CRYPT_50039]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: se produce cuando el cálculo de firma no se ha iniciado previamente mediante la llamada al método Start() [SWS_CRYPT_50039].
• ara::crypto::CryptoErrc::kInvalidInputSize: se notifica si el tamaño de los datos de entrada proporcionados no es compatible con el contexto [SWS_CRYPT_50039].

En cuanto a la concurrencia y la seguridad, el método está declarado como thread-safe y exception safe [SWS_CRYPT_50039]. En combinación con el contexto de firma, el cálculo requiere obligatoriamente que la secuencia se haya iniciado con Start(). El tamaño máximo de búfer permitido para llamadas individuales se puede consultar mediante GetMaximumChunkSize() [SWS_CRYPT_50042]; es probable que este valor límite represente el límite superior cuya superación da lugar a kInvalidInputSize. Pregunta Q-cf204a853a730365 (abierta)