Key Manager (KeyM)

A função KeyM_Init serve para a inicialização do módulo de gerenciamento de chaves ([SWS_KeyM_00043]). A chamada ocorre de forma síncrona e está definida como não reentrante ([SWS_KeyM_00043]). Como único parâmetro de passagem é esperado ConfigPtr, o qual representa um ponteiro para o conjunto de dados de configuração para VARIANT-POST-BUILD; a função não possui valor de retorno ([SWS_KeyM_00043]).

Em relação à interação com outras funções do módulo, KeyM_Init representa um pré-requisito mandatório: com a detecção de desenvolvimento ativada, todas as demais funções do Key Manager verificam se o módulo foi previamente inicializado via KeyM_Init e ainda não desinicializado mediante KeyM_Deinit ([SWS_KeyM_00144]). Se uma função de módulo for chamada em estado não inicializado, o Key Manager notifica o erro de desenvolvimento KEYM_E_UNINIT ([SWS_KeyM_00144]).

Como KeyM_Init está especificada como não reentrante ([SWS_KeyM_00043]), a função só pode ser executada uma única vez na fase de inicialização do sistema e sob exclusão de chamadas concorrentes. O módulo fica disponível após a execução bem-sucedida através do arquivo de cabeçalho KeyM.h ([SWS_KeyM_00043]).

A função KeyM_Deinit serve para repor o módulo Key Manager novamente no estado não inicializado ([SWS_KeyM_00047]).

Utilização e contexto de chamada

A chamada de KeyM_Deinit ocorre de forma síncrona e está especificada como não reentrante (Non Reentrant). A função possui o ID de serviço 0x02, não aceita parâmetros e não devolve qualquer valor de retorno ([SWS_KeyM_00047]).

Concorrência e interação

Devido à não reentrância, KeyM_Deinit não pode ser chamada concorrentemente consigo própria ou em contradição com operações em curso. Após a execução desta desinicialização, o módulo encontra-se no estado não inicializado. Se os erros de desenvolvimento estiverem ativados, o Key Manager verifica em cada chamada de função subsequente se o módulo foi previamente inicializado através de KeyM_Init() e ainda não desinicializado mediante KeyM_Deinit(); caso contrário, é reportado o erro de desenvolvimento KEYM_E_UNINIT ([SWS_KeyM_00144]).

A função síncrona KeyM_Start serve para liberar operações de atualização de chaves no Key Manager ([SWS_KeyM_00050]). Ela é opcional e só está disponível se o parâmetro de configuração KeyMCryptoKeyStartFinalizeFunctionEnabled estiver configurado como true (AUTOSAR_SWS_KeyManager p. 35). A função é disponibilizada através de KeyM.h e espera, através de StartType, o modo de operação a ser executado, bem como, através de Request Data e Request Data Length, dados adicionais de solicitação, como, por exemplo, uma assinatura.

Dados de resposta são retornados através do buffer de saída Response Data. O parâmetro Response Data Length funciona neste caso como parâmetro de entrada e saída: antes da chamada, ele define o número máximo de bytes disponíveis no buffer; após a execução, ele contém o comprimento de dados efetivamente gravado ([SWS_KeyM_00050]).

Tratamento de erros e valores de retorno:

• E_OK: Operação de início executada com sucesso; atualizações de chaves agora são permitidas.
• E_NOT_OK: Operação de início não aceita.
• KEYM_E_PARAMETER_MISMATCH: Os parâmetros passados não coincidem com os valores esperados.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Um tamanho de parâmetro passado não coincide com o tamanho esperado.

A função é especificada como não reentrante (Non Reentrant) ([SWS_KeyM_00050]). Como não há bloqueios internos ao módulo descritos, é provável que o chamador deva assegurar uma execução coordenada e serializada. Pergunta Q-82276b712a8dd170 (aberta)

A função síncrona KeyM_Prepare serve para a preparação de uma atualização de chave (Key Update Operation) e transmite as informações necessárias para o servidor de chaves ou inicia a negociação de um segredo compartilhado para a derivação de chaves [SWS_KeyM_00051]. A função possui o ID de serviço 0x05, está declarada através do cabeçalho KeyM.h e está disponível exclusivamente se o parâmetro de configuração Key MCrypto Key Prepare Function Enabled estiver configurado como TRUE [SWS_KeyM_00051].

Na chamada, devem ser passados os seguintes buffers e indicações de comprimento [SWS_KeyM_00051]:

• Request Data e Request Data Length: Dados de entrada e respectivo comprimento para a solicitação [SWS_KeyM_00051].
• Response Data: Ponteiro para o buffer destinado a receber os dados de saída [SWS_KeyM_00051].
• Response Data Length: Parâmetro de entrada/saída que indica o tamanho máximo de buffer disponível antes da chamada e, no retorno, contém o número de bytes efetivamente gravado [SWS_KeyM_00051].

Se a chamada for confirmada com E_OK, o serviço foi aceito e é processado internamente; os resultados finais são subsequentemente disponibilizados através de um callback [SWS_KeyM_00051]. Se o aceite falhar, a função retorna E_NOT_OK em caso de erros internos, KEYM_E_PARAMETER_MISMATCH em caso de valores de parâmetro divergentes ou KEYM_E_KEY_CERT_SIZE_MISMATCH em caso de especificações de tamanho inadequadas [SWS_KeyM_00051].

Como KeyM_Prepare está especificada como não reentrante (Non Reentrant), não devem ocorrer chamadas simultâneas ou aninhadas [SWS_KeyM_00051].

A função KeyM_Finalize conclui processos de atualização para chaves e transfere a operação de chaves de volta para o estado de repouso (modo ocioso) [SWS_KeyM_00053]. Ela é utilizada tipicamente em conjunto com uma operação KeyM_Start anterior. Após a chamada, o módulo não aceita outras operações de preparação ou atualização (Prepare/Update) até que uma nova sequência seja iniciada através de KeyM_Start [SWS_KeyM_00053]. Além disso, o material da chave atualizado é persistido e colocado no estado válido pela chamada de Csm_KeySetValid [SWS_KeyM_00053].

Uso e concorrência: KeyM_Finalize não é reentrante (Non Reentrant) e opera de forma assíncrona [SWS_KeyM_00053]. Interpretação: na falta de reentrância, é provável que a chamada ocorra tipicamente no contexto de tarefa. Pergunta Q-895ebec2d0d2e635 (aberta) A interface só está disponível se o parâmetro de configuração KeyMCryptoKeyStartFinalizeFunctionEnabled estiver configurado como TRUE, e é declarada através de KeyM.h [SWS_KeyM_00053].

Parâmetros e valores de retorno: Através de RequestDataPtr e RequestDataLength são passados dados específicos da solicitação. Dados de resposta são disponibilizados através de ResponseDataPtr; ResponseMaxDataLength serve inicialmente como tamanho de buffer e fornece, em caso de retorno síncrono, a quantidade real de bytes [SWS_KeyM_00053]. Caso a operação seja aceita e processada internamente, a função retorna E_OK (os resultados seguem assincronamente via callback) e ResponseMaxDataLength permanece inalterado [SWS_KeyM_00053].

