Referência da API DSS

Esta página descreve as regras transversais e os campos comuns da API DSS do Redtrust:

• como a autenticação é realizada
• como as mensagens SOAP devem ser estruturadas
• como os modos de assinatura, os níveis e a encapsulação de documentos são expressos

Se você quiser um guia passo a passo, comece pelo tutorial.
Se você quiser payloads prontos para copiar e colar para cenários comuns, use a página de exemplos.

Endpoints e autenticação

O Redtrust expõe três endpoints de serviço (os exemplos a seguir assumem SOAP 1.2):

Usuário e senha

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

Autenticação por certificado

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

Autenticação por JWToken

• Endpoint: https://REDTRUST_IP:8080/RTDSSService.svc/jwtoken
• Você se autentica por meio de um JWT assinado no cabeçalho SOAP como BinarySecurityToken.
• O Redtrust gera o token.

Transporte e restrições de mensagens

A API DSS do Redtrust utiliza SOAP 1.1 ou 1.2 sobre HTTPS para todas as trocas de solicitações e respostas.

Restrições das solicitações

• Inclua apenas um elemento SignRequest no corpo SOAP.
• Não inclua elementos adicionais dentro do corpo SOAP.
• Use codificação UTF-8.
• É possível incluir cabeçalhos SOAP arbitrários.

Restrições das respostas

• O servidor retorna um elemento SignResponse ou um SOAP fault.
• Não aparecem elementos XML adicionais no corpo SOAP.
• Quando o servidor não consegue analisar a solicitação DSS ou encontra um erro SOAP, um SOAP fault é retornado.
• Quando o servidor processa corretamente a solicitação, ele retorna um código de resultado DSS, mesmo que a operação de assinatura falhe.
• É utilizada codificação UTF-8.
• Cabeçalhos SOAP arbitrários podem aparecer.

Protocolos de segurança

A API DSS do Redtrust cumpre 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, você pode acessar a URL do seu servidor da seguinte forma:

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

or padrão, o serviço escuta na porta 8080. Você pode configurar a porta e o certificado HTTPS no console de administração do Redtrust. O seu cliente deve confiar no certificado do serviço, a menos que você o configure para aceitar qualquer certificado.

Consulte WSDL.

Campos comuns de SignRequest

Os trabalhos de assinatura são enviados por meio de SignRequest (corpo SOAP). A solicitação utiliza:

• Profile (o perfil de assinatura configurado no Redtrust)
• RequestID (opcional, mas altamente recomendado para fins de rastreabilidade)
• OptionalInputs (opções comuns como seleção de certificado e forma de assinatura)
• InputDocuments (o documento que você deseja assinar)

Entradas opcionais

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

info

Alguns inputs opcionais definidos pela especificação OASIS DSS não são utilizados atualmente pelo Redtrust. Esses campos são aceitos para compatibilidade com o esquema, mas não têm efeito no processo de assinatura.

Os seguintes inputs não são atualmente suportados:

• ServicePolicy
• ClaimedIdentity
• AdditionalProfile
• Schemas
• SignatureType
• AddTimestamp
• IntendedAudience
• Properties
• SignedReferences

Entrada genérica
Language	Define o idioma das mensagens descritivas contidas na resposta do serviço (opcional).

Entrada de assinatura
KeySelector	Indica ao serviço qual certificado deve ser usado para assinar o documento por meio de sua impressão digital (obrigatório). Este mecanismo é específico da implementação DSS do Redtrust e é usado em todos os perfis de assinatura.
AdditionalKeyInfo	Indica se o certificado especificado em KeySelector requer verificação por PIN (opcional).
IncludeObject	Indica ao serviço que se deseja uma assinatura no modo enveloping (opcional).
IncludeEContent	Indica ao serviço que se deseja uma assinatura no modo enveloped; válido para assinaturas CMS e CAdES (opcional).
SignaturePlacement	Indica ao serviço que se deseja uma assinatura do tipo enveloped; válido para assinaturas XmlDSig e XAdES (opcional).
SignedReferences	Uso futuro.
SignatureForm	Determina o nível da assinatura que será gerada (opcional).
VisibleSignatureConfiguration	Especifica a representação visual da assinatura em assinaturas PAdES (opcional).

A parte de representação visual da assinatura fica dentro da tag VisibleSignatureConfiguration e contém:

