Version: 4.32

DSS API

Visão geral

O Redtrust é um gerenciador de certificados corporativos de autenticação e assinatura que permite seu uso de forma centralizada, segura e controlada.

Aproveitando a centralização de certificados, o Redtrust oferece um serviço de assinatura para assinaturas simples e avançadas, seguindo o padrão DSS (Digital Signature Service) da OASIS (https://www.oasis-open.org/committees/dss/) e algumas de suas extensões.

Este documento destina-se aos integradores que desejam usar o servidor de assinatura DSS do Redtrust.

Métodos

O serviço de assinatura de documentos do Redtrust está em conformidade com o padrão DSS da OASIS e algumas de suas extensões.

O serviço disponibiliza três operações principais:

1. `GetAccessibleCertificates`

Esta operação recupera a lista de certificados disponíveis para o usuário autenticado, com base nas políticas de autorização do Redtrust.

Para chamá-la, autentique-se como o usuário cujos certificados deseja consultar. A resposta inclui um objeto Result com a lista de certificados acessíveis.

2. `SignHash`

Esta operação realiza uma assinatura digital sobre um hash previamente calculado, utilizando o certificado selecionado.

Você deve chamar a operação SignHash e fornecer:

O hash a ser assinado
O tipo de assinatura
Os dados de identificação do certificado

O serviço gera uma assinatura no formato PKCS#1. As seções a seguir fornecem mais detalhes e exemplos.

3. `SignRequest`

Realiza uma operação completa de assinatura de documentos com base no padrão DSS da OASIS.

Para usar esta operação, envie um objeto SignRequest válido, em conformidade com o esquema DSS e suas extensões. Este objeto deve conter todas as informações necessárias para gerar uma assinatura válida.

O servidor responde com um objeto SignResponse contendo:

Um código de resposta e uma mensagem
O resultado do processo de assinatura

Consulte a especificação da OASIS para a estrutura desses objetos:

As seções seguintes explicam os elementos obrigatórios para que você possa construir solicitações válidas e interpretar as respostas.

Autenticação

Você pode enviar solicitações de assinatura para três URLs diferentes, dependendo do tipo de autenticação desejado (considerando o uso de SOAP 1.2). Substitua REDTRUST_ID pelo DNS ou IP do servidor Redtrust.

Usuário e senha

Usa cabeçalhos WS-Security UsernameToken.
Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/basic

Autenticação com certificado

Requer um certificado de cliente TLS.
Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/secure

Autenticação com JWToken

Esse método permite autenticação por meio de um JSON Web Token (JWT) assinado, incluído no cabeçalho SOAP como um BinarySecurityToken.

Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/jwtoken
Exemplo de cabeçalho:

    <soapenv:Envelope
        xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:urn="urn:evolium:redtrust:dss:ws">
    
    <soapenv:Header>
        <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
            urn:evolium:redtrust:dss:ws/RTDSSService/GetAccessibleCertificates
        </wsa:Action>
        <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
            https://localhost:8080/RTDSSService.svc/jwtoken
        </wsa:To>
        <wsse:Security >
        <wsse:BinarySecurityToken
            ValueType="urn:custom:jwt"
            EncodingType="urn:custom:jwt">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoie1widXNlcm5hbWVcIjpcImRldmVsb3BlclwiLFwidXNlcl9pZFwiOjEsXCJkb21haW5cIjpcImxvY2FsLnVzZXJzXCIsXCJyZWZlcmVuY2VcIjpcImE0YjlhYTg1OWQxNTA5YWRjNTE5NDgyM2ExNmFlNDM2YTQ3ZjUwZjI3ZWZjNjU2ODUyMTg5ZWI5NjY4NDBkNGZcIixcImNvbnN1bWVyXCI6XCJEU1NcIn0iLCJuYmYiOjE3NTAwNzc4ODAsImV4cCI6MTc1MDA3ODE4MCwiaWF0IjoxNzUwMDc3ODgwLCJpc3MiOiJSZWR0cnVzdCBBdXRoIEFQSSIsImF1ZCI6IkRTUyJ9.KzNJl0lDEw2rJ7qQZ3dLKMFI9HpugBdGN5j_zRz6_XI</wsse:BinarySecurityToken>
        </wsse:Security>
    </soapenv:Header>
    
    <soapenv:Body>
        <urn:GetAccessibleCertificates/>
    </soapenv:Body>

    </soapenv:Envelope>

O token deve ser gerado por Redtrust.

Transporte e segurança

A API DSS do Redtrust usa SOAP 1.1 ou 1.2 sobre HTTPS para a troca de requisições e respostas.

Requisitos da requisição

Apenas um elemento <SignRequest> pode ser incluído no corpo da mensagem SOAP.
Elementos XML adicionais não são permitidos no corpo.
A codificação deve ser UTF-8.
Cabeçalhos SOAP arbitrários são permitidos.

Formato da resposta

O servidor retorna um elemento <SignResponse> ou uma falha SOAP.
Elementos XML adicionais não são incluídos no corpo.
Em caso de erro de parsing ou de protocolo, uma falha SOAP será retornada.
Caso a solicitação seja processada corretamente, um código de resultado DSS será retornado (mesmo que a assinatura falhe).
A codificação usada é UTF-8.
Cabeçalhos SOAP arbitrários são permitidos.

Protocolos de segurança

A API DSS do Redtrust está em conformidade com os seguintes padrões WS:

WS-Security 1.1
WS-Trust (fevereiro de 2005)
WS-SecureConversation (fevereiro de 2005)
WS-SecurityPolicy 1.1

WSDL

Para baixar o WSDL com a definição completa do serviço, acesse a seguinte URL:

https://REDTRUST_IP:8080/RTDSSService.svc?wsdl

Por padrão, a porta de conexão é 8080, mas isso pode ser configurado no console administrativo do Redtrust. Da mesma forma, o protocolo padrão é HTTPS e o certificado do serviço é gerado automaticamente na instalação, podendo ser alterado via console. Para que o cliente confie no servidor, será necessário importar a parte pública do certificado, a menos que o cliente aceite qualquer certificado.

Em Apêndice 1: WSDLDL você encontrará o código WSDL necessário para gerar o cliente na linguagem desejada.

Optional inputs

Os OptionalInputs contêm informações adicionais associadas ao processamento da solicitação de assinatura.

O serviço Redtrust considera os seguintes OptionalInputs, sendo que alguns deles são definidos como obrigatórios, conforme especificado abaixo:

Uso genérico
`ServicePolicy`	Uso futuro.
`ClaimedIdentity`	Uso futuro.
`Language`	Define o idioma das mensagens descritivas contidas na resposta do serviço (opcional).
`AdditionalProfile`	Uso futuro.
`Schemas`	Uso futuro.

Entrada de assinatura
`SignatureType`	Uso futuro no registro de data e hora.
`AddTimestamp`	Uso futuro no registro de data e hora.
`IntendedAudience`	Uso futuro.
`Properties`	Uso futuro.
`KeySelector`	Indica ao serviço qual certificado deve ser usado para assinar o documento usando a impressão digital do documento (obrigatório).
`AdditionalKeyInfo`	Especifica se o certificado especificado em `KeySelector` requer verificação de PIN (opcional).
`IncludeObject`	Especifica para o serviço que uma assinatura de envelopamento é desejada (opcional).
`IncludeEContent`	Especifica para o serviço que uma assinatura envelopada é desejada, válida para assinaturas CMS e CadES (opcional).
`SignaturePlacement`	Especifica para o serviço que uma assinatura do tipo envelopada é desejada, válida para assinaturas XmlDsig e XadES (opcional).
`SignedReferences`	Uso futuro.
`SignatureForm`	Determina o nível da assinatura a ser feita (opcional).
`VisibleSignatureConfiguration`	Especifica a representação visual da assinatura nas assinaturas do PadES (opcional).

Modos suportados

O Redtrust permite que as assinaturas sejam feitas em diferentes modos. O modo de assinatura informa ao servidor como a assinatura deve ser empacotada em relação ao documento original das seguintes maneiras:

Enveloped: A assinatura é incluída no documento.
Enveloping: O documento está dentro da assinatura.
Detached: A assinatura é um objeto separado.

O campo de modos suportados pode ser especificado na configuração do perfil de assinatura, como um valor fixo ou deixado em aberto, ou passado como um parâmetro no SignRequest. Se um valor for fornecido no SignRequest, ele deverá ser compatível com os valores definidos no perfil de assinatura.

Dependendo do tipo de documento a ser enviado, há suporte para um ou mais modos. Os OptionalInputs no SignRequest fornecido pelo protocolo são usados para indicar o modo na chamada. A maneira de especificar o modo difere de acordo com o tipo de documento:

Tipo de documento	Modo de assinatura suportado	Especificação
XML	Detached	Nenhuma especificação necessária.
	Enveloped	Você deve especificar o campo `SignaturePlacement`. Consulte https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076071 para obter mais informações.
	Enveloping	Você deve especificar o campo `IncludeObject`. Consulte https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076069 para obter mais informações.
CMS	Detached	Nenhuma especificação necessária.
	Enveloping	Você deve especificar o campo `IncludeEContent`. Consulte https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076070 para obter mais informações.
PDF	Enveloped	Nenhuma especificação necessária.

Tanto o SignaturePlacement quanto o IncludeObject devem especificar o atributo WhichDocument, que contém o identificador do documento a ser assinado. Se o documento não for encontrado no SignRequest, o servidor retornará um erro de documento não encontrado.

Resposta

<soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope”  xmlns:xd=”http://www.w3.org/2000/09/xmldsig#”> 
 <soap:Header> 
  … 
 </soap:Header> 
 <soap:Body> 
  <SignRequest Profile=”profile” RequestID=”dss-sign-request-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema”> 
   <OptionalInputs> 
   … 
  <IncludeObject WhichDocument=”ID-document-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema” /> 
   </OptionalInputs> 
   <InputDocuments> 
    <Document ID=”ID-document-1”> 
    … 
    </Document> 
   </InputDocuments> 
  </SignRequest> 
 </soap:Body> 
</soap:Envelope>

Níveis suportados

O Redtrust permite assinaturas em diferentes níveis. O nível de assinatura informa ao servidor quais objetos devem ser incluídos na assinatura. Quanto mais alto o nível, mais informações são incluídas na assinatura, tornando-a mais segura, mas também mais difícil de criar e validar. Os objetos que podem ser incluídos na assinatura são: a política de assinatura, carimbos de data/hora, certificados da cadeia de certificados da assinatura, validação dos certificados incluídos na assinatura.

Há suporte para diferentes níveis, dependendo do tipo de documento a ser enviado:

XML and CMS
Basic	A forma mais básica de assinatura pode ser XMLDsig ou CMS.
BES	Forma básica que atende aos requisitos legais da diretiva para assinatura eletrônica avançada.
EPES	Formulário básico ao qual foram adicionadas informações de política de assinatura.
ES_T	Adiciona um campo de registro de data e hora para proteger contra repúdio.
ES_C	Adiciona referências a dados de verificação (certificados e listas de revogação) a documentos assinados para permitir verificação e validação off-line no futuro (mas não armazena os dados em si).
ES_X	Adiciona registros de data e hora às referências inseridas pelo XadES-C para evitar que uma cadeia de certificados seja comprometida no futuro.
ES_XL	Adiciona certificados e listas de revogação a documentos assinados para permitir verificações futuras, mesmo que as fontes originais (pesquisa de certificados ou listas de revogação) não estejam mais disponíveis.
ES_A	Adiciona a possibilidade de registro periódico de data e hora (por exemplo, a cada ano) para documentos arquivados. Isso evita que os documentos sejam comprometidos devido a assinaturas fracas durante um longo período de armazenamento.

PDF
BES	Formulário básico que atende aos requisitos legais da diretiva para assinatura eletrônica avançada.
EPES	Formulário básico ao qual foram adicionadas informações sobre a política de assinatura.
LTV	Equivalente ao ES_A.

Para indicar o nível na chamada, use um OptionalInput dentro do SignRequest:

<SignatureForm xmlns=”urn:evolium:Redtrust:dss:1.0:core:schema”>XXX</SignatureForm>

The tag value must contain one of the following values:

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:BES

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:EPES

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-T

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-C

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-1

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-2

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-L-1

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-X-L-2

urn:oasis:names:tc:dss:1.0:profiles:XadES:forms:ES-A

urn:oasis:names:tc:dss:1.0:profiles:PadES:forms:LTV

Encapsulation

O Redtrust permite incluir o documento na solicitação de assinatura de diferentes maneiras.

Esse campo deve ser definido no SignRequest dentro do elemento InputDocuments. Atualmente, o Redtrust suporta os elementos Document, mas não suporta os elementos TransformedData e DocumentHash. Para obter mais informações sobre o elemento InputDocuments, consulte https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076032. Para obter mais informações sobre Document, consulte https://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076034.

Os seguintes encapsulamentos são suportados, dependendo do tipo de documento a ser enviado:

XML

Base64Xml: Conteúdo XML em base64. InlineXml: Conteúdo XML diretamente incorporado. EscapedXml: Conteúdo XML escapado.

CMS e PDF

Base64Data: Conteúdo do arquivo codificado em base64. O tipo de documento a ser enviado deve ser especificado usando o atributo MimeType. Os MimeType compatíveis são application/pdf para arquivos PDF e text/plain ou application/binary para CMS.

Resposta

<soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope”  xmlns:xd=”http://www.w3.org/2000/09/xmldsig#”> 

 <soap:Header> 
  … 
 </soap:Header> 
 <soap:Body> 
  <SignRequest Profile=”profile” RequestID=”dss-sign-request-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema”> 
   <OptionalInputs> 
    … 
    <SignaturePlacement WhichDocument=”ID-document-1” xmlns=”urn:oasis:names:tc:dss:1.0:core:schema” /> 
   </OptionalInputs> 
   <InputDocuments> 
    <Document ID=”ID-document-1”> 
     <Base64Data MimeType=”application/pdf”>…</Base64Data> 
    </Document> 
   </InputDocuments> 
  </SignRequest> 
 </soap:Body> 
</soap:Envelope> 

Visão geral​

Métodos​

1. GetAccessibleCertificates​

2. SignHash​

3. SignRequest​

Autenticação​

Usuário e senha​

Autenticação com certificado​

Autenticação com JWToken​

Transporte e segurança​

Requisitos da requisição​

Formato da resposta​

Protocolos de segurança​

WSDL​

Optional inputs​

Modos suportados​

Níveis suportados​

Encapsulation​