1dcmsign(1)                        OFFIS DCMTK                       dcmsign(1)
2
3
4

NAME

6       dcmsign - Sign and Verify DICOM Files
7
8

SYNOPSIS

10       dcmsign [options] dcmfile-in [dcmfile-out]
11

DESCRIPTION

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
17       Five digital signature operations are supported:
18
19       • 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.

PARAMETERS

26       dcmfile-in   DICOM input filename to be processed
27
28       dcmfile-out  DICOM output filename

OPTIONS

30   general options
31         -h    --help
32                 print this help text and exit
33
34               --version
35                 print version information and exit
36
37               --arguments
38                 print expanded command line arguments
39
40         -q    --quiet
41                 quiet mode, print no warnings and errors
42
43         -v    --verbose
44                 verbose mode, print processing details
45
46         -d    --debug
47                 debug mode, print debug information
48
49         -ll   --log-level  [l]evel: string constant
50                 (fatal, error, warn, info, debug, trace)
51                 use level l for the logger
52
53         -lc   --log-config  [f]ilename: string
54                 use config file f for the logger
55   input options
56       input file format:
57
58         +f    --read-file
59                 read file format or data set (default)
60
61         +fo   --read-file-only
62                 read file format only
63
64         -f    --read-dataset
65                 read data set without file meta information
66
67       input transfer syntax:
68
69         -t=   --read-xfer-auto
70                 use TS recognition (default)
71
72         -td   --read-xfer-detect
73                 ignore TS specified in the file meta header
74
75         -te   --read-xfer-little
76                 read with explicit VR little endian TS
77
78         -tb   --read-xfer-big
79                 read with explicit VR big endian TS
80
81         -ti   --read-xfer-implicit
82                 read with implicit VR little endian TS
83
84       handling of defined length UN elements:
85
86         -uc   --retain-un
87                 retain elements as UN (default)
88
89         +uc   --convert-un
90                 convert to real VR if known
91   signature commands
92               --verify
93                 verify all signatures (default)
94
95         +s    --sign  [p]rivate key file, [c]ertificate file: string
96                 create signature in main object
97
98         +si   --sign-item  [k]eyfile, [c]ertfile, [i]tem location: string
99                 create signature in sequence item
100
101         +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
105         +r    --remove  [s]ignature UID: string
106                 remove signature
107
108         +ra   --remove-all
109                 remove all signatures from data set
110   general signature options
111       key and certificate file format:
112
113         -pem  --pem-keys
114                 read keys/certificates as PEM file (default)
115
116         -der  --der-keys
117                 read keys/certificates as DER file
118
119       signature format:
120
121         -fn   --format-new
122                 use correct DICOM signature format (default)
123
124         -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
131         +rv   --verify-if-present
132                 verify signatures if present, pass otherwise
133                 (default)
134
135         +rg   --require-sig
136                 fail if no signature at all is present
137
138         +rc   --require-creator
139                 fail if no creator RSA signature is present
140
141         +ru   --require-auth
142                 fail if no auth RSA signature is present
143
144         +rs   --require-sr
145                 fail if no SR RSA signature is present
146
147       timestamp verification:
148
149         +tv   --verify-ts
150                 verify certified timestamp if present (default)
151
152         -tv   --ignore-ts
153                 ignore certified timestamps
154
155         +tr   --require-ts
156                 fail if no certified timestamp is present
157
158       certification authority:
159
160         +cf   --add-cert-file
161                 [f]ilename: string
162                 add trusted certificate file to cert store
163
164         +uf   --add-ucert-file
165                 [f]ilename: string
166                 add untrusted intermediate certificate file
167
168         +cd   --add-cert-dir
169                 [d]irectory: string
170                 add certificates in d to cert store
171
172         +cr   --add-crl-file
173                 [f]ilename: string
174                 add certificate revocation list file
175                 (implies --enable-crl-vfy)
176
177         +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
182         +ps   --std-passwd
183                 prompt user to type password on stdin (default)
184
185         +pw   --use-passwd  [p]assword: string
186                 use specified password
187
188         -pw   --null-passwd
189                 use empty string as password
190
191       digital signature profile:
192
193         -pf   --profile-none
194                 don't enforce any signature profile (default)
195
196         +pb   --profile-base
197                 enforce base RSA signature profile
198
199         +pc   --profile-creator
200                 enforce creator RSA signature profile
201
202         +pa   --profile-auth
203                 enforce authorization signature profile
204
205         +pr   --profile-sr
206                 enforce SR RSA signature profile
207
208         +pv   --profile-srv
209                 enforce SR RSA signature profile (verification)
210
211       MAC algorithm:
212
213         +mr   --mac-ripemd160
214                 use RIPEMD 160 (default)
215
216         +ms   --mac-sha1
217                 use SHA-1
218
219         +mm   --mac-md5
220                 use MD 5
221
222         +m2   --mac-sha256
223                 use SHA-256
224
225         +m3   --mac-sha384
226                 use SHA-384
227
228         +m5   --mac-sha512
229                 use SHA-512
230
231       signature purpose:
232
233         +lp   --list-purposes
234                 show list of signature purpose codes and exit
235
236         -sp   --no-sig-purpose
237                 do not add signature purpose (default)
238
239         +sp   --sig-purpose
240                 [p]urpose code: integer (1..18)
241                 add digital signature purpose code p
242
243       tag selection:
244
245         -t    --tag
246                 [t]ag: "gggg,eeee" or dictionary name
247                 sign only specified tag
248                 (this option can be specified multiple times)
249
250         -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
255         -ts   --timestamp-off
256                 do not create timestamp (default)
257
258         +ts   --timestamp-file  [t]sq-filename, [u]id-filename: string
259                 create timestamp query file t and uid file u
260
261       timestamp MAC algorithm (only with --timestamp-file):
262
263         +tm2  --ts-mac-sha256
264                 use SHA-256 (default)
265
266         +tm3  --ts-mac-sha384
267                 use SHA-384
268
269         +tm5  --ts-mac-sha512
270                 use SHA-512
271
272         +tmr  --ts-mac-ripemd160
273                 use RIPEMD 160
274
275         +tms  --ts-mac-sha1
276                 use SHA-1 (not recommended)
277
278         +tmm  --ts-mac-md5
279                 use MD5 (not recommended)
280
281       timestamp query nonce options (only with --timestamp-file):
282
283         +tn   --ts-use-nonce
284                 include random nonce (default)
285
286         -tn   --ts-no-nonce
287                 do not include nonce
288
289       timestamp certificate inclusion options (only with --timestamp-file):
290
291         +tc   --ts-request-cert
292                 request TSA certificate in timestamp (default)
293
294         -tc   --ts-no-cert
295                 do not request TSA certificate in timestamp
296
297       timestamp policy options (only with --timestamp-file):
298
299         -tp   --ts-no-policy
300                 do not specify ts policy (default)
301
302         +tp   --ts-policy  [p]olicy-OID: string
303                 request timestamp policy p
304   output options
305       output transfer syntax:
306
307         +t=   --write-xfer-same
308                 write with same TS as input (default)
309
310         +te   --write-xfer-little
311                 write with explicit VR little endian TS
312
313         +tb   --write-xfer-big
314                 write with explicit VR big endian TS
315
316         +ti   --write-xfer-implicit
317                 write with implicit VR little endian TS
318
319       length encoding in sequences and items:
320
321         +e    --length-explicit
322                 write with explicit lengths (default)
323
324         -e    --length-undefined
325                 write with undefined lengths
326
327       other output options:
328
329         +d    --dump  [f]ilename: string
330                 dump byte stream fed into the MAC codec to file
331                 (only with --sign or --sign-item)

NOTES

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.

LOGGING

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.

COMMAND LINE

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).

EXIT CODES

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

ENVIRONMENT

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-2022  by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
503       Germany.
504
505
506
507Version 3.6.7                   Fri Apr 22 2022                     dcmsign(1)
Impressum