Início rápido do sgcSign

Visão geral

Um assinador e um provedor de chaves

O assinador conhece o formato do documento. O provedor de chaves sabe onde está a chave privada. Eles se encontram em uma propriedade.

O assinador

TsgcPAdESSigner, declarado em sgcSign_PAdES.pas e registrado na página SGC Sign da paleta. SignPDFFile recebe um caminho de entrada e um caminho de saída.

O provedor de chaves

TsgcWindowsCertStoreProvider para o repositório de certificados do Windows, ou TsgcPFXKeyProvider para um arquivo .pfx. Os dois estão na mesma página da paleta.

A propriedade que os une

KeyProvider, cujo tipo é a interface IsgcKeyProvider e não uma referência de componente. Essa distinção importa para o tempo de vida, e a seção de armadilhas abaixo explica por quê.

Plataforma

Win32, Win64, Linux64, macOS em Intel e Apple Silicon, iOS e Android. No Windows, o hashing e a assinatura passam pela API CNG do Windows, e em todas as outras plataformas pela criptografia em Pascal puro da própria biblioteca, sem OpenSSL para distribuir. O provedor do repositório de certificados do Windows é o único componente que continua exclusivo do Windows.

Antes de começar

Requisitos e edições

O sgcSign não tem níveis de recursos, então esta tabela trata de compiladores e plataformas, e não de edições.

O quê	Valor
IDE	Do Delphi 7 ao RAD Studio 13, e C++Builder. No C++Builder, a pasta lib vai no caminho System Include em vez do caminho da biblioteca.
Cláusula uses	O demo escreve `sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes, sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore, sgcSign_KeyProvider_PEM, sgcSign_KeyProvider_PFX`. Remova os provedores que você não usa.
Edições	Não há nenhuma. O `sgcVer.inc` do próprio produto não contém nenhum define `SGC_EDT_*`, e nenhum recurso é controlado por nível. Uma biblioteca, todos os componentes, em todas as licenças. Os níveis comerciais são por número de licenças: single, team e site, além de uma Community Edition gratuita.
Plataforma, verificada no código-fonte	Win32, Win64, Linux64, OSX64, OSXARM64, iOS e Android. A criptografia passa por uma unit de junção, `sgcSign_Crypto.pas`, que usa CNG no Windows e Pascal puro em todos os outros lugares, o HTTP é o WinHTTP no Windows e o cliente da RTL do Delphi nos demais, e os pacotes de runtime habilitam Linux64 e macOS em Intel a partir do Delphi 10.3, Android e iOS a partir do 10.4 e macOS em Apple Silicon a partir do 11. `sgcSign_KeyProvider_WinCertStore.pas` é a única unit exclusiva do Windows.
Dependências externas	Nenhuma. No Windows, a biblioteca chama diretamente as APIs CNG e WinHTTP do Windows, e nas outras plataformas usa sua própria criptografia em Pascal puro e o cliente HTTP da RTL do Delphi, então não há DLLs do OpenSSL para distribuir com seu aplicativo.
Padrões	Um `TsgcPAdESSigner` novo já tem um perfil utilizável: o construtor define o perfil PAdES básico, o nível de assinatura baseline B e SHA-256. Você não precisa tocar em `Profile` para produzir uma assinatura válida.

Prefere XML a PDF? O passo a passo de XAdES em cinco minutos assina um documento XML com um arquivo PFX e cobre a armadilha do Unicode no Delphi 7 e o horário UTC da assinatura. Esta página é a contrapartida de PDF e repositório de certificados.

Passo 1

Instale e encontre a página da paleta

Compile o pacote de runtime antes de instalar o de design-time, porque o segundo referencia o primeiro.

1. Descompacte

Descompacte o download em uma pasta, chamada de {$DIR} abaixo.

2. Caminho da biblioteca

Tools, Environment Options, Directories. Adicione {$DIR}\delphi\source, que vale para toda versão do RAD Studio.

3. Adicione a pasta lib

Adicione também a pasta específica da versão, por exemplo {$DIR}\delphi\libD13\$(Platform) no RAD Studio 13, até libD7 no Delphi 7. No C++Builder, elas vão no caminho System Include.

4. Compile os pacotes

Abra Packages\sgcSignD13.groupproj para a versão da sua IDE, ou sgcSignC13.groupproj para o C++Builder. Compile primeiro o pacote sgcSign e depois instale o dclsgcSign.

5. Confira a paleta

Aparece uma página chamada SGC Sign, com os assinadores, o verificador, os clientes de carimbo de tempo e OCSP e os dez provedores de chaves. No Windows, ela também traz o assinador e o verificador Authenticode.