Entrada	Descrição
VisibleSignaturePolicy	Contém o texto GeneralPolicy, que é a única política de representação visual suportada pelo Redtrust.
VisibleSignaturePosition	Especifica a posição (contando a partir do canto inferior esquerdo) e o tamanho, em pixels, da visualização.
VisibleSignatureItemsConfiguration	Contém uma sequência de elementos que indicam como será a assinatura visível.

Modos de assinatura suportados

O Redtrust permite realizar assinaturas em diferentes modos. O modo de assinatura indica ao servidor como a assinatura deve ser empacotada em relação ao documento original das seguintes formas:

• Enveloped: a assinatura é incluída dentro do documento.
• Enveloping: o documento é incluído dentro da assinatura.
• Detached: a assinatura é um objeto independente.

O campo de modos compatíveis pode ser especificado na configuração do perfil de assinatura, seja como um valor fixo ou deixando-o em aberto, ou ainda informado como parâmetro no SignRequest. Se você fornecer um valor no SignRequest, ele deve ser compatível com os valores definidos no perfil de assinatura.

Um ou mais modos são suportados dependendo do tipo de documento enviado. Os OptionalInputs do SignRequest definidos pelo protocolo são usados para indicar o modo na chamada. A forma de especificar o modo varia de acordo com o tipo de documento:

Tipo de documento	Modo de assinatura compatível	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 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 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 mais informações.
PDF	Enveloped	Nenhuma especificação é necessária.

Ao usar SignaturePlacement ou IncludeObject, defina WhichDocument com o identificador do documento que você deseja assinar.

Níveis de assinatura suportados

O nível de assinatura indica ao servidor quais objetos devem ser incluídos na assinatura, por exemplo, a política de assinatura, os carimbos de tempo, os certificados da cadeia do certificado de assinatura e a validação dos certificados incluídos na assinatura. Níveis mais altos incluem mais dados e oferecem maior segurança, mas exigem mais processamento.

XML e CMS

Nível	Descrição
Basic	Forma mais básica de assinatura, pode ser XMLDsig ou CMS.
BES	Forma básica que cumpre os requisitos legais da diretiva para assinatura eletrônica avançada.
EPES	Forma básica à qual foi adicionada informação da política de assinatura.
ES_T	Adiciona um campo de carimbo de tempo para proteção contra repúdio.
ES_C	Adiciona referências aos dados de verificação (certificados e listas de revogação) aos documentos assinados para permitir verificação e validação offline no futuro (mas não armazena os dados em si).
ES_X	Adiciona carimbos de tempo às referências introduzidas pelo XAdES-C para evitar que uma cadeia de certificados seja comprometida no futuro.
ES_XL	Adiciona certificados e listas de revogação aos documentos assinados para permitir verificação futura mesmo que as fontes originais (busca de certificados ou listas de revogação) não estejam mais disponíveis.
ES_A	Adiciona a possibilidade de aplicar carimbos de tempo periódicos (por exemplo, anuais) a documentos arquivados. Isso evita que os documentos sejam comprometidos por assinaturas fracas durante um período prolongado de armazenamento.

PDF

Nível	Descrição
BES	Forma básica que cumpre os requisitos legais da diretiva para assinatura eletrônica avançada.
EPES	Forma básica à qual foi adicionada informação da política de assinatura.
LTV	Equivalente a ES_A.

SignatureForm

Para definir um nível, adicione SignatureForm dentro de OptionalInputs e use um dos URNs suportados. Eles devem seguir este formato.

SignatureForm xmlns="urn:evolium:Redtrust:dss:1.0:core:schema">URN</

O valor do URN deve ser um dos seguintes:

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

Encapsulamento de documentos

Você fornece o documento que deseja assinar em InputDocuments dentro do SignRequest. Atualmente, o Redtrust oferece suporte a elementos Document, mas não oferece suporte aos elementos TransformedData nem DocumentHash.

info

Para obter mais informações, consulte as seções InputDocuments e Document da documentação da OASIS.

As seguintes formas de encapsulamento são suportadas de acordo com o tipo de documento enviado:

XML

Base64Xml: conteúdo XML em Base64.
InlineXml: conteúdo XML incorporado diretamente.
EscapedXml: conteúdo XML escapado.

CMS e PDF

Base64Data: conteúdo do arquivo codificado em Base64. Você deve especificar o tipo de documento enviado por meio do atributo MimeType.

Os valores compatíveis de MimeType incluem application/pdf para arquivos PDF e text/plain ou application/binary para CMS.