Guia do Desenvolvedor versão 1.9

27/08/2021

Do ponto de vista do desenvolvedor a interação com o Assinador de Documentos MPS pode ser feita de duas formas.

Através dos protocolos mps-assinador-https e mps-assinador-http em aplicações web, ou através da execução direta do aplicativo no caso de aplicações desktop.

Em ambos os casos a comunicação entre a aplicação e o Assinador de Documentos MPS é feita através documentos xml que estão de acordo com um xml schema que está descrito aqui.

As assinaturas geradas pelo Assinador de Documentos MPS estarão nos dois formatos: CAdES. PAdES.

Além disto, se os certificados utilizados na assinatura forem emitidos pela ICP-Brasil, as assinaturas estarão em conformidade com o perfil de uso geral para assinaturas digitais da ICP-Brasil.

Integração de Aplicação Web

Protocolos Suportados

O instalador do Assinador de Documentos MPS registra tratadores para os seguintes protocolos na estação de trabalho do usuário:

  • mps-assinador-https: que permite a comunicação entre o assinador e a aplicação utilizando o protocolo HTTPS.

    Esta é a forma preferida de comunicação com a aplicação, pois garante a segurança e integridade dos dados trafegados pela rede.

    O grande problema do uso deste protocolo é a necessidade de criação de certificados que sejam confiáveis para os clientes e que sejam instalados no servidor web onde a aplicação está hospedada.

  • mps-assinador-http: que permite a comunicação entre o assinador e a aplicação utilizando o protocolo HTTP.

    Esta opção é mais simples do ponto de vista de intfraestrutura, mas impõe sérios riscos de segurança para o processo de assinatura dos documentos.

    Desta forma não deve ser usado a menos que não seja possível configurar o uso do protocolo mps-assinador-https.

Para que o assinador seja executado a aplicação web deve gerar um link no seguinte formato:

protocolo-assinador://servidor/caminho[?parametros]#parametros-assinador

Onde:

  • protocolo-assinador: pode ser especificado como mps-assinador-https ou mps-assinador-http de acordo com o requisito de acesso a aplicação web ser feito via HTTPS ou HTTP

  • servidor: é o nome ou endereço do servidor que está executando a aplicação web.

  • caminho: é o caminho dentro do servidor do endpoint que vai tratar a interação entre o assinador e a aplicação web

  • parametros: opcionalmente podem ser passados parâmetros para o endpoint que vai tratar a interação entre o assinador e a aplicação web

  • parametros-assinador: contém os parâmetros que serão utilizados pelo assinador para fazer a interação com a aplicação web.

    Os seguintes parâmetros podem ser passados para o assinador nesta versão:

    • autorizacao: contém o valor gerado pela aplicação web que será usado nas interações com a aplicação web para fazer a autenticação do usuário.

      O valor recebido através deste parâmetro ser enviado via o cabeçalho Authorization com esquema Bearer do protocolo HTTP.

      O exemplo a seguir mostra o cabeçalho que será gerado caso o parâmetro autorizacao recebido seja 957572d0ebc09a11182dd06c6c652d6d:

      Authorization: Bearer 957572d0ebc09a11182dd06c6c652d6d

      Deve ser notado que é de responsabilidade da aplicação web fazer a autenticação deste valor.

    • nomeCookie e valorCookie: contém o nome e valor de um cookie que será utilizado nas interações com a aplicação web para fazer a autenticação do usuário.

      Normalmente estes parâmetros são utilizados em conjunto com aplicações web que fazem a autenticação via Forms Authentication ou através de Session State.

      O valor recebido através deste parâmetro ser enviado via o cabeçalho Cookie do protocolo HTTP.

      O exemplo a seguir mostra o cabeçalho que será gerado caso o parâmetro nomeCookie seja .forms-auth e o parâmetro valorCookie seja 957572d0ebc09a11182dd06c6c652d6d:

      Cookie: .forms-auth=957572d0ebc09a11182dd06c6c652d6d

      Deve ser notado que é de responsabilidade da aplicação web fazer a autenticação deste valor.