QuickStart

Assine um PDF, em cerca de vinte linhas

Escolha um certificado, crie o assinador, aponte-o para o provedor e chame SignPDFFile. A primeira aba usa o repositório de certificados do Windows, a segunda um arquivo PFX.

frmMain.pas

uses
  SysUtils, Classes,
  // sgcSign
  sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes,
  sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore;

procedure TFormMain.btnSignClick(Sender: TObject);
var
  vSigner: TsgcPAdESSigner;
  vKeyProvider: TsgcWindowsCertStoreProvider;
  vProviderIntf: IsgcKeyProvider;
  vOutputFile: string;
begin
  vKeyProvider := TsgcWindowsCertStoreProvider.Create(nil);
  vSigner := TsgcPAdESSigner.Create(nil);
  try
    vKeyProvider.SelectCertificateBySubject('My Company');
    Log('Certificate found: ' + vKeyProvider.Certificate.Subject);

    // Hold the interface in an explicit local: an inline "as" cast
    // would leave a compiler-generated interface temporary alive in
    // this stack frame until the routine returns, i.e. past
    // vKeyProvider.Free, and releasing it would touch freed memory.
    vProviderIntf := vKeyProvider as IsgcKeyProvider;
    vSigner.KeyProvider := vProviderIntf;
    vSigner.Reason := 'Demo signature';
    vSigner.Location := 'Spain';
    vSigner.SignerName := 'sgcSign Demo';

    vOutputFile := ChangeFileExt(edInputFile.Text, '_signed.pdf');
    vSigner.SignPDFFile(edInputFile.Text, vOutputFile);

    Log('SUCCESS: PDF signed with PAdES profile');
    Log('Output file: ' + vOutputFile);
  finally
    vSigner.Free;
    vProviderIntf := nil;
    vKeyProvider.Free;
  end;
end;

Observe o que não está aqui. Profile nunca é tocado, porque o construtor já define um perfil PAdES básico, o nível de assinatura baseline B e SHA-256. O comentário sobre o temporário de interface é do próprio demo que acompanha o pacote, e a ordem de liberação no bloco finally é o motivo de ele importar.

frmMain.pas

uses
  SysUtils, Classes,
  // sgcSign
  sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes,
  sgcSign_PAdES, sgcSign_KeyProvider_PFX;

var
  vSigner: TsgcPAdESSigner;
  vKeyProvider: TsgcPFXKeyProvider;
  vProviderIntf: IsgcKeyProvider;
begin
  vKeyProvider := TsgcPFXKeyProvider.Create(nil);
  vSigner := TsgcPAdESSigner.Create(nil);
  try
    vKeyProvider.FileName := 'C:\certs\signer.pfx';
    vKeyProvider.Password := GetPfxPassword;
    vKeyProvider.LoadFromFile;
    Log('Certificate loaded (PFX): ' + vKeyProvider.Certificate.Subject);

    vProviderIntf := vKeyProvider as IsgcKeyProvider;
    vSigner.KeyProvider := vProviderIntf;

    vSigner.SignPDFFile('C:\docs\contract.pdf',
      'C:\docs\contract_signed.pdf');
  finally
    vSigner.Free;
    vProviderIntf := nil;
    vKeyProvider.Free;
  end;
end;

A única diferença em relação à primeira aba é qual provedor você cria e como o aponta para uma chave. Tudo a partir de KeyProvider := é idêntico, e isso vale para os dez provedores, incluindo hardware PKCS#11 e os serviços de chaves na nuvem.

uVerify.pas

uses
  SysUtils, Classes,
  // sgcSign
  sgcSign_Types, sgcSign_Interfaces, sgcSign_Verifier;

var
  oVerifier: TsgcSignatureVerifier;
  vVerifier: IsgcSignatureVerifier;
  oStream: TFileStream;
begin
  oVerifier := TsgcSignatureVerifier.Create(nil);
  oStream := TFileStream.Create('C:\docs\contract_signed.pdf',
    fmOpenRead or fmShareDenyWrite);
  try
    // VerifyPDF is reached through the interface the component implements
    vVerifier := oVerifier as IsgcSignatureVerifier;

    if vVerifier.VerifyPDF(oStream) = vsValid then
      Writeln('valid')
    else
      Writeln(oVerifier.GetVerificationDetails);
  finally
    vVerifier := nil;
    oStream.Free;
    oVerifier.Free;
  end;
end;

A mesma regra de interface do assinador: atribua o cast a uma variável local nomeada e limpe-a antes de liberar o componente. GetValidationReportXML produz um relatório no formato de relatório de validação do ETSI quando um valor booleano não é evidência suficiente.

