Debian Codegraph @

doc/canlock.in1

raw
1 .\"=============================================================================
2 .\" Header
3 .\"
4 .\" Copyright (c) 2018-2024 Michael Baeuerle
5 .\"
6 .\" All rights reserved.
7 .\"
8 .\" Permission is hereby granted, free of charge, to any person obtaining
9 .\" a copy of this software and associated documentation files (the
10 .\" "Software"), to deal in the Software without restriction, including
11 .\" without limitation the rights to use, copy, modify, merge, publish,
12 .\" distribute, and/or sell copies of the Software, and to permit persons
13 .\" to whom the Software is furnished to do so, provided that the above
14 .\" copyright notice(s) and this permission notice appear in all copies of
15 .\" the Software and that both the above copyright notice(s) and this
16 .\" permission notice appear in supporting documentation.
17 .\"
18 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
21 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
22 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY
23 .\" SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER
24 .\" RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
25 .\" CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
26 .\" CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
27 .\"
28 .\" Except as contained in this notice, the name of a copyright holder
29 .\" shall not be used in advertising or otherwise to promote the sale, use
30 .\" or other dealings in this Software without prior written authorization
31 .\" of the copyright holder.
32 .\"
33 .\" SPDX-License-Identifier: ICU
34 .\"
35 .\"
36 .TH $NAME 1 $DATE Unix "$NAME $VERSION manual"
37 .\"
38 .\"
39 .\"=============================================================================
40 .\" NAME section
41 .\"
42 .SH NAME
43 $NAME \- CLI frontend for libcanlock library
44 .\"
45 .\"
46 .\"=============================================================================
47 .\" SYNOPSIS section
48 .\"
49 .SH SYNOPSIS
50 .B $NAME
51 -h | -v
52 .PP
53 .B $NAME
54 [-q] -o
55 .PP
56 .B $NAME
57 [-a scheme] -l [uid]mid
58 .PP
59 .B $NAME
60 [-a scheme] -k [uid]mid
61 .PP
62 .B $NAME
63 [-q] -c key,lock
64 .PP
65 .B $NAME
66 [-q] -m keys,locks
67 .\"
68 .\"
69 .\"=============================================================================
70 .\" DESCRIPTION section
71 .\"
72 .SH DESCRIPTION
73 Command line utility for Netnews Cancel-Lock authentication scheme.
74 .PP
75 .B $NAME
76 can be used to create <c-lock> and <c-key> elements according to RFC 8315.
77 The secret data is read from standard input (using EOF for termination).
78 .PP
79 .B $NAME
80 also provides a verify interface with the -c option.
81 An external header parser is required to extract the <c-key> and <c-lock>
82 elements from the article headers.
83 .br
84 The command line utilities
85 .BR canlock-mhp (1)
86 and
87 .BR canlock-hfp (1)
88 can be used for this purpose.
89 .\"
90 .\"
91 .\"=============================================================================
92 .\" OPTIONS section
93 .\"
94 .SH OPTIONS
95 The following options are supported:
96 .TP 20
97 .BI -a " scheme
98 Use the hash algorithm specified by <scheme>.
99 .br
100 Supported values for <scheme> (by version 3.0.0 of $NAME):
101 .br
102 sha1, sha224, sha256, sha384, sha512
103 .sp
104 If this option is not present, sha256 is used as default value (because this is
105 the mandatory algorithm defined by RFC 8315).
106 .TP
107 .BI -l " [uid]mid
108 Generate Cancel-Lock for Message-ID <mid>.
109 .br
110 The Message-ID can be prepended with an optional User-ID <uid>.
111 .sp
112 The result is a <c-lock> element.
113 .TP
114 .BI -k " [uid]mid
115 Generate Cancel-Key for Message-ID <mid>.
116 .br
117 The Message-ID can be prepended with an optional User-ID <uid>.
118 .sp
119 The result is a <c-key> element.
120 .TP
121 .BI -c " c-key,c-lock
122 Verify whether <c-key> element of a cancel or supersede matches the <c-lock>
123 element of a target article.
124 .TP
125 .BI -m " keys,locks
126 Verify whether one of multiple keys matches one of multiple locks.
127 .br
128 The elements of both lists must be separated by SP (space) characters.
129 .br
130 Anything must be passed as single parameter of the "-m" option, use appropriate
131 quoting.
132 .TP
133 .BI -q
134 Write no result to standard output.
135 .sp
136 Only valid if specified before -c and -o options.
137 .TP
138 .BI -h
139 Print help message, then exit.
140 .TP
141 .BI -o
142 Print whether libcanlock reports support for overwriting secret data in memory.
143 .sp
144 The exit status is zero if
145 .BR cl_clear_secret (3)
146 returned zero.
147 .TP
148 .BI -v
149 Print version and compile time options, then exit.
150 .\"
151 .\"
152 .\"=============================================================================
153 .\" EXIT STATUS section
154 .\"
155 .SH EXIT STATUS
156 Zero on success or regular exit respectively.
157 .br
158 All other values indicate an error.
159 .\"
160 .\"
161 .\"=============================================================================
162 .\" AUTHORS section
163 .\"
164 .SH AUTHORS
165 Michael Baeuerle
166 .\"
167 .\"
168 .\"=============================================================================
169 .\" REPORTING BUGS section
170 .\"
171 .SH REPORTING BUGS
172 Report bugs to <mailto:$BUGREPORT>.
173 .\"
174 .\"
175 .\"=============================================================================
176 .\" STANDARDS section
177 .\"
178 .SH STANDARDS
179 .B $NAME
180 tries to comply with the following standards:
181 .PP
182 RFC 5537, RFC 6234, RFC 8315
183 .\"
184 .\"
185 .\"=============================================================================
186 .\" SEE ALSO section
187 .\"
188 .SH SEE ALSO
189 .BR canlock-hfp (1),
190 .BR canlock-mhp (1),
191 .BR cl_clear_secret (3),
192 .BR cl_get_lock (3),
193 .BR cl_get_key (3),
194 .BR cl_split (3),
195 .BR cl_verify (3),
196 .BR cl_verify_multi (3)
197 .br
198 .BR http://en.wikipedia.org/wiki/Usenet
199 .\"
200 .\"
201 .\" EOF