FPdfPkcs11 - PDFium Delphi Component

Unidade: FPdfPkcs11

Back-end de assinatura PKCS#11 para PAdES, que resolve um certificado de assinante e sua chave privada a partir de um token e produz a assinatura SignerInfo dentro do token

Sintaxe

EPdfPkcs11Error = class(Exception);

TPdfPkcs11Options = record
  ModulePath: string;
  SlotId: UInt64;
  UseSpecificSlot: Boolean;
  Pin: string;
  CertificateLabel: string;
  class function Default: TPdfPkcs11Options; static;
end;

TPdfPkcs11SignerProvider = class(TInterfacedObject, IPadesSignerProvider,
  IPdfPkcs11SignerProvider)
  constructor Create(const Options: TPdfPkcs11Options);
  destructor Destroy; override;
  function BackendName: string;
  function Resolve(const Options: TPadesSignerOptions): TPadesResolvedSigner;
  function EnumerateSlots: TPdfPkcs11Slots;
  function EnumerateCertificates(SlotID: UInt64): TPdfPkcs11Certificates;
  procedure CloseProtectedSessions;
end;

function Pkcs11ModuleAvailable(const ModulePath: string): Boolean;
function Pkcs11ModuleVersion(const ModulePath: string): string;
function Pkcs11AbiLayout: string;
function ConfigurePkcs11SignerProvider(
  const Options: TPdfPkcs11Options): IPdfPkcs11SignerProvider;

Descrição

FPdfPkcs11 é o back-end de assinatura PAdES portátil e a contraparte do back-end CNG do Windows. Ele resolve um certificado de assinante e sua chave privada a partir de um token PKCS#11 e, em seguida, retorna um TPadesResolvedSigner cujo ICmsSigner produz a assinatura SignerInfo por meio do token, de modo que a chave nunca o deixa

O módulo é carregado em tempo de execução por caminho — opensc-pkcs11.so, libsofthsm2.so, uma DLL do fornecedor — de modo que nada é ligado em tempo de compilação e um módulo ausente é relatado em vez de ser fatal. Apenas C_GetFunctionList é resolvido pelo nome; todos os outros pontos de entrada saem da tabela de funções que ele retorna, que é como o padrão pretende que um módulo seja acessado

ConfigurePkcs11SignerProvider constrói um TPdfPkcs11SignerProvider a partir de um valor TPdfPkcs11Options e o instala como o back-end de assinantes PAdES ativo, retornando a interface IPdfPkcs11SignerProvider que também carrega os métodos de enumeração de tokens

Pkcs11ModuleAvailable e Pkcs11ModuleVersion relatam se um determinado módulo carrega e expõe uma tabela de funções utilizável, de modo que o aplicativo possa decidir na inicialização se a assinatura por token é possível nesta máquina. Os módulos carregados são armazenados em cache por caminho, porque o padrão permite apenas uma inicialização por processo por módulo

Resolve seleciona o certificado por TPadesSignerOptions.CertificateThumbprint quando um é fornecido e por CertificateLabel caso contrário, e então localiza o objeto de chave privada que carrega o mesmo identificador de token do certificado. O algoritmo da chave do certificado decide a família de algoritmos: uma chave EC assina com ECDSA e sua assinatura bruta é recodificada como a SEQUENCE DER que o CMS espera, enquanto uma chave RSA segue o esquema de preenchimento solicitado

EnumerateSlots e EnumerateCertificates servem a interfaces de usuário de seleção, permitindo que o aplicativo liste os slots que um módulo relata e os certificados que um slot escolhido contém antes de qualquer opção de assinatura ser fixada

Funções

Função	Descrição
`Pkcs11ModuleAvailable`	Retorna True quando o módulo no caminho indicado carrega e expõe uma tabela de funções utilizável
`Pkcs11ModuleVersion`	Retorna a string de versão que o módulo relata, ou uma string vazia quando o módulo não carrega
`Pkcs11AbiLayout`	Retorna o layout de ABI que esta compilação resolveu, como `ulong=<n> attr=<n> pss=<n> table=<n>`
`ConfigurePkcs11SignerProvider`	Constrói um provedor a partir das opções fornecidas, instala-o como o back-end de assinantes PAdES e o retorna como `IPdfPkcs11SignerProvider`

