Manual de Integração - docs.certillion.com · Manual de Integração Certillion Versão: 1.18.1 23/02/2018 Não há limite definido para o tamanho dos arquivos a serem transmitidos

Manual de Integração

Manual de Integração Certillion Versão: 1.18.1 23/02/2018

Sumário 1 Introdução..........................................................................................................................2

1.1 Siglas e acrônimos.....................................................................................................2 1.2 Links úteis...................................................................................................................3 1.3 Tecnologias utilizadas.................................................................................................3

2 Processo de Autenticação.................................................................................................3 3 Processo de Solicitação de Assinaturas............................................................................4

3.1 Identificação do usuário..............................................................................................5 4 Processo de Recebimento de Notificações.......................................................................5 5 Processo de upload e download de arquivos....................................................................6 6 Chaves em HSM................................................................................................................7

6.1 Solicitando assinatura em HSM.................................................................................7 6.2 Tokenização................................................................................................................7 6.3 Gestão do Token.........................................................................................................8 6.4 Assinatura Offline........................................................................................................9 6.5 Restrições...................................................................................................................9

7 Descrição dos métodos do Web Service SOAP................................................................9 7.1 SimpleSignature.........................................................................................................9 7.2 BatchSignature..........................................................................................................11 7.3 SignatureStatusQuery..............................................................................................13 7.4 Validate.....................................................................................................................14 7.5 ValidatePDF..............................................................................................................15 7.6 FindBandwidthInfo....................................................................................................15 7.7 FindUserInfo.............................................................................................................16 7.8 ExecuteTokenCmd....................................................................................................17 7.9 FindSignature...........................................................................................................18 7.10 Códigos de status...................................................................................................18 7.11 Mobile Status..........................................................................................................21

8 Especificações Técnicas..................................................................................................21 8.1 Ambientes Operacionais Suportados.......................................................................21 8.2 Benchmarks..............................................................................................................21

1 Introdução

Este documento tem por objetivo auxiliar os desenvolvedores à realizarem a integração de suas soluções com o Web Service do Certillion Mobile Signature Server (MSS). Este Web Service possui os serviços necessários para que o Integrador possa realizar uma solicitação de assinatura a um cliente de forma prática e segura.

1.1 Siglas e acrônimos

A fim de facilitar o entendimento deste documento, utilizaremos as seguintes terminologias:

• WS – Web Service (solução para integração de sistemas)

Certillion® 2014 Página 2 / 23


• MSS – Mobile Signature Server (servidor que fornece as funcionalidades de assinatura digital)

• WSDL – Web Service Description Language (documento que descreve os métodos de um Web Service)

• SOAP – Simple Object Access Protocol (protocolo de comunicação com Web Services)

• HSM – Hardware Security Module (dispositivo que guarda e administra chaves digitais)

• Integrador – Empresa que integra uma de suas aplicações ao Certillion

1.2 Links úteis

• https://api.certillion.com/mss/SignatureService/SignatureEndpointBeanV2?wsdl WSDL do serviço de assinatura disponibilizado pelo servidor do Certillion na nuvem.

• https://docs.certillion.com/certillion-signature-receiver.xml Modelo do WSDL do serviço de recebimento de notificações, a ser implementado pelo Integrador, caso queira utilizar essa funcionalidade.

• https://github.com/certillion/certillion-ap-samples Projeto de exemplo em Java, que utiliza o Web Service do Certillion na nuvem.

• https://download.certillion.com/ws-signer Ferramenta auxiliar que atua como proxy assinador de requisições.

1.3 Tecnologias utilizadas

• WSDL versão 1.1 Versão da especificação do padrão WSDL usada nos web services providos e consumidos pelo MSS.

• SOAP versão 1.1 Versão da especificação do padrão SOAP usada nos web services providos e consumidos pelo MSS.

• SOAP Binding RPCSOAP Binding Style usado para que os métodos do WS possam ser chamados remotamente.

2 Processo de Autenticação

O processo de autenticação de um Integrador frente ao MSS é realizado com um certificado digital ICP-Brasil de equipamento, emitido em nome de uma pessoa jurídica (no caso, o próprio Integrador). O certificado é utilizado para assinar todas as requisições SOAP utilizando o padrão WS-Security X.509 Certificate Token Profile.

Para facilitar a implementação da assinatura das requisições, é disponibilizado um proxy de assinaturas, chamado WS-Signer. Esse software recebe as requisições SOAP da aplicação do Integrador, assina-as utilizando o certificado ICP-Brasil de equipamento configurado e repassa as requisições para o MSS. O link para download encontra-se na seção 3.

Ressaltamos que apenas certificados ICP-Brasil são aceitos pela aplicação.


https://api.certillion.com/mss/SignatureService/SignatureEndpointBean?wsdl

https://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdf

https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383532

https://www.w3.org/TR/2001/NOTE-wsdl-20010315

https://download.certillion.com/ws-signer

https://github.com/certillion/certillion-ap-samples

https://docs.certillion.com/certillion-signature-receiver.xml


3 Processo de Solicitação de Assinaturas

Todas as transações no MSS são processadas de modo assíncrono. O Integrador realiza uma requisição de assinatura ao MSS, que inicia uma transação para que o Integrador possa acompanhar o andamento dessa requisição. O Integrador pode consultar o status da transação de dois modos: cliente-servidor ou servidor-servidor. Nessa seção explicaremos apenas o modo cliente-servidor, o modo servidor-servidor será explicado na seção 5.

