CDIGIDOC(1)

📦
version 3.10.5 · 4 versions
, in ubuntu questing

💖 NAME 💖

Okay so bestie, welcome to the cdigidoc manual page — that's the section 1 one, iykyk. 💅

cdigidoc reads, digitally signs, verifies files in XAdES format and encrypts, decrypts files in XMLENC format. That's the whole vibe. Periodt. ✨

🦋 SYNOPSIS 🦋

cdigidoc <command(s)> [ -in <input-file> ] [ -out <output-file> ] [ -config <config-file> ]

🌸 DESCRIPTION 🌸

So cdigidoc is an utility that gives you a command line interface to the CDigiDoc library — and that library? It's written in C and it's lowkey carrying the whole operation. It gives you the functionality to:

  • create files in supported DigiDoc formats
  • digitally sign the DigiDoc files using smart cards or other supported cryptographic tokens
  • add time marks and validity confirmations to digital signatures using OCSP protocol
  • verify the digital signatures
  • digitally encrypt and decrypt the DigiDoc files

And not just that — you can also use the cdigidoc utility as a CGI program in web applications created in environments that can't easily use the JDigiDoc library or call the DigiDocService webservice for digital signature functionality. Versatile icon behavior fr fr. 👑

For full documentation, see https://svn.eesti.ee/projektid/idkaart_public/branches/3.6/libdigidoc/doc/SK-CDD-PRG-GUIDE.pdf — go read it, it's giving homework but in a cute way. 🎀

XAdES format: http://www.w3.org/TR/XAdES

XML-ENC format: http://www.w3.org/TR/xmlenc-core

✨ OPTIONS ✨

  • -?, -help — Displays help about command syntax. Your little "what do I even do here" bestie. 🫶
  • -in <input-file> — Specifies the input file name. The recommendation is to pass the full path to the file in this parameter. Like, full path. Don't be shy with it. 💅
  • -out <output-file> — Stores the newly created or modified document in a file. New baby goes here. 🌸
  • -config <configuration-file> — Specifies the CDigiDoc configuration file name. If you leave it unspecified, then the configuration file is looked up from default locations. So if you don't say where, it'll go find it itself. Independent queen. ✨
  • -check-cert <certificate-file-in-pem-format> — Checks the certificate validity status. Used for checking the chosen certificate's validity; returns an OCSP response from the certificate's CA's OCSP responder.
Bestie, heads up: the command is currently not being tested. 😭 If the certificate is valid, then the return code's (RC) value is 0.
  • -new [format] [version] — Creates a new digidoc container with the specified format and version. The current digidoc format in the CDigiDoc library is DIGIDOC-XML, and the default version is 1.3 (the newest, the freshest, the main character 🦋). By using the optional parameter — version — with this command, you can specify an alternative version to be created.
