Ir para o conteúdo

Assinatura digital

Realiza a assinatura digital do hash de um conteúdo, utilizando a chave privada do certificado do usuário.


POST /signature

Solicitação

A aplicação deve enviar os dados a serem assinados ao endpoint de assinatura do PSC NeoID, https://psc-neoid.estaleiro.serpro.gov.br/psc/v0/oauth/signature postando os parâmetros via application/json. O token de acesso gerado em Token de acesso deverá ser enviado via HTTP Header no parâmetro Authorization.

Parâmetros

HEADER:

  • Authorization - (string) - valor "Bearer <access_token>", onde <access_token> se refere ao token de acesso obtido em Token de acesso

JSON:

  • hashes - (array) - lista com os dados a serem assinados, limite atual de 5
    • id - (string) - utilizado para identificação do hash
    • alias - (string) - descrição do conteúdo a ser assinado
    • hash - (string) - Base64 do hash do conteúdo a ser assinado
    • hash_algorithm - (string) - OID (Objetct Identifier) do algoritmo de hash utilizado, valores possíveis: 2.16.840.1.101.3.4.2.1: representa o algoritmo SHA-2 256 e 2.16.840.1.101.3.4.2.3: representa o algoritmo SHA-2 512
    • signature_format - (string) - o tipo de assinatura a ser realizada, RAW para assinatura digital simples (PKCS1) e CMS para assinatura digital qualificada (PKCS7)

Exemplo

O exemplo encontra-se com quebras de linha e espaços para melhor leitura

```http tab="HTTP" POST /psc/v0/oauth/signature HTTP/1.1 Host: psc-neoid.estaleiro.serpro.gov.br Content-Type: application/json Authorization: Bearer

{ "hashes":[ { "id": "", "alias": "", "hash": "", "hash_algorithm": "", "signature_format": "" } ] }

```shell tab="cURL"
curl -X POST \
  https://psc-neoid.estaleiro.serpro.gov.br/psc/v0/oauth/signature \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token_de_acesso>' \
  -d '{
      "hashes":[
          {
            "id": "<identificador do hash>",
            "alias": "<descrição do conteúdo a ser assinado>",
            "hash": "<base_64_hash_sha_256>",
            "hash_algorithm": "<oid_do_hash_utilizado>",
            "signature_format": "<tipo_de_assinatura_desejada>"
          }
        ]
    }'

Poderá ser utilizado os algoritmos de hash SHA2 256 e SHA2 512 e para realização do encode o Base64. A operação para obtenção do hash deve ser similar à seguinte função de exemplo em alto nível: base64(funcao-hash(conteudo_a_ser_assinado)). A função funcao-hash deve retornar um array de bytes contendo o hash do conteúdo a ser assinado, o resultado final da operação após a função base64 deve ser uma string.

Resposta da solicitação

O PSC NeoID irá realizar a assinatura digital utilizando a chave privada do certificado que o usuário autorizou no processo de solicitação de autorização.

Solicitação válida (Sucesso)

Se a solicitação estiver válida, o PSC NeoID irá retornar a solicitação com HTTP code 200 no formato application/json.

Parâmetros

JSON:

  • signatures - (array) - lista com as assinaturas
    • id - (string) - identificação do hash conforme apresentado na solicitação
    • raw_signature - (string) - assinatura do hash no formato solicitado, PKCS7 ou Base64 da assinatura RAW
Exemplo
HTTP/1.1 200 OK
Content-Type: application/json

{
    "signatures":[
        {
            "id": "<identificador_do_hash>",
            "raw_signature": "<assinatura_no_formato_solicitado>"
        }
    ]
}

Solicitação inválida (Erro)

Se a solicitação for considerada inválida, seja devido a verificação dos parâmetros informados ou caso algum erro inesperado aconteça, o PSC NeoID retornará um erro no formato application/json com o HTTP code correspondente ao tipo do erro.

Parâmetros

JSON:

  • code - (string) - código do tipo do erro
  • msg- (string) - mensagem de erro
  • debug - (string) - informações adicionais sobre o erro
Exemplo
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "code": "TOKEN_DE_ACESSO_INVALIDO",
    "msg": "Token de acesso não informado ou inválido",
    "debug": ""
}
Lista de erros
Tipo do erro HTTP Code Detalhes
TOKEN_DE_ACESSO_INVALIDO 401 Token de acesso não informado ou inválido
TOKEN_JA_UTILIZADO 401 Token de acesso já utilizado
NAMESPACE_BLOQUEADO 401 Acesso bloqueado por limite de erro de credenciais
ASSINATURA_DADOS_INVALIDOS 412 Hash(es) para assinatura não informado(s)
ASSINATURA_NOT_SINGLE 412 Token de acesso gerado apenas para escopo "single_signature" e mais de um hash informado
MULTI_SIGNATURE_ASSINATURAS_MAXIMO_ATINGIDO 412 Valor máximo de assinaturas atingido
MULTI_SIGNATURE_TAMANHO_MAXIMO_ATINGIDO 412 Valor máximo em bytes dos hashes atingido
INVALID_SIGNATURE 412 Os parâmetros informados são inválidos ou o certificado não é mais válido (expirado ou revogado)

Cenários possíveis:
  • Valor do hash inválido, Base64 esperado
  • O hash não condiz com o algoritmo de hash informado
  • O certificado encontra-se fora da data de validade
  • Não foi possível verificar se o certificado está revogado
  • O certificado está revogado
TOKEN_USO_EXCLUSIVO_AUTENTICACAO 403 A autorização concedida é para fim exclusivo de autenticação e não possibilita a geração de assinatura digital.
TOKEN_REVOGADO 403 O token apresentado se encontra revogado.
SIGN_FAIL 500 Algo inesperado aconteceu e não foi possível realizar a assinatura