As duas primeiras abas vêm do demo que acompanha o pacote, Demos\Delphi\PAdES\frmMain.pas, com sua ramificação reduzida a um caminho por aba. O comentário sobre manter a interface em uma variável local nomeada é do próprio demo e vale a pena preservá-lo. Um demo irmão mais completo, Demos\Delphi\PAdES_Providers, faz o mesmo com provedores de hardware e de nuvem.

Passo 2

Verifique a assinatura, não apenas olhe o arquivo

Um arquivo apareceu. Isso não é o mesmo que uma assinatura que valida.

O certificado foi resolvido

Leia Certificate.Subject depois de selecionar, como faz o demo. É a diferença entre assinar com o certificado que você pretendia e assinar com o primeiro que coincidiu. IsLoaded responde à mesma pergunta como um booleano.

O arquivo apareceu

SignPDFFile grava o caminho de saída que você informou. O demo que acompanha o pacote o deriva com ChangeFileExt, de modo que o arquivo assinado fique ao lado do original.

Ele gera exceção, não retorna um código

Não há resultado para testar, então coloque a chamada em um try except e leia a mensagem da exceção. É o que o demo faz, e é o único canal de falha.

A assinatura valida

Um arquivo não é uma assinatura válida. TsgcSignatureVerifier.VerifyPDF retorna um TsgcVerificationStatus que você compara com vsValid, e GetVerificationDetails explica uma falha. Abrir o arquivo em um leitor de PDF mostra o mesmo a uma pessoa.

Problemas comuns

O que costuma dar errado na primeira vez

Seis problemas respondem por quase toda primeira assinatura.

Uma violação de acesso na saída

Este é o problema sobre o qual o demo avisa em seu próprio comentário. KeyProvider recebe um IsgcKeyProvider, então um cast as inline deixa uma referência de interface gerada pelo compilador viva até a rotina retornar, o que acontece depois de você liberar o componente provedor. Atribua a interface a uma variável local nomeada e libere na ordem: assinador, depois a interface como nil, depois o provedor.

Profile não é uma string

É um objeto TsgcSignProfileConfig. Você define Profile.Profile e Profile.SignatureLevel, e não Profile := 'something'. O construtor já preenche um padrão utilizável, então o primeiro exemplo não precisa tocar nele.

Nenhum certificado é encontrado

SelectCertificateBySubject procura pelo assunto, e SelectCertificateByThumbprint pela impressão digital. Leia Certificate.Subject depois de selecionar, como faz o demo, para ver qual certificado você realmente obteve. EnumerateCertificates lista o que está disponível.

Não compila fora do Windows

Não pode. O assinador e todo provedor colocam Windows na cláusula uses da interface sem condicional, então isso é um erro de compilação e não uma unit vazia. O sgcSign é uma biblioteca para Windows.

A assinatura aparece como desconhecida no leitor

Uma assinatura básica não traz âncora de confiança nem dados de revogação. Adicione um carimbo de tempo por meio de TSAClient e suba para um perfil de longo prazo quando o documento precisar continuar verificável depois que o certificado expirar.

SignPDFFile gera exceção em vez de retornar um código

Esse é o projeto. Não há valor de retorno para testar, então coloque a chamada em um try except e leia a mensagem da exceção, que é o que o demo que acompanha o pacote faz.

Aprofunde-se

Além da primeira assinatura

Quatro direções, todas dentro da mesma biblioteca.

Outros formatos de documento

XAdES e XMLDSig para XML, CAdES para CMS destacado, contêineres ASiC e assinadores dedicados para pacotes ClickOnce, NuGet e VSIX. No Windows, também há um assinador Authenticode.

Todos os componentes do sgcSign

Onde a chave fica

Acompanham dez provedores de chaves: PFX, PEM, o repositório do Windows, hardware PKCS#11, Azure Trusted Signing, AWS KMS, Google Cloud KMS, Certum SimplySign, HashiCorp Vault e o protocolo de assinatura remota CSC.

Provedores de chaves

Perfis por país

Vinte e um perfis de país e de setor, do VeriFactu espanhol aos formatos de faturamento da UE, cada um com os campos e o nível de assinatura que esse regime espera.

Perfis de assinatura

Assine em outro lugar

O sgcSign Server é um daemon auto-hospedado que guarda as chaves e assina sob demanda, de modo que o certificado nunca sai da máquina em que você confia.

sgcSign Server

Recursos

Referência, demos e documentação