Quando o usuário selecionar o link na página da aplicação o assinador será executado e receberá o conteúdo do link selecionado pelo usuário.

Neste momento o assinador fará as seguintes transformações no link recebido de forma a acessar a aplicação web:

  • Vai trocar o protocolo do link recebido de mps-assinador-https para https ou de mps-assinador-http para http.
  • Em seguida vai obter os parâmetros de interação com a aplicação a partir do campo parametros-assinador e em seguida vai remover o mesmo do link.

Por exmplo, se o link recebido pelo assinador for o seguinte:

mps-assinador-https://exemplo.com/aplicacao/controlador/acao?parametro1=a&parametro2=b#autorizacao=957572d0ebc09a11182dd06c6c652d6d

O seguinte endereço será utilizado nas interações do assinador com a aplicação web:

https://exemplo.com/aplicacao/controlador/acao?parametro1=a&parametro2=b

Interações com a Aplicação Web

O Assinador de Documentos MPS faz duas requisições para a aplicação web para poder executar a assinatura dos documentos.

As duas requisições utilizam o mesmo endereço que foi obtido a partir do link recebido pelo assinador ao ser iniciado.

Identificação de Recursos Suportados

Nas interações com a aplicação web, o assinador envia um cabeçalho HTTP que identifica os recursos suportados.

O cabeçalho enviado é o X-ADOM-Recursos e vai conter uma lista dos recursos separados por ;.

Os recursos suportados nesta versão são:

  • co-assinatura: indica que o assinador suporta o recebimento de assinaturas prévias no documento a ser assinado e, neste caso, vai fazer uma co-assinatura.

  • documento-obrigatorio: indica que o assinador suporta a indicação de documentos em que o usuário não terá a opção de não fazer a assinatura.

  • selecao-certificados: indica que é possível configurar se será possível apenas um ou se mais certificados poderão ser utilizados na assinatura dos documentos.

  • requisito-certificado: indica que o assinador suporta a especificação do requisito mínimo para habilitação de certificados para a assinatura.

  • certificado-automatico: indica que é possível fazer a seleção automática de certificado para assinatura e o fechamento automático do aplicativo ao final do processo.

    Para que a seleção automática de certificado seja feita, todos os documentos a serem assinados devem estar marcados obrigatórios e exigir apenas um certificado. Alem disso, apenas um certificado deve estar qualifidado para fazer a assinatura dos documentos.

  • icp-lpa-2.3: indica que a política de assinatura suportada para assinaturas no padrão ICP-Brasil é a 2.3.

A aplicação web pode utilizar esta lista para impedir versões que não suportem os recursos necessários de fazer a interação com ela (em geral gerando erros HTTP com o código 400 ou 412).

Obtenção da Lista de Documentos

A primeira requisição utiliza o método GET do protocolo HTTP para obter a lista de documentos a serem assinados.

Além dos headers de autenticação, esta requisição configura o header Accept com o valor text/xml.

A aplicação web deve responder a esta requisição com o codigo 200 do protocolo HTTP.

Qualquer outro código será reportado como erro de comunicação pelo assinador.

O conteúdo da resposta deve ser um documento xml construído com base no schema do assinador que é encontrado aqui e deve conter apenas o elemento Documentos para ser considerado válido.

Por exemplo, se o assinador receber o seguinte link:

mps-assinador-https://exemplo.com/aplicacao/controlador/acao?parametro1=a&parametro2=b#autorizacao=957572d0ebc09a11182dd06c6c652d6d

A seguinte requisição será gerada:

GET /aplicacao/controlador/acao?parametro1=a&parametro2=b HTTP/1.1
Host: exemplo.com:443
Authorization: Bearer 957572d0ebc09a11182dd06c6c652d6d
Accept: text/xml
X-ADOM-Recursos: co-assinatura;documento-obrigatorio;selecao-certificados;requisito-certificado;certificado-automatico;icp-lpa-2.3