Tipos

Tipo	Finalidade
`EPdfPkcs11Error`	Exceção lançada quando nenhum caminho de módulo está configurado, o módulo não pode ser carregado, uma chamada ao token falha ou nenhum certificado ou chave privada correspondente é encontrado
`TPdfPkcs11Options`	Registro que nomeia o módulo, o slot, o PIN e o certificado com os quais o provedor trabalha
`TPdfPkcs11SignerProvider`	Classe de provedor que implementa `IPadesSignerProvider` e `IPdfPkcs11SignerProvider` sobre um módulo PKCS#11

Campos de TPdfPkcs11Options

Campo	Descrição
`ModulePath`	Caminho para o módulo PKCS#11; obrigatório, porque qual módulo atende a um token é uma decisão de implantação e não há padrão útil
`SlotId`	Slot de token a ser aberto, respeitado apenas quando `UseSpecificSlot` é True
`UseSpecificSlot`	Deixe False para usar o primeiro slot que relatar um token presente
`Pin`	PIN do usuário; o provedor limpa sua própria cópia assim que o token a consome, e o chamador permanece responsável pelo tempo de vida da string que passar
`CertificateLabel`	Rótulo de objeto opcional do certificado com o qual assinar, usado apenas quando `TPadesSignerOptions.CertificateThumbprint` está vazio
`Default`	Fábrica estática que retorna opções com caminho de módulo vazio, slot 0, seleção automática de slot e sem PIN ou rótulo

Membros de TPdfPkcs11SignerProvider

Membro	Descrição
`Create`	Constrói o provedor a partir de um valor `TPdfPkcs11Options`; o módulo em si é aberto no primeiro uso
`Destroy`	Fecha qualquer sessão de token aberta antes de a instância ser liberada
`BackendName`	Retorna o nome do back-end, com o nome do arquivo do módulo acrescentado quando um caminho de módulo está configurado
`Resolve`	Resolve `TPadesSignerOptions` em um `TPadesResolvedSigner` contendo o assinante do token e o DER do certificado do assinante
`EnumerateSlots`	Retorna todos os slots que o módulo relata como `TPdfPkcs11Slots`, incluindo slots sem token presente
`EnumerateCertificates`	Retorna os certificados contidos em um slot como `TPdfPkcs11Certificates`, abrindo antes uma sessão nesse slot
`CloseProtectedSessions`	Faz logout onde houve login e fecha a sessão aberta, liberando o token para outros consumidores

Observações

Dois detalhes de ABI decidem se um módulo funciona ou não, e ambos diferem por plataforma, não por módulo
CK_ULONG segue o unsigned long de C, de modo que tem 4 bytes no Windows (LLP64) e 8 bytes no Linux e no macOS (LP64); cada handle, contagem e tipo de atributo é um CK_ULONG
Os cabeçalhos PKCS#11 são empacotados em um byte apenas no Windows. Isso é invisível para estruturas cujos campos são todos da largura de um ponteiro, mas desloca cada ponteiro de função na tabela, porque a tabela abre com um campo de versão de dois bytes
Pkcs11AbiLayout relata o layout que esta compilação resolveu, de modo que uma incompatibilidade seja diagnosticável em vez de uma falha silenciosa: o Win32 relata ulong=4 attr=12 pss=12 table=2, o Win64 relata ulong=4 attr=16 pss=12 table=2, e um alvo LP64 relata ulong=8 attr=24 pss=24 table=8
A unidade também se autoverifica em relação ao layout quando um módulo carrega e recusa o módulo em vez de chamar por meio de uma tabela incompatível, de modo que uma ABI incompatível se manifesta como um módulo indisponível
Um módulo que outro consumidor já inicializou é usado como está, e uma sessão em que outra parte do host já fez login também é aceita
Sem thumbprint e sem CertificateLabel, o primeiro certificado do token vence, o que serve para um token de certificado único e para nenhuma implantação de produção
A chave privada é casada com o certificado pelo identificador de objeto que o token atribui a ambos; quando o certificado não traz nenhum, a busca volta para a única chave privada presente

Consulte também

FPdfCrypto, FPdfCryptoWin, FPdfCms

Unidade FPdfPkcs11