OFFIS DCMTK  Version 3.6.0
dcmsign.man
1 /*!
2 
3 \if MANPAGES
4 \page dcmsign Sign and Verify DICOM Files
5 \else
6 \page dcmsign dcmsign: Sign and Verify DICOM Files
7 \endif
8 
9 \section synopsis SYNOPSIS
10 
11 \verbatim
12 dcmsign [options] dcmfile-in [dcmfile-out]
13 \endverbatim
14 
15 \section description DESCRIPTION
16 
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).
20 
21 Five digital signature operations are supported:
22 
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
26  within the dataset,
27 \li removal of a single digital signature from the DICOM file, and
28 \li removal of all digital signatures from the DICOM file.
29 
30 \section parameters PARAMETERS
31 
32 \verbatim
33 dcmfile-in DICOM input filename to be processed
34 
35 dcmfile-out DICOM output filename
36 \endverbatim
37 
38 \section options OPTIONS
39 
40 \subsection general_options general options
41 \verbatim
42  -h --help
43  print this help text and exit
44 
45  --version
46  print version information and exit
47 
48  --arguments
49  print expanded command line arguments
50 
51  -q --quiet
52  quiet mode, print no warnings and errors
53 
54  -v --verbose
55  verbose mode, print processing details
56 
57  -d --debug
58  debug mode, print debug information
59 
60  -ll --log-level [l]evel: string constant
61  (fatal, error, warn, info, debug, trace)
62  use level l for the logger
63 
64  -lc --log-config [f]ilename: string
65  use config file f for the logger
66 \endverbatim
67 
68 \subsection input_options input options
69 \verbatim
70 input file format:
71 
72  +f --read-file
73  read file format or data set (default)
74 
75  +fo --read-file-only
76  read file format only
77 
78  -f --read-dataset
79  read data set without file meta information
80 
81 input transfer syntax:
82 
83  -t= --read-xfer-auto
84  use TS recognition (default)
85 
86  -td --read-xfer-detect
87  ignore TS specified in the file meta header
88 
89  -te --read-xfer-little
90  read with explicit VR little endian TS
91 
92  -tb --read-xfer-big
93  read with explicit VR big endian TS
94 
95  -ti --read-xfer-implicit
96  read with implicit VR little endian TS
97 \endverbatim
98 
99 \subsection signature_commands signature commands
100 \verbatim
101  --verify
102  verify all signatures (default)
103 
104  +s --sign [p]rivate key file, [c]ertificate file: string
105  create signature in main object
106 
107  +si --sign-item [k]eyfile, [c]ertfile, [i]tem location: string
108  create signature in sequence item
109 
110  +r --remove [s]ignature UID: string
111  remove signature
112 
113  +ra --remove-all
114  remove all signatures from data set
115 \endverbatim
116 
117 \subsection signature_creation_options signature creation options (only with --sign or --sign-item):
118 \verbatim
119 private key password:
120 
121  +ps --std-passwd
122  prompt user to type password on stdin (default)
123 
124  +pw --use-passwd [p]assword: string
125  use specified password
126 
127  -pw --null-passwd
128  use empty string as password
129 
130 key and certificate file format:
131 
132  -pem --pem-keys
133  read keys/certificates as PEM file (default)
134 
135  -der --der-keys
136  read keys/certificates as DER file
137 
138 digital signature profile:
139 
140  -pf --profile-none
141  don't enforce any signature profile (default)
142 
143  +pb --profile-base
144  enforce base RSA signature profile
145 
146  +pc --profile-creator
147  enforce creator RSA signature profile
148 
149  +pa --profile-auth
150  enforce authorization signature profile
151 
152 MAC algorithm:
153 
154  +mr --mac-ripemd160
155  use RIPEMD 160 (default)
156 
157  +ms --mac-sha1
158  use SHA-1
159 
160  +mm --mac-md5
161  use MD 5
162 
163 tag selection:
164 
165  -t --tag
166  [t]ag: "gggg,eeee" or dictionary name
167  sign only specified tag
168  (this option can be specified multiple times)
169 
170  -tf --tag-file [f]ilename: string
171  read list of tags from text file
172 
173 signature format:
174 
175  -fn --format-new
176  use correct DICOM signature format (default)
177 
178  -fo --format-old
179  use old (pre-3.5.4) DCMTK signature format, non-conformant
180  if signature includes compressed pixel data
181 \endverbatim
182 
183 \subsection output_options output options
184 \verbatim
185 output transfer syntax:
186 
187  +t= --write-xfer-same
188  write with same TS as input (default)
189 
190  +te --write-xfer-little
191  write with explicit VR little endian TS
192 
193  +tb --write-xfer-big
194  write with explicit VR big endian TS
195 
196  +ti --write-xfer-implicit
197  write with implicit VR little endian TS
198 
199 length encoding in sequences and items:
200 
201  +e --length-explicit
202  write with explicit lengths (default)
203 
204  -e --length-undefined
205  write with undefined lengths
206 
207 other output options:
208 
209  +d --dump [f]ilename: string
210  dump byte stream fed into the MAC codec to file
211  (only with --sign or --sign-item)
212 \endverbatim
213 
214 \section notes NOTES
215 
216 \subsection files_and_parameters Files and Parameters
217 
218 The \b dcmsign utility reads and writes a number of files and file formats
219 which are described in this section.
220 
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
224 standard.
225 
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".
232 
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).
235 
236 On the command line, attribute keys are specified as
237 
238 \verbatim
239 --tag "gggg,eeee" where gggg and eeee are the hexadecimal group
240  and element numbers
241 --tag "Name" where 'Name' is a symbolic attribute name from
242  the DICOM dictionary (see below).
243 \endverbatim
244 
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.
249 
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
252 following format:
253 
254 \verbatim
255 SequenceName[index].SequenceName[index].SequenceName[index](...)
256 \endverbatim
257 
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
262 
263 \verbatim
264 ReferencedSeriesSequence[0].ReferencedImageSequence[1]
265 \endverbatim
266 
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
270 dataset.
271 
272 \section logging LOGGING
273 
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".
283 
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>).
290 
291 \section command_line COMMAND LINE
292 
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.
296 
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.
302 
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>).
312 
313 \section environment ENVIRONMENT
314 
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).
320 
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.
328 
329 \section copyright COPYRIGHT
330 
331 Copyright (C) 2000-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
332 
333 */


Generated on Wed Dec 28 2016 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.8