classe ara::crypto::cryp::CryptoProvider

O método CreateAuthCipherCtx destina-se à criação de um contexto para cifragem autenticada simétrica ([SWS_CRYPT_20745]). Ele é definido como uma interface puramente virtual na classe ara::crypto::cryp::CryptoProvider e deve ser incluído por meio do arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h ([SWS_CRYPT_20745]).

Utilização e semântica

Como parâmetro de entrada, é passado algId, o qual identifica o algoritmo criptográfico de destino ([SWS_CRYPT_20745]). A função opera de forma síncrona e não lança exceções (noexcept) ([SWS_CRYPT_20745]). Em caso de execução bem-sucedida, ela retorna um ara::core::Result com um smart pointer para a instância criada AuthCipherCtx::Sptr ([SWS_CRYPT_20745]).

Tratamento de erros

Em caso de erro, um código de erro correspondente é retornado no ara::core::Result com semântica de rollback ([SWS_CRYPT_20745]):

• ara::crypto::CryptoErrc::kInvalidArgument: quando algId não especifica um algoritmo para uma cifra de fluxo autenticada simétrica ([SWS_CRYPT_20745]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: quando um valor não suportado foi passado para algId ([SWS_CRYPT_20745]).

simultaneidade

A chamada de CreateAuthCipherCtx é thread-safe e especificada como exception-safe ([SWS_CRYPT_20745]).

usar

O método CreateDecryptorPrivateCtx da interface ara::crypto::cryp::CryptoProvider destina-se à criação de um contexto para a descriptografia assimétrica usando uma chave privada de acordo com [SWS_CRYPT_20751]. Como parâmetro de entrada, a função espera algId, o qual define o identificador do algoritmo desejado de criptografia ou descriptografia assimétrica. Interpretação: presume-se que a chamada seja executada de forma síncrona, visto que a assinatura retorna diretamente um ara::core::Result que, em caso de sucesso, contém um smart pointer para o contexto criado (DecryptorPrivateCtx::Sptr) [SWS_CRYPT_20751]. Pergunta Q-45d1c4a1b2133f4c (aberta)

Tratamento de erros

Se o contexto não puder ser criado, o erro é transportado no ara::core::Result retornado. Caso tenha sido passado um valor não suportado para o parâmetro algId, isso resulta especificamente no código de erro ara::crypto::CryptoErrc::kUnknownIdentifier com semântica de rollback [SWS_CRYPT_20751].

Simultaneidade e restrições

A função é definida como noexcept e garante segurança contra exceções (exception safe) [SWS_CRYPT_20751]. Para o acesso simultâneo a partir de várias threads, o método está especificado como thread-safe [SWS_CRYPT_20751]. Como a assinatura no cabeçalho ara/crypto/cryp/crypto_provider.h é declarada como método puramente virtual, a implementação concreta fica a cargo da respectiva implementação do provedor [SWS_CRYPT_20751].

O método de interface puramente virtual CreateEncryptorPublicCtx pertence à classe ara::crypto::cryp::CryptoProvider e é declarado por meio do arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20750]. Sua tarefa consiste em instanciar um novo contexto para operações de criptografia assimétrica com uma chave pública [SWS_CRYPT_20750].

Uso: a chamada ocorre de forma síncrona mediante a indicação do parâmetro algId do tipo AlgId, o qual define o identificador do algoritmo desejado de criptografia ou descriptografia assimétrica [SWS_CRYPT_20750]. O método retorna o resultado em um ara::core::Result, o qual, em caso de sucesso, fornece um smart pointer do tipo EncryptorPublicCtx::Sptr para o contexto criado [SWS_CRYPT_20750].

Tratamento de erros: se o argumento algId contiver um valor de algoritmo não suportado, a chamada falha e retorna no ara::core::Result o código de erro ara::crypto::CryptoErrc::kUnknownIdentifier [SWS_CRYPT_20750]. Para este caso de erro, está especificada uma semântica explícita de rollback [SWS_CRYPT_20750].

Concorrência e segurança de exceções: a interface é declarada como noexcept, considerada segura contra exceções (exception safe) e expressamente especificada como thread-safe (thread-safe) [SWS_CRYPT_20750].

O método CreateHashFunctionCtx destina-se à instanciação de um contexto de hash criptográfico ([SWS_CRYPT_20747]). Ele é disponibilizado como interface puramente virtual da classe ara::crypto::cryp::CryptoProvider por meio do cabeçalho ara/crypto/cryp/crypto_provider.h.

Utilização e parâmetros

A chamada ocorre de forma síncrona e espera como parâmetro de entrada algId (do tipo AlgId), o qual identifica o algoritmo criptográfico desejado ([SWS_CRYPT_20747]). Como valor de retorno, a função fornece um ara::core::Result<HashFunctionCtx::Sptr>, o qual, em caso de sucesso, contém um smart pointer para o contexto criado.

Tratamento de erros

Se a criação falhar, o ara::core::Result contém um código de erro correspondente com semântica de rollback ([SWS_CRYPT_20747]):

