1dcmsign(1) OFFIS DCMTK dcmsign(1)
2
6 dcmsign - Sign and Verify DICOM Files
7
10 dcmsign [options] dcmfile-in [dcmfile-out]
11
13 The dcmsign utility reads a DICOM file (dcmfile-in), performs a digital
14 signature operation and, if any modification has taken place, writes
15 the DICOM object to an output file (dcmfile-out).
16 Five digital signature operations are supported:
18 • verification of all signatures in the DICOM file
20 • creation of a new digital signature located in the main dataset,
21 • creation of a new digital signature in an item of a sequence embedded
22 within the dataset,
23 • removal of a single digital signature from the DICOM file, and
24 • removal of all digital signatures from the DICOM file.
26 dcmfile-in DICOM input filename to be processed
27 dcmfile-out DICOM output filename
30 general options
31 -h --help
32 print this help text and exit
33 --version
35 print version information and exit
36 --arguments
38 print expanded command line arguments
39 -q --quiet
41 quiet mode, print no warnings and errors
42 -v --verbose
44 verbose mode, print processing details
45 -d --debug
47 debug mode, print debug information
48 -ll --log-level [l]evel: string constant
50 (fatal, error, warn, info, debug, trace)
51 use level l for the logger
52 -lc --log-config [f]ilename: string
54 use config file f for the logger
55 input options
56 input file format:
57 +f --read-file
59 read file format or data set (default)
60 +fo --read-file-only
62 read file format only
63 -f --read-dataset
65 read data set without file meta information
66 input transfer syntax:
68 -t= --read-xfer-auto
70 use TS recognition (default)
71 -td --read-xfer-detect
73 ignore TS specified in the file meta header
74 -te --read-xfer-little
76 read with explicit VR little endian TS
77 -tb --read-xfer-big
79 read with explicit VR big endian TS
80 -ti --read-xfer-implicit
82 read with implicit VR little endian TS
83 handling of defined length UN elements:
85 -uc --retain-un
87 retain elements as UN (default)
88 +uc --convert-un
90 convert to real VR if known
91 signature commands
92 --verify
93 verify all signatures (default)
94 +s --sign [p]rivate key file, [c]ertificate file: string
96 create signature in main object
97 +si --sign-item [k]eyfile, [c]ertfile, [i]tem location: string
99 create signature in sequence item
100 +t --insert-timestamp ts[q]file, ts[r]file [u]idfile: string
102 insert certified timestamp from ts response r
103 from timestamp query q at signature UID u
104 +r --remove [s]ignature UID: string
106 remove signature
107 +ra --remove-all
109 remove all signatures from data set
110 general signature options
111 key and certificate file format:
112 -pem --pem-keys
114 read keys/certificates as PEM file (default)
115 -der --der-keys
117 read keys/certificates as DER file
118 signature format:
120 -fn --format-new
122 use correct DICOM signature format (default)
123 -fo --format-old
125 use old (pre-3.5.4) DCMTK signature format, non-conformant
126 if signature includes compressed pixel data. This option should
127 only be used to verify signatures in the old format.
128 signature verification options (only with –verify)
129 signature verification:
130 +rv --verify-if-present
132 verify signatures if present, pass otherwise
133 (default)
134 +rg --require-sig
136 fail if no signature at all is present
137 +rc --require-creator
139 fail if no creator RSA signature is present
140 +ru --require-auth
142 fail if no auth RSA signature is present
143 +rs --require-sr
145 fail if no SR RSA signature is present
146 timestamp verification:
148 +tv --verify-ts
150 verify certified timestamp if present (default)
151 -tv --ignore-ts
153 ignore certified timestamps
154 +tr --require-ts
156 fail if no certified timestamp is present
157 certification authority:
159 +cf --add-cert-file
161 [f]ilename: string
162 add trusted certificate file to cert store
163 +uf --add-ucert-file
165 [f]ilename: string
166 add untrusted intermediate certificate file
167 +cd --add-cert-dir
169 [d]irectory: string
170 add certificates in d to cert store
171 +cr --add-crl-file
173 [f]ilename: string
174 add certificate revocation list file
175 (implies --enable-crl-vfy)
176 +cl --enable-crl-vfy
178 enable certificate revocation list verification.fi
179 signature creation options (only with –sign or –sign-item)
180 private key password:
181 +ps --std-passwd
183 prompt user to type password on stdin (default)
184 +pw --use-passwd [p]assword: string
186 use specified password
187 -pw --null-passwd
189 use empty string as password
190 digital signature profile:
192 -pf --profile-none
194 don't enforce any signature profile (default)
195 +pb --profile-base
197 enforce base RSA signature profile
198 +pc --profile-creator
200 enforce creator RSA signature profile
201 +pa --profile-auth
203 enforce authorization signature profile
204 +pr --profile-sr
206 enforce SR RSA signature profile
207 +pv --profile-srv
209 enforce SR RSA signature profile (verification)
210 MAC algorithm:
212 +mr --mac-ripemd160
214 use RIPEMD 160 (default)
215 +ms --mac-sha1
217 use SHA-1
218 +mm --mac-md5
220 use MD 5
221 +m2 --mac-sha256
223 use SHA-256
224 +m3 --mac-sha384
226 use SHA-384
227 +m5 --mac-sha512
229 use SHA-512
230 signature purpose:
232 +lp --list-purposes
234 show list of signature purpose codes and exit
235 -sp --no-sig-purpose
237 do not add signature purpose (default)
238 +sp --sig-purpose
240 [p]urpose code: integer (1..18)
241 add digital signature purpose code p
242 tag selection:
244 -t --tag
246 [t]ag: "gggg,eeee" or dictionary name
247 sign only specified tag
248 (this option can be specified multiple times)
249 -tf --tag-file [f]ilename: string
251 read list of tags from text file.fi
252 timestamp creation options (only with –sign or –sign-item)
253 timestamp creation:
254 -ts --timestamp-off
256 do not create timestamp (default)
257 +ts --timestamp-file [t]sq-filename, [u]id-filename: string
259 create timestamp query file t and uid file u
260 timestamp MAC algorithm (only with --timestamp-file):
262 +tm2 --ts-mac-sha256
264 use SHA-256 (default)
265 +tm3 --ts-mac-sha384
267 use SHA-384
268 +tm5 --ts-mac-sha512
270 use SHA-512
271 +tmr --ts-mac-ripemd160
273 use RIPEMD 160
274 +tms --ts-mac-sha1
276 use SHA-1 (not recommended)
277 +tmm --ts-mac-md5
279 use MD5 (not recommended)
280 timestamp query nonce options (only with --timestamp-file):
282 +tn --ts-use-nonce
284 include random nonce (default)
285 -tn --ts-no-nonce
287 do not include nonce
288 timestamp certificate inclusion options (only with --timestamp-file):
290 +tc --ts-request-cert
292 request TSA certificate in timestamp (default)
293 -tc --ts-no-cert
295 do not request TSA certificate in timestamp
296 timestamp policy options (only with --timestamp-file):
298 -tp --ts-no-policy
300 do not specify ts policy (default)
301 +tp --ts-policy [p]olicy-OID: string
303 request timestamp policy p
304 output options
305 output transfer syntax:
306 +t= --write-xfer-same
308 write with same TS as input (default)
309 +te --write-xfer-little
311 write with explicit VR little endian TS
312 +tb --write-xfer-big
314 write with explicit VR big endian TS
315 +ti --write-xfer-implicit
317 write with implicit VR little endian TS
318 length encoding in sequences and items:
320 +e --length-explicit
322 write with explicit lengths (default)
323 -e --length-undefined
325 write with undefined lengths
326 other output options:
328 +d --dump [f]ilename: string
330 dump byte stream fed into the MAC codec to file
331 (only with --sign or --sign-item)
333 Files and Parameters
334 The dcmsign utility reads and writes a number of files and file formats
335 which are described in this section.
336 Public Key Certificates are expected in X.509v3 format, either with PEM
337 or DER encoding. The dcmsign utility currently supports RSA and DSA
338 public keys, although only RSA keys are defines in the Security
339 Profiles of the DICOM standard.
340 Private Keys are expected in PEM or DER encoding. PEM is recommended
341 (and default) because this allows one to keep private keys in encrypted
342 form. Command line options control the behavior of dcmsign when an
343 encrypted PEM key is opened (see above). In general it is not
344 recommended to specify the encryption password in the command line
345 because the command line may be visible to other processes in the
346 system, e.g. 'ps -ef'.
347 By default, dcmsign will create a signature covering all data elements
348 in the dataset or item. This default can be overridden by explicitly
349 specifying a list of data elements (attribute tags). This list can
350 either be read from a file or specified on the command line or both (in
351 this case the attribute tags are combined).
352 On the command line, attribute tags are specified as
353 --tag "gggg,eeee" where gggg and eeee are the hexadecimal group
354 and element numbers
355 --tag "Name" where 'Name' is a symbolic attribute name from
356 the DICOM dictionary (see below).
357 When attribute tags are read from file with the --tag-file option, a
358 plain text file is expected. Tags within the file are either symbolic
359 names from the data dictionary or have the format (gggg,eeee) (with
360 braces). Tags are separated by one or more whitespace characters.
361 The currently selected digital signature profile may specify additional
362 attribute tags required to be included in the signature, which will be
363 silently added.
364 The --sign-item operation requires a location string that describes in
365 which sequence item a signature is to be created. The location string
366 has the following format:
367 SequenceName[index].SequenceName[index].SequenceName[index](...)
368 where SequenceName is either a symbolic attribute name from the data
369 dictionary or a numeric tag in the format (gggg,eeee) and index is an
370 unsigned decimal integer for the item number, starting with zero for
371 the first item in a sequence. As an example, the following location
372 string
373 ReferencedSeriesSequence[0].ReferencedImageSequence[1]
374 would cause a digital signature to be created in the second item of the
375 ReferencedImageSequence (0008,1140) which is located in the first item
376 of the ReferencedSeriesSequence (0008,1115) which is located in the
377 main DICOM dataset.
378 Certified Timestamps
379 Starting with release 3.6.6, dcmsign offers support for certified
380 timestamps according to RFC 3161. For now, the tool does not implement
381 any of the network protocols defined in RFC 3161 for communicating with
382 a timestamp authority (TSA), but it can write a timestamp query (TSQ)
383 during signature creation, and the new command --insert-timestamp will
384 read a timestamp response (TSR) from file and add it to the DICOM
385 digital signature. Since a DICOM file can contain multiple signatures,
386 a 'UID file' (which contains the Digital Signature UID) is used to
387 identify the signature to which the TSR should be added. The dcmsign
388 tool will also perform various consistency checks before storing the
389 timestamp.
390 During signature verification, the presence of a certified timestamp
391 will be detected and the timestamp will also be verified unless option
392 --ignore-ts was used. Signature verification and timestamp verification
393 use a common certificate store to check the certificates of the DICOM
394 signature and the timestamp. This store can be populated with the
395 options --add-cert-file and --add-cert-dir, which both add trusted CA
396 certificates, --add-ucert-file, which adds an untrusted intermediate CA
397 certificate, and --add-crl-file, which adds a certificate revocation
398 list.
399 Hashed Certificate Directories
400 Instead of adding CA certificates and certificate revocation lists
401 (CRLs) manually using --add-cert-file and --add-crl-file, the user can
402 set-up a directory where dcmsign will look-up and load certificates and
403 CRLs from as needed, using --add-cert-dir.
404 Th directory should contain one certificate or CRL per file in PEM
405 format, with a filename of the form hash.N for a certificate, or
406 hash.rN for a CRL. The hash is the value returned by
407 openssl x509 -hash -noout -in <filename.pem> (for a certificate)
408 openssl crl -hash -noout -in <filename.pem> (for a CRL)
409 The .N or .rN suffix is a sequence number that starts at zero, and is
410 incremented consecutively for each certificate or CRL with the same
411 hash value. Gaps in the sequence numbers are not supported, it is
412 assumed that there are no more objects with the same hash beyond the
413 first missing number in the sequence.
414 CRLs will only be verified when option --enable-crl-vfy is specified.
415 In this case, dcmsign will expect a CRL to be present for each CA and
416 will fail signature verification if no CRL can be found for the CA that
417 issued the signer certificate.
419 The level of logging output of the various command line tools and
420 underlying libraries can be specified by the user. By default, only
421 errors and warnings are written to the standard error stream. Using
422 option --verbose also informational messages like processing details
423 are reported. Option --debug can be used to get more details on the
424 internal activity, e.g. for debugging purposes. Other logging levels
425 can be selected using option --log-level. In --quiet mode only fatal
426 errors are reported. In such very severe error events, the application
427 will usually terminate. For more details on the different logging
428 levels, see documentation of module 'oflog'.
429 In case the logging output should be written to file (optionally with
430 logfile rotation), to syslog (Unix) or the event log (Windows) option
431 --log-config can be used. This configuration file also allows for
432 directing only certain messages to a particular output stream and for
433 filtering certain messages based on the module or application where
434 they are generated. An example configuration file is provided in
435 <etcdir>/logger.cfg.
437 All command line tools use the following notation for parameters:
438 square brackets enclose optional values (0-1), three trailing dots
439 indicate that multiple values are allowed (1-n), a combination of both
440 means 0 to n values.
441 Command line options are distinguished from parameters by a leading '+'
442 or '-' sign, respectively. Usually, order and position of command line
443 options are arbitrary (i.e. they can appear anywhere). However, if
444 options are mutually exclusive the rightmost appearance is used. This
445 behavior conforms to the standard evaluation rules of common Unix
446 shells.
447 In addition, one or more command files can be specified using an '@'
448 sign as a prefix to the filename (e.g. @command.txt). Such a command
449 argument is replaced by the content of the corresponding text file
450 (multiple whitespaces are treated as a single separator unless they
451 appear between two quotation marks) prior to any further evaluation.
452 Please note that a command file cannot contain another command file.
453 This simple but effective approach allows one to summarize common
454 combinations of options/parameters and avoids longish and confusing
455 command lines (an example is provided in file <datadir>/dumppat.txt).
457 The dcmsign utility uses the following exit codes when terminating.
458 This enables the user to check for the reason why the application
459 terminated.
460 general
461 EXITCODE_NO_ERROR 0
462 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
463 EXITCODE_NOOPENSSL 5
464 input file errors
465 EXITCODE_CANNOT_READ_INPUT_FILE 20
466 EXITCODE_NO_INPUT_FILES 21
467 EXITCODE_CANNOT_READ_TAG_FILE 30
468 EXITCODE_CANNOT_READ_TSQ_FILE 31
469 EXITCODE_CANNOT_READ_TSR_FILE 32
470 EXITCODE_CANNOT_READ_UID_FILE 33
471 output file errors
472 EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40
473 EXITCODE_CANNOT_WRITE_SUPPORT_FILE 46
474 processing errors
475 EXITCODE_CANNOT_ACCESS_SIGNATURE 80
476 EXITCODE_CANNOT_ACCESS_TS 81
477 EXITCODE_CANNOT_INSERT_TS 82
478 EXITCODE_SIGNATURE_REMOVAL_FAILED 83
479 EXITCODE_SIGNATURE_UID_NOT_FOUND 84
480 EXITCODE_SIGNATURE_CREATION_FAILED 85
481 EXITCODE_SYNTAX_ERROR_IN_TAG_FILE 86
482 EXITCODE_TS_CONSISTENCY_CHECK_FAILED 87
483 application specific errors
484 EXITCODE_NO_SIGNATURES_PRESENT 100
485 EXITCODE_SIGNATURE_VERIFICATION_FAILED 101
486 EXITCODE_SIGNATURE_VERIFICATION_POLICY 102
488 The dcmsign utility will attempt to load DICOM data dictionaries
489 specified in the DCMDICTPATH environment variable. By default, i.e. if
490 the DCMDICTPATH environment variable is not set, the file
491 <datadir>/dicom.dic will be loaded unless the dictionary is built into
492 the application (default for Windows).
493 The default behavior should be preferred and the DCMDICTPATH
494 environment variable only used when alternative data dictionaries are
495 required. The DCMDICTPATH environment variable has the same format as
496 the Unix shell PATH variable in that a colon (':') separates entries.
497 On Windows systems, a semicolon (';') is used as a separator. The data
498 dictionary code will attempt to load each file specified in the
499 DCMDICTPATH environment variable. It is an error if no data dictionary
500 can be loaded.
502 Copyright (C) 2000-2021 e.V., Escherweg 2, 26121 Oldenburg, Germany.
503Version 3.6.6 Thu Jan 14 2021 dcmsign(1)