Tratamento de erros: Em caso de erro, KeyM_Finalize sinaliza a falha através de valores de retorno específicos [SWS_KeyM_00053]:

• E_NOT_OK: Operação não aceita devido a um erro interno.
• KEYM_E_BUSY: O KeyM está ocupado com outras requisições; a validação ainda não pode ser executada.
• KEYM_E_PARAMETER_MISMATCH: Os parâmetros não coincidem com o valor esperado.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O tamanho do parâmetro não coincide.

usar

A função síncrona KeyM_SetCertificate passa dados de certificado para o módulo de gerenciamento de chaves a fim de armazenar temporariamente um certificado [SWS_KeyM_00057]. Ela espera como parâmetros de entrada o identificador do certificado CertId (tipo KeyM_CertificateIdType), bem como o ponteiro CertificateDataPtr (tipo const KeyM_CertDataType*), que faz referência à estrutura de certificado a ser disponibilizada [SWS_KeyM_00057]. A interface é declarada através do cabeçalho KeyM.h e possui o ID de serviço 0x0a [SWS_KeyM_00057].

Valores de retorno e tratamento de erros

O valor de retorno do tipo Std_ReturnType fornece informações sobre o aceite dos dados [SWS_KeyM_00057]:

• E_OK: o certificado foi aceito com sucesso [SWS_KeyM_00057].
• E_NOT_OK: não foi possível definir o certificado [SWS_KeyM_00057].
• KEYM_E_PARAMETER_MISMATCH: Os parâmetros passados não coincidem com os valores esperados [SWS_KeyM_00057].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O tamanho dos dados de certificado passados diverge do tamanho esperado [SWS_KeyM_00057].

Simultaneidade e restrições

A função é classificada como não reentrante (Non Reentrant) [SWS_KeyM_00057]. Chamadas concorrentes devem, portanto, ser sincronizadas ou excluídas do lado do chamador. Como a especificação prevê explicitamente um armazenamento temporário, presume-se que os dados de certificado passados permaneçam inicialmente na memória volátil do módulo, antes que ocorra um armazenamento permanente ou uma verificação. Pergunta Q-c35c4b02344d5bc9 (aberta)

usar

A função síncrona KeyM_GetCertificate serve para disponibilizar os dados de certificado para um identificador de certificado especificado [SWS_KeyM_00058]. O chamador passa através do parâmetro CertId o identificador do certificado desejado e, através do parâmetro de entrada/saída CertificateDataPtr, um ponteiro para a estrutura de dados do certificado. O chamador é responsável por fornecer o buffer para o qual o ponteiro na estrutura aponta [SWS_KeyM_00058]. Antes da chamada, o comprimento máximo deste buffer deve ser especificado na estrutura; em caso de retorno bem-sucedido (E_OK), o campo de comprimento contém o comprimento real dos dados de certificado disponibilizados [SWS_KeyM_00058].

Tratamento de erros

A função sinaliza o sucesso ou erros específicos através do valor de retorno do tipo Std_ReturnType [SWS_KeyM_00058]:

• E_OK: Os dados de certificado estão disponíveis e foram transferidos com sucesso.
• KEYM_E_PARAMETER_MISMATCH: o ID de certificado passado (CertId) é inválido.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O buffer fornecido é pequeno demais para o certificado.
• KEYM_E_KEY_CERT_EMPTY: Não existem dados de certificado disponíveis, pois o slot de certificado está vazio.
• KEYM_E_KEY_CERT_READ_FAIL: O certificado não pode ser disponibilizado, pois o acesso foi negado.
• E_NOT_OK: A operação não foi aceita devido a um erro interno.

Simultaneidade e restrições

A função é especificada como não reentrante (Non Reentrant) e está disponível através do arquivo de cabeçalho KeyM.h [SWS_KeyM_00058]. Os chamadores devem, portanto, assegurar que chamadas paralelas da função sejam sincronizadas entre si.

A função KeyM_VerifyCertificates serve para a verificação assíncrona mútua de dois certificados armazenados internamente e analisados sintaticamente (parsed) de acordo com [SWS_KeyM_00059]. Para tal, valida-se se o certificado subordinado referenciado através de CertId foi assinado pelo certificado superior referenciado com CertUpperId.

Uma vez que o serviço está definido como não reentrante (Non Reentrant), não pode ser chamado concorrentemente para processos sobrepostos [SWS_KeyM_00059]. A execução ocorre de forma assíncrona em segundo plano: Um valor de retorno de E_OK sinaliza apenas a aceitação bem-sucedida da ordem de verificação. O resultado efetivo da verificação é comunicado ao chamador através da função de callback configurada KeyMCertificateVerifyCallbackNotificationFunc, desde que esta esteja validamente configurada [SWS_KeyM_00153].

Se o pedido não for aceite, a função devolve valores de retorno específicos para o tratamento de erros [SWS_KeyM_00059]:

• KEYM_E_BUSY: O Key Manager está sobrecarregado com outras tarefas; a validação ainda não pode ser iniciada neste momento.
• KEYM_E_PARAMETER_MISMATCH: Pelo menos um ID de certificado transmitido é inválido.
• KEYM_E_KEY_CERT_EMPTY: Um dos slots de certificado referenciados está vazio.
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: O certificado superior (CertUpperId) não é válido.
• E_NOT_OK: A ordem foi rejeitada devido a um erro interno.

A função KeyM_VerifyCertificate destina-se à verificação assíncrona de um certificado que foi previamente disponibilizado via KeyM_SetCertificate() [SWS_KeyM_00060]. A verificação é realizada com base no identificador de certificado CertId passado contra certificados de outros IDs de certificado já armazenados no Key Manager [SWS_KeyM_00060]. A declaração está disponível através do arquivo de cabeçalho KeyM.h [SWS_KeyM_00060].

Semântica de chamada e valores de retorno

Um valor de retorno de E_OK confirma que a solicitação de verificação foi aceita com sucesso e que a operação está sendo executada em segundo plano [SWS_KeyM_00060]. Se a requisição não puder ser aceita, o feedback ocorre de forma síncrona através de códigos de erro específicos [SWS_KeyM_00060]:

• E_NOT_OK: A operação foi rejeitada devido a um erro interno [SWS_KeyM_00060].
• KEYM_E_BUSY: O módulo KeyM está atualmente ocupado com outras tarefas, de modo que a validação ainda não pode ser executada [SWS_KeyM_00060].
• KEYM_E_PARAMETER_MISMATCH: O CertId passado é inválido [SWS_KeyM_00060].
• KEYM_E_KEY_CERT_EMPTY: Pelo menos um dos slots de certificado necessários está vazio [SWS_KeyM_00060].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Um certificado superior na cadeia de confiança é inválido [SWS_KeyM_00060].

Simultaneidade e assincronia

