Lines Matching refs:the
38 reliable virtual connections using UDP over IPv4 (or IPv6) as the transport
39 layer, but implements a real network protocol; and there's the presentation
57 making the session part of it a Linux network protocol (AF_RXRPC).
59 (2) A two-phase protocol. The client transmits a blob (the request) and then
60 receives a blob (the reply), and the server receives the request and then
61 transmits the reply.
63 (3) Retention of the reusable bits of the transport system set up for one call
66 (4) A secure protocol, using the Linux kernel's key retention facility to
67 manage security on the client end. The server end must of necessity be
71 left to the application. AF_RXRPC only deals in blobs. Even the operation ID
72 is just the first four bytes of the request blob, and as such is beyond the
80 (2) provided with a protocol of the type of underlying transport they're going
92 An overview of the RxRPC protocol:
94 (*) RxRPC sits on top of another networking protocol (UDP is the only option
99 endpoint, thus allowing the endpoints to be shared, even to the same
103 to multiple services. A service may be considered the RxRPC equivalent of
126 (*) Calls are two-phase and asymmetric: the client sends its request data,
127 which the service receives; then the service transmits the reply data
128 which the client receives.
130 (*) The data blobs are of indefinite size, the end of a phase is marked with a
131 flag in the packet. The number of packets of data making up one blob may
132 not exceed 4 billion, however, as this would cause the sequence number to
135 (*) The first four bytes of the request data are the service operation ID.
138 initiated by the first data packet on it arriving. If security is
139 requested, the server then issues a "challenge" and then the client
140 replies with a "response". If the response is successful, the security is
141 set for the lifetime of that connection, and all subsequent calls made
142 upon it use that same security. In the event that the server lets a
143 connection lapse before the client, the security will be renegotiated if
144 the client uses the connection again.
150 A hard-ACK indicates to the far side that all the data received to a point
151 has been received and processed; a soft-ACK indicates that the data has
155 (*) Reception of a reply data packet implicitly hard-ACK's all the data
156 packets that make up the request.
158 (*) An call is complete when the request has been sent, the reply has been
159 received and the final hard-ACK on the last packet of the reply has
160 reached the server.
169 About the AF_RXRPC driver:
171 (*) The AF_RXRPC protocol transparently uses internal sockets of the transport
176 make multiple simultaneous calls to the same service. One server socket
183 the last call currently using it has completed in case a new call is made
187 time [tunable] after the last connection using it discarded, in case a new
191 the same key struct describing their security (and assuming the calls
192 would otherwise share the connection). Non-secured calls would also be
195 (*) A server-side connection is shared if the client says it is.
197 (*) ACK'ing is handled by the protocol driver automatically, including ping
200 (*) SO_KEEPALIVE automatically pings the other side to keep the connection
207 Interaction with the user of the RxRPC socket:
212 (*) In the client, sending a request is achieved with one or more sendmsgs,
213 followed by the reply being received with one or more recvmsgs.
217 tag is carried in the control data.
220 socket. This may be overridden by supplying an alternate address to the
224 bound before the operation takes place.
226 (*) A server socket may also be used to make client calls. To do this, the
227 first sendmsg() of the call must specify the target address. The server's
228 transport endpoint is used to send the packets.
230 (*) Once the application has received the last message associated with a call,
231 the tag is guaranteed not to be seen again, and so it can be used to pin
232 client resources. A new call can then be initiated with the same tag
235 (*) In the server, a request is received with one or more recvmsgs, then the
236 the reply is transmitted with one or more sendmsgs, and then the final ACK
246 to indicate the terminal message for that call.
248 (*) A call may be aborted by adding an abort control message to the control
249 data. Issuing an abort terminates the kernel's use of that call's tag.
250 Any messages waiting in the receive queue for that call will be discarded.
253 and control data messages will be set to indicate the context. Receiving
254 an abort or a busy message terminates the kernel's use of that call's tag.
256 (*) The control data part of the msghdr struct is used for a number of things:
258 (*) The tag of the intended or affected call.
266 (*) When the kernel has received and set up an incoming call, it sends a
269 application then uses sendmsg to assign a tag to the new call. Once that
270 is done, the first part of the request data will be delivered by recvmsg.
272 (*) The server application has to provide the server socket with a keyring of
273 secret keys corresponding to the security types it permits. When a secure
274 connection is being set up, the kernel looks up the appropriate secret key
275 in the keyring and then sends a challenge packet to the client and
276 receives a response packet. The kernel then checks the authorisation of
277 the packet and either aborts the connection or sets up the security.
279 (*) The name of the key a client will use to secure its communications is
286 the receive queue, then recvmsg will keep working through them until:
288 (a) it meets the end of that call's received data,
294 (d) it fills the user buffer.
296 If recvmsg is called in blocking mode, it will keep sleeping, awaiting the
297 reception of further data, until one of the above four conditions is met.
300 data in the buffer rather than sleeping until it can fill the buffer.
303 then the remainder of that message will be left on the front of the queue
304 for the next taker. MSG_TRUNC will never be flagged.
306 (4) If there is more data to be had on a call (it hasn't copied the last byte
307 of the last data message in that phase yet), then MSG_MORE will be
333 This is used to indicate the application's call ID. It's an unsigned long
334 that the app specifies in the client by attaching it to the first data
335 message or in the server by passing it in association with an RXRPC_ACCEPT
337 those of the RXRPC_NEW_CALL message.
344 specify the call affected. If an abort is being sent, then error EBADSLT
349 This is delivered to a server application to indicate that the final ACK
350 of a call was received from the client. It will be associated with an
351 RXRPC_USER_CALL_ID to indicate the call that's now complete.
356 was encountered in the process of trying to talk to the peer. An
357 errno-class integer value will be included in the control message data
358 indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call
364 rejected by the server due to the server being busy. It will be
365 associated with an RXRPC_USER_CALL_ID to indicate the rejected call.
371 errno-class integer value will be included in the control message data
372 indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call
385 to indicate the user ID to be assigned. If there is no call to be
387 return error ENODATA. If the user ID is already in use by another call,
395 AF_RXRPC sockets support a few socket options at the SOL_RXRPC level:
399 This is used to specify the description of the key to be used. The key is
400 extracted from the calling process's keyrings with request_key() and
403 The optval pointer points to the description string, and optlen indicates
404 how long the string is, without the NUL terminator.
409 type "keyring"). See the "Security" section.
418 This is used to specify the minimum security level required for calls on
419 this socket. optval must point to an int containing one of the following
429 encrypted - which includes the actual packet length.
441 Currently, only the kerberos 4 equivalent protocol has been implemented
442 (security index 2 - rxkad). This requires the rxkad module to be loaded and,
443 on the client, tickets of the appropriate type to be obtained from the AFS
444 kaserver or the kerberos server and installed as "rxrpc" type keys. This is
445 normally done using the klog program. An example simple klog program can be
450 The payload provided to add_key() on the client should be of the following
460 uint8_t ticket[0]; /* the encrypted ticket */
463 Where the ticket blob is just appended to the above structure.
466 For the server, keys of type "rxrpc_s" must be made available to the server.
468 rxkad key for the AFS VL service). When such a key is created, it should be
469 given the server's secret key as the instantiation data (see the example
474 A keyring is passed to the server socket by naming it in a sockopt. The server
475 socket then looks the server secret keys up in this keyring when secure
492 Where the third parameter indicates the protocol family of the transport
507 This specifies the local UDP port to be used. If not given, a random
517 This issues a request_key() to get the key representing the security
537 (5) The request data should then be posted to the server socket using a series
538 of sendmsg() calls, each with the following control message attached:
540 RXRPC_USER_CALL_ID - specifies the user ID for this call
542 MSG_MORE should be set in msghdr::msg_flags on all but the last part of
543 the request. Multiple requests may be made simultaneously.
545 If a call is intended to go to a destination other than the default
546 specified through connect(), then msghdr::msg_name should be set on the
549 (6) The reply data will then be posted to the server socket for recvmsg() to
551 for a particular call to be read. MSG_EOR will be set on the terminal
554 All data will be delivered with the following control message attached:
556 RXRPC_USER_CALL_ID - specifies the user ID for this call
558 If an abort or error occurred, this will be returned in the control data
559 buffer instead, and MSG_EOR will be flagged to indicate the end of that
567 A server would be set up to accept operations in the following manner:
573 Where the third parameter indicates the address type of the transport
576 (2) Security is set up if desired by giving the socket a keyring with server
588 The keyring can be manipulated after it has been given to the socket. This
589 permits the server to add more keys, replace keys, etc. whilst it is live.
607 (4) The kernel notifies the server of pending incoming connections by sending
608 it a message for each. This is received with recvmsg() on the server
615 ignored since the call for which the message was posted may have gone by
616 the time it is accepted - in which case the first call still on the queue
619 (5) The server then accepts the new call by issuing a sendmsg() with two
625 (6) The first request data packet will then be posted to the server socket for
626 recvmsg() to pick up. At that point, the RxRPC address for the call can
627 be read from the address fields in the msghdr struct.
629 Subsequent request data will be posted to the server socket for recvmsg()
630 to collect as it arrives. All but the last piece of the request data will
633 All data will be delivered with the following control message attached:
635 RXRPC_USER_CALL_ID - specifies the user ID for this call
637 (8) The reply data should then be posted to the server socket using a series
638 of sendmsg() calls, each with the following control messages attached:
640 RXRPC_USER_CALL_ID - specifies the user ID for this call
642 MSG_MORE should be set in msghdr::msg_flags on all but the last message
645 (9) The final ACK from the client will be posted for retrieval by recvmsg()
646 when it is received. It will take the form of a dataless message with two
649 RXRPC_USER_CALL_ID - specifies the user ID for this call
652 MSG_EOR will be flagged to indicate that this is the final message for
655 (10) Up to the point the final packet of reply data is sent, the call can be
656 aborted by calling sendmsg() with a dataless message with the following
659 RXRPC_USER_CALL_ID - specifies the user ID for this call
662 Any packets waiting in the socket's receive queue will be discarded if
665 Note that all the communications for a particular service take place through
666 the one server socket, using control messages on sendmsg() and recvmsg() to
667 determine the call affected.
675 such as the AFS filesystem. This permits such a utility to:
681 (2) Avoid having RxRPC call request_key() at the point of issue of a call or
682 opening of a socket. Instead the utility is responsible for requesting a
683 key at the appropriate point. AFS, for instance, would do this during VFS
685 when the call is initiated.
687 (3) Request the use of something other than GFP_KERNEL to allocate memory.
689 (4) Avoid the overhead of using the recvmsg() call. RxRPC messages can be
690 intercepted before they get put into the socket Rx queue and the socket
693 To use the RxRPC facility, a kernel utility must still open an AF_RXRPC socket,
695 then it passes this to the kernel interface functions.
708 This allocates the infrastructure to make a new RxRPC call and assigns
709 call and connection numbers. The call will be made on the UDP port that
710 the socket is bound to. The call will go to the destination address of a
714 If a key is supplied then this will be used to secure the call instead of
715 the key bound to the socket with the RXRPC_SECURITY_KEY sockopt. Calls
718 The user_call_ID is equivalent to that supplied to sendmsg() in the
722 If this function is successful, an opaque reference to the RxRPC call is
732 the specified call.
739 This is used to supply either the request part of a client call or the
740 reply part of a server call. msg.msg_iovlen and msg.msg_iov specify the
746 other than MSG_MORE. len is the total amount of data to transmit.
753 abort code specified will be placed in the ABORT message sent.
765 This installs an interceptor function on the specified AF_RXRPC socket.
766 All messages that would otherwise wind up in the socket's Rx queue are
768 the messages in the right order to maintain DATA message sequentiality.
770 The interceptor function itself is provided with the address of the socket
771 and handling the incoming message, the ID assigned by the kernel utility
772 to the call and the socket buffer containing the message.
774 The skb->mark field indicates the type of message:
790 Data messages can have their contents extracted with the usual bunch of
792 be the last one in a sequence with rxrpc_kernel_is_data_last(). When a
798 freeing, but this may pin the state of a call until the message is finally
809 be ended in the same way.
811 If this function is successful, an opaque reference to the RxRPC call is
819 This is used to reject the first incoming call on the socket's queue with
821 Other errors may be returned if the call had been aborted (-ECONNABORTED)
824 (*) Record the delivery of a data message and free it.
829 update the ACK state for the call. The socket buffer will be freed.
838 (*) Determine if a data message is the last one on a call.
842 This is used to determine if a socket buffer holds the last data message
846 The data message will be part of the reply on a client call and the
847 request on an incoming call. In the latter case there will be more
848 messages, but in the former case there will not.
850 (*) Get the abort code from an abort message.
854 This is used to extract the abort code from a remote abort message.
856 (*) Get the error number from a local or network error message.
860 This is used to extract the error number from a message indicating either
880 The amount of time in milliseconds after receiving a packet with the
881 request-ack flag set before we honour the flag and actually send the
884 Usually the other side won't stop sending packets until the advertised
885 reception window is full (to a maximum of 255 packets), so delaying the
891 generate a soft-ACK to tell the sender that it doesn't need to resend.
895 The amount of time in milliseconds after all the packets currently in the
897 the sender it can free its buffers, assuming no other reason occurs that
903 transmit it again, assuming no ACK is received from the receiver telling
913 The amount of time in seconds before we remove a dead call from the call
914 list. Dead calls are kept around for a little while for the purpose of
920 remove it from the connection list. Whilst a connection is in existence,
922 the security must be renegotiated.
927 remove it from the transport list. Whilst a transport is in existence, it
928 serves to anchor the peer data and keeps the connection ID counter.
932 The size of the receive window in packets. This is the maximum number of
939 indicates to the peer whether we're willing to accept jumbo packets.