Os projetos de demo acompanham o download, em Demos\Delphi. O demo PAdES é aquele em que esta página se baseia.

	Passo a passo de XAdES em cinco minutos O início rápido na versão longa: um projeto VCL novo, um arquivo PFX e um envelope XML assinado.	Abrir
	Provedores de chaves Todos os dez lugares em que uma chave privada pode ficar e o que cada um exige.	Abrir
	Perfis de assinatura Os vinte e um perfis de país e de setor e o que cada um exige.	Abrir
	Tutorial de assinatura de PDF Um passo a passo mais longo do PAdES, incluindo assinaturas visíveis.	Abrir
	sgcSign Server O daemon de assinatura auto-hospedado, para quando a chave não pode viajar.	Abrir
	Baixe a versão de avaliação O mesmo instalador da versão de produção, com tempo limitado, além de uma Community Edition gratuita.	Abrir

Leitura relacionada: a introdução ao sgcSign e o servidor de assinatura de código. Cada produto tem seu próprio início rápido, listado na página de primeiros passos.

FAQ

Perguntas sobre o início rápido do sgcSign

TsgcPAdESSigner, declarado em sgcSign_PAdES.pas, e um provedor de chaves. Para o repositório de certificados do Windows, é TsgcWindowsCertStoreProvider, de sgcSign_KeyProvider_WinCertStore.pas. Para um arquivo .pfx, é TsgcPFXKeyProvider, de sgcSign_KeyProvider_PFX.pas. Os dois ficam na página SGC Sign da paleta. Atribua o provedor à propriedade KeyProvider do assinador e depois chame SignPDFFile(aInputFile, aOutputFile).

Porque KeyProvider é tipado como a interface IsgcKeyProvider, e não como um componente. Um cast as inline cria um temporário de interface gerado pelo compilador que permanece vivo no frame da pilha até a rotina retornar, o que acontece depois de o componente provedor ter sido liberado, e liberá-lo então toca em memória que já não existe. O demo atribui o cast a uma variável local nomeada e depois libera na ordem: assinador, interface como nil, provedor. Copie essa ordem.

Não há edições. O sgcVer.inc do produto não contém nenhum define SGC_EDT_*, e nenhum componente ou formato é controlado por nível. Toda licença contém todos os assinadores, todos os provedores de chaves e todos os perfis de país. Os níveis comerciais são por número de licenças, single, team e site, e há uma Community Edition gratuita ao lado da versão de avaliação.

Sim, desde a 2026.10.0. A biblioteca compila e roda em Linux64, em macOS para Intel e Apple Silicon, em iOS e em Android, além de Win32 e Win64. A assinatura e a verificação de documentos, a leitura e a gravação de arquivos PKCS#12, a assinatura de arquivos PE, catálogos, MSI, MSP, MSIX e APPX e os tokens PKCS#11 funcionam todos ali, e o servidor de assinatura roda como um daemon systemd no Linux. Dois provedores usam o repositório de chaves que a plataforma já tem, o keychain da Apple e o Android KeyStore. Duas coisas continuam no Windows: o provedor do repositório de certificados do Windows e os formatos específicos do Windows no servidor e na ferramenta de linha de comando, que ainda os recusam em uma compilação que não seja Windows, embora a própria biblioteca os assine.

Não para uma primeira assinatura. O construtor já define um perfil PAdES básico, o nível de assinatura baseline B e SHA-256. Quando você quiser mudá-lo, Profile é um objeto TsgcSignProfileConfig, então você define Profile.Profile e Profile.SignatureLevel em vez de atribuir uma string. Para uma assinatura de longo prazo, passe para o perfil LTV e o nível baseline LT e anexe um TSAClient.

Use TsgcSignatureVerifier. VerifyPDF recebe um stream e retorna um TsgcVerificationStatus, que você compara com vsValid. GetVerificationDetails explica uma falha, e GetValidationReportXML produz um relatório no formato de relatório de validação do ETSI quando você precisa de evidência em vez de um booleano.

Não. No Windows, o sgcSign faz hash e assina por meio das APIs CNG e BCrypt e fala com a rede por meio do WinHTTP. No Linux, macOS, iOS e Android, ele usa sua própria criptografia em Pascal puro e o cliente HTTP da RTL do Delphi. Em qualquer caso, não há DLLs do OpenSSL para distribuir, e esse é um dos motivos de a implantação ser simples.

Elas cobrem tarefas diferentes, de propósito. O início rápido de cinco minutos monta um projeto VCL novo, usa um arquivo PFX e assina um documento XML com XAdES, e aborda a armadilha do Unicode no Delphi 7 e o horário UTC da assinatura. Esta página assina um PDF com PAdES usando um certificado do repositório do Windows, que é o que o demo PAdES que acompanha o pacote faz. Leia esta primeiro e depois aquela quando precisar de XML.

sgcSign em cinco minutos