1AF_RXRPC(7) Linux Programmer's Manual AF_RXRPC(7)
2
6 rxrpc - Linux RxRPC (AFS) protocol implementation
7
9 #include <sys/socket.h>
10 #include <linux/rxrpc.h>
11 socket = socket(AF_RXRPC, SOCK_DGRAM, PF_INET);
13 socket = socket(AF_RXRPC, SOCK_DGRAM, PF_INET6);
14
17 Linux optionally implements the RxRPC transport protocol, as used by
18 the AFS network filesystem. Both client and server ends are support -
19 even on the same socket - and authentication is supported at both ends.
20 This can be used through the BSD socket interface, using the sendmsg(2)
22 and recvmsg(2) system calls with control data to multiplex calls over
23 the socket and to provide or retrieve call metadata. request_key(2) is
24 used to find the authentication keys to use in the calling process's
25 keyrings.
26 The AF_RXRPC driver uses udp(7) sockets underneath, either IPv4-only or
28 IPv6 (with IPv4), for transport. Under certain circumstances, the
29 underlying transport sockets may be shared between client-only sockets
30 (but are never shared if a socket is implementing a server).
31 Address format
33 struct sockaddr_rxrpc {
34 sa_family_t srx_family; /* AF_RXRPC */
35 uint16_t srx_service; /* The service identifier */
36 uint16_t transport_type; /* The type of transport */
37 uint16_t transport_len; /* Transport address length */
38 union {
39 sa_family_t family; /* Transport address family */
40 struct sockaddr_in sin; /* IPv4 transport address */
41 struct sockaddr_in6 sin6; /* IPv6 transport address */
42 } transport;
43 };
44 Where srx_family is always set to AF_RXRPC; srx_service is set to the
46 service ID of the desired service; transport_type is set to the trans‐
47 port type, which is always SOCK_DGRAM for now; transport_len says how
48 big the address in transport is.
49 Inside the transport address part, and appropriate address for the
51 underlying socket should be set, including things like family, port and
52 address as appropriate. Note that it may be permissible to use IPv4
53 addresses on an IPv6 socket.
54 Socket Options
56 AF_RXRPC provides a number of socket options that can be set with set‐
57 sockopt(2) and read with getsockopt(2). The socket option level for
58 IPv6 is SOL_RXRPC.
59 RXRPC_SECURITY_KEY
61 The option value is a string that specifies the name of a key to
62 pass to request_key(2) to get an appropriate authentication key.
63 Such keys are expected to be of rxrpc type.
64 If this isn't set, AF_RXRPC will perform an unauthenticated,
66 unencrypted call to the server.
67 RXRPC_SECURITY_KEYRING
69 The option value is a string that specifies the name of a
70 keyring to pass to request_key(2) to specify the keys used by
71 the server end to authenticate connections.
72 The service keys in the ring should be of type rxrpc_s and their
74 descriptions should be of the form "<service-id>:<security-
75 index>" and each should be given an 8-byte secret.
76 RXRPC_EXCLUSIVE_CONNECTION
78 The option value should be empty. This causes each call made on
79 this socket to get its own virtual connection and thus its own
80 negotiated security context.
81 RXRPC_MIN_SECURITY_LEVEL
83 The option value should be a 4-byte unsigned integer. This can
84 be one of the following constants: RXRPC_SECURITY_PLAIN,
85 RXRPC_SECURITY_AUTH or RXRPC_SECURITY_ENCRYPT; the first indi‐
86 cating the packets should be securely checksummed only, the sec‐
87 ond that packets should be authenticated and the third that full
88 encryption should be employed.
89 RXRPC_UPGRADEABLE_SERVICE
92 The option value should be a 2-slot array of 2-byte unsigned
93 integers. To use this, the socket must be a server socket and
94 must have been bound to more than one address with different
95 srx_service specifiers.
96 Slot[0] in the array specified the service ID to upgrade from;
98 slot[1] specifies the service ID to upgrade to. This allows a
99 client to find out if there's a 'better' version of the service
100 available on the same address, but a different service ID.
101 If the client follows the correct protocol for probing an
103 upgradeable service, the kernel will automatically upgrade the
104 service ID on the connection and this will be reflected in the
105 address returned by recvmsg(2).
106 RXRPC_SUPPORTED_CMSG
108 The option buffer should have room for a 4-byte integer. The
109 maximum control buffer message type supported by the kernel is
110 written into the buffer. This allows an application to find out
111 what control messages it may use so that it can avoid getting an
112 error if it tries to use something unsupported.
113 Message flags
115 AF_RXRPC communicates certain information by way of the message flags
116 passed to and received from sendmsg(2) and recvmsg(2).
117 MSG_MORE
119 This is passed to sendmsg() to indicate that there is more data
120 to be transmitted as part of the request phase of a client call
121 or the reply phase of a service operation. MSG_EOR recvmsg()
122 sets this to indicate that the call has been terminated (the
123 control messages must be parsed for information as to why) and
124 that the kernel has discarded the user call ID tag. The tag may
125 now be reused. MSG_PEEK This is passed to recvmsg() to look at
126 the front of the message queue without removing any messages or
127 changing the state of any outstanding calls. MSG_WAITALL This
128 is passed to sendmsg() to instruct it not to return for a signal
129 if it is still loading up the message queue and progress is
130 being made at the other side in emptying it. This works around
131 the problem of sendmsg() getting interrupted after partially
132 queuing its data, but not then being able to return how much it
133 has consumed. MSG_DONTWAIT This is passed to recvmsg() to indi‐
134 cate that it shouldn't wait if the message queue is empty.
135 Control messages
138 AF_RXRPC communicates metadata to the caller through the ancillary data
139 buffer (msg_control) in the messages passed to and fro using sendmsg(2)
140 and recvmsg(2). When building a control message buffer for sendmsg(),
141 the RXRPC_SUPPORTED_CMSG value should be consulted to make sure that
142 the control message type is supported.
143 RXRPC_USER_CALL_ID
145 The data for this is an arbitrary long integer/pointer-sized tag
146 that represents the call to the kernel. It may, for example,
147 hold a pointer to some userspace structure representing the call
148 to the process.
149 [sendmsg] This is passed to sendmsg() when the message proposed
151 will create a client call. It must thereafter be included in
152 all future sendmsg() calls pertaining to that call.
153 [recvmsg] recvmsg() includes the tag in all messages pertaining
155 to a call until the final termination message is reached - which
156 recvmsg() will mark by setting MSG_EOR.
157 RXRPC_ABORT
159 The data for this is a 32-bit integer that is the abort code.
160 [sendmsg] When passed to sendmsg(), this causes the operation
162 matching the tag to be aborted; this will be followed up by
163 recvmsg() indicating MSG_EOR and a local error of ECONNABORTED,
164 thereby terminating the tag.
165 [recvmsg] When obtained from recvmsg(), this indicates that a
167 remote abort was received from the peer and the data gives the
168 code for that abort.
169 RXRPC_ACK
171 [recvmsg] This conveys no data. It indicates the final acknowl‐
172 edgement to a service call has been received.
173 RXRPC_NET_ERROR
175 [recvmsg] This conveys a 32-bit integer into which the network
176 error that terminated a call will have been placed.
177 RXRPC_BUSY
179 [recvmsg] This conveys no data. It indicates that the operation
180 has been rejected because the server is busy.
181 RXRPC_LOCAL_ERROR
183 [recvmsg] This conveys a 32-bit integer into which the local
184 error that terminated a call will have been placed.
185 RXRPC_NEW_CALL
187 [recvmsg] This conveys no data. It indicates that a new service
188 call has arrived at a server socket and is in need of a tag.
189 RXRPC_ACCEPT is must be used for that.
190 RXRPC_ACCEPT
192 The data for this is an arbitrary long integer/pointer-sized tag
193 that represents the call to the kernel with the same semantics
194 as for RXRPC_USER_CALL_ID.
195 [sendmsg] Supply a user call ID tag to a new service call.
197 RXRPC_EXCLUSIVE_CALL
199 [sendmsg] Indicate that this particular call should be made on
200 its own connection with an unshared negotiated security context.
201 This requires no additional data.
202 RXRPC_UPGRADE_SERVICE
204 [sendmsg] Indicate that this call should attempt to probe the
205 service ID on the other side to see if it gets upgraded. The
206 answer can be found in the srx_service value of the peer address
207 recvmsg() returns for this call. This requires no additional
208 data.
209 RXRPC_TX_LENGTH
211 The data for this is a signed 64-bit integer.
212 [sendmsg] Specify the exact total transmit size. This allows
214 AF_RXRPC to work out in advance how big encrypted packets are
215 going to be (under some circumstances, there's a data length
216 encrypted inside the packet).
217 If this is set, it may allow AF_RXRPC to be more efficient at
219 filling packets. If the wrong amount of data is given (too lit‐
220 tle or too much), then the call will be aborted.
221 RXRPC_SET_CALL_TIMEOUT
223 The data for this is an array of 1-3 32-bit integers.
224 [sendmsg] Specify various call timeouts. The first timeout is
226 the hard timeout for the call in seconds: the call will be
227 aborted if it takes longer than this amount of time in total.
228 The second timeout is the idle timeout for the call in millisec‐
230 onds: the call will be aborted if we don't receive the next DATA
231 packet within that amount of time during the reception phase.
232 The third timeout is the normal timeout for the call in mil‐
234 liseconds: the call will be aborted if we go for that amount of
235 time without receiving any type of packet pertaining to the
236 call.
237
241 kafs(7), request_key(2)
242Linux 16 Apr 2019 AF_RXRPC(7)