1=========================================
2rpcsec_gss support for kernel RPC servers
3=========================================
4
5This document gives references to the standards and protocols used to
6implement RPCGSS authentication in kernel RPC servers such as the NFS
7server and the NFS client's NFSv4.0 callback server.  (But note that
8NFSv4.1 and higher don't require the client to act as a server for the
9purposes of authentication.)
10
11RPCGSS is specified in a few IETF documents:
12
13 - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt
14 - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt
15
16and there is a 3rd version  being proposed:
17
18 - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt
19   (At draft n. 02 at the time of writing)
20
21Background
22==========
23
24The RPCGSS Authentication method describes a way to perform GSSAPI
25Authentication for NFS.  Although GSSAPI is itself completely mechanism
26agnostic, in many cases only the KRB5 mechanism is supported by NFS
27implementations.
28
29The Linux kernel, at the moment, supports only the KRB5 mechanism, and
30depends on GSSAPI extensions that are KRB5 specific.
31
32GSSAPI is a complex library, and implementing it completely in kernel is
33unwarranted. However GSSAPI operations are fundementally separable in 2
34parts:
35
36- initial context establishment
37- integrity/privacy protection (signing and encrypting of individual
38  packets)
39
40The former is more complex and policy-independent, but less
41performance-sensitive.  The latter is simpler and needs to be very fast.
42
43Therefore, we perform per-packet integrity and privacy protection in the
44kernel, but leave the initial context establishment to userspace.  We
45need upcalls to request userspace to perform context establishment.
46
47NFS Server Legacy Upcall Mechanism
48==================================
49
50The classic upcall mechanism uses a custom text based upcall mechanism
51to talk to a custom daemon called rpc.svcgssd that is provide by the
52nfs-utils package.
53
54This upcall mechanism has 2 limitations:
55
56A) It can handle tokens that are no bigger than 2KiB
57
58In some Kerberos deployment GSSAPI tokens can be quite big, up and
59beyond 64KiB in size due to various authorization extensions attacked to
60the Kerberos tickets, that needs to be sent through the GSS layer in
61order to perform context establishment.
62
63B) It does not properly handle creds where the user is member of more
64than a few thousand groups (the current hard limit in the kernel is 65K
65groups) due to limitation on the size of the buffer that can be send
66back to the kernel (4KiB).
67
68NFS Server New RPC Upcall Mechanism
69===================================
70
71The newer upcall mechanism uses RPC over a unix socket to a daemon
72called gss-proxy, implemented by a userspace program called Gssproxy.
73
74The gss_proxy RPC protocol is currently documented `here
75<https://fedorahosted.org/gss-proxy/wiki/ProtocolDocumentation>`_.
76
77This upcall mechanism uses the kernel rpc client and connects to the gssproxy
78userspace program over a regular unix socket. The gssproxy protocol does not
79suffer from the size limitations of the legacy protocol.
80
81Negotiating Upcall Mechanisms
82=============================
83
84To provide backward compatibility, the kernel defaults to using the
85legacy mechanism.  To switch to the new mechanism, gss-proxy must bind
86to /var/run/gssproxy.sock and then write "1" to
87/proc/net/rpc/use-gss-proxy.  If gss-proxy dies, it must repeat both
88steps.
89
90Once the upcall mechanism is chosen, it cannot be changed.  To prevent
91locking into the legacy mechanisms, the above steps must be performed
92before starting nfsd.  Whoever starts nfsd can guarantee this by reading
93from /proc/net/rpc/use-gss-proxy and checking that it contains a
94"1"--the read will block until gss-proxy has done its write to the file.
95