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.
Contexto
O serviço de assinatura de documentos da Redtrust está em conformidade com o padrão OASIS DSS e algumas extensões dele.
O serviço é composto por três métodos: (1) um método para recuperar certificados a serem usados para assinatura com o serviço DSS (por meio de políticas de autorização da Redtrust), (2) um método para realizar assinaturas usando o padrão DSS e (3) um método para realizar assinaturas de hash.
Para recuperar a lista de certificados acessíveis, é necessário chamar o método GetAccessibleCertificates autenticado como o usuário do qual você deseja recuperar a lista de certificados. Como resposta, você obterá um objeto Result com as informações da solicitação.
Para assinar um hash, você deve chamar o método SignHash, fornecendo o hash a ser assinado, o tipo de assinatura que deseja executar e o tipo de certificado que deseja obter.
Para assinar, é necessário chamar o método SignRequest, para o qual você deve passar um objeto do tipo signRequest como parâmetro. Esse objeto deve ser válido para o esquema OASIS DSS e suas extensões e deve conter todas as informações necessárias para que o serviço gere uma assinatura válida. Para obter informações detalhadas sobre o objeto signRequest, consulte a documentação da OASIS http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076052.
A resposta a uma chamada SignRequest retorna um objeto signResponse, que, assim como o signRequest, deve ser válido de acordo com o esquema DSS da OASIS e deve conter um código de resposta, além de uma mensagem e o resultado do processo de assinatura (dependendo do fato de a assinatura poder ser processada). Para obter informações detalhadas sobre o objeto signResponse, consulte a documentação da OASIS http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html#_Toc159076053.
As seções a seguir explicam o conteúdo desses objetos para que você possa compor uma mensagem válida para o serviço e interpretar a resposta.
Definição do serviço
Para fazer o download do WSDL com a definição completa do serviço, você pode acessar o URL do seu servidor da seguinte forma:
https://REDTRUST_IP:8080/RTDSSService.svc?wsdl
Por padrão, a porta de conexão é 8080, mas essa porta pode ser configurada pela console de administração do Redtrust. Da mesma forma, por padrão, o protocolo é HTTPS e o certificado de serviço é gerado automaticamente no momento da instalação, mas você também pode configurá-lo na console de administração. Ao implementar um cliente que acessa o serviço, você deve levar em conta que precisará da parte pública do certificado de serviço para que o cliente confie no servidor, a menos que o cliente aceite qualquer certificado.
No Apêndice 1: WSDL, você tem o código WSDL necessário para gerar o cliente no idioma desejado.
Transporte e segurança
Na camada de transporte, a troca de solicitação/resposta é feita via SOAP 1.1 ou 1.2. Para a solicitação, aplicam-se as seguintes regras:
- Apenas um elemento
<SignRequest>no corpo da mensagem SOAP. - Nenhum elemento XML adicional pode ser incluído no SOAP.
- A codificação deve ser UTF-8.
- Cabeçalhos SOAP arbitrários podem estar presentes.
Os itens a seguir se aplicam à resposta:
- O servidor retorna um único elemento
<SignResponse>no corpo da mensagem SOAP ou um código de erro SOAP. - O servidor não inclui elementos XML adicionais no corpo do SOAP.
- Se o servidor não puder analisar uma solicitação DSS ou se houver um erro com o SOAP, o servidor retornará um código de erro SOAP. Em qualquer outro caso, um código de resultado DSS será retornado, tanto para assinaturas bem-sucedidas quanto para erros.
- A codificação deve ser UTF-8.
- Cabeçalhos SOAP arbitrários podem estar presentes.
O protocolo está em conformidade com as especificações de segurança WS-Security 1.1, WS-Trust February 2005, WS-SecureConversation February 2005 e WS-SecurityPolicy 1.1.
Há dois links para os quais enviar solicitações de assinatura, dependendo do tipo de autenticação desejada (supondo que você esteja usando SOAP 1.2). Você deve substituir <Redtrust_IP> pelo DNS ou IP do servidor Redtrust.
Senha de usuário → https://<Redtrust_IP>:8080/RTDSSService.svc/basic
Certificado → https://<Redtrust_IP>:8080/RTDSSService.svc/secure
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. | |
| 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.
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.
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. |
| 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>