Como KeyM_VerifyCertificate é especificada como não reentrante (Non Reentrant), o chamador deve garantir que não ocorram chamadas simultâneas ou que causem interrupção [SWS_KeyM_00060]. Após a aceitação bem-sucedida da ordem de verificação (retorno E_OK), o resultado da operação em segundo plano é transmitido à função de callback configurada KeyMCertificateVerifyCallbackNotificationFunc, desde que esta possua um nome de função válido [SWS_KeyM_00153].

A função KeyM_VerifyCertificateChain serve para a verificação assíncrona de um certificado contra uma cadeia de certificados transmitidos [SWS_KeyM_00061]. Como parâmetros, são passados o identificador do último certificado da cadeia (CertId), um ponteiro para o array de certificados ordenado segundo a sequência da PKI (certChainData), bem como o número de certificados (NumberOfCertificates) [SWS_KeyM_00061]. Antes da chamada, o certificado a verificar deve ter sido registado através de KeyM_SetCertificate(), e o certificado raiz deve estar contido na lista ou já atribuído a um dos outros certificados [SWS_KeyM_00061].

A função é não reentrante (Non Reentrant) e é disponibilizada através do ficheiro de cabeçalho KeyM.h [SWS_KeyM_00061]. Os seguintes valores de retorno síncronos indicam o estado de aceitação da ordem [SWS_KeyM_00061]:

• E_OK: A ordem de verificação foi aceite e é executada em segundo plano [SWS_KeyM_00061].
• E_NOT_OK: A ordem foi recusada devido a um erro interno [SWS_KeyM_00061].
• KEYM_E_BUSY: O módulo está sobrecarregado com outras ordens; a validação ainda não pode ser executada [SWS_KeyM_00061].
• KEYM_E_PARAMETER_MISMATCH: O ID de certificado transmitido é inválido [SWS_KeyM_00061].
• KEYM_E_KEY_CERT_EMPTY: Um dos slots de certificado necessários está vazio [SWS_KeyM_00061].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Um certificado superior na cadeia de confiança é inválido [SWS_KeyM_00061].

Se a ordem tiver sido aceite com E_OK, a avaliação ocorre em segundo plano. Desde que KeyMCertificateVerifyCallbackNotificationFunc esteja configurado com uma função válida, o KeyM reporta o resultado final da operação de verificação à aplicação chamadora através desta função de callback [SWS_KeyM_00061] [SWS_KeyM_00153].

Utilização e contexto de chamada

A função síncrona KeyM_CertElementGet serve para ler os dados de um elemento de certificado específico de um slot de certificado para um buffer fornecido pelo chamador [SWS_KeyM_00063]. Ela é utilizada quando exatamente um único elemento está associado ao identificador de objeto (OID) definido na configuração do certificado [SWS_KeyM_00063].

O chamador passa o identificador de certificado CertId, o identificador de elemento CertElementId e um ponteiro para o buffer de destino CertElementData [SWS_KeyM_00063]. O parâmetro CertElementDataLength atua como um valor combinado de entrada e saída: antes da chamada, ele deve conter o tamanho máximo do buffer. Em caso de sucesso (E_OK), ele é sobrescrito com o comprimento real dos dados gravados; em caso de erro, a função redefine o valor referenciado para zero [SWS_KeyM_00063].

Tratamento de erros e valores de retorno

A função reporta o status de execução através dos seguintes valores de retorno [SWS_KeyM_00063]:

