1AF_RXRPC(7)                Linux Programmer's Manual               AF_RXRPC(7)
2
3
4

NAME

6       rxrpc - Linux RxRPC (AFS) protocol implementation
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <linux/rxrpc.h>
11
12       socket = socket(AF_RXRPC, SOCK_DGRAM, PF_INET);
13       socket = socket(AF_RXRPC, SOCK_DGRAM, PF_INET6);
14
15

DESCRIPTION

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
21       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
27       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
32   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
45       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
50       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
55   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
60       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
65              If this isn't set, AF_RXRPC  will  perform  an  unauthenticated,
66              unencrypted call to the server.
67
68       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
73              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
77       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
82       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
90
91       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
97              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
102              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
107       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
114   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
118       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
136
137   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
144       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
150              [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
154              [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
158       RXRPC_ABORT
159              The data for this is a 32-bit integer that is the abort code.
160
161              [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
166              [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
170       RXRPC_ACK
171              [recvmsg] This conveys no data.  It indicates the final acknowl‐
172              edgement to a service call has been received.
173
174       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
178       RXRPC_BUSY
179              [recvmsg] This conveys no data.  It indicates that the operation
180              has been rejected because the server is busy.
181
182       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
186       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
191       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
196              [sendmsg] Supply a user call ID tag to a new service call.
197
198       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
203       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
210       RXRPC_TX_LENGTH
211              The data for this is a signed 64-bit integer.
212
213              [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
218              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
222       RXRPC_SET_CALL_TIMEOUT
223              The data for this is an array of 1-3 32-bit integers.
224
225              [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
229              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
233              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
238
239

SEE ALSO

241       kafs(7), request_key(2)
242
243
244
245Linux                             16 Apr 2019                      AF_RXRPC(7)
Impressum