Métodos DSS
O serviço de assinatura de documentos do Redtrust cumpre o padrão DSS da OASIS e algumas de suas extensões.
O serviço é composto por três métodos:
1. GetAccessibleCertificates
Este método obtém a lista de certificados disponíveis para o usuário autenticado, com base nas políticas de autorização do Redtrust.
Para chamar este método, você deve se autenticar como o usuário cujos certificados deseja obter. A resposta inclui um objeto Result que contém a lista de certificados acessíveis.
Na resposta, é retornado um objeto Result, com um ResultStatus em estado de sucesso indicando que nenhum erro ocorreu. Também é retornado um ResultMessage com uma mensagem descritiva e um objeto ResultData, que é uma lista de objetos Certificate.
Cada objeto Certificate contém as informações necessárias para seu uso. Por exemplo:
| Parâmetros | Descrição |
|---|---|
needPin | Indica se é necessário um PIN para usar o certificado. |
thumbprint | Identificador usado em SignHash e SignRequest; o campo expiration permite verificar se o certificado expirou. |
alias | Nome atribuído ao certificado na configuração do Redtrust. |
issuer ou subject | Informações extraídas diretamente do certificado para esses campos ou, na ausência delas, a própria impressão digital. |
X509Data | Parte pública do certificado. O conteúdo deste atributo é codificado em Base64 para poder ser incluído na resposta. |
filter | Filtro opcional para a lista de certificados retornada. Permite filtrar por qualquer string incluída no campo subject do certificado. Se for omitido ou estiver vazio, o serviço retorna todos os certificados acessíveis. |
2. SignHash
Este método realiza uma assinatura digital sobre um hash previamente calculado, utilizando o certificado selecionado.
Você deve chamar o método SignHash e fornecer:
- O hash que será assinado
- O tipo de assinatura
- Os dados de identificação do certificado
O serviço gera uma assinatura no formato PKCS#1. Nas seções seguintes, são fornecidos mais detalhes e exemplos.
Os parâmetros de entrada do método são:
| Parâmetros | Descrição |
|---|---|
toSignHash | Hash binário codificado em Base64. |
thumbprint | Impressão digital do certificado. |
certificatePin | PIN do certificado (opcional). |
algorithm | Algoritmo de hash; os valores suportados são RSA_SHA1, RSA_SHA256, RSA_SHA512, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512. |
Na resposta, é retornado um objeto Result com os seguintes campos:
| Campo | Descrição |
|---|---|
ResultStatus | Código de resultado; SUCCESS se a assinatura foi realizada com sucesso. |
ResultMessage | Mensagem que descreve o resultado da operação. |
ResultData | Contém o resultado da operação se a assinatura foi realizada com sucesso (opcional). |
Consulte os códigos de resposta Result deste documento para conhecer os possíveis códigos de erro que podem ser retornados na resposta.
3. SignRequest
Realiza uma operação completa de assinatura de documentos baseada no padrão DSS da OASIS.
Para usar este método, envie um objeto SignRequest válido que cumpra o esquema DSS e suas extensões. A solicitação especifica o perfil de assinatura, o certificado de assinatura e o documento de entrada. O servidor responde com um objeto SignResponse que contém:
- Um código de resposta e uma mensagem
- O resultado da operação de assinatura
Estrutura da solicitação
Os campos a seguir constituem o núcleo da maioria das solicitações de assinatura. Dependendo da configuração do perfil de assinatura, alguns campos podem ser forçados pelo perfil e omitidos da solicitação.
| Campo | Localização | Descrição |
|---|---|---|
Profile | Atributo de SignRequest | Identifica o perfil de assinatura configurado no Redtrust. O perfil pode forçar o modo de assinatura, o nível e outras opções. |
RequestID | Atributo de SignRequest | Identificador retornado na resposta para facilitar a correlação entre solicitações e respostas. |
OptionalInputs | Corpo de SignRequest | Entradas opcionais que influenciam como a assinatura é gerada. |
KeySelector | OptionalInputs | Seleciona o certificado de assinatura (normalmente por meio da impressão digital). |
AdditionalKeyInfo | OptionalInputs | Informações adicionais da chave exigidas pelo certificado, como um PIN. |
SignatureForm | OptionalInputs | Forma de assinatura usada pelo serviço para validar e processar a solicitação. |
| Elemento de modo de assinatura | OptionalInputs | Especifica como a assinatura se relaciona com o documento quando o perfil não a força (por exemplo, enveloped, enveloping ou detached). |
InputDocuments | Corpo de SignRequest | Contêiner do documento ou dos documentos que serão assinados. |
Document | InputDocuments | Documento de entrada. O atributo ID pode ser referenciado por outros elementos da solicitação. |
| Elemento de conteúdo do documento | Document | Fornece o conteúdo do documento (binário ou XML), de acordo com o cenário de assinatura. |
Para ver exemplos completos de solicitações e respostas, consulte Exemplos da API DSS.
Para obter definições detalhadas, valores suportados e restrições de elementos DSS como Profile, SignatureForm e InputDocuments, consulte a referência da API DSS.
Para a estrutura normativa das mensagens DSS, consulte a especificação da OASIS:
Esta página foi útil?