clase ara::crypto::cryp::EncryptorPublicCtx

El método Cancel() cancela una operación activa de streaming en el contexto ara::crypto::cryp::EncryptorPublicCtx, la cual fue iniciada previamente mediante Start() y aún no ha finalizado [SWS_CRYPT_50089]. No acepta parámetros de transferencia y devuelve un ara::core::Result<void>, el cual está vacío en caso de éxito [SWS_CRYPT_50089]. Dado que la firma devuelve inmediatamente un Result y ningún Future, es probable que la cancelación se ejecute de forma síncrona. Pregunta Q-cd18e56d693fe1a4 (abierta)

Tratamiento de errores y concurrencia

Si el procesamiento de datos no se inició previamente mediante Start(), la operación falla con el código de error ara::crypto::CryptoErrc::kProcessingNotStarted manteniendo la semántica de reversión (rollback) [SWS_CRYPT_50089]. Conforme a la especificación, la interfaz está declarada con noexcept, es segura frente a excepciones (exception safe) y está clasificada como segura para hilos (thread-safe) para el acceso concurrente [SWS_CRYPT_50089].

Interacción en la pila criptográfica

El comportamiento de cancelación implementado mediante Cancel() sigue un patrón de diseño uniforme para operaciones de streaming con estado en el módulo criptográfico. Existen interfaces análogas con idéntica semántica de error para:

• Operaciones de firma y verificación en SignerPrivateCtx [SWS_CRYPT_50041] y VerifierPublicCtx [SWS_CRYPT_50023],
• cifrados simétricos y autenticados en SymmetricCipherCtx [SWS_CRYPT_50046] así como AuthCipherCtx [SWS_CRYPT_50077],
• descifrado asimétrico en DecryptorPrivateCtx [SWS_CRYPT_50069],
• códigos de autenticación de mensajes en MessageAuthnCodeCtx [SWS_CRYPT_50027], así como cálculos de hash en HashFunctionCtx [SWS_CRYPT_50058].

El método síncrono Encrypt sirve para el cifrado de datos de texto plano en una sola llamada ([SWS_CRYPT_50090]). Toma los datos de entrada del búfer in (ReadOnlyMemRegion) y escribe el criptograma en el búfer de salida out (ReadWriteMemRegion) ([SWS_CRYPT_50090]). El valor de retorno ara::core::Result<std::size_t> entrega en caso de éxito el tamaño de los datos de salida realmente escritos, que puede ser inferior a la capacidad total de out ([SWS_CRYPT_50090]).

En lo que respecta a la concurrencia, la función está especificada como segura para subprocesos (thread-safe) y segura ante excepciones (exception safe) ([SWS_CRYPT_50090]).

En combinación con el contexto EncryptorPublicCtx, deben tenerse en cuenta los siguientes límites de búfer antes de la llamada:

• El tamaño de entrada debe encontrarse dentro de los límites predefinidos por [SWS_CRYPT_50178] (GetMinimumChunkSize) y [SWS_CRYPT_50091] (GetMaximumChunkSize).
• La capacidad máxima requerida del búfer de salida out puede calcularse previamente mediante GetRequiredOutputBufferSize con el parámetro isFinal = true ([SWS_CRYPT_50177]).

Todos los casos de error poseen semántica de reversión ([SWS_CRYPT_50090]). Entre los errores definidos de ara::crypto::CryptoErrc se incluyen:

• kUninitializedContext: El contexto no se ha inicializado mediante el suministro de una clave ([SWS_CRYPT_50090]).
• kEmptyKeySlot: Un KeySlot configurado está vacío ([SWS_CRYPT_50090]).
• kIncompatibleObject: El tipo de clave no coincide con la transformación ([SWS_CRYPT_50090]).
• kUsageViolation: El uso de la clave no permite el cifrado de datos (kAllowDataEncryption) ([SWS_CRYPT_50090]).
• kInsufficientCapacity: El búfer out es demasiado pequeño ([SWS_CRYPT_50090]).
• kInvalidInputSize o kInvalidArgument: El tamaño de entrada no es procesable o los datos de entrada no son válidos ([SWS_CRYPT_50090]).
• kUnsupported: No se admite el cifrado de llamada única (single-call) ([SWS_CRYPT_50090]).
• kBusyResource: Un recurso necesario está ocupado ([SWS_CRYPT_50090]).

usar

El método Finish concluye el proceso de cifrado asimétrico en el contexto de ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50088]. La llamada se realiza de forma síncrona y está especificada como noexcept, exception-safe y thread-safe. Como parámetro, la función toma a través de in (ReadOnlyMemRegion) el fragmento de texto plano final y escribe los datos resultantes del criptograma en el búfer de salida out (ReadWriteMemRegion). El tamaño de búfer requerido para out se puede determinar previamente mediante GetRequiredOutputBufferSize(). El valor de retorno ara::core::Result<std::size_t> entrega en caso de éxito el número de bytes realmente escritos, que puede resultar inferior a la capacidad total del búfer de salida [SWS_CRYPT_50088].

