CDIGIDOC(1)cdigidoc man page CDIGIDOC(1)NAMEcdigidoc - read, digitally sign, verify files in XAdES format and
encrypt, decrypt files in XMLENC format
SYNOPSIScdigidoc <command(s)> [ -in <input-file> ] [ -out <output-file> ] [
-config <config-file> ]
DESCRIPTIONcdigidoc is an utility which provides a command line interface to the
CDigiDoc library, which is a library in C programming language offering
the the functionality to create files in supported DigiDoc formats,
sigitally sign the DigiDoc files using smart cards or other supported
cryptographic tokens, add time marks and validity confirmations to dig‐
ital signatures using OCSP protocol, verify the digital signatures, and
digitally encrypt and decrypt the DigiDoc files. It is also possible to
use cdigidoc utility as a CGI program in web applications created in
environments that cannot easily use the JDigiDoc library or call the
DigiDocService webservice for digital signature functionality.
For full documentation, see
https://svn.eesti.ee/projektid/idkaart_public/branches/3.6/libdigidoc/doc/SK-CDD-PRG-GUIDE.pdf
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.
-in <input-file>
Specifies the input file name. It is recommended to pass the
full path to the file in this parameter.
-out <output-file>
Stores the newly created or modified document in a file.
-config <configuration-file>
Specifies the CDigiDoc configuration file name. If left unspeci‐
fied, then the configuration file is looked up from default
locations.
-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. Note that the command is cur‐
rently 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 CDigiDoc library is DIGI‐
DOC-XML, default version is 1.3 (newest). 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.
-add <input-file> <mime-type> [<content-type>] [<charset>]
Adds a new data file to a digidoc document. If digidoc doesn't
exist then creates one in the default format.
Input file (required)
Specifies the name of the data file (it is recommended to
include full path in this parameter; the path is removed
when writing to 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 con‐
tainer 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 following parameters:
pin code
In case of Estonian ID cards, pin code2 is used for digi‐
tal signing. If signing with a software token (PKCS#12
file), then the password of 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 smart‐
card. 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 authenti‐
cation key then they are in different slots
- you can sign with signature key that has a correspond‐
ing 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 sign‐
ing, 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).
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 sig‐
nature is a signature with no OCSP confirmation and no
timestamp value.
token type
Speciafies type of signature token to be use.
- PKCS11 default value. Signs with a smart-card or soft‐
ware 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)] [<ser‐
vice>(Testing)] [<manifest>] [<city> <state> <zip>]]
Invokes mobile signing of a ddoc file using Mobile-ID and Digi‐
DocService. Mobile-ID is a service based on Wireless PKI pro‐
viding 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 ser‐
vice, 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 for‐
mat +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 data
file to be extracted from inside the DigiDoc container (e.g. D0,
D1…). Output file represents the name of the output file.
-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]
Adds a new recipient certificate and other metadata to an
encrypted document. Certificate file (required) specifies the
file from which the public key component is fetched for encrypt‐
ing the data. The decryption can be performed only by using pri‐
vate key corresponding to that certificate. The input certifi‐
cate files for encryption must come from the file system (PEM
encodings are supported). Possible sources where the certificate
files can be obtained from include: Windows Certificate Store
("Other Persons"), LDAP directories, ID-card in smart-card
reader. For example the certificate files for Estonian ID card
owners can be retrieved from a LDAP directory at
ldap://ldap.sk.ee. The query can be made in following format
through the web browser (IE):
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 left unspecified, then the program assigns the CN
value of the certificate passwed as first parameter.
This is later used as a command line option to identify
the recipient whose key and smart card is used to decrypt
the data. Note: Although this parameter is optional, it
is recommended to pass on the entire CN value from the
recipient’s certificate as the recipient identifier here,
especially when dealing with multiple recipients.
KeyName
Sub-element <KeyName> can be added to better identify the
key object. Optional, but can be used to search for the
right recipient’s key or display its data in an applica‐
tion.
CarriedKeyName
Sub-element <CarriedKeyName> can be added to better iden‐
tify the key object. Optional, but can be used to search
for the right recipient’s key or display its data in an
application.
-encrypt-sk <input-file>
Encrypts the data from the given input file and writes the com‐
pleted encrypted document in a file. Recommended for providing
cross-usability with other DigiDoc software components. This
command places the data file to be encrypted in a new DigiDoc
container. Therefore handling such encrypted documents later
with other DigiDoc applications is fully supported (e.g. Digi‐
Doc3 client). Input file (required) specifies the original data
file to be encrypted. Note: There are also alternative encryp‐
tion commands which are however not recommended for providing
cross-usability with other DigiDoc software components:
-encrypt <input-file>
Encrypts the data from the given input file and writes
the completed encrypted document in a file. Should be
used only for encrypting small documents, already in
DIGIDOC-XML format. Input file (required) specifies the
original data file to be encrypted.
-encrypt-file <input-file> <output-file>
Encrypts the input file and writes to output file. Should
be used only for encrypting large documents, already in
DIGIDOC-XML format. Note that the command in not cur‐
rently tested. Input file (required) specifies the orig‐
inal data file to be encrypted. Output file (required)
specifies the name of the output file which will be cre‐
ated in the current encrypted document format (ENCDOC-XML
ver 1.0), with file extension .cdoc.
-decrypt-sk <input-file> <pin> [pkcs12-file] [slot(0)]
Decrypts and possibly decompresses the encrypted file just read
in and writes to output file. Expects the encrypted file to be
inside a DigiDoc container. Input file (required) specifies the
input file’s name. Pin (required) represents the recipient’s
pin1 (in context of Estonian ID cards). pkcs12-file (optional)
specifies the PKCS#12 file if decrypting is done with a software
token. slot deafult is slot 0 containing 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.
Note: There are also alternative commands for decryption,
depending on the encrypted file’s format, size and the certifi‐
cate type used for decrypting it.
-decrypt <input-file> <pin> [pkcs12-file] [slot(0)]
Offers same functionality as -decrypt-sk, should be used
for decrypting small files (which do not need to be
inside a DigiDoc container). Input file (required) spec‐
ifies the input file’s name. Pin (required) represents
the recipient’s pin1 (in contexts of Estonian ID cards).
pkcs12-file (optional) specifies the PKCS#12 file if
decrypting is done with a software token. slot deafult
is slot 0 containing 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 same functionality as -decrypt for decrypting doc‐
uments, should be used for decrypting large files (which
do not need to be inside a DigiDoc container). Expects
the encrypted data not to be compressed. Note that the
command is not currently tested. Input file (required)
specifies the encrypted file to be decrypted. Output
file (required) specifies the output file name. Pin
(required) represents the recipient’s pin1 (in contexts
of Estonian ID cards). pkcs12-file (optional) specifies
the PKCS#12 file if decrypting is done with a software
token.
-calc-sign <cert-file> [<manifest>] [<city> <state> <zip> <country>]
Offers an alternative to -sign command to be used in CGI
pograms. Adds signers certificate in pem format and optionally
manifest and signers address and calculates the final hash value
to be signed. This value is hex-encoded and can now be sent to
users computer to be signed using a web plugin. This command
creates an incomplete signature that lacks the actual RSA signa‐
ture value. It must be stored in a temporary file and later com‐
pleted using the -add-sign-value command. -IP "-add-sign-value
<sign-value-file> <sign-id>" Offers an alternative to -sign com‐
mand to be used in CGI pograms. Adds an RSA signature hex-
encoded value to an incomplete signature created using the
-calc-sign command. This signature is still lacking the ocsp
timemark, that can now be obtained using the -get-confirmation
command producing a complete XAdES signature.
-get-confirmation <signature-id>
Adds an OCSP confirmation to a DigiDoc file’s signature.
EXAMPLEScdigidoc-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 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 console.
cdigidoc-in <signed-input-file> -extract D0 <output-file>
Reads in a signed document, finds the first signed document and
writes it to output file.
cdigidoc-encrecv <recipient1.pem> -encrecv <recipient2.pem> -encrypt-
sk <file-to-encrypt> -out <output-file.cdoc>
Creates a new encypted file by encrypting input file that is
encrypted using AES-128 and encrypts the generated randome
transport key using RSA for two possible recipients identified
by their certificates. Transport key is encrypted using RSA1.5.
cdigidoc-decrypt-sk <input-file.cdoc> <pin1> -out <output-file>
Reads in encrypted file and decrypts it with smartcards first
keypair (Estonian ID cards authentication key) and writes
decrypted data to given putput file.
cdigidoc-decrypt-sk <input-file.cdoc> <password> <keyfile.p12d> -out
<output-file>
Reads in encrypted file and decrypts it with a PKCS#12 key-con‐
tainer and writes decrypted data to given putput file.
AUTHORS
AS Sertifitseerimiskeskus (Certification Centre Ltd.)
SEE ALSOdigidoc-tool(1), qesteidutil(1), qdigidocclient(1), qdigidoccrypto(1)3.7.2.0 19.10.2013 CDIGIDOC(1)