No modo cliente-servidor, o Integrador realiza, periodicamente, uma nova requisição para consultar o status da transação. Quando a transação estiver concluída, a resposta conterá o resultadoda assinatura. Veja o diagrama abaixo:

Toda comunicação entre a Aplicação do Integrador e o servidor Certillion é feita via rede. No caso da comunicação entre o servidor Certillion e o aplicativo Certillion no dispositivo do usuário, a comunicação pode se dar por rede local, ou via Internet por wi-fi ou plano de dados.

Existem dois métodos principais para solicitar assinatura, são eles:

• SimpleSignature: Usado para solicitar assinatura de um documento de texto simples. O conteúdo a ser assinado é passado na própria requisição. Esse método é ideal para implementar fluxos de login ou autorização. Suporta apenas o padrão CAdES. Permite visualização nativa do conteúdo a ser assinado (isto é, sem a necessidade de instalação de aplicativos externos) em todas as plataformas clientes.

• BatchSignature: Usado para assinar um lote de documentos (um ou mais). Desta forma, o usuário pode assinar todos os documentos em um único passo, digitando sua senha uma única vez. É necessário fazer upload dos arquivos a serem assinados previamente. Esse método é ideal para assinar grandes documentos nos formatos PDF (simples e PAdES), XML, DOC, entre outros. Como regra geral, os padrões aceitos podem ser utilizados da seguinte forma:

◦ CAdES: suporta assinatura de qualquer tipo de arquivo. O arquivo será considerado como uma sequência de bytes e o padrão não interpreta seu conteúdo. A assinatura pode ser um arquivo separado (também conhecido como detached, em geral, de extensão .p7s) ou pode encapsular o arquivo original (também chamado de attached, em geral, de extensão .p7m)



◦ PAdES: suporta assinatura apenas de arquivos pdf válidos. A vantagem com relação ao padrão CAdES é que suporta assinatura visível e o Acrobat Reader, seu visualizador padrão, tem suporte embutido para verificação e visualização da assinatura.

◦ XAdES: suporta assinatura apenas de aquivos XML. Suporta assinatura visível.

◦ XML-DSig: suporta assinatura apenas de arquivos XML. Formato utilizado no padrão brasileiro NF-e, de notas fiscais eletrônicas (versão enveloped)

• SignatureStatusQuery: Usado para consultar o status de uma transação de assinatura, tanto texto simples quanto lote de documentos. A resposta contém: um código de status geral da transação; um código de status para a assinatura de cada documento; a assinatura de cada documento em formato PKCS#7/CMS e codificada em Base64; dados do certificado usado para assinar. Uma assinatura de texto simples é exibida como um lote com um único documento. Em caso de status de erro, os outros campos não são retornados.

3.1 Identificação do usuário

Existem 2 formas de identificar o usuário no envio da solicitação de assinatura:

• e-mail: identifica o dispositivo (smartphone, tablet ou computador) onde o certificado digital foi instalado. Um mesmo email está sempre vinculado exclusivamente um único dispositivo; caso seja registrado em outro dispositivo ele é desvinculado do anterior e apenaso mais recente recebe solicitações.

• CPF/CNPJ: identifica a pessoa ou organização que se deseja a assinatura, independente dequal(is) dispositivo(s) ela instalou seu certificado. Esta informação é extraída automaticamente do próprio certificado digital. Ao enviar uma solicitação para um CPJ/CNPJ todos os dispositivos onde o certificado digital estiver instalado serão notificados.

4 Processo de Recebimento de Notificações

No modo servidor-servidor para troca de mensagens, o MSS notificará o seu Web Service quando a transação for concluída. Para isso, o Integrador deverá fornecer um SOAP Web Service que implemente o WSDL de recebimento de notificações descrito na seção 3. Esse modo é recomendado para aqueles que esperam uma carga de centenas ou milhares de requisições por segundo.

O processo para solicitar a assinatura, inicia-se igual ao descrito na seção 4, porém não é necessário consultar periodicamente o status da transação. Veja o diagrama abaixo:


https://tools.ietf.org/pdf/rfc2315.pdf


Há dois métodos no Web Service do Integrador que o MSS pode chamar:

• SignatureNotification: Para notificar a conclusão de uma transação de assinatura de texto simples.

• BatchSignatureNotification: Para notificar a conclusão de uma transação de assinatura de lote de documentos.

5 Processo de upload e download de arquivos

Para solicitar a assinatura de um lote de documentos, deve-se, primeiramente, fazer upload de todos os arquivos que compõem o lote. O envio do arquivo para o servidor é necessário para:

• permitir que o Certillion se encarregue da montagem do padrão de assinatura em uma API de alto nível;

• permitir que o usuário visualize o documento a ser assinado, se possuir o aplicativo correspondente de visualização do arquivo, se assim desejar.

O MSS retornará um identificador para cada documento. O Integrador deverá utilizar esse identificador na solicitação de assinatura. Desse modo, é possível enviar o arquivo apenas uma vez, e solicitar que ele seja assinado várias vezes.

