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