summaryrefslogtreecommitdiff
path: root/tools/rscryutil.1
blob: c1d8d042bb73a6955908217dde097a677a8f60b4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
.\" Man page generated from reStructuredText.
.
.TH RSCRYUTIL 1 "2013-04-15" "" ""
.SH NAME
rscryutil \- Manage Encrypted Log Files
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rscryutil [OPTIONS] [FILE] ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
This tool performs various operations on encrypted log files.
Most importantly, it provides the ability to decrypt them.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-d\fP,\fB  \-\-decrypt
Select decryption mode. This is the default mode.
.TP
.BI \-W\fP,\fB  \-\-write\-keyfile \ <file>
Utility function to write a key to a keyfile. The key can be obtained
via any method.
.TP
.B \-v\fP,\fB  \-\-verbose
Select verbose mode.
.TP
.B \-f\fP,\fB  \-\-force
Forces operations that otherwise would fail.
.TP
.BI \-k\fP,\fB  \-\-keyfile \ <file>
Reads the key from <file>. File _must_ contain the key, only, no headers
or other meta information. Keyfiles can be generated via the
\fI\-\-write\-keyfile\fP option.
.TP
.BI \-p\fP,\fB  \-\-key\-program \ <path\-to\-program>
In this mode, the key is provided by a so\-called "key program". This program
is executed and must return the key to (as well as some meta information)
via stdout. The core idea of key programs is that using this interface the
user can implement as complex (and secure) method to obtain keys as
desired, all without the need to make modifications to rsyslog.
.TP
.BI \-K\fP,\fB  \-\-key \ <KEY>
TESTING AID, NOT FOR PRODUCTION USE. This uses the KEY specified
on the command line. This is the actual key, and as such this mode
is highly insecure. However, it can be useful for intial testing
steps. This option may be removed in the future.
.TP
.BI \-a\fP,\fB  \-\-algo \ <algo>
Sets the encryption algorightm (cipher) to be used. See below
for supported algorithms. The default is "AES128".
.TP
.BI \-m\fP,\fB  \-\-mode \ <mode>
Sets the ciphermode to be used. See below for supported modes.
The default is "CBC".
.TP
.BI \-r\fP,\fB  \-\-generate\-random\-key \ <bytes>
Generates a random key of length <bytes>. This option is
meant to be used together with \fI\-\-write\-keyfile\fP (and it is hard
to envision any other valid use for it).
.UNINDENT
.SH OPERATION MODES
.sp
The operation mode specifies what exactly the tool does with the provided
files. The default operation mode is "dump", but this may change in the future.
Thus, it is recommended to always set the operations mode explicitely. If
multiple operations mode are set on the command line, results are
unpredictable.
.SS decrypt
.sp
The provided log files are decrypted. Note that the \fI\&.encinfo\fP side files
must exist and be accessible in order for decryption to to work.
.SS write\-keyfile
.sp
In this mode no log files are processed; thus it is an error to specify
any on the command line. The specified keyfile is written. The key itself
is obtained via the usual key commands. If \fI\-\-keyfile\fP is used, that
file is effectively copied.
.sp
For security reasons, existing key files are _not_ overwritten. To permit
this, specify the \fI\-\-force\fP option. When doing so, keep in mind that lost
keys cannot be recovered and data encrypted with them may also be considered
lost.
.sp
Keyfiles are always created with 0400 permission, that is read access for only
the user. An exception is when an existing file is overwritten via the
\fI\-\-force\fP option, in which case the former permissions still apply.
.SH EXIT CODES
.sp
The command returns an exit code of 0 if everything went fine, and some
other code in case of failures.
.SH SUPPORTED ALGORITHMS
.sp
We basically support what libgcrypt supports. This is:
.INDENT 0.0
.INDENT 3.5
3DES
CAST5
BLOWFISH
AES128
AES192
AES256
TWOFISH
TWOFISH128
ARCFOUR
DES
SERPENT128
SERPENT192
SERPENT256
RFC2268_40
SEED
CAMELLIA128
CAMELLIA192
CAMELLIA256
.UNINDENT
.UNINDENT
.SH SUPPORTED CIPHER MODES
.sp
We basically support what libgcrypt supports. This is:
.INDENT 0.0
.INDENT 3.5
ECB
CFB
CBC
STREAM
OFB
CTR
AESWRAP
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
\fBrscryutil logfile\fP
.sp
Decrypts "logfile" and sends data to stdout.
.sp
\fBrscryutil \-\-generate\-random\-key 16 \-\-keyfile /some/secured/path/keyfile\fP
.sp
Generates random key and stores it in the specified keyfile.
.SH LOG SIGNATURES
.sp
Encrypted log files can be used together with signing. To verify such a file,
it must be decrypted first, and the verification tool \fBrsgtutil(1)\fP must be
run on the decrypted file.
.SH SECURITY CONSIDERATIONS
.sp
Specifying keys directly on the command line (\fI\-\-key\fP option) is very
insecure and should
not be done, except for testing purposes with test keys. Even then it is
recommended to use keyfiles, which are also easy to handle during testing.
Keep in mind that command history is usally be kept by bash and can also
easily be monitored.
.sp
Local keyfiles are also a security risk. At a minimum, they should be
used with very restrictive file permissions. For this reason,
the \fIrscryutil\fP tool creates them with read permissions for the user,
only, no matter what umask is set to.
.sp
When selecting cipher algorithms and modes, care needs to be taken. The
defaults should be reasonable safe to use, but this tends to change over
time. Keep up with the most current crypto recommendations.
.SH SEE ALSO
.sp
\fBrsgtutil(1)\fP, \fBrsyslogd(8)\fP
.SH COPYRIGHT
.sp
This page is part of the \fIrsyslog\fP project, and is available under
LGPLv2.
.SH AUTHOR
Rainer Gerhards <rgerhards@adiscon.com>
.\" Generated by docutils manpage writer.
.