Já para o seguinte link:

mps-assinador-https://exemplo.com/aplicacao/controlador/acao?parametro1=a&parametro2=b#nomeCookie=teste&valorCookie=957572d0ebc09a11182dd06c6c652d6d

A seguinte requisição será gerada:

GET /aplicacao/controlador/acao?parametro1=a&parametro2=b HTTP/1.1
Host: exemplo.com:443
Cookie: teste=957572d0ebc09a11182dd06c6c652d6d
Accept: text/xml
X-ADOM-Recursos: co-assinatura;documento-obrigatorio;selecao-certificados;requisito-certificado;certificado-automatico;icp-lpa-2.3

A seguinte resposta é esperada, caso a requisição seja bem sucedida (os dados foram omitidos para facilitar a leitura):

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<Documentos xmlns="https://mps.com.br/assinador/v1/assinador.xsd">
    <Documento>
    ...
    </Documento>
    ...
</Documentos>
Envio da Lista de Assinaturas

A segunda requisição utiliza o método POST do protocolo HTTP para enviar a lista de documentos assinados.

Além dos headers de autenticação, esta requisição configura os headers Accept e Content-Type com o valor text/xml.

A aplicação web deve responder a esta requisição com algum código de sucesso do protocolo HTTP, de preferência deve utilizar os códigos 202 ou 204.

Qualquer outro código será reportado como erro de comunicação pelo assinador.

O assinador vai enviar como conteúdo desta requisição para a aplicação web um documento xml gerado com base no schema do assinador que é encontrado aqui e vai conter apenas um elemento do tipo Assinaturas.

Por exemplo, se o assinador receber o seguinte link:

mps-assinador-https://exemplo.com/aplicacao/controlador/acao?parametro1=a&parametro2=b#autorizacao=957572d0ebc09a11182dd06c6c652d6d

A seguinte requisição será gerada:

POST /aplicacao/controlador/acao?parametro1=a&parametro2=b HTTP/1.1
Host: exemplo.com:443
Authorization: Bearer 957572d0ebc09a11182dd06c6c652d6d
Accept: text/xml
Content-Type: text/xml; charset=utf-8
X-ADOM-Recursos: co-assinatura;documento-obrigatorio;selecao-certificados;requisito-certificado;certificado-automatico;icp-lpa-2.3

<?xml version="1.0" encoding="utf-8"?>
<Assinaturas xmlns="https://mps.com.br/assinador/v1/assinador.xsd">
    <Assinatura>
    ...
    </Assinatura>
    ...
</Assinatura>

A seguinte resposta é esperada, caso a requisição seja bem sucedida:

HTTP/1.1 204 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 0

E caso de erro, por exemplo, a seguinte resposta pode ser recebida:

HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
Content-Length: 37

Os dados enviados não são válidos.
Considerações

É importante notar que o Assinador de Documentos MPS não tem como notificar o navegador que disparou o processo de assinaturas de que a operação foi encerrada.

Então é reponsabilidade da aplicação web fornecer alguma forma de atualização da página para que o usuário possa ver o resultado do processo de assinatura.

Integração de Aplicação Desktop

Uma aplicação desktop pode disparar o Assinador de Documentos MPS diretamente.

Para isso ela deve obter o caminho onde o assinador foi instalado e que está no registro do windows em HKEY_CURRENT_USER\SOFTWARE\MPS\Assinador de Documentos\1\Assinador (Note que nas versões anteriores esta chave de registro estava em HKEY_LOCAL_MACHINE, pois o assinador não era instalado por usuário).

