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