Note: the older SK-XML format is supported only for backward compatibility. It's giving legacy, not giving glow-up. 💀
  • -add <input-file> <mime-type> [<content-type>] [<charset>] — Adds a new data file to a digidoc document. If the digidoc doesn't exist, then it creates one in the default format. Self-sufficient tbh.
    • Input file (required) — Specifies the name of the data file (it is recommended to include the full path in this parameter; the path is removed when writing to the DigiDoc container file).
    • Mime type (required) — Represents the MIME type of the original file like "text/plain" or "application/msword".
    • Content type — Reflects how the original files are embedded in the container — EMBEDDED_BASE64 (used by default). In previous versions, cdigidoc allowed content type EMBEDDED to sign pure xml or text.
    • Charset — UTF-8 encoding is supported and used by default. 💜
  • -sign <pin-code> [[[manifest] [[city] [state] [zip] [country]] [slot(0)] [ocsp(1)] [token-type(PKCS11)] [pkcs12-file-name]] — Adds a digital signature to the digidoc document. You can use it with the following parameters:
    • pin code — In case of Estonian ID cards, pin code2 is used for digital signing. If signing with a software token (PKCS#12 file), then the password of the PKCS#12 file should be entered here.
    • manifest — Role or resolution of the signer.
    • city — City where the signature is created.
    • state — State or province where the signature is created.
    • zip — Postal code of the place where the signature is created.
    • country — Country of origin. ISO 3166-type 2-character country codes are used (e.g. EE).
    • slot — Identifier of the signer's private key's slot on a smartcard. When operating, for example, with a single Estonian ID card, its signature key can be found in slot 1 — which is used by default. The library makes some assumptions about PKCS#11 drivers and card layouts:
      • you have signature and/or authentication keys on the card
      • both key and certificate are in one slot
      • if you have many keys like 1 signature and 1 authentication key, then they are in different slots
      • you can sign with a signature key that has a corresponding certificate with "NonRepudiation" bit set.

You may need to specify a different slot to be used when, for example, operating with multiple smart cards on the same system. If the slot needs to be specified during signing, then the 5 previous optional parameters (manifest, city, state, zip, country) should be filled first (either with the appropriate data or as "" for no value). No skipping steps bestie. 🎀

  • ocsp — Specifies whether an OCSP confirmation is added to the signature that is being created. Possible values are 0 — confirmation is not added; 1 — confirmation is added. By default, the value is set to 1. Parameter value 0 can be used when creating a technical signature. Technical signature is a signature with no OCSP confirmation and no timestamp value. It's giving bare minimum, on purpose. 💅
  • token type — Specifies type of signature token to be used.
    • PKCS11 — default value. Signs with a smart-card or software pkcs11 token
    • CNG — on windows platforms uses CSP/CNG for signing
    • PKCS12 — signs with a PKCS#12 key container that must be entered in the next parameter
  • pkcs12 file name — Name of the PKCS#12 key container file to be used for signing.
  • -mid-sign <phone-no> <per-code> [[<country>(EE)] [<lang>(EST)] [<service>(Testing)] [<manifest>] [<city> <state> <zip>]] — Invokes mobile signing of a ddoc file using Mobile-ID and DigiDocService.

Mobile-ID is a service based on Wireless PKI providing for mobile authentication and digital signing, currently supported by all Estonian and some Lithuanian mobile operators. The Mobile-ID user gets a special SIM card with private keys on it. Hash to be signed is sent over the GSM network to the phone and the user shall enter PIN code to sign. The signed result is sent back over the air. 📱✨

DigiDocService is a SOAP-based web service; access to the service is IP-based and requires a written contract with provider of DigiDocService. You can use Mobile-ID signing with the following parameters:

  • phone-no — Phone number of the signer with the country code in format +xxxxxxxxx (for example +3706234566).
  • per-code — Identification number of the signer (personal national ID number).
  • country — Country of origin. ISO 3166-type 2-character country codes are used (e.g. default is EE).
  • lang — Language for user dialog in mobile phone. 3-character capitalized acronyms are used (e.g. default is EST).
  • service — Name of the service — previously agreed with Application Provider and DigiDocService operator. Maximum length — 20 chars. (e.g. default is Testing).
  • manifest — Role or resolution of the signer.
  • city — City where the signature is created.
  • state — State or province where the signature is created.
  • zip — Postal code of the place where the signature is created.
  • -list — Displays the data file and signature info of a DigiDoc document just read in; verifies all signatures. 🔥
    • Returns Digidoc container data, in format: SignedDoc | <format-identifier> | <version>
    • List of all data files, in format: DataFile | <file identifier> | <file name> | <file size in bytes> | <mime type> | <data file embedding option>
    • List of all signatures (if existing), in format: Signature | <signature identifier> | <signer's key info: last name, first name, personal code> | <verification return code> | <verification result>
    • Signer's certificate information.
    • OCSP responder certificate information.
  • -verify — Returns signature verification results (if signatures exist):
    • Signature | <signature identifier> | <signer's key info: last name, first name, personal code> | <verification return code> | <verification result>
    • Returns signer's certificate and OCSP Responder certificate information.
  • -extract <data-file-id> <output-file> — Extracts the selected data file from the DigiDoc container and stores it in a file. Data file id represents the ID for the data file to be extracted from inside the DigiDoc container (e.g. D0, D1…). Output file represents the name of the output file. Get that file out of there bestie, it's free now. 🦋
  • -denc-list <input-encrypted-file> — Displays the encrypted data and recipient's info of an encrypted document just read in. 🎀
  • -encrecv <certificate-file> [recipient] [KeyName] [CarriedKeyName] — okay so this one is the add-a-whole-new-recipient move 💖 It adds a brand-new recipient certificate plus some extra metadata onto an encrypted document. The certificate file is required — that's the file the public key component gets fetched from, and that key is what encrypts your data. Heads up though: the decryption can only ever be done with the private key that matches that exact certificate, no substitutes 🔐

The input certificate files you use for encryption must come from the file system — PEM encodings are supported ✨ Places you can go get those certificate files include: the Windows Certificate Store (look under "Other Persons"), LDAP directories, or an ID-card sitting in a smart-card reader 🎀 For example, the certificate files for Estonian ID card owners can be retrieved from an LDAP directory at ldap://ldap.sk.ee. You can run that query through your web browser (IE) in this format:

ldap://ldap.sk.ee:389/c=EE??sub?(serialNumber= xxxxxxxxxxx)

where serial Number is the recipient's personal identification number, e,g.38307240240 💅

Other parameters include:

  • recipient — if you leave this unspecified, then the program just assigns the CN value of the certificate passed as the first parameter. Later on, that's used as a command line option to identify the recipient whose key and smart card gets used to decrypt the data. Note: even though this parameter is optional, it's recommended that you pass on the entire CN value from the recipient's certificate as the recipient identifier here — especially when you're dealing with multiple recipients 👯‍♀️
  • KeyName — the sub-element <KeyName> can be added to better identify the key object. Optional, but it can be used to search for the right recipient's key or display its data in an application 🔎
  • CarriedKeyName — the sub-element <CarriedKeyName> can be added to better identify the key object. Also optional, also usable to search for the right recipient's key or display its data in an application 🫶
  • -encrypt-sk <input-file> — this encrypts the data from the given input file and writes the completed encrypted document into a file. It's the recommended one, because it plays nice with other DigiDoc software components — cross-usability, bestie ✨ This command drops the data file you're encrypting into a new DigiDoc container, so handling those encrypted documents later with other DigiDoc applications is fully supported (think DigiDoc3 client) 🎀 The input file is required — it specifies the original data file to be encrypted.

Note: there are also alternative encryption commands, but they are not recommended if you want cross-usability with other DigiDoc software components:

  • -encrypt <input-file> — encrypts the data from the given input file and writes the completed encrypted document into a file. Should be used only for encrypting small documents that are already in DIGIDOC-XML format. The input file (required) specifies the original data file to be encrypted.
  • -encrypt-file <input-file> <output-file> — encrypts the input file and writes to the output file. Should be used only for encrypting large documents that are already in DIGIDOC-XML format. Note that this command is not currently tested 💀 The input file (required) specifies the original data file to be encrypted. The output file (required) specifies the name of the output file, which will be created in the current encrypted document format (ENCDOC-XML ver 1.0), with the file extension .cdoc.
  • -decrypt-sk <input-file> <pin> [pkcs12-file] [slot(0)] — decrypts and possibly decompresses the encrypted file that was just read in, and writes it to an output file. It expects the encrypted file to be inside a DigiDoc container 📦 The input file (required) specifies the input file's name. Pin (required) is the recipient's pin1 (in the context of Estonian ID cards). pkcs12-file (optional) specifies the PKCS#12 file if the decrypting is done with a software token. The slot default is slot 0, which contains the Estonian ID cards authentication keypair — you can use this parameter to decrypt with a key from the second ID card attached to the computer, etc. 👑

Note: there are also alternative commands for decryption, depending on the encrypted file's format, size, and the certificate type used for decrypting it.

  • -decrypt <input-file> <pin> [pkcs12-file] [slot(0)] — offers the same functionality as -decrypt-sk, and should be used for decrypting small files (which do not need to be inside a DigiDoc container). The input file (required) specifies the input file's name. Pin (required) is the recipient's pin1 (in contexts of Estonian ID cards). pkcs12-file (optional) specifies the PKCS#12 file if the decrypting is done with a software token. The slot default is slot 0, containing the Estonian ID cards authentication keypair — this parameter can be used to decrypt with a key from the second ID card attached to the computer, etc. 🌸
  • -decrypt-file <input-file> <output-file> <pin> [pkcs12-file] — offers the same functionality as -decrypt for decrypting documents, and should be used for decrypting large files (which do not need to be inside a DigiDoc container). It expects the encrypted data not to be compressed. Note that this command is not currently tested 😭 The input file (required) specifies the encrypted file to be decrypted. The output file (required) specifies the output file name. Pin (required) is the recipient's pin1 (in contexts of Estonian ID cards). pkcs12-file (optional) specifies the PKCS#12 file if the decrypting is done with a software token.
  • -calc-sign <cert-file> [<manifest>] [<city> <state> <zip> <country>] — this is the alternative to -sign that you'd use inside CGI programs 👩‍💻 It adds the signer's certificate in pem format, and optionally the manifest plus the signer's address, then calculates the final hash value that's gonna be signed. That value comes out hex-encoded and can now be sent to the user's computer to be signed using a web plugin 🌈 This command creates an incomplete signature — it lacks the actual RSA signature value. You have to store it in a temporary file and complete it later with the -add-sign-value command.
    • -IP "-add-sign-value <sign-value-file> <sign-id>" — offers an alternative to the -sign command, for use in CGI programs. It adds an RSA signature hex-encoded value to an incomplete signature that was created with the -calc-sign command. This signature is still missing the ocsp timemark, which you can now grab using the -get-confirmation command, producing a complete XAdES signature ✨
  • -get-confirmation <signature-id> — adds an OCSP confirmation to a DigiDoc file's signature. That's it, that's the whole job, and it slays 💅

💖 EXAMPLES 💖

cdigidoc -new DIGIDOC-XML 1.3 -add <input-file> <mime> -sign <pin2> -out <output-file>

Creates a new signed document in DIGIDOC-XML 1.3 format, adds one input file, signs with a smartcard using the default signature slot, and writes to a signed document file 📝

cdigidoc -in <signed-input-file> -list

Reads in a signed document, verifies signatures, and prints the results to the console 🔍

cdigidoc -in <signed-input-file> -extract D0 <output-file>

Reads in a signed document, finds the first signed document, and writes it to the output file ✂️

cdigidoc -encrecv <recipient1.pem> -encrecv <recipient2.pem> -encrypt-sk <file-to-encrypt> -out <output-file.cdoc>

Creates a new encrypted file by encrypting the input file — which is encrypted using AES-128 — and encrypts the generated random transport key using RSA for two possible recipients, identified by their certificates. The transport key is encrypted using RSA1.5 🔐

cdigidoc -decrypt-sk <input-file.cdoc> <pin1> -out <output-file>

Reads in an encrypted file and decrypts it with the smartcard's first keypair (the Estonian ID cards authentication key), then writes the decrypted data to the given output file 💳

cdigidoc -decrypt-sk <input-file.cdoc> <password> <keyfile.p12d> -out <output-file>

Reads in an encrypted file and decrypts it with a PKCS#12 key-container, then writes the decrypted data to the given output file 🗝️

👑 AUTHORS 👑

AS Sertifitseerimiskeskus (Certification Centre Ltd.) — iconic, legendary, no notes 💜

🦋 SEE ALSO 🦋

and that's the whole page bestie, you made it to the end 🎀 this edition is version 3.10.5.0, dated 20.05.2025, and it lives under the name CDIGIDOC(1) in the manual. go forth and encrypt responsibly, mwah 💖✨

📦 where this page comes from