Pular para o conteúdo principal
Version: 4.41

Tutorial: Primeiros passos com a API DSS

Visão geral​

Este guia acompanha você nos primeiros passos com a API DSS: autenticação no serviço, obtenção de um certificado de assinatura disponível e envio de uma solicitação de assinatura.

Ao final deste guia, você será capaz de:

  • Autenticar-se no serviço DSS
  • Obter os certificados disponíveis para um usuário local
  • Assinar um documento usando a operação SignRequest

Antes de começar​

Antes de começar, certifique-se de ter o seguinte:

  • Acesso a um ambiente Redtrust com o serviço DSS habilitado
  • Uma conta de usuário local do Redtrust (usuario@dominio) com uma política que permita serviços de assinatura (consulte a seção Onde da política)
  • Um certificado de assinatura disponível para esse usuário
  • SoapUI ou outro cliente HTTP capaz de enviar solicitações SOAP 1.2
  • Um arquivo que você deseja assinar (convertido para Base64 para a solicitação)
tip

Para converter um arquivo para Base64, você pode usar o comando abaixo.

[System.IO.File]::WriteAllText("CAMINHO_DO_ARQUIVO_DESTINO.txt",[System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("CAMINHO_DO_ARQUIVO_ORIGEM.pdf")))

Para convertê-lo novamente para o formato original, você pode usar o comando abaixo.

[System.IO.File]::WriteAllBytes("CAMINHO_DO_ARQUIVO_DESTINO.pdf",[System.Convert]::FromBase64String([System.IO.File]::ReadAllText("CAMINHO_DO_ARQUIVO_ORIGEM.txt")))

Etapa 1: Criar um perfil DSS​

Antes de fazer qualquer solicitação à API, você precisa criar um perfil DSS no console de administração.

  1. Acesse o console de administração com uma função que tenha acesso ao gerenciamento de assinaturas. Se a função tiver acesso, você verá a aba Assinatura na barra de navegação.
  2. Vá até Assinatura e clique em Novo.
  3. Adicione um nome, neste exemplo pades-bes-profile.
  4. Selecione um tipo de assinatura, neste exemplo PAdES, e clique em Seguinte.
  5. Selecione um nível de assinatura, neste exemplo BES. Para mais informações, consulte os níveis suportados.
  6. Clique em Seguinte nas demais opções e, por fim, em Aplicar.

Etapa 2: Autenticar-se no serviço DSS​

Para fazer uma solicitação à API DSS, é necessário autenticar-se. O serviço DSS oferece suporte a vários mecanismos de autenticação, cada um com um endpoint diferente. Neste guia, os exemplos usam autenticação por nome de usuário e senha, adequada para testes iniciais e desenvolvimento. No SoapUI, a autenticação é configurada por meio de opções específicas. Siga estas etapas:

  1. Abra o SoapUI e clique em SOAP.

  2. No formulário New SOAP Project, adicione o Initial WSDL: https://REDTRUST_IP:8080/RTDSSService.svc.

    nota

    Por padrão, a porta de conexão é 8080, embora possa ser configurada no console de administração do Redtrust (Sistema > Unidade > Rede). Da mesma forma, por padrão o protocolo é HTTPS e o certificado do serviço é gerado automaticamente durante a instalação, embora você também possa configurá-lo no console. Ao implementar um cliente que acesse o serviço, você deve considerar que será necessária a parte pública do certificado do serviço para que o cliente confie no servidor, a menos que o cliente aceite qualquer certificado.

  3. Clique no nome do projeto. Na janela de configuração:

    1. Clique em WS-Security Configurations (terceira aba).
    2. Clique no ícone verde + e adicione o nome do usuário, por exemplo final.
    3. Clique no segundo ícone verde + e selecione Username.
    4. Adicione USUARIO@DOMINIO, por exemplo final@local.users. Feche a janela para salvar as alterações.

Etapa 3: Adicionar a URL base​

No SoapUI, clique no ícone + ao lado do método GetAccessibleCertificates e clique duas vezes em Request 1. Adicione o endpoint base para autenticação por usuário e senha:

https://REDTRUST_IP:8080/RTDSSService.svc/basic
nota

A URL base das solicitações depende do método de autenticação e da configuração da implantação.

Etapa 4: Realizar a primeira solicitação à API​

Para realizar sua primeira solicitação à API, chame GetAccessibleCertificates para obter a impressão digital (thumbprint) do certificado. Na janela Request 1, siga estas etapas:

  1. Selecione a aba Auth (Basic) na parte inferior.
  2. No menu Authorization, selecione Add New Authorization > Basic.
  3. De volta à janela da solicitação, vá até Outgoing WSS e selecione o usuário que você acabou de criar.
  4. Selecione a aba WS-A na parte inferior e marque Add default wsa:Action e Add default wsa:To.

Execute a solicitação clicando no botão verde de reprodução (▶).

Solicitação
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:dss:ws">
<soap:Header/>
<soap:Body>
   <urn:GetAccessibleCertificates>
      <urn:filter></urn:filter>
   </urn:GetAccessibleCertificates>
</soap:Body>
</soap:Envelope>

Uma resposta bem-sucedida retorna um objeto Result com os certificados disponíveis para o usuário autenticado.

Resposta
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
<s:Header>
   <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/GetAccessibleCertificatesResponse</a:Action>