Quando a transação é concluída com sucesso, a resposta que o Integrador recebe contém a assinatura de cada documento do lote em formato detached (somente a assinatura). Para alguns tipos de documentos, como PDF e XML, é comum trabalhar com o formato attached (documento completo com a assinatura embutida). O Integrador pode fazer a operação de attach em seu próprio sistema ou realizar o download do arquivo assinado pelo MSS. Em ambos os casos, o Certillion garante a validade da assinatura digital, através dos procedimentos padrões da ICP-Brasil DocICP-15, e do certificado digital, através de consulta OCSP ou X.509 CRL V2.

Tanto o upload quanto o download são feitos através de simples requisições HTTP, explicadas abaixo:

• POST /applicationProvider/document: Usada para enviar arquivos a serem assinados. O MSS retornará um identificador do arquivo.

• GET /applicationProvider/document/signed/{transactionId}: Usada para fazer download da assinatura em formato attached.



Não há limite definido para o tamanho dos arquivos a serem transmitidos. Em ambiente de teste, arquivos de 160 MB (megabytes) de tamanho foram assinados com sucesso. Os principais limitadores do tamanho do arquivo são as configurações de memória e espaço em disco alocado para o servidor MSS.

6 Chaves em HSM

Além de trabalhar com chaves locais (armazenadas no próprio dispositivo do usuário), desdea versão 1.11 o Certillion suporta que a chave do usuário final possa também estar armazenada em HSM, conectado diretamente a um servidor MSS, permitindo que aplicativos móveis Android e iOSfaçam assinatura com certificados A3. Quando a chave e certificado do usuário foram emitidos em HSM, o papel do app Certillion no dispositivo do usuário muda, passando a ser um segundo fator deautenticação e não mais o local onde a assinatura digital é realizada. Esta sessão trata dos conceitos principais envolvendo este recurso.

6.1 Solicitando assinatura em HSM

O Certillion precisa ser informado na solicitação da assinatura se a chave do usuário se encontra no HSM configurado para o servidor MSS ao qual se encaminha a solicitação de assinatura. Para isso, em CertificateFilters utilize o parâmetro HsmCertificate com o valortrue, tal como especificado nas sessões 7.1 e 7.3, por exemplo:

<CertificateFilters><HsmCertificate value="true"></HsmCertificate>

</CertificateFilters>

6.2 Tokenização

Quando a chave do usuário se encontra em HSM é possível estabelecer uma sessão de assinatura onde a senha do usuário é digitata apenas uma vez, na autorização da sessão, e as solicitações seguintes não precisarão ser autorizadas enquanto a sessão estiver válida.

Para informar ao servidor MSS do Certillion para abrir uma sessão de tokenização, acrescente, em conjunto com o parâmetro HsmCertificate , o parâmetro Fingerprint, tal como especificado nas sessões 7.1 e 7.3, por exemplo:

<Fingerprint>AUTH</Fingerprint><CertificateFilters>

<HsmCertificate value="true"></HsmCertificate></CertificateFilters>

Adicionando qualquer valor em Fingerprint, a sessão é forçada com os valores default configurados no servidor MSS. É possíve alterar o comportamento da sessão de tokenização com osseguintes atributos:

• UseToken – Informa se o Certillion deve fazer uso de tokenização de sessão do HSM ou não. Quando recebe o valor ‘true’ indica ao Certillion que deve fazer uso de tokenização. Quando recebe o valor ‘false’ significa que deve solicitar o PIN de autenticação no HSM para cada transação. Caso não seja informado, segue o valor padrão ‘false’.

• TokenValidity – Indica o período de validade em horas do Token da sessão do HSM a ser emitido. Caso não seja informado, segue o valor padrão cadastrado para o CNPJ do AP



solicitante. Esse campo só será considerado caso o campo ‘UseToken’ seja informado com valor ‘true’.

• InvalidateToken – Informa se o Certillion deve invalidar um Token de sessão HSM previamente emitido. Quando recebe o valor ‘true’ indica que o token existente deve ser invalidado imediatamente. Quando recebe o valor ‘false’ não altera a situação de validade do token existente. Caso não seja informado, segue o valor padrão ‘false’. Esse campo só será considerado caso o campo ‘UseToken’ seja informado com valor ‘true’.

• OtpValue – Informa o valor da senha OTP (One Time Password) que deve ser utilizada como segundo fator de autenticação (ver sessão 6.4). Caso seja informada, o Certillion usaráessa informação para se autenticar no HSM. Caso não seja informada, o Certillion terá 2 comportamentos possíveis:

◦ Se o campo ‘UseToken’ estiver com valor ‘true’, o Certillion verifica se existe um Token de sessão HSM válido. Se existir, não considera o valor do campo ‘OtpValue’ para efetuar autenticação no HSM. Se não existir Token de sessão HSM válido, utiliza o valor do campo ‘OtpValue’ para se autenticar no HSM e gerar um Token de sessão válido.

◦ Se o campo ‘UseToken’ estiver com valor ‘false’, sempre utiliza o valor do campo ‘OtpValue’ para se autenticar no HSM e executar a operação solicitada.

A String do campo FingerPrint deve estar no seguinte formato:

[NOME_CAMPO_1]=[VALOR_CAMPO_1];NOME_CAMPO_2]=[VALOR_CAMPO_2];...[NOME_CAMPO_N]=[VALOR_CAMPO_N]