Neste caso três parâmetros devem ser informados para o assinador.

  • arquivos: indica que a assinatura vai ser feita a lendo o arquivo informado no parâmetro arquivo_entrada.xml e vai salvar as assinaturas no arquivo informado no parâmetro arquivo_saida.xml.

  • arquivo_entrada.xml: indica o caminho para um arquivo xml com os documentos a serem assinados.

    O arquivo deve ser construído com base no schema do assinador que é encontrado aqui e deve conter apenas o elemento Documentos para ser considerado válido.

  • arquivo_saida.xml: indica o caminho onde o assinador vai salar o arquivo com as assinaturas para os documentos.

    O arquivo vai ser gerado com base no schema do assinador que é encontrado aqui e vai conter apenas um elemento do tipo Assinaturas.

A aplicação que dispara o Assinador de Documentos MPS pode esperar pela finalização do processo para saber se as assinaturas foram feitas com sucesso.

Os seguintes códigos são retornados pelo assinador e podem ser obtidos através da chamada a função GetExitCodeProcess.

  • 0: indica que o processo de assinatura foi bem sucedido e o arquivo de saída contém as assinaturas dos documentos.

  • 1: indica que houve um erro durante o processo de assinatura dos documentos.

  • 2: indica que os parâmetros passados para o Assinador de Documentos MPS foram inválidos.

  • 3: indica que o usuário cancelou o processo de assinatura dos documentos.

XML Schema

O Assinador de Documentos MPS define os seguintes tipos no namespace https://mps.com.br/assinador/v1/assinador.xsd.

O arquivo com o xml schema do assinador pode ser obtido aqui.

Documentos

Corresponde a uma lista do tipo Documento e é utilizado para obter os documentos que precisam ser assinados a partir da aplicação que acionou o Assinador de Documentos MPS.

Documento

