sphereon-signatures-sdk-docotic-extension 1.0.3

Docotic extension for the eIDAS Advanced Electronic Signature Client for .NET

This module adds a Docotic PDF-based signing engine to the Sphereon signatures SDK. The PDF stays local; only the digest is sent to the signing service.

For details about the core SDK, see the sphereon-signatures-sdk README on NuGet and the eidas-signature-openapi spec.

Prerequisites

Required Software

• .NET SDK: .NET Core 2.0 or later (library targets netstandard2.0)
• Development: Visual Studio 2019+, VS Code with C# extension, or JetBrains Rider
• Testing: .NET 8.0 SDK (for running tests)

Required Licenses and Access

• Sphereon Signature Service: A valid agreement with Sphereon International B.V. is required to access the signature service
• Docotic PDF License: A valid license from BitMiracle for the Docotic.Pdf SDK
  • Configure the license programmatically using LicenseManager.AddLicenseData(...)
  • Without a valid license, the library will run in evaluation mode with limitations

Required Accounts and Credentials

• OpenID/OAuth Provider: Access to an OpenID Connect authentication server (Azure AD, Auth0, etc.)
  • Client ID and Client Secret for your application
• Sphereon Signature Service Endpoint: URL to the Sphereon signature service (cloud or on-premise)

Optional Components

• Azure Key Vault: If using Azure Key Vault for certificate storage
  • Azure AD tenant with application registration
  • Key Vault with appropriate access policies

What you get

• One-shot signing (single call that signs and returns the PDF).
• Two-phase signing (determine digest, sign remotely, merge locally).
• PAdES and PKCS7 detached formats.
• SHA-256 and SHA-512 digest algorithms.
• Optional visual signature images.
• LTV (PAdES B-LT / B-LTA) with Docotic AddLtvInfo and optional document timestamp.

Target frameworks

• Library: netstandard2.0 (matches the core SDK and keeps compatibility with older runtimes).
• Tests: net8.0 only.

NuGet package

Package name: sphereon-signatures-sdk-docotic-extension
NuGet page: https://www.nuget.org/packages/sphereon-signatures-sdk-docotic-extension

Install

Add a package reference to the module project or include it via the solution:

<PackageReference Include="sphereon-signatures-sdk-docotic-extension" Version="1.0.0" />

Configuration

Configuration mirrors the iText extension and uses the main sphereon-signatures-sdk model objects.

Required environment variables for service auth:

• SIGNATURES_SDK_SERVICE_ENDPOINT
• SIGNATURES_SDK_OPENID_ENDPOINT
• SIGNATURES_SDK_OPENID_CLIENT_ID
• SIGNATURES_SDK_OPENID_CLIENT_SECRET

Optional (online config and keys):

• SIGNATURES_SDK_KEY_PROVIDER_ID
• SIGNATURES_SDK_KEY_ID (certificate alias)
• SIGNATURES_SDK_SIGNATURE_CONFIG_ID

Programmatic license configuration:

using BitMiracle.Docotic;

LicenseManager.AddLicenseData("<docotic-license-data>");

For Azure Key Vault integration (if used by your key provider):

• SIGNATURES_SDK_AZURE_TENANT_ID
• SIGNATURES_SDK_AZURE_APP_ID
• SIGNATURES_SDK_AZURE_CLIENT_ID
• SIGNATURES_SDK_AZURE_CLIENT_SECRET
• SIGNATURES_SDK_AZURE_KEYVAULT_URL

Usage

One-shot signing

var sdkConfig = SignaturesSdkConfig.FromEnvironment();
var authnApi = new AuthnApi(sdkConfig);
string token = authnApi.LoginUsingClientCredentialsOnly().GetAwaiter().GetResult();

var apiFactory = new ApiFactory(sdkConfig, token, sdkConfig.ServiceEndpoint);
var configProvider = new ConfigProvider()
    .WithOnlineCertificates(apiFactory.KeysApi)
    .WithOnlineConfiguration(apiFactory.SignatureConfigApi);

var docoticSigningApi = new DocoticSigningOneShotApi(apiFactory.SigningApi, configProvider);
var signOutput = docoticSigningApi.Sign(determineSignInput);
File.WriteAllBytes("signed.pdf", signOutput.Value);

Two-phase signing

Two-phase signing is supported via DocoticSigningApi. It prepares a PDF with a placeholder signature to capture the digest, then patches the raw signature bytes into the CMS during MergeSignature and (when required) adds a signature timestamp using the TSA URL. DetermineSignInput returns a SignInput in DIGEST mode because Docotic exposes a digest-like payload rather than the raw bytes-to-sign. No PDF bytes are uploaded to the signing service.

var configProvider = new ConfigProvider()
    .WithOfflineConfiguration(signatureConfig)
    .WithOnlineCertificates(apiFactory.KeysApi);

var signingApi = new DocoticSigningApi(configProvider);
var signInputResponse = signingApi.DetermineSignInput(determineSignInput);
var digestResponse = signingApi.Digest(new Digest(signInputResponse.SignInput));
var signatureResponse = apiFactory.SigningApi.CreateSignature(new CreateSignature(digestResponse.SignInput));
var mergeResponse = signingApi.MergeSignature(new MergeSignature(origData, signatureResponse.Signature), signInputResponse.State);
File.WriteAllBytes("signed.pdf", mergeResponse.SignOutput.Value);

LTV and timestamps

• LT/LTA levels add LTV information via Docotic AddLtvInfo() and save incrementally.
• LTA additionally applies a document timestamp using the TSA URL.
• A TSA URL is required for LT/LTA (TimestampParameters.TsaUrl).

For certification signatures that disallow changes, LTV information is added before signing using AddLtvInfo(signingOptions). Document timestamps for LTA are not supported in that mode.

Visual signatures and limitations

Docotic does not expose the same layered appearance model as iText. This extension supports:

• Visual signature images and field placement.
• Docotic default appearance text.

Not supported the same way as iText:

• Annotation overlays and layered appearance customization.
• Custom text styling (color/font/position).
• Background fills.

Testing

dotnet test signatures-sdk-docotic-extension\DocoticSignatureTest\DocoticSignatureTest.csproj

Troubleshooting

• TLS errors (expired/invalid certificates) are reported explicitly during TSA or service calls.
• LTV failures often indicate OCSP/CRL network issues or restricted outbound traffic.
• TSA failures include response code and body summaries when possible.

Security notes

• Keep .env / .ps1 files with secrets out of git.
• PDF content is never uploaded to the signing service; only the digest is sent.

License

Use of the BitMiracle Docotic PDF SDK requires a valid Docotic license from BitMiracle.