Tratamiento de errores y concurrencia

Todos los casos de error poseen semántica de reversión, de modo que el estado del contexto permanece consistente en caso de fallo [SWS_CRYPT_50088]. El método notifica los siguientes códigos de error específicos de ara::crypto::CryptoErrc:

• kProcessingNotStarted: El procesamiento de datos no se ha iniciado previamente mediante la llamada a Start().
• kInsufficientCapacity: El búfer de salida provisto out es demasiado pequeño.
• kInvalidInputSize: El contexto no puede procesar el tamaño de búfer de in.
• kInvalidArgument: Los datos de entrada pasados contienen valores no válidos.
• kUnsupported: El contexto concreto no admite el procesamiento por secuencias (stream).

Interacción

La finalización concluye la secuencia de procesamiento criptográfico [SWS_CRYPT_50088]. Como contrapartida complementaria para el descifrado actúa DecryptorPrivateCtx::Finish [SWS_CRYPT_50068], mientras que en el ámbito del cifrado simétrico SymmetricCipherCtx::Finish [SWS_CRYPT_50045] proporciona un patrón de secuencia comparable.

Uso y contexto de llamada

El método puramente virtual SetKey de la interfaz ara::crypto::cryp::EncryptorPublicCtx (archivo de cabecera ara/crypto/cryp/encryptor_public_ctx.h) sirve para asignar una clave para operaciones de cifrado asimétrico [SWS_CRYPT_50086]. Como parámetro se pasa un puntero inteligente keySlot del tipo KeySlot::Sptr, que debe contener un PublicKey [SWS_CRYPT_50086]. La llamada se realiza de forma síncrona y señala el éxito mediante un ara::core::Result<void> vacío. Esencial para la semántica es que la clave almacenada en la ranura solo se utiliza en el momento en que se inicia el cifrado [SWS_CRYPT_50086]. (Interpretación: Dado que la resolución de la clave solo tiene lugar con el inicio real del cifrado, es probable que las actualizaciones del contenido de la ranura antes de dicho momento de inicio sigan surtiendo efecto). Pregunta Q-25c5d462aafde8a1 (abierta)

Manejo de errores

Si la configuración falla, se devuelve un código de error con semántica de reversión (rollback) en el objeto Result [SWS_CRYPT_50086]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Se notifica si el keySlot provisto es incompatible con este contexto [SWS_CRYPT_50086].
• ara::crypto::CryptoErrc::kUnsupported: Se produce si la implementación concreta del contexto solo admite el establecimiento directo de un PublicKey y no permite la vinculación de clave a través de un KeySlot [SWS_CRYPT_50086].

Concurrencia e interacción

La operación está declarada como noexcept, con seguridad ante excepciones (exception safe) y especificada para uso concurrente como segura para subprocesos (thread-safe) [SWS_CRYPT_50086].

El concepto de referenciación indirecta de claves mediante KeySlot se encuentra de forma comparable también en otros contextos asimétricos, tales como VerifierPublicCtx::SetKey [SWS_CRYPT_50018] y KeyEncapsulatorPublicCtx::SetKey [SWS_CRYPT_50012]. Se distingue de aquellos métodos que reciben objetos de clave directamente, como por ejemplo en [SWS_CRYPT_24115] o [SWS_CRYPT_21815].

usar

El método virtual SetKey de la clase ara::crypto::cryp::EncryptorPublicCtx configura el contexto para el uso de una clave pública proporcionada [SWS_CRYPT_50175].\nA través del parámetro key (del tipo PublicKey::Sptr) se transfiere el objeto de clave que se utilizará para el cifrado [SWS_CRYPT_50175].\nLa ejecución se realiza de forma síncrona y devuelve un ara::core::Result<void>, que en caso de éxito no contiene ningún valor [SWS_CRYPT_50175].

Manejo de errores

Si se produce un error durante la configuración, se notifica un código de error correspondiente con semántica de reversión definida [SWS_CRYPT_50175]:

• ara::crypto::CryptoErrc::kUsageViolation: el uso permitido de la clave no autoriza el cifrado de datos (kAllowDataEncryption) [SWS_CRYPT_50175].
• ara::crypto::CryptoErrc::kIncompatibleObject: el objeto de clave transferido es incompatible con este contexto de cifrado [SWS_CRYPT_50175].
• ara::crypto::CryptoErrc::kUnsupported: la implementación concreta del contexto admite exclusivamente la vinculación mediante un KeySlot [SWS_CRYPT_50175].

Concurrencia y restricciones