</s:Header>
<s:Body>
   <GetAccessibleCertificatesResponse xmlns="urn:evolium:redtrust:dss:ws">
      <Result xmlns:b="http://schemas.datacontract.org/2004/07/RTDSSService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
         <b:ResultStatus>SUCCESS</b:ResultStatus>
         <b:ResultMessage>Operation finalized successfully</b:ResultMessage>
         <b:ResultData i:type="b:ArrayOfCertificate">
            <b:Certificate>
               <b:X509Data>...</b:X509Data>
               <b:alias>my-certificate</b:alias>
               <b:certificateHandler>16</b:certificateHandler>
               <b:expiration>2028-03-11T14:05:30</b:expiration>
               <b:issuer>Ceres</b:issuer>
               <b:needPin>false</b:needPin>
               <b:needReason>false</b:needReason>
               <b:subject>EIDAS CERTIFICADO PRUEBAS - 99999972C</b:subject>
               <b:thumbprint>5F5162563AFF01EB353D346C8B786AAA2A0CFB09</b:thumbprint>
               <b:type>PRIVATE</b:type>
            </b:Certificate>
         </b:ResultData>
         <b:TotalItems>1</b:TotalItems>
      </Result>
   </GetAccessibleCertificatesResponse>
</s:Body>
</s:Envelope>

Anote o thumbprint do certificado que você deseja usar para assinar.

Etapa 5: Assinar um documento PDF​

Para assinar o documento, chame a operação SignRequest. Para isso, você deve configurar o método da mesma forma que no passo anterior, ou seja, a partir da janela Request 1 no SoapUI:

  1. Selecione a aba Auth (Basic) na parte inferior.
  2. No menu Authorization, selecione Add New Authorization > Basic.
  3. De volta à janela da solicitação, vá até Outgoing WSS e selecione o usuário que você criou (neste exemplo, final).
  4. Selecione a aba WS-A na parte inferior e marque Add default wsa:Action e Add default wsa:To.

Em seguida, chame SignRequest clicando em Request 1 do método correspondente. Considere o seguinte:

  • Profile é o nome do perfil de assinatura que você criou no etapa 1.
  • O thumbprint é o que você obteve no etapa 4, junto com o PDF do documento em Base64.
  • A solicitação usa profile:XAdES:forms:BES, que inclui PAdES. Não substitua esse valor por uma URI de PAdES, pois este endpoint não a aceita.
  • A API DSS é sensível ao formato das solicitações. Pequenas diferenças em quebras de linha podem afetar o processamento. Se uma solicitação retornar resultados incompletos ou inesperados, compare-a cuidadosamente com os exemplos fornecidos.
  • Inclua AdditionalKeyInfo apenas se o certificado exigir um PIN.

Solicitação

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
   <soap:Header/>
      <soap:Body>
         <SignRequest Profile="DSS_PROFILE" RequestID="dss-sign-request-1" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
            <OptionalInputs>
               <Language xmlns="urn:oasis:names:tc:dss:1.0:core:schema">en-US</Language>
            <KeySelector xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
               <KeyInfo Id="Thumbprint" xmlns="http://www.w3.org/2000/09/xmldsig#">THUMBPRINT</KeyInfo>
            </KeySelector><SignatureForm xmlns="urn:evolium:redtrust:dss:1.0:core:schema">urn:oasis:names:tc:dss:1.0:profiles:XAdES:forms:BES</SignatureForm>
            <AdditionalKeyInfo xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
               <KeyInfo Id="Pin" xmlns="http://www.w3.org/2000/09/xmldsig#"></KeyInfo>
            </AdditionalKeyInfo>
            </OptionalInputs>
            <InputDocuments>
               <Document ID="ID-document-1">
                  <Base64Data MimeType="application/pdf">PDF_EN_BASE_64</Base64Data>
               </Document>
            </InputDocuments>
      </SignRequest>
   </soap:Body>
</soap:Envelope>

Uma assinatura bem-sucedida é indicada quando ResultMajor tem o valor …:Success.

Resposta

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
   <s:Header>
      <a:Action s:mustUnderstand="1">urn:evolium:redtrust:dss:ws/RTDSSService/SignRequestResponse</a:Action>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SignResponse RequestID="pades-bes-profile" Profile="pades-bes-profile" xmlns="urn:oasis:names:tc:dss:1.0:core:schema">
         <Result>
            <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
         </Result>
         <SignatureObject>
            <Base64Signature Type="urn:ietf:rfc:3369">PDF_FIRMADO_EN_BASE64</Base64Signature>
         </SignatureObject>
      </SignResponse>
   </s:Body>
</s:Envelope>

Próximos passos​

  • Visão geral
    Aprenda como o serviço DSS é estruturado, quais operações ele expõe e como os diferentes componentes da API se relacionam.

  • Exemplos da API DSS
    Explore exemplos completos de solicitações e respostas para cenários comuns de assinatura, incluindo diferentes tipos e formatos de assinatura.

  • Referência da API DSS
    Consulte definições detalhadas de todos os elementos de solicitação e resposta do DSS, incluindo Profile, KeySelector, SignatureForm e InputDocuments.

  • Métodos DSS
    Revise todas as operações DSS, seu propósito e quando usar cada método.

  • Códigos de resposta de SignRequest da API DSS
    Entenda os possíveis resultados de uma solicitação de assinatura e como interpretar respostas de sucesso e erro.

  • WSDL
    Inspecione a definição do serviço usada pelos clientes SOAP, incluindo as operações disponíveis, bindings e endpoints.

  • Esquemas de serviço da API DSS
    Examine os esquemas XML que definem a estrutura e as regras de validação das solicitações e respostas DSS.

  • Códigos de resposta Result da API DSS
    Aprenda a interpretar ResultMajor, ResultMinor e as informações de status relacionadas retornadas pelo serviço DSS.