Development of the 1C-Bitrix electronic signature module

Digital Signature Module Development for 1C-Bitrix

Digital signature in 1C-Bitrix context is not a "sign button," but integration of cryptographic stack into web environment: browser plugin, server verification, storage of signed documents with legal significance guarantee. The task touches frontend (token/certificate interaction via JavaScript), backend (certificate chain verification, CRL/OCSP handling), and infrastructure (cryptoprovider setup on server).

Cryptographic Stack: CryptoPro and Signature Formats

Russian digital signature de-facto standard is CryptoPro CSP. Web applications use:

• CryptoPro CSP — cryptoprovider installed on user's machine (or server for server-side signing). Implements GOST R 34.10-2012 and GOST R 34.11-2012.
• CryptoPro Digital Signature Browser plug-in — NPAPI/ActiveX plugin (legacy browsers) or modern replacement via native app + Chrome/Firefox/Edge extension.
• cadesplugin.js — JavaScript library from CryptoPro, providing API for plugin interaction via cadesplugin.CreateObjectAsync().

Signature formats encountered in real projects:

For most Bitrix projects, CAdES-BES is sufficient for internal processes and CAdES-X Long Type 1 for documents with counterparties and government agencies.

Technical Implementation of Signature via CryptoPro

This is the key technical block. Document signing process from browser consists of several stages, each a potential failure point.

Step 1: Plugin initialization.

Client side loads cadesplugin.js. Library detects browser and interaction method — via native app (CryptoPro Extension for CAdES Browser Plug-in) or NPAPI (legacy). Initialization is async:

cadesplugin.then(function() {
    // plugin ready
}, function(error) {
    // plugin not installed or misconfigured
});

At this stage critical to handle case where plugin is absent — show user clear instructions, not blank screen.

Step 2: Certificate selection.

Plugin API queries certificate store (cadescom.CAPICOM_MY_STORE). User sees certificate list with owner names and expiration dates. In practice store may contain 5–10 certificates — personal, organizational, test. Filtering by OID designation (document signing — 1.3.6.1.5.5.7.3.4) narrows list.

For each certificate check:

• Expiration (ValidFromDate, ValidToDate)
• Private key presence (HasPrivateKey())
• Status — not revoked (preliminary check via cached CRL)

Step 3: Signature formation.

Document (PDF, XML, any file) transmitted as Base64 string. For CAdES-BES:

1. Create CAdESCOM.CadesSignedData object
2. Set content (ContentEncoding = CADESCOM_BASE64_TO_BINARY)
3. Call SignCades() method with certificate and signature type

Result — CMS format string (PKCS#7), encoded in Base64. This is detached signature.

Step 4: Server transmission.

Signature transferred to Bitrix server via AJAX request. Server saves:

• Original document
• Signature file (.sig or .p7s)
• Metadata: who signed (certificate subject), when, certificate serial number

For CAdES-X Long Type 1 process is complex — need access to TSP server (timestamp) and OCSP responder. Plugin handles these automatically if appropriate signature type specified, but TSP server must be accessible (default — http://cryptopro.ru/tsp/, production requires own or paid subscription).

Error handling — separate topic. Typical issues:

• Plugin installed but browser extension disabled — cadesplugin promise rejected
• Certificate exists but private key on token not plugged in — HasPrivateKey() returns false
• TSP server inaccessible — CAdES-X Long Type 1 signature not formed, fallback to CAdES-BES with warning
• Token PIN code — user enters PIN when accessing private key, system dialog impossible to customize

Signature and Certificate Verification

Verification executed on server via CryptoPro CSP installed on server machine. For PHP available phpcades module (CryptoPro PHP extension) or cryptcp utility call via exec().

Server verification includes:

• Signature integrity — document hash matches hash in signature
• Certificate validity — not expired, not revoked
• Trust chain — from signer certificate to root CA

Revocation check implemented two ways:

• CRL (Certificate Revocation List) — periodically downloaded list of revoked certificates. Loaded into CSP store on server. Drawback — delay between revocation and CRL update (usually 24 hours).
• OCSP (Online Certificate Status Protocol) — real-time status request to CA responder. More accurate, but depends on service availability. CryptoPro CSP supports OCSP via registry or config settings.

Signed Document Storage

Signed documents stored in Bitrix via highload-block or separate table:

• DOCUMENT_ID — link to entity (order, contract, act)
• FILE_ID — original document in b_file table
• SIGNATURE_FILE_ID — signature file
• SIGNER_SUBJECT — data from certificate (name, organization INN)
• SIGN_DATE — signing date
• SIGN_FORMAT — CAdES-BES / CAdES-X Long Type 1
• VERIFICATION_STATUS — last verification result

For long-term storage (archive) periodic re-signing recommended — adding new timestamp before previous one expires. This ensures signature verification possible 5–10 years later, when algorithms may become legacy.

Integration into Bitrix Document Flow

In sale module signature integrated into order lifecycle:

• Order status "Awaiting Signature" — customer in personal account sees documents to sign
• After signing status changes automatically via handler — AJAX callback calls CSaleOrder::Update() or D7 method
• Admin panel shows signature status to manager: signed / unsigned / verification failed

If project uses Bitrix24, signature can be embedded in business processes via activity module bizproc. Document passes approval route, at final stage signed with digital signature of responsible person.

Digital signature module is infrastructure component. Its complexity not in code volume, but in quantity of external dependencies: cryptoprovider, browser plugin, TSP server, OCSP responder, root certificates. Each requires setup and monitoring.