La interfaz está definida como noexcept y especifica un comportamiento que es tanto thread-safe como exception safe [SWS_CRYPT_50175].\nGracias a la semántica de reversión, el contexto permanece en su estado anterior en caso de error.\nInterpretación: es probable que una llamada correcta sea un requisito indispensable para operaciones de cifrado posteriores, ya que el contexto no puede realizar operaciones sin una clave asignada. Pregunta Q-ab4779cac18793fa (abierta)

Interacción

Este procedimiento sigue el patrón para todo el módulo de los contextos asimétricos, tal y como también se utiliza en VerifierPublicCtx::SetKey [SWS_CRYPT_24115] y KeyEncapsulatorPublicCtx::SetKey [SWS_CRYPT_21815] para la vinculación de claves.\nAlternativamente, las interfaces relacionadas también prevén para la configuración variantes de KeySlot, como por ejemplo en VerifierPublicCtx [SWS_CRYPT_50018] o KeyEncapsulatorPublicCtx [SWS_CRYPT_50012].

Uso y semántica

El método puramente virtual Start de la clase ara::crypto::cryp::EncryptorPublicCtx sirve para inicializar el contexto para un nuevo cifrado [SWS_CRYPT_50087]. No recibe parámetros de entrada y se ejecuta de forma síncrona. Como valor devuelto, la función entrega un ara::core::Result<void>, que confirma la inicialización exitosa o transporta un código de error ocurrido [SWS_CRYPT_50087].

Tratamiento de errores y comportamiento de reversión (rollback)

Si no se cumplen las condiciones previas requeridas para la operación de cifrado, la llamada falla. La especificación garantiza una semántica de reversión para los casos de error y define las siguientes causas de error [SWS_CRYPT_50087]:

• UninitializedContext: No se ha asignado previamente ninguna clave al contexto.
• ara::crypto::CryptoErrc::kEmptyKeySlot: Un KeySlot configurado está actualmente desocupado.
• ara::crypto::CryptoErrc::kUsageViolation: Los permisos de la clave no contienen el indicador de uso kAllowDataEncryption.
• ara::crypto::CryptoErrc::kIncompatibleObject: El tipo de clave asignado es incompatible con la transformación requerida.
• ara::crypto::CryptoErrc::kBusyResource: Un recurso necesario para la inicialización está ocupado.
• ara::crypto::CryptoErrc::kUnsupported: El contexto concreto no admite el procesamiento por secuencias (stream).

Concurrencia e interacción

El método está especificado como thread-safe y exception safe [SWS_CRYPT_50087]. El suministro de una clave adecuada en el contexto es un requisito obligatorio para el éxito. Conceptualmente, la función se integra en los ciclos de vida estandarizados de los contextos criptográficos, en los cuales las operaciones se preparan mediante llamadas sin parámetros, comparable a las comprobaciones de firma [SWS_CRYPT_50019], las generaciones de firma [SWS_CRYPT_50037] o los cálculos de MAC [SWS_CRYPT_22111]. Es de suponer que la llamada represente el punto de partida indispensable antes de la realización real de un cifrado por secuencias. Pregunta Q-db262c3914e6b4cf (abierta)

usar

El método síncrono Update de la clase ara::crypto::cryp::EncryptorPublicCtx sirve para el cifrado paso a paso de bloques de datos de un texto sin formato [SWS_CRYPT_50176]. Mediante el parámetro in (ReadOnlyMemRegion) se transfiere una parte del texto sin formato, mientras que los datos cifrados se escriben en el búfer de salida out (ReadWriteMemRegion) [SWS_CRYPT_50176]. Como valor devuelto, la función proporciona a través de ara::core::Result<std::size_t> el número real de bytes escritos, el cual puede ser inferior a la capacidad provista de out [SWS_CRYPT_50176].

Secuencia e interacción

Antes de la primera llamada a Update, el procesamiento de datos debe haberse iniciado obligatoriamente mediante Start() [SWS_CRYPT_50176]. El tamaño de entrada máximo admisible para llamadas individuales puede consultarse a través del método GetMaximumChunkSize() [SWS_CRYPT_50091]. Además, el tamaño mínimo requerido para out se puede calcular mediante GetRequiredOutputBufferSize() [SWS_CRYPT_50176].

Tratamiento de errores y concurrencia

Si se produce un error durante la ejecución, este se notifica con semántica de reversión [SWS_CRYPT_50176]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: el procesamiento de datos no se inició previamente con Start() [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kInsufficientCapacity: la capacidad del búfer out no es suficiente para el resultado [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kInvalidInputSize: el tamaño del búfer de in no es válido [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kUnsupported: el procesamiento en flujo (stream) no es admitido por el contexto actual [SWS_CRYPT_50176].

El método está declarado como seguro frente a excepciones y seguro para subprocesos [SWS_CRYPT_50176]. No obstante, la llamada paralela de múltiples operaciones sobre el mismo objeto de contexto probablemente requiera sincronización externa para garantizar un orden determinista de los fragmentos de datos cifrados. Pregunta Q-b22ffe505b583b25 (abierta)