Guia do Desenvolvedor versão 1.5

27/04/2017

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 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.

É importante notar que o Assinador de Documentos MPS assina diretamente os hashes dos arquivos não sendo necessário trafegar os conteúdos dos mesmos para que sejam feitas as assinaturas.

Em virtude de não receber o conteúdo dos arquivos só é possível gerar assinaturas do tipo external signatures, ou seja, que não incluem o conteúdo do documento na própria assinatura.


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.

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

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

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

<?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.

  • 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 site 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.