Exemplo: “UseToken=true;TokenValidity=24”

Obs: Nenhum dos campos descritos acima é obrigatório. Caso os campos sejam omitidos o Certillion irá assumir valor padrão.

6.3 Gestão do Token

Desde a versão 1.17.2, o MSS permite a gestão do token - criação, consulta de status e regovação - independente da solicitação de assinatura, através da chamada ExecuteTokenCmd.

Os parâmetros de ExecuteTokenCmd seguem a mesma sintaxe do campo FingerPrint:

• OperationType: Valores possíveis: TOKEN_STATUS, INVALIDATE_TOKEN, GENERATE_TOKEN

• OtpValue (Opcional): Só é considerado para o tipo GENERATE_TOKEN. Se presente usa o valor para gerar a tokenização; Se ausente, chama o celular para assinar o token;

• TokenValidity (Opcional): Só é considerado para o tipo GENERATE_TOKEN. Se presente usa o valor para definir o número de horas de validade de tokenização; Se ausente, usa o valor default cadastrado para o AP;

Retornos:

• Se erro, lança exceção com a mensagem de erro;

• Se OK,

◦ Para o tipo GENERATE_TOKEN, retorna mensagem de sucesso: Token gerado com sucesso



◦ Para o tipo INVALIDATE_TOKEN, retorna mensagem de sucesso: Token invalidado com sucesso

◦ Para o tipo TOKEN_STATUS, retorna seguinte sintaxe:

▪ Status=INVALID

▪ Status=VALID; ExpirationDate=dd/MM/yyyy HH:mm:ss

6.4 Assinatura Offline

Outra possiblidade quando a chave do usuário se encontra no HSM são as assinaturas offline. Assinaturas offline são aprovadas pelo usuário final sem ter um dispositivo Certillion conectado à rede, mas sim um dispositivo OTP (One Time Password). Estes dispositivos alteram a senha após um período curto programado (por exemplo, 30 ou 60 segundos) e cada senha só pode ser utilizada apenas uma vez.

A principal diferença da senha OTP da senha do Certillion é que no caso da OTP o sistema tem que solicitar a senha diretamente para o usuário e informá-la para o Certillion através da API. Para informar ao Certillion a senha OTP, utilize o atributo OtpValue do campo Fingerprint(ver sessão 6.2).

Nota: no momento, apenas OTP via hardware é suportado.

6.5 Restrições

Como a assinatura é feita no HSM, nem os documentos nem a mensagem da solicitação é vista no dispositivo. O usuário enxerga apenas um código no celular, que deve ser exibido pelo sistema que solicitou a assinatura, para que o usuário possa verificar. Este código é retornado pelo parâmetro VerificationCode, nas respostas de SimpleSignatureRespTypeV3 e BatchSignatureRespTypeV2.

7 Descrição dos métodos do Web Service SOAP

Esta seção descreve os métodos disponibilizados pelo Web Service do MSS.

7.1 SimpleSignature

Descrição Realiza a solicitação de assinatura de um texto simples a um usuário cadastrado no MSS.

Requisição

SimpleSignatureReqTypeV4

Descrição Requisição com informações sobre o conteúdo a ser assinado e o usuário a quem a mensagem será enviada.

Campos

User

Obrigatório Sim

Descrição Identificador do destinatário.

Valores Válidos Endereço de e-mail, CPF ou CNPJ.

DataToBeSigned



Obrigatório Sim

Descrição Texto a ser assinado.

Valores Válidos Texto simples, sem formatação.

ApId

Obrigatório Não

Descrição Identificador da aplicação. Utilizado quando existe mais de uma aplicação cadastrada para uma mesma empresa.

Valores Válidos ID previamente fornecido pelo Certillion.

TimeOut

Obrigatório Não

Descrição Tempo de expiração da mensagem, em minutos.

Valores Válidos Número inteiro positivo.

MessagingMode

Obrigatório Sim

Descrição Modelo de troca de mensagens.

Valores Válidos asynchClientServer ou asynchServerServer.

Fingerprint

Obrigatório Não

Descrição Autenticação para usuários que utilizam certificado em um HSM.

Valores Válidos Veja seção 6.2

CertificateFilters

Obrigatório Não

Descrição Especifica tipos de certificados aceitos nesta transação.

Valores Válidos TrustChain (ICPBR, JUS ou RFB), Owner (PERSON ou COMPANY), Algorithm (RSA ou ECC), ForceHardware (true ou false) ou HsmCertificate (true ou false).

AdditionalServices

Obrigatório Não

Descrição Serviços adicionais usados nessa transação.

Valores Válidos aetDriver ou kaspersky

SignatureStandardType

Obrigatório Não

Descrição Padrão de assinatura a ser utilizado.