É utilizado para conter os dados de um documento específico e é composto dos seguintes campos (todos os campos são obrigatórios):

  • Codigo: É uma string que contem o identificador do documento para a aplicação.

    Este campo não é mostrado para o usuário, mas é utilizado para correlacionar o documento com sua respectiva assinatura.

  • Nome: É uma string que contém o nome do documento que será assinado.

    Este campo é mostrado em negrito na lista de documentos que é apresentada pelo assinador.

  • Descricao: É uma string que contém um texto que descreve o documento que será assinado.

    Este campo pode ter múltiplas linhas e é mostrado na lista de documentos que é apresentada pelo assinador.

  • Tamanho: É um inteiro de 64 bits que contém o tamanho em bytes do documento que será assinado.

    Este campo é mostrado na lista de documentos que é apresentada pelo assinador.

  • Motivo: É uma string que contém um texto que descreve o motivo da assinatura que está relacionado ao contexto da aplicação. Exemplo: “Aprovado pelo departamente financeiro.".

    Esse campo, quando não passado nada, será utilizado o valor default Assinatura Digital. O mesmo só aparece no formato PAdES.

  • Local: É uma string que contém um texto que descreve o local, físico ou virtual, da assinatura que está relacionado ao contexto da aplicação. Exemplo1: “Administrativo - Curitiba-PR.", Exemplo2: “Setor financeiro.".

    Esse campo, quando não passado nada, será utilizado o valor default ADOM - Assinador de Documentos MPS. O mesmo só aparece no formato PAdES.

  • Arquivo (opcional): contém o conteúdo do arquivo em formato PDF.

    Se este campo for informado, o assinador vai embutir a assinatura dentro do PDF (formato PAdES) e após isso gerar a assinatura PCKS#7 sobre esse arquivo.

    Importante: Todo e qualquer metadado necessário para o arquivo deve ser incluído pela aplicação antes que ela envie o arquivo ao assinador.

    Importante: Somente arquivos PDF podém ser passados para esse formato, caso contrário será lançada uma exceção.

  • Hash: é um campo composto que contém as seguintes informações:

    • Algoritmo: o algorítmo utilizado para gerar o hash do conteúdo do documento a ser assinado.

      Os seguintes valores são suportados SHA1 ou SHA256 (tipo de hash recomendado no momento).

    • Valor: o valor do hash calculado para o conteúdo do documento a ser assinado.

      É um array de 20 bytes no caso do algorítmo SHA1 ou 32 bytes no caso do algorítmo SHA256.

  • TipoSelecao (opcional): indica as opções de seleção do documento para o usuário, pode conter um dos seguintes valores:

    • Opcional: indica que o usuário pode escolher assinar o documento ou não.

    • Obrigatorio: indica que o documento deve obrigatoriamente ser assinado.

    Se não for informado valor para este elemento, será assumido o valor Opcional.

    Se todos os documentos tiverem a propriedade TipoSelecao configurada como Obrigatorio, a tela de seleção de documentos do assinador não será exibida.

  • Assinatura (opcional): contém as assinaturas já efetuadas no documento em formato PCKS#7.

    Se este campo for informado, o assinador vai fazer co-assinatura (adicionar uma nova assinatura a lista já existente) do documento enviando a lista com as assinaturas rececbidas mais as novas assinaturas para a aplicação.

    Não é feito nenhum controle sobre as assinaturas existentes para evitar duplicação. É responsabilidade da aplicação evitar a duplicação de assinaturas.

    Importante: O assinador não tem como fazer controle de concorrência no acesso a lista de assinaturas.

    É de responsabilidade da aplicação verificar se as assinaturas enviadas. Se a aplicação não tomar nenhum cuidado assinaturas podem ser perdidas.

    Recomendamos que esta funcionalidade seja usada com muito cuidado e, se possível, que co-assinaturas sejam implementadas dentro da aplicação e não dentro do assinador.

  • TipoSelecaoCertificado (opcional): indica as opções de seleção de certificados para o usuário, pode conter um dos seguintes valores:

    • Simples: indica que será possível selecionar apenas um certificado para fazer a assinatura (este é o valor padrão).

    • Multipla: indica que vários certificados poderão ser selecionados para fazer a assinatura.

    Importante: Para manter o comportamento das versões anteriores deve ser especificado o valor Multipla neste campo.

  • RequisitoCertificado (opcional): serve para restringir o tipo dos certificados que poderão ser utilizados na assinatura dos documentos. O valor especificado serve para indicar o requisito mínimo para habilitar o certificado. Pode assumir um dos seguintes valores:

    • Assinatura: habilita qualquer certificado com a finalidade de assinatura (valor padrão).

    • A1: habilita certificados no padrão ICP-Brasil do tipo A1 ou superior.

    • A2: habilita certificados no padrão ICP-Brasil do tipo A2 ou superior.

    • A3: habilita certificados no padrão ICP-Brasil do tipo A3 ou superior (a partir deste requisito, o padrão exige que o certificado esteja em um token ou smartcard).

    • A4: habilita certificados no padrão ICP-Brasil do tipo A4 ou superior.

      Mais informações sobre os padrões de certificado podem ser obtidas no documento requisitos mínimos para política de certificado da ICP-Brasil..

Assinaturas

Corresponde a uma lista do tipo Assinatura e é utilizado para enviar as assinaturas dos documentos de volta para a aplicação que acionou o Assinador de Documentos MPS.

Assinatura

É utilizado para conter os dados da assinatura de um documento específico e é composto dos seguintes campos (todos os campos são obrigatórios):

  • Codigo: É uma string que contem o identificador do documento para a aplicação.

    O valor deste campo é copiado do campo correspondente obtido das informações do documento.

  • Valor: É um array de bytes que contém a assinatura do documento.

    As assinaturas geradas pelo Assinador de Documentos MPS estarão no formato CAdES.

    Além disto, se os certificados utilizados na assinatura forem emitidos pela ICP-Brasil, as assinaturas estarão em conformidade com o perfil de uso geral para assinaturas digitais da ICP-Brasil.

  • Arquivo: É um array de bytes que contém o documento PDF assinado.

    As assinaturas geradas pelo Assinador de Documentos MPS nesse campo estarão no formato PAdES.