chiark / gitweb /
wip manpage
[inn-innduct.git] / doc / man / auth_krb5.8
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "AUTH_KRB5 8"
132 .TH AUTH_KRB5 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 auth_krb5 \- nnrpd Kerberos v5 authenticator
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBauth_krb5\fR [\fB\-i\fR \fIinstance\fR]
138 .SH "DESCRIPTION"
139 .IX Header "DESCRIPTION"
140 This program does authentication for \fBnnrpd\fR against a Kerberos v5 \s-1KDC\s0.
141 This is \s-1NOT\s0 real Kerberos authentication using service tickets; instead, a
142 username and password is used to attempt to obtain a Kerberos v5 \s-1TGT\s0 to
143 confirm that they are valid.  As such, this authenticator assumes that
144 \&\fBnnrpd\fR has been given the user's username and password, and therefore is
145 not as secure as real Kerberos authentication.  It generally should only
146 be used with \s-1NNTP\s0 over \s-1SSL\s0 to protect the password from sniffing.
147 .SH "OPTIONS"
148 .IX Header "OPTIONS"
149 .IP "\fB\-i\fR \fIinstance\fR" 4
150 .IX Item "-i instance"
151 If this option is given, \fIinstance\fR will be used as the instance of the
152 principal received from \fBnnrpd\fR and authentication will be done against
153 that principal instead of the base principal.  In other words, a principal
154 like \f(CW\*(C`user\*(C'\fR, when passed to \fBauth_krb5\fR invoked with \f(CW\*(C`\-i nntp\*(C'\fR, will be
155 transformed into \f(CW\*(C`user/nntp\*(C'\fR before attempting Kerberos authentication.
156 .Sp
157 Since giving one's password to \fBnnrpd\fR is not as secure as normal
158 Kerberos authentication, this option supports a configuration where all
159 users are given a separate instance just for news authentication with its
160 own password, so their regular account password isn't exposed via \s-1NNTP\s0.
161 .SH "EXAMPLE"
162 .IX Header "EXAMPLE"
163 The following \fIreaders.conf\fR\|(5) fragment tells nnrpd to authenticate users
164 by attempting to obtain Kerberos v5 TGTs for them, appending an instance
165 of \f(CW\*(C`nntp\*(C'\fR to usernames before doing so:
166 .PP
167 .Vb 3
168 \&    auth kerberos {
169 \&        auth: "auth_krb5 \-i nntp"
170 \&    }
171 .Ve
172 .PP
173 .Vb 4
174 \&    access kerberos {
175 \&        users: "*/nntp"
176 \&        newsgroups: example.*
177 \&    }
178 .Ve
179 .PP
180 Access is granted to the example.* groups for all users who successfully
181 authenticate.
182 .SH "BUGS"
183 .IX Header "BUGS"
184 Currently, any username containing realm information (containing \f(CW\*(C`@\*(C'\fR) is
185 rejected.  This is to prevent someone from passing in a username
186 corresponding to a principal in another realm that they have access to and
187 gaining access to the news server via it.  However, this is also something
188 that people may wish to do under some circumstances, so there should be a
189 better way of handling it (such as, perhaps, a list of acceptable realms
190 or a \-r flag specifying the realm in which to attempt authentication).
191 .PP
192 It's not clear the right thing to do when the username passed in contains
193 a \f(CW\*(C`/\*(C'\fR and \fB\-i\fR was also given.  Right now, \fBauth_krb5\fR will create a
194 malformed Kerberos principal with multiple instances and attempt to
195 authenticate against it, which will fail but perhaps not with the best
196 error message.
197 .SH "HISTORY"
198 .IX Header "HISTORY"
199 Originally written by Christopher P. Lindsey.  This documentation was
200 written by Russ Allbery <rra@stanford.edu> based on Christopher's original
201 \&\s-1README\s0 file.
202 .PP
203 $Id: auth_krb5.8 7880 2008-06-16 20:37:13Z iulius $
204 .SH "SEE ALSO"
205 .IX Header "SEE ALSO"
206 \&\fInnrpd\fR\|(8), \fIreaders.conf\fR\|(5)
207 .PP
208 The latest version of Christopher's original \fBnnrpkrb5auth\fR may be found
209 on his web site at <http://www.mallorn.com/tools/>.