• ara::crypto::CryptoErrc::kInvalidArgument: é retornado quando o algId passado estiver especificado para um tipo de algoritmo diferente de uma função hash ([SWS_CRYPT_20747]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: ocorre caso tenha sido passado para algId um identificador não suportado ([SWS_CRYPT_20747]).

Simultaneidade e restrições

A função é declarada como noexcept e especificada como segura contra exceções (“exception safe”) ([SWS_CRYPT_20747]). Além disso, a chamada é thread-safe (“thread-safe”), de modo que chamadas simultâneas a partir de múltiplas threads na mesma instância de CryptoProvider são permitidas ([SWS_CRYPT_20747]).

O método CreateKeyAgreementPrivateCtx da classe ara::crypto::cryp::CryptoProvider destina-se à criação de um contexto de chave privada para acordos de chaves (KeyAgreementPrivateCtx) de acordo com [SWS_CRYPT_20758]. A declaração é fornecida por meio do arquivo de cabeçalho #include "ara/crypto/cryp/crypto_provider.h".

Uso e chamada

Como parâmetro de passagem, o método síncrono espera o identificador algId do tipo AlgId, o qual especifica o algoritmo criptográfico desejado para o key agreement. Como valor de retorno, a função fornece um ara::core::Result<KeyAgreementPrivateCtx::Sptr>, o qual, em caso de sucesso, encapsula um smart pointer para a instância de contexto recém-criada [SWS_CRYPT_20758].

Tratamento de erros

Se a instanciação falhar, o ara::core::Result retornado contém um código de erro com semântica de rollback [SWS_CRYPT_20758]:

• ara::crypto::CryptoErrc::kInvalidArgument: ocorre quando o argumento algId indica um algoritmo criptográfico diferente de procedimentos de acordo de chaves.
• ara::crypto::CryptoErrc::kUnknownIdentifier: é retornado caso o identificador algId apresente um valor não suportado.

Concorrência e segurança

A interface é declarada como noexcept e definida como segura contra exceções (exception safe). Além disso, a chamada é especificada como thread-safe (thread-safe), de modo que chamadas simultâneas na mesma instância de CryptoProvider são permitidas [SWS_CRYPT_20758].

usar

O método CreateKeyDecapsulatorPrivateCtx da interface ara::crypto::cryp::CryptoProvider serve para a criação de um contexto privado para decapsulamento de chave para um Key Encapsulation Mechanism (KEM) [SWS_CRYPT_20753]. Como parâmetro de entrada, ele espera algId do tipo AlgId, que identifica o algoritmo criptográfico KEM desejado [SWS_CRYPT_20753]. A função opera de forma síncrona e retorna o resultado em um ara::core::Result<KeyDecapsulatorPrivateCtx::Sptr>, que, em caso de sucesso, encapsula um smart pointer para o contexto recém-instanciado [SWS_CRYPT_20753].

Tratamento de erros

Se ocorrer um erro durante a criação do contexto, este é reportado através de ara::core::Result com semântica de rollback [SWS_CRYPT_20753]:

• ara::crypto::CryptoErrc::kInvalidArgument: O argumento algId especifica um algoritmo criptográfico que não se trata de um procedimento KEM assimétrico [SWS_CRYPT_20753].
• ara::crypto::CryptoErrc::kUnknownIdentifier: O argumento algId apresenta um valor não suportado [SWS_CRYPT_20753].

Simultaneidade e segurança de execução

A interface é declarada como noexcept e especificada como segura contra exceções (exception safe) [SWS_CRYPT_20753]. Além disso, a execução é projetada como segura para threads (thread-safe) [SWS_CRYPT_20753].

O método CreateKeyDerivationFunctionCtx da classe ara::crypto::cryp::CryptoProvider serve para a criação de um contexto de execução para funções de derivação de chave ([SWS_CRYPT_20748]). Como parâmetro de entrada, é passado o identificador algId do tipo AlgId, o qual define o algoritmo criptográfico de destino desejado. A chamada síncrona retorna um ara::core::Result, que, em caso de execução bem-sucedida, fornece um ponteiro inteligente (smart pointer) para o contexto gerado (KeyDerivationFunctionCtx::Sptr) ([SWS_CRYPT_20748]).

Se ocorrer um erro durante a instanciação, o resultado é retornado com um código de erro correspondente sob semântica de rollback ([SWS_CRYPT_20748]):

• ara::crypto::CryptoErrc::kInvalidArgument: O argumento algId especifica um algoritmo criptográfico que não representa uma função de derivação de chave ([SWS_CRYPT_20748]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: O identificador transmitido algId possui um valor não suportado ([SWS_CRYPT_20748]).

A interface é declarada como função virtual pura, designada como noexcept e categorizada obrigatoriamente como thread-safe e exception safe ([SWS_CRYPT_20748]). A inclusão é feita através do arquivo de cabeçalho #include "ara/crypto/cryp/crypto_provider.h". A função atende aos requisitos superiores [RS_CRYPTO_02103] e [RS_AP_00144].

usar

O método CreateKeyEncapsulatorPublicCtx da interface ara::crypto::cryp::CryptoProvider destina-se à criação de um contexto público para um Key Encapsulation Mechanism (KEM) [SWS_CRYPT_20752]. Para isso, deve-se incluir o arquivo de cabeçalho #include "ara/crypto/cryp/crypto_provider.h" [SWS_CRYPT_20752]. A chamada ocorre de forma síncrona: como parâmetro de entrada é passado algId, o qual especifica o algoritmo criptográfico de destino do KEM. Em caso de execução bem-sucedida, o método retorna um smart pointer para o contexto criado (KeyEncapsulatorPublicCtx::Sptr), encapsulado em um ara::core::Result [SWS_CRYPT_20752].

Tratamento de erros

Se ocorrer um erro durante a criação, uma semântica de rollback entra em ação e o ara::core::Result contém um código de erro específico de ara::crypto::CryptoErrc [SWS_CRYPT_20752]:

• ara::crypto::CryptoErrc::kInvalidArgument: é retornado quando o argumento algId nomeia um algoritmo criptográfico que não seja um KEM assimétrico [SWS_CRYPT_20752].
• ara::crypto::CryptoErrc::kUnknownIdentifier: é reportado caso o argumento algId apresente um valor não suportado [SWS_CRYPT_20752].

Concorrência e segurança

A função de interface é declarada com noexcept e classificada como exception-safe (exception safe) bem como thread-safe (thread-safe) [SWS_CRYPT_20752]. Ela pode, portanto, ser chamada com segurança a partir de contextos concorrentes sem sincronização externa [SWS_CRYPT_20752].

usar

O método puramente virtual CreateMessageAuthnCodeCtx da interface ara::crypto::cryp::CryptoProvider requer o arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h e destina-se à criação síncrona de um contexto para códigos de autenticação de mensagem simétricos [SWS_CRYPT_20746]. Como valor de entrada, a função recebe o parâmetro algId do tipo AlgId, o qual especifica o algoritmo criptográfico de destino [SWS_CRYPT_20746]. Em caso de execução bem-sucedida, o método retorna um ara::core::Result<MessageAuthnCodeCtx::Sptr>, o qual encapsula um smart pointer para a instância de contexto recém-instanciada [SWS_CRYPT_20746].

Tratamento de erros

Em caso de erro, o objeto Result retornado fornece códigos de erro específicos com semântica de rollback [SWS_CRYPT_20746]:

• ara::crypto::CryptoErrc::kInvalidArgument: o argumento algId especifica um algoritmo criptográfico que não é um código de autenticação de mensagem simétrico [SWS_CRYPT_20746].
• ara::crypto::CryptoErrc::kUnknownIdentifier: para o argumento algId foi passado um identificador desconhecido ou não suportado [SWS_CRYPT_20746].

Simultaneidade e segurança de execução

A interface é munida com o especificador noexcept e garante total segurança contra exceções (exception safe) [SWS_CRYPT_20746]. Além disso, a função é especificada explicitamente como thread-safe (thread-safe), de modo que chamadas podem ocorrer em paralelo e sem sincronização externa a partir de threads concorrentes [SWS_CRYPT_20746].

usar

A interface CreateProtectedKeyImportCtx da classe ara::crypto::cryp::CryptoProvider (definida em ara/crypto/cryp/crypto_provider.h) serve para a criação síncrona de um contexto para a importação protegida de chaves ([SWS_CRYPT_50017]). Através do parâmetro de entrada algId, é transmitido o identificador do algoritmo de wrapping pretendido ([SWS_CRYPT_50017]). Em caso de instanciação bem-sucedida, o método retorna um ara::core::Result que disponibiliza um ponteiro inteligente ProtectedKeyImportCtx::Sptr para o contexto gerado ([SWS_CRYPT_50017]).

Tratamento de erros

Se a criação falhar, o método retorna no ara::core::Result um código de erro com semântica de reversão ([SWS_CRYPT_50017]):

• ara::crypto::CryptoErrc::kInvalidArgument: Ocorre se o algoritmo criptográfico especificado por algId não for suportado pelo CryptoProvider para o wrapping ([SWS_CRYPT_50017]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: É reportado se o argumento algId contiver um valor de identificador desconhecido ou não suportado ([SWS_CRYPT_50017]).

Simultaneidade e restrições

O método puramente virtual está declarado como noexcept, oferece segurança contra exceções e está explicitamente especificado como seguro para threads (thread-safe) ([SWS_CRYPT_50017]). Assim, pode ser chamado em paralelo a partir de múltiplas threads sem sincronização externa ([SWS_CRYPT_50017]).

O método CreateRandomGeneratorCtx destina-se à criação de um contexto para geradores de números aleatórios (Random Number Generator, RNG) dentro da classe ara::crypto::cryp::CryptoProvider [SWS_CRYPT_20741].

Utilização e contexto de chamada

A função é chamada de forma síncrona e requer o arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20741]:

• Parâmetros: é passado algId do tipo AlgId, o qual identifica o algoritmo de RNG desejado. Se nenhum algId específico for indicado, o método fornece o RNG padrão [SWS_CRYPT_20741].
• Valor de retorno: um ara::core::Result<RandomGeneratorCtx::Sptr> que, em caso de sucesso, contém um shared pointer para a instância criada de RandomGeneratorCtx [SWS_CRYPT_20741].

Tratamento de erros

O método não lança exceções (noexcept) e está especificado como seguro contra exceções [SWS_CRYPT_20741]. Se a operação falhar, o ara::core::Result fornece um código de erro:

• ara::crypto::CryptoErrc::kUnknownIdentifier: ocorre quando o argumento algId apresenta um valor não suportado (com semântica de rollback) [SWS_CRYPT_20741].

Simultaneidade e restrições

O método é classificado como thread-safe (thread-safe), de modo que chamadas paralelas através da mesma instância do CryptoProvider são permitidas [SWS_CRYPT_20741].

O método CreateSignerPrivateCtx da classe ara::crypto::cryp::CryptoProvider destina-se à criação de um contexto para operações de assinatura com uma chave privada ([SWS_CRYPT_20756]).

Uso e parâmetros: a chamada requer a inclusão do arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h. Por meio do parâmetro de entrada algId, especifica-se o algoritmo criptográfico de assinatura de destino. Em caso de sucesso, a função fornece através do tipo de retorno ara::core::Result<SignerPrivateCtx::Sptr> um smart pointer para a instância de contexto criada ([SWS_CRYPT_20756]). Interpretação: como o método retorna diretamente um ara::core::Result, presume-se que a chamada seja executada de forma síncrona. Pergunta Q-8480f3cf5cef5f49 (aberta)

Concorrência e segurança: o método é especificado como thread-safe (thread-safe) bem como exception-safe (exception safe) e declarado com noexcept ([SWS_CRYPT_20756]). Ele pode, portanto, ser chamado a partir de contextos concorrentes sem sincronização adicional.

Tratamento de erros: em caso de erro, o resultado fornece um código de erro do tipo ara::crypto::CryptoErrc com semântica de rollback ([SWS_CRYPT_20756]):

• ara::crypto::CryptoErrc::kInvalidArgument: ocorre quando o argumento algId indica um algoritmo criptográfico diferente de uma assinatura com chave privada ([SWS_CRYPT_20756]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: ocorre quando algId contém um valor desconhecido ou não suportado ([SWS_CRYPT_20756]).

usar

O método virtual CreateSymmetricCipherCtx da interface ara::crypto::cryp::CryptoProvider destina-se à criação de um contexto para operações de cifragem simétrica ([SWS_CRYPT_20742]). Ele é incluído por meio do arquivo de cabeçalho #include "ara/crypto/cryp/crypto_provider.h" ([SWS_CRYPT_20742]).

Como parâmetro de entrada, a função espera algId do tipo AlgId, o qual indica o identificador do algoritmo criptográfico de destino desejado ([SWS_CRYPT_20742]). A chamada ocorre de forma síncrona e retorna como resultado um ara::core::Result<SymmetricCipherCtx::Sptr>, o qual, em caso de sucesso, fornece um smart pointer para a instância de contexto recém-instanciada ([SWS_CRYPT_20742]).

Tratamento de erros

Se a criação falhar, o ara::core::Result retornado contém um código de erro correspondente ([SWS_CRYPT_20742]):

• ara::crypto::CryptoErrc::kUnknownIdentifier: é reportado com semântica de rollback caso o valor passado para algId faça referência a um algoritmo não suportado ([SWS_CRYPT_20742]).

Simultaneidade e restrições

A função é declarada como noexcept e explicitamente especificada como segura contra exceções (exception safe) ([SWS_CRYPT_20742]). Além disso, a chamada é thread-safe (thread-safe), de modo que criações paralelas de contexto por meio da mesma instância de CryptoProvider são permitidas ([SWS_CRYPT_20742]).

usar

O método CreateSymmetricKeyWrapperCtx da classe ara::crypto::cryp::CryptoProvider serve para a criação de um contexto para algoritmos simétricos de key wrap ([SWS_CRYPT_20743]). Como parâmetro de entrada é transmitido algId, que identifica univocamente o algoritmo criptográfico de destino ([SWS_CRYPT_20743]). A chamada é síncrona e, em caso de sucesso, retorna um ara::core::Result que encapsula um ponteiro inteligente para o contexto criado (SymmetricKeyWrapperCtx::Sptr) ([SWS_CRYPT_20743]).

Tratamento de erros

Se a criação falhar, a função retorna o objeto de erro dentro do ara::core::Result ([SWS_CRYPT_20743]):

• ara::crypto::CryptoErrc::kUnknownIdentifier: É reportado se o argumento algId contiver um valor não suportado; aplicam-se semânticas de reversão ([SWS_CRYPT_20743]).

Simultaneidade e restrições

A interface está declarada como noexcept, é considerada segura contra exceções (exception safe) e é thread-safe ([SWS_CRYPT_20743]). Deste modo, pode ser chamada com segurança a partir de contextos concorrentes, desde que o algId fornecido seja suportado pelo CryptoProvider subjacente ([SWS_CRYPT_20743]).

Utilização e contexto de chamada

O método puramente virtual CreateVerifierPublicCtx da classe ara::crypto::cryp::CryptoProvider é declarado por meio do arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20757]. Ele destina-se à criação síncrona de um contexto para verificação de assinatura com chaves públicas (verificação de assinatura com chave pública) [SWS_CRYPT_20757].

O chamador passa, por meio do parâmetro algId (tipo AlgId), o identificador do algoritmo criptográfico de assinatura desejado [SWS_CRYPT_20757]. Em caso de sucesso, a função retorna um ara::core::Result que contém um smart pointer para o contexto de verificação criado (VerifierPublicCtx::Sptr) [SWS_CRYPT_20757].

Tratamento de erros

Em caso de erro, aplica-se uma semântica de rollback e o ara::core::Result resultante transporta um código de erro correspondente [SWS_CRYPT_20757]:

• ara::crypto::CryptoErrc::kInvalidArgument: é reportado quando o argumento algId nomeia um algoritmo criptográfico que não esteja previsto para a verificação de assinatura com chaves públicas [SWS_CRYPT_20757].
• ara::crypto::CryptoErrc::kUnknownIdentifier: é reportado quando foi passado para algId um identificador desconhecido ou não suportado [SWS_CRYPT_20757].

Simultaneidade e restrições

O método é declarado como noexcept, completamente seguro contra exceções (exception safe) e explicitamente especificado como thread-safe (thread-safe) [SWS_CRYPT_20757]. Chamadas paralelas a partir de múltiplos contextos de execução são, portanto, permitidas sem sincronização externa.

O método ExportSecuredKey da interface ara::crypto::cryp::CryptoProvider exporta um objeto de chave criptográfica para um formato serializado e seguro [SWS_CRYPT_20728]. O objeto de chave passado key é preparado conforme o formato implicitamente determinado por algId, criptograficamente empacotado (“wrapped”) e serializado no buffer de saída resultBuffer [SWS_CRYPT_20728]. Para o empacotamento pode ser passada opcionalmente uma chave de criptografia de chave (kek, KEK); caso nenhuma kek seja fornecida, o método recorre a uma KEK determinada implicitamente pela algId ou à KEK padrão do CryptoProvider [SWS_CRYPT_20728].

A função é classificada como thread-safe e exception safe, bem como anotada com noexcept [SWS_CRYPT_20728]. Interpretação: como a assinatura retorna diretamente um ara::core::Result sem tipos de retorno assíncronos, como futures, presume-se que todo o processo de empacotamento e serialização seja executado de forma síncrona no contexto do chamador. Pergunta Q-3fb89afcc9300695 (aberta)

Após a conclusão bem-sucedida, o ara::core::Result<std::size_t> retornado fornece o número de bytes gravados em resultBuffer [SWS_CRYPT_20728]. Se a operação falhar, uma semântica de rollback entra em ação e um dos seguintes erros é reportado [SWS_CRYPT_20728]:

• UnknownIdentifier: o valor de algId passado não é suportado [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kInvalidArgument: o objeto de chave não pode ser empacotado (por exemplo, tamanho inválido ou tipo incompatível) ou uma kek mandatória esperada não foi passada [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kUsageViolation: o uso permitido de key ou kek é incompatível com o algoritmo selecionado [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kIncompatibleArguments: o kek passado é incompatível com o algoritmo de exportação [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kInsufficientCapacity: o buffer de saída resultBuffer é pequeno demais para o resultado [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kBusyResource: um recurso necessário para a exportação está ocupado [SWS_CRYPT_20728].

O método GeneratePrivateKey da classe ara::crypto::cryp::CryptoProvider (declarado em ara/crypto/cryp/crypto_provider.h) gera de forma síncrona um novo par de chaves assimétricas e retorna a chave privada criada como PrivateKey::Sptr dentro de um ara::core::Result [SWS_CRYPT_20722]. A chave pública correspondente não é retornada diretamente, mas pode ser obtida posteriormente por meio do método PrivateKey::GetPublicKey() da chave resultante [SWS_CRYPT_20722].

Na chamada, o parâmetro algId especifica o algoritmo criptográfico, enquanto privateKeyAllowedUsage define os tipos de transformação permitidos para a chave privada [SWS_CRYPT_20722]. As flags de uso permitidas da chave pública são mapeadas com base nas permissões da chave privada da seguinte forma [SWS_CRYPT_20722]:

• kAllowDataDecryption resulta em kAllowDataEncryption
• kAllowSigGeneration resulta em kAllowSigVerification
• kAllowKeyAgreement resulta em kAllowKeyAgreement
• kAllowKeyUnwrapping resulta em kAllowKeyWrapping

Adicionalmente, as flags de uso kAllowPlaintextExport e kAllowPersist são atribuídas automaticamente à chave pública [SWS_CRYPT_20722].

Em relação à concorrência e à execução, a função é especificada como thread-safe e exception-safe [SWS_CRYPT_20722]. Se ocorrer um erro durante a geração da chave, o resultado é tratado com semântica de rollback [SWS_CRYPT_20722]. Os seguintes códigos de erro podem ser retornados:

• ara::crypto::CryptoErrc::kUnknownIdentifier, se um algoritmo não suportado for passado para algId,
• ara::crypto::CryptoErrc::kIncompatibleArguments, caso as flags de privateKeyAllowedUsage especificadas sejam incompatíveis com o algoritmo ou tipo de chave selecionado,
• ara::crypto::CryptoErrc::kBusyResource, se a geração estiver temporariamente indisponível devido a recursos ocupados temporariamente [SWS_CRYPT_20722].

O método puramente virtual GenerateRandomData da interface ara::crypto::cryp::CryptoProvider serve para preencher com dados criptográficos aleatórios uma região de memória fornecida pelo chamador [SWS_CRYPT_30098]. A declaração encontra-se no arquivo de cabeçalho ara/crypto/cryp/crypto_provider.h.

Como parâmetro de saída, passa-se randomData do tipo ReadWriteMem Region, o qual representa o buffer a ser preenchido e cujo tamanho determina a quantidade de bytes aleatórios gerados [SWS_CRYPT_30098]. Interpretação: como a função utiliza diretamente ara::core::Result<void> como tipo de retorno e nenhum objeto Future, a geração dos dados deve ocorrer de forma síncrona e bloqueante [SWS_CRYPT_30098]. Pergunta Q-315c0492dcf7f37d (aberta) O valor de retorno fica vazio em caso de sucesso ou contém um código de erro correspondente em caso de falha [SWS_CRYPT_30098].

Se ocorrer um problema durante a execução, aplica-se uma semântica de rollback, de modo que nenhum estado parcial ou inválido permaneça [SWS_CRYPT_30098]. Os seguintes estados de erro estão especificados:

• ara::crypto::CryptoErrc::kBusyResource: o gerador de números aleatórios (RNG) subjacente possui atualmente entropia insuficiente e não pode fornecer a quantidade solicitada de bytes aleatórios [SWS_CRYPT_30098].
• ara::crypto::CryptoErrc::kUnsupported: a implementação concreta de CryptoProvider não suporta um gerador de números aleatórios padrão [SWS_CRYPT_30098].

Quanto à concorrência e robustez, o método é especificado como thread-safe e exception safe [SWS_CRYPT_30098]. Múltiplas threads podem, portanto, chamar a função em paralelo, e a especificação noexcept garante que nenhuma exceção C++ seja lançada além do limite da interface.

usar

O método puramente virtual GenerateSymmetricKey é fornecido por meio da interface ara::crypto::cryp::CryptoProvider (arquivo de cabeçalho #include "ara/crypto/cryp/crypto_provider.h") e serve para gerar uma nova chave simétrica [SWS_CRYPT_20721]. A chamada síncrona espera como parâmetro algId o identificador do algoritmo criptográfico simétrico de destino e como allowedUsage bitflags que definem os tipos de transformação permitidos para a chave gerada [SWS_CRYPT_20721]. Em caso de execução bem-sucedida, o método fornece um ara::core::Result com um SymmetricKey::Sptr, ou seja, um ponteiro compartilhado (shared pointer) para o objeto de chave simétrica recém-gerado [SWS_CRYPT_20721].

Tratamento de erros

Se ocorrer um erro durante a geração da chave, este será transmitido no ara::core::Result. Para todos os casos de erro especificados, aplica-se uma semântica de rollback [SWS_CRYPT_20721]:

• ara::crypto::CryptoErrc::kUnknownIdentifier: é reportado quando um valor não suportado foi passado para algId [SWS_CRYPT_20721].
• ara::crypto::CryptoErrc::kIncompatibleArguments: ocorre quando os flags allowedUsage especificados são incompatíveis com o algoritmo algId selecionado ou com o tipo de chave [SWS_CRYPT_20721].
• ara::crypto::CryptoErrc::kBusyResource: indica que a operação não pode ser realizada temporariamente devido a recursos temporariamente ocupados [SWS_CRYPT_20721].

Simultaneidade e restrições

A operação está declarada como noexcept e possui as propriedades de ser segura contra exceções (exception safe) e segura para threads (thread-safe) [SWS_CRYPT_20721]. Ela pode, portanto, ser chamada concorrentemente a partir de múltiplas threads, podendo ocorrer o erro kBusyResource para sinalizar gargalos temporários em situações de alta carga no sistema [SWS_CRYPT_20721].

O método GetSecureCounter() da classe ara::crypto::cryp::CryptoProvider (declarado em #include "ara/crypto/cryp/crypto_provider.h") consulta a contagem atual do contador seguro da instância do provedor [SWS_CRYPT_20098]. A função opera de forma síncrona e não requer parâmetros de passagem [SWS_CRYPT_20098]. Em caso de sucesso, ela retorna por meio de ara::core::Result<SecureCounter> a estrutura SecureCounter, a qual consiste em dois valores de 64 bits não assinados (LSQW para Least Significant Quad Word e MSQW para Most Significant Quad Word) [SWS_CRYPT_20098]. Garante-se que cada contagem retornada seja estritamente maior do que todos os valores fornecidos anteriormente por meio desta instância [SWS_CRYPT_20098].

Se a contagem não puder ser determinada, a chamada falha e retorna um código de erro com semântica de rollback no objeto Result [SWS_CRYPT_20098]:

• ara::crypto::CryptoErrc::kUnsupported: o CryptoProvider específico não suporta um contador seguro [SWS_CRYPT_20098].
• ara::crypto::CryptoErrc::kBusyResource: um recurso necessário para o acesso ou a atualização do contador está atualmente ocupado [SWS_CRYPT_20098].

Em relação à concorrência e robustez, a função é especificada como thread-safe e declarada como exception-safe com noexcept [SWS_CRYPT_20098]. Chamadas paralelas a partir de várias threads são, portanto, permitidas sem sincronização externa, permanecendo assegurada a estrita monotonicidade dos valores de contagem fornecidos [SWS_CRYPT_20098].

usar

O método ImportPrivateKey da classe ara::crypto::cryp::CryptoProvider serve para importar sincronicamente uma chave privada serializada [SWS_CRYPT_50132]. Na chamada, os dados úteis são passados através da área de memória serialized (ReadOnlyMemRegion), complementados com as restrições de utilização pretendidas (allowedUsage) e o formato de serialização (formatId). O parâmetro algId é opcional (ara::core::Optional<AlgId>) e só precisa de ser definido se o formato selecionado não definir já de forma inequívoca as propriedades necessárias da chave [SWS_CRYPT_50132]. Como valor de retorno, a função fornece um ara::core::Result<PrivateKey::Sptr> que, em caso de sucesso, contém um shared pointer para o objeto de chave criado.

Tratamento de erros

Em caso de erro, o método assegura a aplicação da semântica de rollback [SWS_CRYPT_50132]. Podem ser retornados os seguintes códigos de erro através de Result:

• InvalidArgument: Os dados serializados em serialized não correspondem ao formato especificado [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kIncompatibleArguments: Os allowedUsage passados são incompatíveis com a algId [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kUnsupported: A função não é suportada pelo provider concreto [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kBusyResource: A operação temporariamente não pode ser executada devido a recursos ocupados [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kUnsupportedFormat: A formatId não é suportada para este tipo de objeto [SWS_CRYPT_50132].

Simultaneidade e restrições

A interface está declarada como noexcept e oferece segurança para exceções (exception safe) bem como segurança para threads (thread-safe) [SWS_CRYPT_50132]. As chamadas podem, portanto, ocorrer em paralelo a partir de diferentes threads.

usar

O método ImportPublicKey destina-se a importar uma chave pública serializada para o respectivo ara::crypto::cryp::CryptoProvider [SWS_CRYPT_20732]. A chamada ocorre de forma síncrona e retorna um ara::core::Result<PublicKey::Sptr>, o qual, em caso de sucesso, contém um smart pointer para o objeto de chave criado [SWS_CRYPT_20732].

Na chamada, são passados os seguintes parâmetros [SWS_CRYPT_20732]:

• serialized: uma área de memória ReadOnlyMemRegion que disponibiliza os dados brutos da chave serializada.
• allowedUsage: as flags de uso permitidas (AllowedUsageFlags) para a chave importada.
• formatId: o identificador do formato de serialização (FormatId).
• algId: um ID de algoritmo opcional (ara::core::Optional<AlgId>). Ele não é necessário se o formato de serialização já determinar de forma unívoca as propriedades da chave.

Tratamento de erros

Se ocorrer um erro durante o processamento, ele é encapsulado no ara::core::Result retornado. Os seguintes códigos de erro estão especificados [SWS_CRYPT_20732]:

• InvalidArgument: os dados passados em serialized não correspondem ao formato indicado.
• ara::crypto::CryptoErrc::kIncompatibleArguments: as flags de uso allowedUsage são incompatíveis com algId.
• ara::crypto::CryptoErrc::kUnsupportedFormat: o formatId especificado não é suportado para este tipo de objeto.
• ara::crypto::CryptoErrc::kUnsupported: a função solicitada não é suportada pelo CryptoProvider.
• ara::crypto::CryptoErrc::kBusyResource: temporariamente não é possível executar a operação.

Concorrência e segurança

O método é declarado como noexcept, considerado exception-safe e especificado como thread-safe de acordo com a especificação [SWS_CRYPT_20732]. Casos de erro seguem semânticas de rollback definidas [SWS_CRYPT_20732].

usar

O método ImportSymmetricKey da interface ara::crypto::cryp::CryptoProvider serve para importar uma chave simétrica serializada [SWS_CRYPT_50014]. Como valor de retorno, ele fornece um ara::core::Result<SymmetricKey::Sptr> que, em caso de sucesso, disponibiliza um smart pointer para o objeto de chave recém-instanciado [SWS_CRYPT_50014]. Visto que nenhum tipo de retorno assíncrono como um future é utilizado, a execução presumivelmente ocorre de forma síncrona. Pergunta Q-720a495b07c4f31d (aberta)

Na chamada, devem ser passados os seguintes parâmetros [SWS_CRYPT_50014]:

• serialized (ReadOnlyMemRegion): a área de memória que contém os dados de chave serializados.
• allowedUsage (AllowedUsageFlags): máscara de bits das operações e utilizações permitidas para esta chave.
• formatId (FormatId): identificador do formato de serialização dos dados de chave.
• algId (ara::core::Optional<AlgId>): identificador de algoritmo opcional; não é necessário se o formato de serialização especificado já determinar de forma unívoca todas as propriedades requeridas da chave.

Tratamento de erros e condições de contorno

O método está especificado como thread-safe e exception safe [SWS_CRYPT_50014]. Em caso de erro, a implementação assegura uma semântica de rollback e retorna um código de erro correspondente no ara::core::Result [SWS_CRYPT_50014]:

• InvalidArgument: os dados binários passados em serialized não correspondem ao formato especificado.
• ara::crypto::CryptoErrc::kIncompatibleArguments: as flags allowedUsage definidas são incompatíveis com a algId especificada.
• ara::crypto::CryptoErrc::kUnsupported: a função não é suportada pela instância concreta do CryptoProvider.
• ara::crypto::CryptoErrc::kUnsupportedFormat: o formato especificado não é suportado para este tipo de chave.
• ara::crypto::CryptoErrc::kBusyResource: a operação não pode ser executada no momento devido a recursos temporariamente ocupados.

usar

O método LoadPrivateKey da interface ara::crypto::cryp::CryptoProvider carrega uma chave privada a partir de um slot de chave fornecido ([SWS_CRYPT_20764]). A chamada é executada de forma síncrona e recebe como parâmetro um shared pointer para o recurso de origem (keySlot). Em caso de sucesso, a função fornece um shared pointer para o objeto de chave carregado (PrivateKey::Sptr), o qual é retornado dentro de um ara::core::Result ([SWS_CRYPT_20764]).

Tratamento de erros

Se ocorrer um erro durante a operação, aplica-se uma semântica de rollback e o ara::core::Result contém um código de erro específico ([SWS_CRYPT_20764]):

• ara::crypto::CryptoErrc::kEmptyKeySlot: O slot de chave transmitido está vazio ([SWS_CRYPT_20764]).
• ara::crypto::CryptoErrc::kIncompatibleObject: O recurso subjacente pertence a outro CryptoProvider incompatível ou contém um tipo de chave divergente ([SWS_CRYPT_20764]).
• ara::crypto::CryptoErrc::kBusyResource: A operação não pode ser executada temporariamente ([SWS_CRYPT_20764]).

Concorrência e segurança

A especificação classifica a função como thread-safe e exception safe; a assinatura é declarada como noexcept ([SWS_CRYPT_20764]). Múltiplas threads podem acessar o método em paralelo, devendo, no entanto, tratar um possível retorno de kBusyResource no caso de conflitos temporários de recursos.

usar

O método LoadPublicKey da interface ara::crypto::cryp::CryptoProvider carrega uma chave pública a partir do espaço de armazenamento de chave fornecido [SWS_CRYPT_20763]. Como parâmetro keySlot, ele espera um KeySlot::Sptr que referencia o espaço de armazenamento com a chave a ser carregada [SWS_CRYPT_20763]. Como valor de retorno, a função fornece um ara::core::Result<PublicKey::Sptr> que, em caso de sucesso, contém um ponteiro compartilhado para o objeto de chave pública carregado [SWS_CRYPT_20763]. O fornecimento direto do valor de Result provavelmente indica um comportamento de chamada síncrono. Pergunta Q-e0d2480909b1398a (aberta)

Tratamento de erros

Se o processo de carregamento falhar, o ara::core::Result contém um código de erro correspondente do domínio ara::crypto::CryptoErrc, sendo definida uma semântica de rollback para todos os casos de erro especificados [SWS_CRYPT_20763]:

• ara::crypto::CryptoErrc::kEmptyKeySlot: Ocorre quando o KeySlot transmitido está vazio [SWS_CRYPT_20763].
• ara::crypto::CryptoErrc::kIncompatibleObject: É retornado quando o recurso subjacente pertence a outro CryptoProvider incompatível ou contém um tipo de chave divergente [SWS_CRYPT_20763].
• ara::crypto::CryptoErrc::kBusyResource: Ocorre caso a operação não possa ser executada temporariamente devido ao recurso estar ocupado de outra forma [SWS_CRYPT_20763].

Concorrência e segurança

O método é declarado com noexcept e especificado como exception-safe [SWS_CRYPT_20763]. Quanto à concorrência, a operação é categorizada expressamente como thread-safe, sendo permitidas chamadas paralelas a partir de múltiplas threads [SWS_CRYPT_20763].

O método virtual puro LoadSymmetricKey da classe ara::crypto::cryp::CryptoProvider serve para carregar uma chave simétrica a partir de um espaço de armazenamento de chave fornecido [SWS_CRYPT_20762]. Como parâmetro, a função recebe um ponteiro compartilhado (shared pointer) para o respectivo espaço de armazenamento (keySlot) e retorna sincronicamente um ara::core::Result<SymmetricKey::Sptr>, o qual, em caso de execução bem-sucedida, disponibiliza um shared pointer para o objeto de chave carregado [SWS_CRYPT_20762].

No que diz respeito à concorrência e à segurança de execução, o método é especificado como thread-safe e exception safe, e declarado com noexcept [SWS_CRYPT_20762].

Se ocorrer um erro durante o carregamento, o método retorna, através do objeto Result, códigos de erro específicos do domínio ara::crypto::CryptoErrc com semântica de rollback definida [SWS_CRYPT_20762]:

• ara::crypto::CryptoErrc::kEmptyKeySlot: Ocorre quando o KeySlot transmitido está vazio [SWS_CRYPT_20762].
• ara::crypto::CryptoErrc::kIncompatibleObject: É retornado caso o recurso subjacente pertença a outro Crypto-Provider incompatível ou contenha outro tipo de chave [SWS_CRYPT_20762].
• ara::crypto::CryptoErrc::kBusyResource: Sinaliza que a operação não pode ser executada temporariamente [SWS_CRYPT_20762].