• E_OK: O elemento foi encontrado e copiado com sucesso para o buffer [SWS_KeyM_00063].
• E_NOT_OK: Os dados do elemento não foram encontrados [SWS_KeyM_00063].
• KEYM_E_PARAMETER_MISMATCH: CertId ou CertElementId inválido [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O buffer fornecido é pequeno demais para os dados do elemento [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_EMPTY: Não existem dados para o slot especificado, o slot está vazio [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_INVALID: O certificado é inválido ou ainda não foi verificado [SWS_KeyM_00063].

simultaneidade

A função é especificada como não reentrante (Non Reentrant) [SWS_KeyM_00063]. Em chamadas concorrentes a partir de diferentes tarefas ou contextos, é provável que seja necessária uma sincronização por parte do chamador. Pergunta Q-238a3e53ce0e3a45 (aberta)

A função síncrona KeyM_CertificateElementGetByIndex destina-se à leitura direcionada de dados de um elemento de certificado com base em um índice de base zero (0..N), quando existem múltiplas entradas para um tipo de elemento [SWS_KeyM_91014]. Ela representa, assim, uma alternativa de acesso direto à iteração sequencial.

Utilização e parâmetros

O chamador passa o identificador de certificado CertId, o identificador de elemento CertElementId bem como o Index desejado [SWS_KeyM_91014]. Além disso, o chamador deve alocar a memória para CertElementDataPtr e passar através de CertElementDataLengthPtr o tamanho máximo disponível do buffer. Em caso de retorno bem-sucedido, CertElementDataLengthPtr é sobrescrito com o comprimento real dos dados copiados [SWS_KeyM_91014].

Valores de retorno e tratamento de erros

A função sinaliza o resultado através de valores de retorno específicos de Std_ReturnType [SWS_KeyM_91014]:

• E_OK: O elemento foi encontrado e copiado com sucesso para o buffer de destino.
• KEYM_E_PARAMETER_MISMATCH: CertId inválido, CertElementId inválido ou o Index passado está fora da faixa válida.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O buffer fornecido é pequeno demais para o elemento de certificado.
• KEYM_E_KEY_CERT_EMPTY: O certificado especificado não contém dados ou está vazio.
• KEYM_E_CERT_INVALID: O certificado é inválido ou a verificação não foi bem-sucedida.
• E_NOT_OK: A leitura dos dados do elemento falhou.

simultaneidade

De acordo com a especificação, o serviço é classificado como não reentrante (Non Reentrant) [SWS_KeyM_91014]. As chamadas não devem, portanto, ser executadas concorrentemente de forma desprotegida.

A interface síncrona KeyM_CertificateElementGetCount determina o número total de elementos de dados armazenados para um elemento de certificado específico e grava o resultado no buffer CountPtr [SWS_KeyM_91015].

Utilização e parâmetros

A função é declarada através do cabeçalho KeyM.h e possui o Service-ID 0x1c [SWS_KeyM_91015]. Ela processa os seguintes parâmetros:

• CertId (IN): Identificador exclusivo do certificado a ser consultado ([SWS_KeyM_91015]).
• CertElementId (IN): Determina o elemento concreto dentro do certificado ([SWS_KeyM_91015]).
• CountPtr (OUT): Ponteiro para o buffer do tipo uint16, no qual o número de elementos de dados disponíveis é copiado ([SWS_KeyM_91015]).

Tratamento de erros e valores de retorno

O valor de retorno do tipo Std_ReturnType fornece informações sobre o resultado da execução [SWS_KeyM_91015]:

• E_OK: O valor de contagem foi gravado com sucesso no buffer ([SWS_KeyM_91015]).
• E_NOT_OK: Não foi possível disponibilizar o valor de contagem ([SWS_KeyM_91015]).
• KEYM_E_PARAMETER_MISMATCH: O ID de certificado (CertId) ou o ID de elemento (CertElementId) é inválido ou está fora do intervalo permitido ([SWS_KeyM_91015]).

Concorrência e interação

A execução é síncrona, mas classificada como não reentrante (Non Reentrant), de modo que chamadas simultâneas devem ser coordenadas [SWS_KeyM_91015]. Embora tipicamente apenas um único elemento de dados esteja atribuído aos elementos de certificado, em determinados casos múltiplos elementos de dados podem estar presentes consecutivamente [SWS_KeyM_91015]. O número total determinado serve como base para, em seguida, ler os elementos individuais de forma direcionada via KeyM_CertificateElementGetByIndex(), o que se assemelha funcionalmente à abordagem iterativa com KeyM_CertElementGetFirst e KeyM_CertElementGetNext [SWS_KeyM_91015].

A função síncrona KeyM_CertElementGetFirst serve, de acordo com [SWS_KeyM_00064], para iniciar a extração iterativa de dados de certificado. Ela lê o elemento superior do elemento de certificado endereçado através de CertElementId a partir do certificado CertId e inicializa a construção do iterador CertElementIterator para chamadas subsequentes de KeyM_CertElementGetNext().

Na chamada, devem ser observados os seguintes requisitos de parâmetros e de memória de acordo com [SWS_KeyM_00064]:

• CertElementIterator: Ponteiro para uma estrutura alocada e gerenciada pelo chamador; esta não deve ser destruída nem modificada pela aplicação enquanto nem todos os dados tiverem sido recuperados via KeyM_CertElementGetNext().
• CertElementData: Ponteiro para um buffer de saída fornecido pelo chamador, para o qual os dados úteis são copiados em caso de localização bem-sucedida (E_OK).
• CertElementDataLength: Passa como entrada o comprimento máximo do buffer de dados e é sobrescrito com o comprimento de dados efetivamente gravado no retorno de E_OK.

Em relação à simultaneidade, o serviço é reentrante de acordo com [SWS_KeyM_00064], mas restrito a exatamente um iterador (“Reentrant for one iterator”).

Em caso de erro, a função diferencia através de valores de retorno específicos de acordo com [SWS_KeyM_00064]: E_NOT_OK indica que nenhum dado de elemento foi encontrado (o iterador não deve mais ser utilizado para chamadas adicionais depois disso). KEYM_E_PARAMETER_MISMATCH sinaliza um ID de certificado ou de elemento inválido, KEYM_E_KEY_CERT_SIZE_MISMATCH um buffer de dados pequeno demais, KEYM_E_KEY_CERT_EMPTY um certificado vazio sem dados disponíveis e KEYM_E_CERT_INVALID um certificado inválido ou não verificado com sucesso.

A função síncrona KeyM_CertElementGetNext (Service-ID 0x11, disponibilizada via KeyM.h) serve para a leitura contínua de dados adicionais de um elemento de certificado, caso múltiplos registros de dados estejam armazenados sequencialmente nele [SWS_KeyM_00065]. Como pré-condição obrigatória de chamada, a especificação exige que a função KeyM_CertElementGetFirst() tenha sido chamada previamente pelo menos uma vez [SWS_KeyM_00065].

As áreas de memória para todos os parâmetros devem ser fornecidas pela aplicação chamadora [SWS_KeyM_00065]:

• CertElementIterator: Ponteiro para uma estrutura de iterador alocada, que não deve ser modificada nem destruída pela aplicação durante a iteração, até que todos os elementos tenham sido completamente lidos [SWS_KeyM_00065].
• CertElementData: Ponteiro para o buffer de saída, no qual a função copia os dados úteis em caso de execução bem-sucedida [SWS_KeyM_00065].
• CertElementDataLength: Passa na chamada a capacidade máxima do buffer de dados e é sobrescrito no retorno bem-sucedido com o comprimento real dos dados copiados [SWS_KeyM_00065].

Se a chamada retornar E_OK, o próximo elemento foi encontrado, gravado no buffer e o iterador avançado adequadamente [SWS_KeyM_00065]. No caso de E_NOT_OK, não foi possível encontrar mais dados de elementos; nessa situação, o iterador não deve mais ser utilizado para nenhuma chamada adicional [SWS_KeyM_00065]. Situações de erro são reportadas através de valores de retorno específicos: KEYM_E_KEY_CERT_SIZE_MISMATCH indica um buffer de dados subdimensionado, KEYM_E_PARAMETER_MISMATCH um ID de certificado ou de elemento inválido, KEYM_E_KEY_CERT_EMPTY um certificado vazio e KEYM_E_CERT_INVALID um certificado inválido ou não verificado com sucesso [SWS_KeyM_00065].

Quanto à concorrência, a função síncrona é especificada como reentrante para um iterador de cada vez [SWS_KeyM_00065].

A função síncrona KeyM_CertGetStatus serve para consultar o status de um certificado e disponibilizá-lo através de um parâmetro de saída [SWS_KeyM_00066]. A declaração da função é acessível através do arquivo de cabeçalho KeyM.h, e o Service-ID hexadecimal 0x12 está atribuído ao serviço [SWS_KeyM_00066].

Para a chamada, são utilizados os seguintes parâmetros [SWS_KeyM_00066]:

• CertId (IN): Contém o identificador do certificado a ser consultado e é passado com o tipo de dados KeyM_CertificateIdType [SWS_KeyM_00066].
• Status (OUT): Ponteiro para a área de memória do tipo KeyM_CertificateStatusType, na qual a função grava o status determinado do certificado [SWS_KeyM_00066].

O valor de retorno do tipo Std_ReturnType informa sobre o resultado da consulta de status [SWS_KeyM_00066]:

• E_OK: O status do certificado foi determinado e disponibilizado com sucesso [SWS_KeyM_00066].
• E_NOT_OK: A disponibilização do status não é possível no momento [SWS_KeyM_00066]. Isso ocorre, por exemplo, quando um ID de certificado inválido é passado, documentado com o código de erro KEYM_E_PARAMETER_MISMATCH [SWS_KeyM_00066].

Em relação à execução e simultaneidade, a interface se comporta de forma puramente síncrona e é especificada como não reentrante (Non Reentrant) [SWS_KeyM_00066]. Chamadas simultâneas entre múltiplos contextos de execução não são, portanto, permitidas. Parâmetros de entrada e saída adicionais não estão previstos para esta interface [SWS_KeyM_00066].

A função KeyM_MainFunction serve como função principal periódica para o módulo Classic AUTOSAR KeyM [SWS_KeyM_00074]. De acordo com a especificação, a função possui o ID de serviço 0x19 em representação hexadecimal, bem como a assinatura void KeyM_MainFunction (void) [SWS_KeyM_00074]. As instâncias que a chamam não passam, assim, quaisquer parâmetros de entrada e não recebem nenhum valor de retorno [SWS_KeyM_00074].

Para o controlo temporal, está definido que a função deve ser chamada periodicamente de acordo com um intervalo de tempo definido [SWS_KeyM_00074]. O ficheiro de cabeçalho SchM_KeyM.h está declarado como ficheiro de interface [SWS_KeyM_00074]. Disto resulta a interpretação: Devido à disponibilização através de SchM_KeyM.h, é provável que a chamada regular da função ocorra no contexto do escalonador do Basic Software (SchM) [SWS_KeyM_00074]. Pergunta Q-761ff71812bda3c2 (aberta) Além disso, o acionamento cíclico serve presumivelmente para o processamento interno de fluxos dependentes do tempo no módulo KeyM.

No que diz respeito ao tratamento de erros e ao comportamento face a falhas, não estão documentados códigos de retorno, constantes de erro ou mensagens para o DET ou DEM no elemento de especificação para este serviço [SWS_KeyM_00074]. Uma vez que não existem parâmetros de entrada, não se aplica também uma verificação de valores transmitidos aquando da chamada [SWS_KeyM_00074].

Utilização e contexto de chamada

A função KeyM_MainBackgroundFunction possui a assinatura void KeyM_MainBackgroundFunction(void) e está especificada sob o ID de serviço 0x1a [SWS_KeyM_00075]. Não recebe parâmetros de passagem e não devolve qualquer valor de retorno ao chamador [SWS_KeyM_00075]. Para a integração, a interface é declarada e disponibilizada através do ficheiro de cabeçalho SchM_KeyM.h [SWS_KeyM_00075].

A chamada é realizada por um sistema operativo preemptivo em segundo plano, assim que nenhuma outra operação de tarefa estiver pendente para processamento [SWS_KeyM_00075]. A finalidade primária desta função é a disponibilização de um contexto de segundo plano não crítico para operações síncronas demoradas do módulo KeyM, conforme descrito exemplificativamente para a execução de KeyM_KH_Update() [SWS_KeyM_00075].

Simultaneidade e tratamento de erros

Como a função é executada no contexto de segundo plano de um sistema operativo preemptivo, é provável que possa ser interrompida a qualquer momento por quaisquer tarefas regulares de prioridade mais alta. Pergunta Q-a2394a51ba63467f (aberta) Para este serviço de segundo plano, a norma não especifica códigos de erro específicos nem notificações ao DET ou DEM [SWS_KeyM_00075]. Além disso, nos dados fornecidos não são prescritas propriedades especiais de reentrância ou condições rígidas de ordenação relativamente a outras funções do módulo [SWS_KeyM_00075].

A função síncrona e não reentrante KeyM_KH_Start é declarada através do cabeçalho KeyM_Externals.h [SWS_KeyM_00067]. Quando os parâmetros de configuração KeyMCryptoKeyStartFinalizeFunctionEnabled e KeyMCryptoKeyHandlerStartFinalizeEnabled estão definidos como TRUE, ela é executada imediatamente em uma chamada de KeyM_Start [SWS_KeyM_00067].

Através do parâmetro StartType, define-se o modo de execução da operação de chave. Por meio de RequestData e RequestDataLength, a função recebe dados adicionais específicos da solicitação, como, por exemplo, assinaturas. O chamador passa através do parâmetro de entrada/saída ResponseDataLength a quantidade máxima de bytes disponível no buffer ResponseData; em caso de sucesso, a função reporta através dele o número real de bytes de resposta gravados [SWS_KeyM_00067].

Como valor de retorno a função fornece um status do tipo Std_ReturnType [SWS_KeyM_00067]:

• E_OK: A operação de inicialização foi bem-sucedida. Somente através deste valor de retorno o Key Manager muda para o estado ativo, de modo que atualizações subsequentes de chaves (Key Updates) sejam permitidas.
• E_NOT_OK: a operação de início não foi aceita.
• KEYM_E_PARAMETER_MISMATCH: um parâmetro passado não coincide com o valor esperado.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O tamanho de parâmetro especificado não corresponde ao tamanho esperado.

Como KeyM_KH_Start está definida como não reentrante, chamadas para operações de chave paralelas não devem ocorrer de forma concorrente [SWS_KeyM_00067].

Utilização e contexto de chamada

A função KeyM_KH_Prepare é declarada através do arquivo de cabeçalho KeyM_Externals.h e serve para a preparação de uma operação de gerenciamento de chaves [SWS_KeyM_00068]. Ela é disparada imediatamente na chamada de KeyM_Prepare, quando ambos os parâmetros de configuração KeyMCryptoKeyPrepareFunctionEnabled e KeyMCryptoKeyHandlerPrepareEnabled estão definidos, cada um, como TRUE [SWS_KeyM_00068]. A execução ocorre de forma síncrona e é especificada como não reentrante [SWS_KeyM_00068].

A passagem de dados ocorre através de quatro parâmetros [SWS_KeyM_00068]:

• RequestData: Dados de entrada passados juntamente com a solicitação [SWS_KeyM_00068].
• RequestDataLength: Comprimento dos dados no array RequestData [SWS_KeyM_00068].
• ResponseDataPtr: Ponteiro para o buffer para os dados de resposta retornados pela função, os quais são encaminhados inalterados ao chamador de Key_Prepare [SWS_KeyM_00068].
• ResponseDataLength: Parâmetro de entrada e saída; passa na chamada o número máximo de bytes disponível no buffer e retorna, após o retorno, a quantidade de bytes efetivamente gravada [SWS_KeyM_00068].

Valores de retorno e comportamento em caso de falha

A função retorna o valor de status Std_ReturnType como resultado [SWS_KeyM_00068]:

• E_OK: O serviço foi aceito e será processado internamente; os resultados são transmitidos através de um callback [SWS_KeyM_00068].
• E_NOT_OK: O serviço não foi aceito devido a um erro interno [SWS_KeyM_00068].
• KEYM_E_PARAMETER_MISMATCH: um parâmetro não coincide com o valor esperado [SWS_KeyM_00068].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O tamanho de um parâmetro não é adequado [SWS_KeyM_00068].

Uso e delegação

A função KeyM_KH_Finalize é declarada através do arquivo de cabeçalho KeyM_Externals.h e atua como um key-handler específico do usuário [SWS_KeyM_00070]. Quando na configuração tanto KeyMCryptoKeyStartFinalizeFunctionEnabled quanto KeyMCryptoKeyHandlerStartFinalizeEnabled estão definidos como TRUE, KeyM_Finalize() não executa nenhuma operação autônoma, mas delega o processamento imediatamente a esta função controladora (handler) [SWS_KeyM_00070].

Contexto de chamada e parâmetros

A chamada de KeyM_KH_Finalize ocorre de forma síncrona, mas é classificada como não reentrante (Non Reentrant) e exige um contexto de chamada protegido [SWS_KeyM_00070]. A transferência de dados ocorre através dos seguintes parâmetros:

• RequestData e RequestDataLength: Ponteiro para os dados de entrada passados com a solicitação, bem como o comprimento do array de dados [SWS_KeyM_00070].
• ResponseData: Buffer para os dados de saída fornecidos pela função [SWS_KeyM_00070].
• ResponseDataLength: Um parâmetro In/Out que define, na chamada, a quantidade máxima de bytes disponível no buffer de resposta e contém, no retorno, o número de bytes efetivamente gravado [SWS_KeyM_00070].

Valores de retorno e tratamento de erros

O resultado da operação é retornado através de Std_ReturnType [SWS_KeyM_00070]:

• E_OK: A operação foi aceita e é processada internamente; os resultados são disponibilizados através de um callback [SWS_KeyM_00070]. Interpretação: embora a interface da função seja definida como síncrona, o processamento real provavelmente prossegue em segundo plano. Pergunta Q-02c4aac040570c03 (aberta)
• E_NOT_OK: A operação não foi aceita devido a um erro interno [SWS_KeyM_00070].
• KEYM_E_BUSY: O Key Manager está ocupado com outras tarefas, razão pela qual a validação não pode ser realizada no momento [SWS_KeyM_00070].
• KEYM_E_PARAMETER_MISMATCH: um parâmetro não coincide com o valor esperado [SWS_KeyM_00070].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: O tamanho do parâmetro passado não atende às especificações [SWS_KeyM_00070].

A função de callback KeyM_CryptoKeyUpdateCallbackNotification() notifica a aplicação de que uma atualização de uma chave criptográfica foi concluída ([SWS_KeyM_00077]). A função é disponibilizada via KeyM_Externals.h, é síncrona e reentrante e não possui valor de retorno ([SWS_KeyM_00077]).

Parâmetros

• Result: Transmite informações sobre o resultado da operação de atualização através do tipo KeyM_ResultType ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataLength: Indica o comprimento dos dados resultantes desta operação ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataPtr: Ponteiro para os dados do resultado ([SWS_KeyM_00077]).

Interação e gerenciamento de buffers

A chamada de KeyM_CryptoKeyUpdateCallbackNotification() é feita por KeyM_Update() assim que o key-handler retorna e fornece o tipo de operação KEYM_KH_UPDATE_FINISH ([SWS_KeyM_00093]). Nesse processo, os dados de resultado de KeyM_KH_Update::ResultDataPtr são copiados para o buffer que foi passado na chamada de KeyM_Update(), e o valor de retorno do key-handler é assumido ([SWS_KeyM_00093]).

Caso KeyM_Update() tenha aceitado o processo com E_OK, a função chamadora não deve, em hipótese alguma, alterar o buffer ResultDataPtr até que a notificação de callback KeyM_CryptoKeyUpdateCallbackNotification() tenha ocorrido ([SWS_KeyM_00156]). O mesmo ponteiro de buffer é passado no callback como ResultDataPtr com os resultados da operação copiados para dentro dele ([SWS_KeyM_00156]).

A função de callback KeyM_CryptoKeyFinalizeCallbackNotification notifica a aplicação sobre a conclusão de uma operação de finalização de chave [SWS_KeyM_00079]. Ela é especificada como síncrona e reentrante, não possui valor de retorno e é declarada através do arquivo de cabeçalho KeyM_Externals.h [SWS_KeyM_00079].

A interface passa os seguintes parâmetros para a aplicação no momento da chamada [SWS_KeyM_00079]:

• Result (tipo KeyM_ResultType): Transmite o resultado e informações de status da operação concluída [SWS_KeyM_00079].
• Result Data Length (tipo uint16): Informa o comprimento dos dados resultantes desta operação [SWS_KeyM_00079].
• Result Data Ptr (tipo const uint8*): Ponteiro para o buffer com os dados de resultado, que foi previamente disponibilizado para a função de serviço [SWS_KeyM_00079].

Em termos de configuração, a função de callback só é chamada e necessária se o parâmetro de configuração KeyMCryptoKeyStartFinalizeFunctionEnabled estiver definido como TRUE [SWS_KeyM_00079]. Mensagens de erro específicas de DET ou DEM não estão definidas para esta função de callback. Supõe-se que a aplicação implemente este callback para receber os resultados assíncronos de uma finalização de chave previamente iniciada. Pergunta Q-6d9e4e062b008832 (aberta)

Utilização e parâmetros

A função de callback KeyM_CryptoKeyVerifyCallbackNotification informa a aplicação sobre a conclusão de uma operação de verificação para uma chave criptográfica pelo módulo KeyM [SWS_KeyM_00081]. Interpretação: como o elemento está disponível através do cabeçalho KeyM_Externals.h segundo a especificação e serve para a notificação da aplicação, a implementação provavelmente deve ser realizada pelo componente de software usuário, enquanto a chamada é efetuada pelo Key Manager [SWS_KeyM_00081]. Pergunta Q-e88e332a7d2cac40 (aberta)

Para a chamada, estão definidos quatro parâmetros puramente de entrada [SWS_KeyM_00081]:

• Result (KeyM_ResultType): Passa o resultado da verificação concluída [SWS_KeyM_00081].
• KeyId (uint32): Identifica o identificador de chave para o qual a verificação foi iniciada [SWS_KeyM_00081].
• ResultDataLength (uint16): Contém o comprimento dos dados de resultado resultantes, caso existam [SWS_KeyM_00081].
• ResultDataPtr (const uint8*): Aponta para os dados do resultado da verificação [SWS_KeyM_00081].

Simultaneidade e restrições

A função não possui valor de retorno (void), nem parâmetros de saída ou de entrada/saída [SWS_KeyM_00081]. A chamada é executada de forma síncrona e reentrante [SWS_KeyM_00081]. Códigos de erro específicos, bem como mensagens de DET ou DEM, não são especificados para este callback; informações de status e de erro são transmitidas à aplicação exclusivamente através do parâmetro Result [SWS_KeyM_00081].

Utilização e semântica

A função de callback KeyM_ServiceCertificateCallbackNotification é chamada pelo submódulo de certificados do KeyM para notificar a aplicação sobre a conclusão de uma operação de serviço de certificado [SWS_KeyM_00147]. A operação de certificado precedente é executada de forma assíncrona e, ao ser finalizada, executa este callback para transmitir os resultados à aplicação [SWS_KeyM_00149].

Por meio dos parâmetros da função, são transmitidos todos os dados de resultado relevantes [SWS_KeyM_00147]:

• CertId: identificador do certificado para o qual a operação foi iniciada.
• Result: tipo KeyM_ResultType com o status ou resultado da operação.
• ResultDataLength: comprimento dos dados de resultado, caso existentes.
• ResultDataPtr: ponteiro para os dados de resultado.

A própria função não possui valor de retorno (void) e apresenta semântica de execução síncrona [SWS_KeyM_00147].

Configuração e restrições

O callback é disponibilizado por meio do cabeçalho KeyM_Externals.h, mas está disponível apenas se o parâmetro de configuração KeyMServiceCertificateFunctionEnabled estiver definido como TRUE [SWS_KeyM_00147]. O nome real da função de notificação é customizável por meio do parâmetro de configuração KeyMServiceCertificateCallbackNotificationFunc [SWS_KeyM_00147].

Simultaneidade e tratamento de erros

De acordo com a especificação, a função é classificada como reentrante [SWS_KeyM_00147]. Estados de erro ou de sucesso da operação assíncrona anterior são sinalizados por meio do parâmetro de passagem Result; mensagens específicas de DET ou DEM não estão definidas para esta interface de callback no payload [SWS_KeyM_00147].

usar

A função de callback KeyM_CertificateVerifyCallbackNotification destina-se a notificar a aplicação sobre a conclusão de uma verificação de certificado [SWS_KeyM_00073]. A declaração está disponível através do cabeçalho KeyM_Externals.h, sendo que o nome da função pode ser configurado através do parâmetro de configuração KeyMCertificateVerifyCallbackNotificationFunc [SWS_KeyM_00073].

Na chamada, são passados dois parâmetros de entrada [SWS_KeyM_00073]:

• CertId (tipo KeyM_CertificateIdType): Identificador do certificado verificado [SWS_KeyM_00073].
• Result (tipo KeyM_CertificateStatusType): Contém informações sobre o resultado da operação de verificação [SWS_KeyM_00073].

A função retorna como valor de status do tipo Std_ReturnType o valor E_OK [SWS_KeyM_00073].

Execução e tratamento de erros

A execução da notificação é definida como síncrona e reentrante [SWS_KeyM_00073]. Códigos de erro específicos, valores de retorno divergentes ou mensagens para o DET ou DEM não estão previstos para este callback [SWS_KeyM_00073]. Interpretação: a implementação do lado da aplicação provavelmente deve ser projetada para ser thread-safe, a fim de processar chamadas simultâneas para diferentes certificados sem efeitos colaterais. Pergunta Q-6bf5313c425fe1a8 (aberta)

usar

O tipo de dados KeyM_CertElementIteratorType está definido conforme [SWS_KeyM_00042] como estrutura (Structure) e é disponibilizado através do arquivo de cabeçalho KeyM.h. Conforme a especificação, este tipo serve para iterar sobre uma série de elementos de um certificado ([SWS_KeyM_00042]). Como o conteúdo concreto da estrutura de dados está expressamente estabelecido como específico de implementação ([SWS_KeyM_00042]), os usuários devem provavelmente considerar o tipo como um estado de iteração opaco e não acessar diretamente os campos internos da estrutura. Pergunta Q-81b5deb7dcdf2812 (aberta)

Manuseamento e restrições

Da especificação decorrem as seguintes condições práticas de enquadramento para o uso:

• Estrutura específica de implementação: como os campos de KeyM_CertElementIteratorType são implementados de forma específica pelo fabricante ([SWS_KeyM_00042]), o layout interno da memória depende da respectiva realização do BSW.
• Gerenciamento de estado: interpretação: é provável que uma instância da estrutura deva ser alocada pelo chamador como contexto de iterador e passada para as funções correspondentes de travessia de elementos de certificado, para acompanhar o progresso na verificação ou extração de campos de certificado. Pergunta Q-5ddb438001abe656 (aberta)
• Concorrência: presumivelmente, uma instância de iterador não pode ser utilizada de forma concorrente sem sincronização externa através de múltiplas tarefas caso ocorram acessos paralelos ao mesmo certificado. Pergunta Q-6b4b8b1cdc35f021 (aberta)

O tipo de enumeração KeyM_ServiceCertificateType é disponibilizado através do cabeçalho Rte_KeyM_Type.h e especifica a operação de serviço de certificados solicitada pelo servidor de chaves, bem como a natureza das informações passadas com a função [SWS_KeyM_00039]. É provável que a declaração no arquivo de cabeçalho da RTE indique que o tipo é empregado sobretudo no intercâmbio de dados entre componentes de software e o módulo Key Manager. Pergunta Q-37ed693ea3eda646 (aberta)

Os seguintes códigos de operação padronizados estão definidos para o gerenciamento de certificados [SWS_KeyM_00039]:

• KEYM_SERVICE_CERT_REQUEST_CSR (0x01): O servidor de chaves solicita ao cliente de chaves que gere um certificado ou uma solicitação de certificado (CSR) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_SIGNED_CSR (0x02): O servidor retorna um certificado recebido anteriormente e, entretanto, assinado pela autoridade de certificação (CA) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_ROOT (0x03) e KEYM_SERVICE_CERT_UPDATE_ROOT (0x04): Criação de um novo certificado raiz ou atualização de um existente [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_INTERMEDIATE (0x05) e KEYM_SERVICE_CERT_UPDATE_INTERMEDIATE (0x06): Adição ou atualização de um certificado intermediário (certificado de CA) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_CRL (0x07): Disponibilização ou atualização de uma lista de revogação de certificados (CRL) [SWS_KeyM_00039].

Como pré-requisito essencial, KEYM_SERVICE_CERT_SET_INTERMEDIATE exige que, antes de definir um certificado intermediário, o certificado raiz correspondente já esteja armazenado para garantir uma verificação bem-sucedida [SWS_KeyM_00039]. Para extensões específicas do projeto, a especificação prevê a faixa de valores reservada de 0x80 a 0x9F [SWS_KeyM_00039].

O tipo de enumeração KeyM_CertificateStatusType representa o resultado de verificações de certificados e reproduz o estado atual de verificação e processamento de um certificado no Key Manager [SWS_KeyM_91003]. O tipo é disponibilizado através do header Rte_KeyM_Type.h e serve para os chamadores avaliarem de forma diferenciada o estado ou causas de erro específicas de uma verificação de certificado [SWS_KeyM_91003].

Os valores de enumeração cobrem tanto estados intermédios e de sucesso regulares como padrões de erro precisos [SWS_KeyM_91003]:

• KEYM_CERTIFICATE_VALID (0x00): O certificado foi analisado sintaticamente (parsed) e verificado com sucesso [SWS_KeyM_91003].
• KEYM_CERTIFICATE_INVALID (0x01): O certificado é inválido devido a um erro não especificado detalhadamente [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_PARSED (0x02): O certificado ainda não foi analisado sintaticamente (parsed) até ao momento [SWS_KeyM_91003].
• KEYM_CERTIFICATE_PARSED_NOT_VALIDATED (0x03): O certificado foi analisado sintaticamente (parsed), mas ainda não foi validado [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_AVAILABLE (0x04): Não está definido nenhum certificado [SWS_KeyM_91003].
• Resultados de verificação específicos de erros: Período de validade falhado (KEYM_E_CERTIFICATE_VALIDITY_PERIOD_FAIL, 0x05), assinatura incorreta (KEYM_E_CERTIFICATE_SIGNATURE_FAIL, 0x06), cadeia de confiança inválida (KEYM_E_CERTIFICATE_INVALID_CHAIN_OF_TRUST, 0x07), tipo inválido (KEYM_E_CERTIFICATE_INVALID_TYPE, 0x08), formato incorreto (KEYM_E_CERTIFICATE_INVALID_FORMAT, 0x09), conteúdo inválido (KEYM_E_CERTIFICATE_INVALID_CONTENT, 0x0A), bem como revogação ou âmbito de validade inválido (KEYM_E_CERTIFICATE_REVOKED, 0x0B) [SWS_KeyM_91003].

Os chamadores devem verificar o status antes da utilização de chaves criptográficas; normalmente, as operações só podem basear-se em um certificado se o status sinalizar explicitamente KEYM_CERTIFICATE_VALID. Como o tipo é declarado via Rte_KeyM_Type.h, é provável que seja utilizado principalmente em interfaces de serviço padronizadas e portas para a interação entre KeyM e SWCs de aplicação. Pergunta Q-f3ca10ee673798df (aberta)

Utilização e estrutura

O tipo de dados KeyM_CertificateElementType é especificado como array de bytes com o tipo de elemento uint8 e serve, segundo a especificação, como uma área de memória suficientemente grande para o armazenamento de dados de um elemento de certificado [SWS_KeyM_91004]. A disponibilização e declaração do tipo de dados ocorre para o módulo KeyM por meio do arquivo de cabeçalho Rte_KeyM_Type.h [SWS_KeyM_91004].

Configuração e criação de variantes

A manifestação do tipo de dados está sujeita a uma variação de nome e tamanho dependente da configuração, a qual é derivada dos parâmetros configurados do módulo [SWS_KeyM_91004]:

• Padrão de nomenclatura: o nome concreto do tipo é gerado de forma específica para o elemento de acordo com o esquema KeyM_CertificateElementType_{KeyMCertificate}_{KeyMCertificateElement}, no qual os marcadores de posição correspondem aos nomes curtos configurados SHORT-NAME das respectivas instâncias de certificado e elemento de certificado [SWS_KeyM_91004].
• Tamanho do array: a quantidade de elementos uint8 é determinada pelo parâmetro de configuração KeyMCertificateElementMaxLength, para que o array ofereça espaço de memória suficiente para os dados brutos do respectivo elemento [SWS_KeyM_91004].

Restrições e premissas

Como a definição é disponibilizada em Rte_KeyM_Type.h, o tipo provavelmente deve ser utilizado primariamente como um buffer padronizado nas interfaces para componentes de software para a troca de conteúdos de certificados [SWS_KeyM_91004]. Pergunta Q-994f8ac6772de3c1 (aberta) O comprimento máximo de dados processável permanece, assim, estaticamente vinculado ao comprimento máximo definido no momento da configuração [SWS_KeyM_91004].

Utilização e definição de tipo

O tipo de dados KeyM_CryptoKeyDataType é definido como tipo de ponteiro para uint8* e serve como ponteiro de byte para dados de entrada ou saída dentro do módulo KeyM [SWS_KeyM_91012]. A definição do tipo é disponibilizada por meio do arquivo de cabeçalho Rte_KeyM_Type.h [SWS_KeyM_91012].

Restrições e gerenciamento de memória

Ao utilizar KeyM_CryptoKeyDataType como ponteiro para buffers de bytes, devem ser observadas condições de contorno específicas:

• Interpretação: Como o tipo é especificado como um simples ponteiro de byte (uint8*) [SWS_KeyM_91012], a alocação, o dimensionamento bem como a validade da memória referenciada provavelmente cabem ao respectivo chamador. Pergunta Q-07c167f400cbfb9c (aberta)
• Interpretação: Ao passar como buffer de saída, provavelmente deve ser assegurado que a área de memória referenciada seja grande o suficiente para os dados de chave ou criptográficos a serem recebidos, a fim de evitar estouros de buffer. Pergunta (aberta)
• Interpretação: Para o acesso concorrente ao buffer referenciado, medidas adicionais de sincronização pelo software chamador provavelmente devem ser necessárias, uma vez que o próprio tipo não oferece mecanismo de sincronização. Pergunta (aberta)

Integração

Chamadores que passam dados de chaves criptográficas ou certificados para interfaces KeyM, ou os recebem destas, incluem Rte_KeyM_Type.h para obter acesso à definição de ponteiro tipada de KeyM_CryptoKeyDataType [SWS_KeyM_91012].

O tipo enumerado KeyM_ResultType especifica o resultado de funções assíncronas do módulo KeyM para gerenciamento de chaves e certificados [SWS_KeyM_91008]. O tipo é disponibilizado através do arquivo de cabeçalho Rte_KeyM_Type.h e serve para o feedback sobre o desfecho de uma ordem de trabalho assíncrona solicitada [SWS_KeyM_91008].

O intervalo de valores abrange códigos de status e de erro padronizados para avaliação diferenciada por parte dos chamadores [SWS_KeyM_91008]:

• KEYM_RT_OK (0x00): A operação de gerenciamento de chaves foi concluída com sucesso [SWS_KeyM_91008].
• KEYM_RT_NOT_OK (0x01): Ocorreu um erro geral durante a operação de gerenciamento de chaves [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_INVALID (0x02): A chave ou o certificado referenciado é inválido e não pode ser utilizado para a operação [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_WRITE_FAIL (0x03): A escrita da chave ou do certificado na memória de destino prevista falhou [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_UPDATE_FAIL (0x04): Erro geral na atualização de uma chave ou certificado que não pôde ser especificado com maior precisão por um código mais específico [SWS_KeyM_91008].
• KEYM_RT_CERT_INVALID_CHAIN_OF_TRUST (0x05): A verificação do certificado falhou devido a uma cadeia de confiança inválida [SWS_KeyM_91008].

Chamadores de funções assíncronas do KeyM devem avaliar este tipo de retorno para poder reagir de forma direcionada, em caso de erro, a cadeias de confiança inválidas, falhas de acesso à memória ou material de chave incorreto [SWS_KeyM_91008].

A estrutura KeyM_CertDataType é utilizada no módulo KeyM para a passagem e o intercâmbio de dados de certificado através de funções de interface [SWS_KeyM_00041]. A definição de tipo está disponível através do arquivo de cabeçalho KeyM.h [SWS_KeyM_00041].

A estrutura reúne dois elementos essenciais [SWS_KeyM_00041]:

• certDataLength: Elemento do tipo uint32, que indica o comprimento dos dados de certificado [SWS_KeyM_00041].
• certData: Elemento do tipo VoidPtr, que referencia como ponteiro diretamente os dados de certificado em uma área de dados local do chamador [SWS_KeyM_00041].

Como certData faz referência a áreas de memória no contexto local do chamador [SWS_KeyM_00041], o gerenciamento de buffer compete à instância chamadora. Interpretação: é provável que o chamador tenha de assegurar que a memória referenciada permaneça válida durante todo o período de execução da respectiva função de interface e abranja pelo menos o número de bytes indicado em certDataLength. Pergunta Q-7da9d5ed0975ddbd (aberta) Além disso, presume-se que, com um comprimento maior que zero, deva ser passado um ponteiro válido diferente de NULL para evitar acessos incorretos à memória dentro da função de interface.