Valores Válidos cades ou raw (com suporte a pkcs#1)

SignaturePolicy

Obrigatório Não

Descrição Política de assinatura a ser utilizada.

Valores Válidos AD_RB, AD_RT, AD_RC, AD_RV ou AD_RA

Resposta

SimpleSignatureRespTypeV4



Descrição Resposta com o ID e status da transação de assinatura.

Campos

Status

Obrigatório Sim

Descrição Código de sucesso ou erro da requisição.

Valores Válidos Veja seção 7.11.

TransactionId

Obrigatório Sim

Descrição ID da transação de assinatura.


VerificationCode

Obrigatório Não

Descrição Código que será exibido ao usuário para validar a operação.

Valores Válidos Código numérico de 6 dígitos.

7.2 BatchSignature

Descrição Realiza a solicitação de assinatura de um lote de documentos a um usuário cadastrado no MSS.

Requisição

BatchSignatureReqTypeV2


Campos

User

Obrigatório Sim



DataToBeDisplayed

Obrigatório Sim

Descrição Texto a ser exibido na tela do usuário.

Valores Válidos Texto simples, sem formatação.

DocumentsToBeSigned

Obrigatório Sim

Descrição Informações sobre os documentos a serem assinados, tais como: tipo de arquivo, nome do arquivo e código hash.

Valores Válidos Código hash retornado no upload do arquivo.

ApId

Obrigatório Não





TimeOut

Obrigatório Não

Descrição Tempo de expiração da mensagem, em segundos.


MessagingMode

Obrigatório Sim

Descrição Modelo de troca de mensagens.

Valores Válidos asynchClientServer ou asynchServerServer.

CertificateFilters

Obrigatório Não



AdditionalServices

Obrigatório Não



SignatureStandardType

Obrigatório Não


Valores Válidos pades. cades, adobepdf, xades, xmldsig_enveloped ou xmldsig_enveloping

SignaturePolicy

Obrigatório Não



Fingerprint

Obrigatório Não


Valores Válidos Veja seção 6.2 Tokenização

SignatureStandard

Obrigatório Não

Descrição Especifica valores necessários para assinatura visível (PADES) eXMLDSIG.

Valores Válidos --XMLDSIG-- - ElementsId (String) - AttributeIdName (String) - ElementsName (String) - AddSubjectName (true ou false) - AddKeyVal (true ou false)



- MultipleSignatures (true ou false) - DigestMethod (SHA1, SHA256 e SHA512) - RemoveSignatureId (true ou false)

--ADOBEPDF/PADES-- - TextOfPadesSignature (Texto a ser exibido) - PageOfPadesSignature (Página onde a assinatura vai estar localizada) - PosXOfPadesSignature (Coordenada x para assinatura visível) - PosYOfPadesSignature (Coordenada y para assinatura visível) - HeightOfPadesSignature (Altura do campo visível) - WidthOfPadesSignature (Largura do campo visível) - FontSizeOfPadesSignature (Tamanho da fonte) - ZoomOfPadesSignature (Aumenta ou diminui o tamanho detodos os elementos do campo visivel de forma proporcional; 50= 150%; -30 = 70%; 0 = 100%)

Resposta

BatchSignatureRespTypeV2

Descrição Resposta com o ID e status da transação de assinatura.

Campos

Status

Obrigatório Sim



TransactionId

Obrigatório Sim



Signatures

Obrigatório Não

Descrição Assinatura em formato detached, presente apenas quando a transação é finalizada com sucesso.

Valores Válidos Lista de objetos com strings em Base64.

VerificationCode

Obrigatório Não

Descrição Código que será exibido ao usuário para validar a operação.

Valores Válidos Código numérico de 6 dígitos.

7.3 HSMSyncSignature

Descrição Variação do BatchSignature para assinaturas executadas exclusivamente com chaves em HSM e comresposta síncrona, ou seja, na response já vem o resultado da assinatura (response de SignatureStatusQuery). Possui menor tempo de resposta que o BatchSignature e seu uso é recomendado sempre que a chave estiver em HSM. Nota: o BatchSignature continua funcionando para qualquer situação da chave, em HSM ou tradicional (arquivo ou token).



Requisição

HsmSyncSignature


Campos

User

Obrigatório Sim



DocumentsToBeSigned

Obrigatório Sim

Descrição Informações sobre os documentos a serem assinados, tais como: tipo de arquivo, nome do arquivo e código hash.

Valores Válidos Código hash retornado no upload do arquivo.

ApId

Obrigatório Não



CertificateFilters

Obrigatório Não



AdditionalServices

Obrigatório Não



SignatureStandard

Obrigatório Não


Valores Válidos pades. cades, adobepdf, xades, xmldsig_enveloped ou xmldsig_enveloping

SignaturePolicy

Obrigatório Não



Fingerprint

Obrigatório Não




Valores Válidos Veja seção 6.2 Tokenização

SignatureStandardOptions

Obrigatório Não

Descrição Especifica valores necessários para assinatura visível PADES ou XMLDSIG.

Valores Válidos --XMLDSIG-- - ElementsId (String) - AttributeIdName (String) - ElementsName (String) - AddSubjectName (true ou false) - AddKeyVal (true ou false) - MultipleSignatures (true ou false) - DigestMethod (SHA1, SHA256 e SHA512) - RemoveSignatureId (true ou false)

--ADOBEPDF/PADES-- - TextOfPadesSignature (Texto a ser exibido) - PageOfPadesSignature (Página onde a assinatura vai estar localizada) - PosXOfPadesSignature (Coordenada x para assinatura visível) - PosYOfPadesSignature (Coordenada y para assinatura visível) - HeightOfPadesSignature (Altura do campo visível) - WidthOfPadesSignature (Largura do campo visível) - FontSizeOfPadesSignature (Tamanho da fonte) - ZoomOfPadesSignature (Aumenta ou diminui o tamanho detodos os elementos do campo visivel de forma proporcional; 50= 150%; -30 = 70%; 0 = 100%)

Resposta

HsmSyncSignatureResp

Descrição Resposta com o resultado da assinatura de cada documento.

Campos

Status

Obrigatório Sim



7.4 SignatureStatusQuery

Descrição Consulta o status de uma transação de assinatura, tanto texto simples quanto lote de documentos.

Requisição

SignatureStatusReqType

Descrição Requisição com ID da transação a ser consultada.

Campos

TransactionId



Obrigatório Sim


Valores Válidos Número de uma transação existente.

Resposta

StatusRespType

Descrição Resposta com o resultado da assinatura de cada documento.

Campos

Status

Obrigatório Sim



7.5 Validate

Descrição Valida uma assinatura CAdES feita por outro sistema (as assinaturas retornadas pelo Certillion sempre são válidas). A validação é completa, aderente às especificações dos padrões ICP-Brasil e PKIX, abrangendo automaticamente, dentre outras, a cadeia de certificação, listas de certificados revogados (LCR ou CRL) ou protoloco on-line de estado de certificado (OCSP).

Requisição

ValidateReqType

Descrição Requisição com a assinatura a ser validada.

Campos

Content

Obrigatório Não

Descrição Conteúdo que foi assinado.

Valores Válidos String em Base64.

Signature

Obrigatório Sim

Descrição


Resposta

ValidateRespType

Descrição Resposta com o resultado da validação.

Campos

Signatures

Obrigatório Não

Descrição Informações detalhadas de todas as assinaturas do documento. Presente apenas se a assinatura for válida.

Valores Válidos N/A

Error



Obrigatório Não

Descrição Explicação do porquê de a assinatura não ser válida.

Valores Válidos TRANSPORT_ERROR, ENCODING_ERROR, INCOMPLETE_CERTIFICATE_CHAIN_ERROR, INVALID_CERTIFICATE_CHAIN_ERROR, UNSUPORTED_ALGORITHM_ERROR, SIGNING_POLICY_VERIFICATION_ERROR, CRYPTOGRAPHIC_ERROR ou UNEXPECTED_ERROR

7.6 ValidatePDF

Descrição Valida uma assinatura PADES feita por outro sistema (as assinaturas retornadas pelo Certillion sempre são válidas).

Requisição

ValidatePdfReqType

Descrição Requisição com a assinatura a ser validada.

Campos

Signature

Obrigatório Sim

Descrição Conteúdo que foi assinado.


Resposta

ValidateRespType

Descrição Resposta com o resultado da validação.

Campos

Signatures

Obrigatório Não

Descrição Informações detalhadas de todas as assinaturas do documento. Presente apenas se a assinatura for válida.

Valores Válidos N/A

Error

Obrigatório Não

Descrição Explicação do porquê de a assinatura não ser válida.

Valores Válidos TRANSPORT_ERROR, ENCODING_ERROR, INCOMPLETE_CERTIFICATE_CHAIN_ERROR, INVALID_CERTIFICATE_CHAIN_ERROR, UNSUPORTED_ALGORITHM_ERROR, SIGNING_POLICY_VERIFICATION_ERROR, CRYPTOGRAPHIC_ERROR ou UNEXPECTED_ERROR

7.7 FindBandwidthInfo

Descrição Consulta consumo de tráfego do Integrador, conforme seu pacote de dados.



Resposta

BandwidthInfoType

Descrição Resposta com o limite de dados mensais e a quantidade consumida.

Campos

TotalBandwidth

Obrigatório Sim

Descrição Limite total de banda contratada, em bytes.


UsedBandwidth

Obrigatório Sim

Descrição Volume de banda utilizada, em bytes.


DateToRenew

Obrigatório Sim

Descrição Data em que a banda utilizada será zerada.

Valores Válidos Valores do tipo DateTime.

7.8 FindUserInfo

Descrição Fornece informações sobre uma conta, utilizando como identificador o email, cpf ou cnpj

Requisição

FindUserInfoReq

Descrição Solicitação de informações do usuário

Campos

User

Obrigatório Sim

Descrição Identificador do usuário

Valores Válidos e-mail, cpf ou cnpj

Resposta

FindUserInfoResp

Descrição Resposta com o status do usuário e os dispositivos que ele possui certificado.

Campos

Users/Status

Obrigatório Sim

Descrição Status do usuário: se possui dispositivo cadastrado ou não. Se o usuário não existir é retornada uma exceção.

Valores Válidos USER_ACTIVE, USER_NO_DEVICE.

Users/Device/Status



Obrigatório Não

Descrição Status do dispositivo (se existir): se o dispositivo possui certificado cadastrado ou não.

Valores Válidos DEVICE_READY, DEVICE_NO_CERTIFICATE.

Users/Device/Email

Obrigatório Não

Descrição Email identificador do dispositivo (se device existir).

Valores Válidos Email identificador do dispositivo.

Users/Device/Certificates

Obrigatório Não

Descrição Certificados existentes no dispositivo (se existir)

Valores Válidos Lista dos dados dos certificados existentes no dispositivo: número serial, emissor e tipo de hardware (A1, A3 ou HSM).

7.9 ExecuteTokenCmd

Descrição Permite o gerenciamento da tokenização (criação, consulta de status e revogação), possível quando ousuário possui chave em HSM

Requisição

TokenCmdReq

Descrição Solicitação de execução de comando de tokenização

Campos

ApId

Obrigatório Não



User

Obrigatório Sim

Descrição Identificador do usuário

Valores Válidos e-mail, cpf ou cnpj

Command

Obrigatório Sim

Descrição Comando(s) de tokenização

Valores Válidos OperationType (TOKEN_STATUS, INVALIDATE_TOKEN, GENERATE_TOKEN), OtpValue, TokenValidity.(ver sessão 6.3 Gestão do Token)

Resposta

TokenCmdResp

Descrição Resposta da execução do comando de tokenização

Campos



Status

Obrigatório Sim

Descrição Status da execução do comando solicitado: criação do token, consulta de status, revogação do token.

Valores Válidos OK ou ERROR.

Value

Obrigatório Sim

Descrição Mensagem de descrição do resultado da execução do comando de tokenização.

Valores Válidos "Token gerado com sucesso", "Token invalidado com sucesso",Status=INVALID, Status=VALID;ExpirationDate, (ver sessão 6.3 Gestão do Token)

7.10 FindSignature

Este método está depreciado e não deve ser utilizado. Em vez desse, utilize SignatureStatusQuery.

7.11 Códigos de status

NOME CÓDIGO DESCRIÇÃO

REQUEST_OK 100 Request accepted by the receiver.

TRANSACTION_IN_PROGRESS 110 The message has been received and still being processed.

REGISTRATION_VALID 120 You are registered in the system.

CERTIFICATE_VALID 130 The certificate is valid.

CSR_VALID 131 The CSR is valid.

REVOCATION_ACCEPTED 132 The certificate is marked as revoked, then enduser will be informed.

SIGNATURE_VALID 140 The signature is valid.

USER_ACTIVE 150 User account ready for signature.

DEVICE_READY 151 Device ready for signature.

REQUEST_MISSING_PARAM 200 An argument in the request is missing: %S

REQUEST_WRONG_PARAM 201 Error among the arguments of the request.

REQUEST_WRONG_LENGTH 202 The message is too large or one of it's arguments has the wrong length.

REQUEST_BAD_FORMAT 203 Cannot handle given MIME-Type or encoding style.

REQUEST_BAD_PROFILE 204 The AP requested a key type, key usage or signing policy that the MSS does not support.

REQUEST_BAD_DATA 205 The enduser's mobile equipment cannot handle this kind of data.

REQUEST_DUPLICATED 206 The request or it's parameters are duplicated.



ACCOUNT_NO_BANDWIDTH 210 Insufficient bandwidth left to realize the transaction.

ACCOUNT_MAX_TRIES 211 Maximum number of tries exceeded.

ACCOUNT_NO_CREDIT 212 The user must pay for the certificate usage, but he's out of credit.

ACCESS_NOT_AUTHORIZED 220 The AP is unknown or the authentication is wrong.

ACCESS_NO_HANDSHAKE 221 The MSS wants prior to negotiate with the AP the use of XML signatures in the messages.

ACCESS_NO_SPECIFIED 222 The authentication mechanism was not specified.

TRANSACTION_NOT_AUTHORIZED 223 The transaction was not authorized. The specific reason is informed in details.

NETWORK_ERROR 300 The MSS could not contact the enduser's mobile equipment.

TRANSACTION_NOT_FOUND 310 This transaction is unknown.

IDENTIFIER_NOT_FOUND 311 This enduser is unknown.

SERVICE_NOT_FOUND 312 This additional service is unknown.

MOBILE_SIGNATURE_ERROR 320 Error during the signature process on the Mobile equipment.

MOBILE_CERTIFICATE_ERROR 321 Error during the certificate generation on the mobile equipment.

USER_CANCELED 400 The client has cancelled the transaction.

MESSAGE_BAD_INTEGRITY 410 The integrity check failed.

MESSAGE_BAD_AUTHENTICATION 411 The authentication failed.

MESSAGE_BAD_ENCRYPTION 412 The decryption of the message failed.

MESSAGE_BAD_ENCODING 413 The message could not be decoded.

MESSAGE_EXPIRED 414 The message has expired.

MESSAGE_WRONG_VERSION 420 The version of the message is inappropriate for the receiver.

MESSAGE_MISSING_KEY 421 The receiver was expecting a symmetric key.

MESSAGE_UNEXPECTED_KEY 422 The receiver was not expecting a symmetric key.

MESSAGE_UNEXPECTED 423 This message is not suppose to be received at this time.

KEY_EXPIRED 424 The authentication key is expired.

KEY_REJECTED 425 The new key is not acceptable.

MESSAGE_NOT_FOUND 430 This message doesn't exist on the mobile equipment or has beendeleted.

USER_NOT_FOUND 431 There's no mobile user with this ID.

INTERNAL_ERROR 440 Internal Error.

SERVICE_CANT_ACTIVATE 450 This additional service cannot be activated to this mobile or thiscompany.

SERVICE_CANT_USE 451 This additional service is not allowed or not supported.

SERVICE_WAS_ACTIVATED 452 This additional service was already activated.

PLATFORM_NOT_FOUND 500 This platform is unknown.

TOKEN_WRONG 501 The token is incorrect.

IDENTIFIER_INVALID 502 Unique identifier is invalid.

IDENTIFIER_DUPLICATED 503 Unique identifier already registered.

CERTIFICATE_INVALID 600 The certificate is invalid, no further details.

CSR_INVALID 601 The CSR is invalid, no further details.



CRL_INVALID 602 The CRL is invalid, no further details.

CERTIFICATE_MALFORMED 603 A X509 certificate could not be constructed.

CERTIFICATE_REVOKED 604 The certificate is revoked.

CERTIFICATE_EXPIRED 605 The certificate is expired.

CERTIFICATE_NOT_IN_EFFECT 606 The current date precedes the one in the NOT_BEFORE field of the certificate.

CERTIFICATE_BLOCKED 607 The certificate is blocked or in one of the pending operation statuses.

CERTIFICATE_NOT_TRUSTED 608 The certificate was issued by an unknown or untrusted CA.

KEY_SIZE_INVALID 609 The certificate uses a key size that's not supported.

CRL_UNAVAILABLE 610 The CRL wasn't available at the time it was tried to download.

CERTIFICATE_NOT_FOUND 620 No certificate has been found.

CHAIN_NOT_FOUND 621 Trust chain not found.

KEY_NOT_FOUND 622 The private key of this certificate has not been found.

CARD_ERROR 630 The smartcard found an error during the operation.

CARD_PIN_BLOCKED 631 The PIN of the smartcard has been blocked.

CARD_BLOCKED 632 The smartcard is blocked and can never be used anymore.

CARD_NOT_PRESENT 633 The smartcard is not connected on the mobile equipment.

PIN_WRONG 640 The pin is wrong.

CERTIFICATE_CANT_REVOKE 650 This certificate cannot be revoked.

CERTIFICATE_DUPLICATED 660 This certificate already exists in the server database and cannot be duplicated.

CERTIFICATE_WRONG_SUBJECT 661 The user isn't the owner of the certificate.

KEY_MISMATCH 662 The public key in this certificate is different from the public key contained in the CSR.

SIGNATURE_INVALID 700 The signature is not valid.

SIGNATURE_CANT_VALIDATE 701 Security parametes (certificate, policies, TSA) has a corruption or is wrong.

TEMPLATE_NOT_FOUND 710 The template does not exist.

DOCUMENT_NOT_FOUND 711 The document can not be found on intern storage.

WRONG_DOCUMENT_HASH 712 The document downloaded on the url has another hash.

WRONG_DOCUMENT_TYPE 713 The document type doesn't match the requested standard (XMLor PDF)

XMLDSIG_EMPTY_ELEMENT_LIST 720 Empty emement list in XMLDSig

XMLDSIG_ELEMENTS_WITHOUT_ATRIBUTE_ID

721 Element tags without attribute id in XMLDSig

XMLDSIG_SAME_ID_FOR_MULTIPLE_ELEMENTS

722 Same id in multiple elements in XMLDSig

XMLDSIG_NO_ELEMENT_FOUND 723 No element tag in XMLDSig

7.12 Mobile Status



NOME DESCRIÇÃO

UNREAD Requisição foi enviada mas ainda não foi recebida pelo mobile.

READ Requisição enviada e recebida e recebida pelo mobile.

DONE Requisição enviada e tratada pelo mobile.

8 Especificações Técnicas

8.1 Ambientes Operacionais Suportados

A tecnologia está disponível para os seguintes ambientes:

• Ambiente Cliente

◦ Sistemas Operacionais (versão desktop e notebook)

▪ Windows (7, 8 e 10)

◦ Sistemas Operacionais (versão Mobile)

▪ IOS (8 e superior): smartphone (iPhone) e tablet (iPad)

▪ Android (4.0.1 ou superior): smartphone e tablet

• Ambiente Servidor

◦ Appliance virtual baseado em Hypervisor ou Monitor de Máquina Virtual Vmware ESXi5.5 ou superior

8.2 Benchmarks

Basicamente, 3 variáveis principais influenciam o desempenho de um servidor Certillion:

• Hardware: CPU e memória

• Arquivo: tamanho, formato (pdf, doc, etc)

• Padrão e política de assinatura

Dos 3 padrões - CAdES, XAdES e PAdES - o CAdES apresenta o melhor desempenho. Em um teste realizado com um servidor com 4 vCPUs e 16GB de memória RAM, foram realizadas assinatura de 1.100 documentos por minuto, média de 18 documentos por segundo, de 600kb cada, utilizando padrão CAdES e política AD-RB.

Um segundo teste executado com o padrão PAdES, com servidor de 2 vCPUs e 8GB de memória RAM foi executada assinatura de 20 pdfs de 7mb cada em 25 segundos (desconsiderando o tempo de upload e download do arquivo), com uma média de 1,25 segundo para cada arquivo.

A configuração padrão para um servidor MSS Certillion é de 1 CPU, 8 GB RAM de memória e 20 GB de espaço em disco. Entretanto, essas configurações devem ser ajustadas para o uso mais frequente da organização, considerando as variáveis citadas inicialmente. Por exemplo, se for comum na organização a assinatura de arquivos de maior tamanho (ex: acima de 1 MB) ou com maior quantidade de arquivos por lote ou uso mais intensivo por minuto, pode ser necessário elevar a memória alocada para o servidor.
