Short answer. In Ukraine, a file-based digital signature/QES key comes in at least four formats: PKCS#12/PFX (.p12/.pfx), JKS (Java KeyStore), PKCS#8 (a standalone private key), and IIT Key-6.dat. Different providers issue keys in different containers, so a website that accepts a "file key" has to understand all four. In DSTUcrypt this is already done: the widget detects the container format itself, picks the right key by its purpose (keyUsage) itself, and the user simply selects a file and enters a password — everything in the browser, without the key being sent anywhere.
Why there are several file formats — and why that hurts your website
A single "Ukrainian file key format" never existed. The QES infrastructure grew historically: qualified trust service providers built their systems on different software stacks, and each one packaged keys into whatever container was native to its software. So today different providers issue keys in different containers — and all of them are equally legal and functional.
For the user this is invisible: they just have "a key file and a password". But for a website that wants to accept QES, the difference is huge. Each format is a separate data structure, a separate password-based encryption scheme, separate edge cases: a container without a certificate, a container with several keys, non-standard file extensions. Writing and maintaining parsers for four containers yourself means weeks of work that have nothing to do with your product. And skipping even one of them means turning away part of your users right at the "select your key" step.
The four file key formats: what's inside
| Format | Typical file | What's inside | Distinctive trait |
|---|---|---|---|
| PKCS#12 / PFX | .p12 , .pfx | private key + certificates | international container standard |
| JKS | .jks | a store of keys and certificates | Java KeyStore format |
| PKCS#8 | key file | private key only | certificate often comes as a separate file |
| IIT Key-6.dat | Key-6.dat | private keys | IIT format widespread in Ukraine |
PKCS#12/PFX is the international standard for a cryptographic container. A single password-protected file holding both the private key and its certificates. A PFX QES key is the most convenient one to move between systems, because most cryptographic software in the world understands it.
JKS is Java KeyStore, a key store from the Java world. It is built differently from PKCS#12 but solves the same problem: several keys and certificates in one password-protected file. A signature made from a JKS is no different in its result — the only difference is the container.
PKCS#8 is not a container but a "raw" private key: a standardized structure of the key itself, usually encrypted with a password. There may be no certificate inside at all — in that case it has to be supplied as a separate file.
Key-6.dat is a protected key store format developed by IIT that is widespread in Ukraine. Millions of users know their key precisely as a file named Key-6.dat, so supporting it on a Ukrainian website is a must.
A separate problem: several keys in one container
A container often holds not one key but two: a signing key (for applying a QES) and a decryption key (for key agreement protocols — decrypting data addressed to you). You must use the one that matches the operation: you cannot sign with the decryption key.
The naive solution is to show the user a list of keys from the container and ask them to choose. That is the worst possible UX: a person sees two technical entries with cryptic identifiers and has to guess the right one. Each key's certificate has a keyUsage field — the key's purpose — and that is exactly what lets the decision be made automatically. DSTUcrypt does this for you: the signing widget finds the signing key in the container itself, and the decryption widget finds the decryption key. The user never sees technical lists at all.
What this means for your website: zero key-parsing code
On the integrator's side, everything boils down to a single call. You pass the data to be signed — and your code does not care which key format the user picks in the widget:
Signing — identical code for any key file
import { embed } from 'https://dstucrypt.io/embed/dstucrypt-embed.mjs';
const signer = await embed('sign', { mount: 'modal' });
// the user picks the file themselves: .p12/.pfx, .jks, PKCS#8, or Key-6.dat —
// it makes no difference to your code
const { signature, accredited } = await signer.sign(fileBytes, {
format: 'CAdES-T',
});
signature.download('document.p7s');
The widget opens in a modal window, prompts the user to select a key file, detects the container format itself, takes the signing key by keyUsage, and returns a ready signature. If the container has no certificate (typical for PKCS#8), the widget itself shows a field for a separate certificate file. By default the signature is hashed with DSTU GOST 34.311-95, and the modern Kupyna (DSTU 7564:2014) can be enabled with a single option, digest:'kupyna-256' — regardless of the key file format.
What DSTUcrypt gives you out of the box. All file key formats — PKCS#12/PFX, JKS, PKCS#8, IIT Key-6.dat — work in one widget with no configuration. The signing or decryption key is picked from the container automatically by keyUsage — the user sees no technical lists. And the key and password themselves never leave the browser: all cryptography runs in WebAssembly inside our iframe and never reaches your server or ours.
File key security: what to advise your users
A file key is the most accessible QES medium, but its security depends entirely on the owner's discipline. A few tips worth passing on to your users:
- A strong password. The container is only as protected as the password is complex. A short password reduces the file's protection to nothing.
- Do not send the key by email or messenger. Copies of emails and messages remain on servers — the key file should be stored locally by its owner.
- Do not upload the key to websites. A legitimate signing service does not need the key file on its server. In DSTUcrypt the key is read and used only in the user's browser.
- Secure tokens are the next step. For the most critical scenarios, providers offer hardware secure tokens from which the key cannot be copied. That is a different category of media: DSTUcrypt works specifically with file keys.
Frequently asked questions
Which QES key files does DSTUcrypt support?
PKCS#12/PFX, JKS, PKCS#8, and IIT Key-6.dat — all in one widget. The user simply selects the key file and enters the password; the widget detects the container format itself. Hardware tokens (secure media) are not currently supported.
My container has two keys — a signing key and a decryption key. Which one will be used?
The widget automatically picks the right key by its purpose (keyUsage): the signing key for signing, the decryption key for decryption. The user never sees technical key lists and cannot make a mistake.
Is it OK to send a key file by email or messenger?
No. A file key together with its password gives full control over your signature, and copies of the email or message remain on servers. Store the key locally, and if it may have fallen into someone else's hands — contact your provider to revoke the certificate and generate a new key.
What if the container has no certificate?
Some containers hold only the private key. In that case the DSTUcrypt widget shows an additional field for a separate certificate file — upload it alongside the key, and signing proceeds as usual.
Read next
- How to add QES to your website in 10 minutes
- Why the private key must never leave the browser
- Several signers on one document: multi-signature
All QES file keys on your website — in 10 minutes
Ready-made widgets for signing, verification, and encryption under DSTU. The key and password never leave the user's browser. Every new domain gets 7 days free.
Live demoHow to integrate