4 \page dcmsign Sign and Verify DICOM Files
6 \page dcmsign dcmsign: Sign and Verify DICOM Files
9 \section synopsis SYNOPSIS
12 dcmsign [options] dcmfile-in [dcmfile-out]
15 \section description DESCRIPTION
17 The \b dcmsign utility reads a DICOM file (\e dcmfile-in), performs a digital
18 signature operation and, if any modification has taken place, writes the DICOM
19 object to an output file (\e dcmfile-out).
21 Five digital signature operations are supported:
23 \li verification of all signatures in the DICOM file
24 \li creation of a new digital signature located in the main dataset,
25 \li creation of a new digital signature in an item of a sequence embedded
27 \li removal of a single digital signature from the DICOM file, and
28 \li removal of all digital signatures from the DICOM file.
30 \section parameters PARAMETERS
33 dcmfile-in DICOM input filename to be processed
35 dcmfile-out DICOM output filename
38 \section options OPTIONS
40 \subsection general_options general options
43 print this help text and exit
46 print version information and exit
49 print expanded command line arguments
52 quiet mode, print no warnings and errors
55 verbose mode, print processing details
58 debug mode, print debug information
60 -ll --log-level [l]evel: string constant
61 (fatal, error, warn, info, debug, trace)
62 use level l for the logger
64 -lc --log-config [f]ilename: string
65 use config file f for the logger
68 \subsection input_options input options
73 read file format or data set (default)
79 read data set without file meta information
81 input transfer syntax:
84 use TS recognition (default)
86 -td --read-xfer-detect
87 ignore TS specified in the file meta header
89 -te --read-xfer-little
90 read with explicit VR little endian TS
93 read with explicit VR big endian TS
95 -ti --read-xfer-implicit
96 read with implicit VR little endian TS
99 \subsection signature_commands signature commands
102 verify all signatures (default)
104 +s --sign [p]rivate key file, [c]ertificate file: string
105 create signature in main object
107 +si --sign-item [k]eyfile, [c]ertfile, [i]tem location: string
108 create signature in sequence item
110 +r --remove [s]ignature UID: string
114 remove all signatures from data set
117 \subsection signature_creation_options signature creation options (only with --sign or --sign-item):
119 private key password:
122 prompt user to type password on stdin (default)
124 +pw --use-passwd [p]assword: string
125 use specified password
128 use empty string as password
130 key and certificate file format:
133 read keys/certificates as PEM file (default)
136 read keys/certificates as DER file
138 digital signature profile:
141 don't enforce any signature profile (default)
144 enforce base RSA signature profile
146 +pc --profile-creator
147 enforce creator RSA signature profile
150 enforce authorization signature profile
155 use RIPEMD 160 (default)
166 [t]ag: "gggg,eeee" or dictionary name
167 sign only specified tag
168 (this option can be specified multiple times)
170 -tf --tag-file [f]ilename: string
171 read list of tags from text file
176 use correct DICOM signature format (default)
179 use old (pre-3.5.4) DCMTK signature format, non-conformant
180 if signature includes compressed pixel data
183 \subsection output_options output options
185 output transfer syntax:
187 +t= --write-xfer-same
188 write with same TS as input (default)
190 +te --write-xfer-little
191 write with explicit VR little endian TS
194 write with explicit VR big endian TS
196 +ti --write-xfer-implicit
197 write with implicit VR little endian TS
199 length encoding in sequences and items:
202 write with explicit lengths (default)
204 -e --length-undefined
205 write with undefined lengths
207 other output options:
209 +d --dump [f]ilename: string
210 dump byte stream fed into the MAC codec to file
211 (only with --sign or --sign-item)
216 \subsection files_and_parameters Files and Parameters
218 The \b dcmsign utility reads and writes a number of files and file formats
219 which are described in this section.
221 Public Key Certificates are expected in X.509v3 format, either with PEM or DER
222 encoding. The dcmsign utility currently supports RSA and DSA public keys,
223 although only RSA keys are defines in the Security Profiles of the DICOM
226 Private Keys are expected in PEM or DER encoding. PEM is recommended (and
227 default) because this allows to keep private keys in encrypted form. Command
228 line options control the behaviour of \b dcmsign when an encrypted PEM key is
229 opened (see above). In general it is not recommended to specify the encryption
230 password in the command line because the command line may be visible to other
231 processes in the system, e.g. "ps -ef".
233 The list of data elements to sign can either be read from a file or specified
234 on the command line or both (in this case the keys are combined).
236 On the command line, attribute keys are specified as
239 --tag "gggg,eeee" where gggg and eeee are the hexadecimal group
241 --tag "Name" where 'Name' is a symbolic attribute name from
242 the DICOM dictionary (see below).
245 When attribute tags are read from file with the \e --tag-file option, a plain
246 text file of max. 64 kbyte is expected. Tags within the file are either
247 symbolic names from the data dictionary or have the format (gggg,eeee) (with
248 braces). Tags are separated by one or more whitespace characters.
250 The \e --sign-item operation requires a location string that describes in which
251 sequence item a signature is to be created. The location string has the
255 SequenceName[index].SequenceName[index].SequenceName[index](...)
258 where SequenceName is either a symbolic attribute name from the data dictionary
259 or a numeric tag in the format (gggg,eeee) and index is an unsigned decimal
260 integer for the item number, starting with zero for the first item in a
261 sequence. As an example, the following location string
264 ReferencedSeriesSequence[0].ReferencedImageSequence[1]
267 would cause a digital signature to be created in the second item of the
268 ReferencedImageSequence (0008,1140) which is located in the first item of the
269 ReferencedSeriesSequence (0008,1115) which is located in the main DICOM
272 \section logging LOGGING
274 The level of logging output of the various command line tools and underlying
275 libraries can be specified by the user. By default, only errors and warnings
276 are written to the standard error stream. Using option \e --verbose also
277 informational messages like processing details are reported. Option
278 \e --debug can be used to get more details on the internal activity, e.g. for
279 debugging purposes. Other logging levels can be selected using option
280 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
281 very severe error events, the application will usually terminate. For more
282 details on the different logging levels, see documentation of module "oflog".
284 In case the logging output should be written to file (optionally with logfile
285 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
286 can be used. This configuration file also allows for directing only certain
287 messages to a particular output stream and for filtering certain messages
288 based on the module or application where they are generated. An example
289 configuration file is provided in <em><etcdir>/logger.cfg</em>).
291 \section command_line COMMAND LINE
293 All command line tools use the following notation for parameters: square
294 brackets enclose optional values (0-1), three trailing dots indicate that
295 multiple values are allowed (1-n), a combination of both means 0 to n values.
297 Command line options are distinguished from parameters by a leading '+' or '-'
298 sign, respectively. Usually, order and position of command line options are
299 arbitrary (i.e. they can appear anywhere). However, if options are mutually
300 exclusive the rightmost appearance is used. This behaviour conforms to the
301 standard evaluation rules of common Unix shells.
303 In addition, one or more command files can be specified using an '@' sign as a
304 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
305 is replaced by the content of the corresponding text file (multiple
306 whitespaces are treated as a single separator unless they appear between two
307 quotation marks) prior to any further evaluation. Please note that a command
308 file cannot contain another command file. This simple but effective approach
309 allows to summarize common combinations of options/parameters and avoids
310 longish and confusing command lines (an example is provided in file
311 <em><datadir>/dumppat.txt</em>).
313 \section environment ENVIRONMENT
315 The \b dcmsign utility will attempt to load DICOM data dictionaries specified
316 in the \e DCMDICTPATH environment variable. By default, i.e. if the
317 \e DCMDICTPATH environment variable is not set, the file
318 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
319 into the application (default for Windows).
321 The default behaviour should be preferred and the \e DCMDICTPATH environment
322 variable only used when alternative data dictionaries are required. The
323 \e DCMDICTPATH environment variable has the same format as the Unix shell
324 \e PATH variable in that a colon (":") separates entries. On Windows systems,
325 a semicolon (";") is used as a separator. The data dictionary code will
326 attempt to load each file specified in the \e DCMDICTPATH environment variable.
327 It is an error if no data dictionary can be loaded.
329 \section copyright COPYRIGHT
331 Copyright (C) 2000-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.