^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) RxRPC Network Protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The RxRPC protocol driver provides a reliable two-phase transport on top of UDP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) that can be used to perform RxRPC remote operations. This is done over sockets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) of AF_RXRPC family, using sendmsg() and recvmsg() with control data to send and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) receive data, aborts and errors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Contents of this document:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) (#) Overview.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) (#) RxRPC protocol summary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) (#) AF_RXRPC driver model.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) (#) Control messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) (#) Socket options.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) (#) Security.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) (#) Example client usage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) (#) Example server usage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) (#) AF_RXRPC kernel interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) (#) Configurable parameters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) RxRPC is a two-layer protocol. There is a session layer which provides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) reliable virtual connections using UDP over IPv4 (or IPv6) as the transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) layer, but implements a real network protocol; and there's the presentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) layer which renders structured data to binary blobs and back again using XDR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) (as does SunRPC)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) +-------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) | Application |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) +-------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) | XDR | Presentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) +-------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) | RxRPC | Session
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) +-------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) | UDP | Transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) +-------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) AF_RXRPC provides:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) (1) Part of an RxRPC facility for both kernel and userspace applications by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) making the session part of it a Linux network protocol (AF_RXRPC).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) (2) A two-phase protocol. The client transmits a blob (the request) and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) receives a blob (the reply), and the server receives the request and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) transmits the reply.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) (3) Retention of the reusable bits of the transport system set up for one call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) to speed up subsequent calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) (4) A secure protocol, using the Linux kernel's key retention facility to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) manage security on the client end. The server end must of necessity be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) more active in security negotiations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) AF_RXRPC does not provide XDR marshalling/presentation facilities. That is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) left to the application. AF_RXRPC only deals in blobs. Even the operation ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) is just the first four bytes of the request blob, and as such is beyond the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) kernel's interest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Sockets of AF_RXRPC family are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) (1) created as type SOCK_DGRAM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) (2) provided with a protocol of the type of underlying transport they're going
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) to use - currently only PF_INET is supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) The Andrew File System (AFS) is an example of an application that uses this and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) that has both kernel (filesystem) and userspace (utility) components.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) RxRPC Protocol Summary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) An overview of the RxRPC protocol:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) (#) RxRPC sits on top of another networking protocol (UDP is the only option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) currently), and uses this to provide network transport. UDP ports, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) example, provide transport endpoints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) (#) RxRPC supports multiple virtual "connections" from any given transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) endpoint, thus allowing the endpoints to be shared, even to the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) remote endpoint.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) (#) Each connection goes to a particular "service". A connection may not go
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) to multiple services. A service may be considered the RxRPC equivalent of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) a port number. AF_RXRPC permits multiple services to share an endpoint.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) (#) Client-originating packets are marked, thus a transport endpoint can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) shared between client and server connections (connections have a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) direction).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) (#) Up to a billion connections may be supported concurrently between one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) local transport endpoint and one service on one remote endpoint. An RxRPC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) connection is described by seven numbers::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Local address }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Local port } Transport (UDP) address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Remote address }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Remote port }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Direction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Connection ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Service ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) (#) Each RxRPC operation is a "call". A connection may make up to four
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) billion calls, but only up to four calls may be in progress on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) connection at any one time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) (#) Calls are two-phase and asymmetric: the client sends its request data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) which the service receives; then the service transmits the reply data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) which the client receives.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) (#) The data blobs are of indefinite size, the end of a phase is marked with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) flag in the packet. The number of packets of data making up one blob may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) not exceed 4 billion, however, as this would cause the sequence number to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) wrap.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) (#) The first four bytes of the request data are the service operation ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) (#) Security is negotiated on a per-connection basis. The connection is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) initiated by the first data packet on it arriving. If security is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) requested, the server then issues a "challenge" and then the client
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) replies with a "response". If the response is successful, the security is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) set for the lifetime of that connection, and all subsequent calls made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) upon it use that same security. In the event that the server lets a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) connection lapse before the client, the security will be renegotiated if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) the client uses the connection again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) (#) Calls use ACK packets to handle reliability. Data packets are also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) explicitly sequenced per call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) (#) There are two types of positive acknowledgment: hard-ACKs and soft-ACKs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) A hard-ACK indicates to the far side that all the data received to a point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) has been received and processed; a soft-ACK indicates that the data has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) been received but may yet be discarded and re-requested. The sender may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) not discard any transmittable packets until they've been hard-ACK'd.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) (#) Reception of a reply data packet implicitly hard-ACK's all the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) packets that make up the request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) (#) An call is complete when the request has been sent, the reply has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) received and the final hard-ACK on the last packet of the reply has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) reached the server.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) (#) An call may be aborted by either end at any time up to its completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) AF_RXRPC Driver Model
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) About the AF_RXRPC driver:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) (#) The AF_RXRPC protocol transparently uses internal sockets of the transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) protocol to represent transport endpoints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) (#) AF_RXRPC sockets map onto RxRPC connection bundles. Actual RxRPC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) connections are handled transparently. One client socket may be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) make multiple simultaneous calls to the same service. One server socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) may handle calls from many clients.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) (#) Additional parallel client connections will be initiated to support extra
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) concurrent calls, up to a tunable limit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) (#) Each connection is retained for a certain amount of time [tunable] after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) the last call currently using it has completed in case a new call is made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) that could reuse it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) (#) Each internal UDP socket is retained [tunable] for a certain amount of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) time [tunable] after the last connection using it discarded, in case a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) connection is made that could use it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) (#) A client-side connection is only shared between calls if they have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) the same key struct describing their security (and assuming the calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) would otherwise share the connection). Non-secured calls would also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) able to share connections with each other.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) (#) A server-side connection is shared if the client says it is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) (#) ACK'ing is handled by the protocol driver automatically, including ping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) replying.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) (#) SO_KEEPALIVE automatically pings the other side to keep the connection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) alive [TODO].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) (#) If an ICMP error is received, all calls affected by that error will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) aborted with an appropriate network error passed through recvmsg().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Interaction with the user of the RxRPC socket:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) (#) A socket is made into a server socket by binding an address with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) non-zero service ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) (#) In the client, sending a request is achieved with one or more sendmsgs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) followed by the reply being received with one or more recvmsgs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) (#) The first sendmsg for a request to be sent from a client contains a tag to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) be used in all other sendmsgs or recvmsgs associated with that call. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) tag is carried in the control data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) (#) connect() is used to supply a default destination address for a client
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) socket. This may be overridden by supplying an alternate address to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) first sendmsg() of a call (struct msghdr::msg_name).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) (#) If connect() is called on an unbound client, a random local port will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) bound before the operation takes place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) (#) A server socket may also be used to make client calls. To do this, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) first sendmsg() of the call must specify the target address. The server's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) transport endpoint is used to send the packets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) (#) Once the application has received the last message associated with a call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) the tag is guaranteed not to be seen again, and so it can be used to pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) client resources. A new call can then be initiated with the same tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) without fear of interference.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) (#) In the server, a request is received with one or more recvmsgs, then the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) the reply is transmitted with one or more sendmsgs, and then the final ACK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) is received with a last recvmsg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) (#) When sending data for a call, sendmsg is given MSG_MORE if there's more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) data to come on that call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) (#) When receiving data for a call, recvmsg flags MSG_MORE if there's more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) data to come for that call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) (#) When receiving data or messages for a call, MSG_EOR is flagged by recvmsg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) to indicate the terminal message for that call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) (#) A call may be aborted by adding an abort control message to the control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) data. Issuing an abort terminates the kernel's use of that call's tag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) Any messages waiting in the receive queue for that call will be discarded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) (#) Aborts, busy notifications and challenge packets are delivered by recvmsg,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) and control data messages will be set to indicate the context. Receiving
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) an abort or a busy message terminates the kernel's use of that call's tag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) (#) The control data part of the msghdr struct is used for a number of things:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) (#) The tag of the intended or affected call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) (#) Sending or receiving errors, aborts and busy notifications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) (#) Notifications of incoming calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) (#) Sending debug requests and receiving debug replies [TODO].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) (#) When the kernel has received and set up an incoming call, it sends a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) message to server application to let it know there's a new call awaiting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) its acceptance [recvmsg reports a special control message]. The server
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) application then uses sendmsg to assign a tag to the new call. Once that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) is done, the first part of the request data will be delivered by recvmsg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) (#) The server application has to provide the server socket with a keyring of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) secret keys corresponding to the security types it permits. When a secure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) connection is being set up, the kernel looks up the appropriate secret key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) in the keyring and then sends a challenge packet to the client and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) receives a response packet. The kernel then checks the authorisation of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) the packet and either aborts the connection or sets up the security.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) (#) The name of the key a client will use to secure its communications is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) nominated by a socket option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) Notes on sendmsg:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) (#) MSG_WAITALL can be set to tell sendmsg to ignore signals if the peer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) making progress at accepting packets within a reasonable time such that we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) manage to queue up all the data for transmission. This requires the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) client to accept at least one packet per 2*RTT time period.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) If this isn't set, sendmsg() will return immediately, either returning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) EINTR/ERESTARTSYS if nothing was consumed or returning the amount of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) consumed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) Notes on recvmsg:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) (#) If there's a sequence of data messages belonging to a particular call on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) the receive queue, then recvmsg will keep working through them until:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) (a) it meets the end of that call's received data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) (b) it meets a non-data message,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) (c) it meets a message belonging to a different call, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) (d) it fills the user buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) If recvmsg is called in blocking mode, it will keep sleeping, awaiting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) reception of further data, until one of the above four conditions is met.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) (2) MSG_PEEK operates similarly, but will return immediately if it has put any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) data in the buffer rather than sleeping until it can fill the buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) (3) If a data message is only partially consumed in filling a user buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) then the remainder of that message will be left on the front of the queue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) for the next taker. MSG_TRUNC will never be flagged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) (4) If there is more data to be had on a call (it hasn't copied the last byte
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) of the last data message in that phase yet), then MSG_MORE will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) flagged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) Control Messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) AF_RXRPC makes use of control messages in sendmsg() and recvmsg() to multiplex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) calls, to invoke certain actions and to report certain conditions. These are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) ======================= === =========== ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) MESSAGE ID SRT DATA MEANING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) ======================= === =========== ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) RXRPC_USER_CALL_ID sr- User ID App's call specifier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) RXRPC_ABORT srt Abort code Abort code to issue/received
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) RXRPC_ACK -rt n/a Final ACK received
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) RXRPC_NET_ERROR -rt error num Network error on call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) RXRPC_BUSY -rt n/a Call rejected (server busy)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) RXRPC_LOCAL_ERROR -rt error num Local error encountered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) RXRPC_NEW_CALL -r- n/a New call received
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) RXRPC_ACCEPT s-- n/a Accept new call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) RXRPC_EXCLUSIVE_CALL s-- n/a Make an exclusive client call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) RXRPC_UPGRADE_SERVICE s-- n/a Client call can be upgraded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) RXRPC_TX_LENGTH s-- data len Total length of Tx data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) ======================= === =========== ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) (SRT = usable in Sendmsg / delivered by Recvmsg / Terminal message)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) (#) RXRPC_USER_CALL_ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) This is used to indicate the application's call ID. It's an unsigned long
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) that the app specifies in the client by attaching it to the first data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) message or in the server by passing it in association with an RXRPC_ACCEPT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) message. recvmsg() passes it in conjunction with all messages except
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) those of the RXRPC_NEW_CALL message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) (#) RXRPC_ABORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) This is can be used by an application to abort a call by passing it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) sendmsg, or it can be delivered by recvmsg to indicate a remote abort was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) received. Either way, it must be associated with an RXRPC_USER_CALL_ID to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) specify the call affected. If an abort is being sent, then error EBADSLT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) will be returned if there is no call with that user ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) (#) RXRPC_ACK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) This is delivered to a server application to indicate that the final ACK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) of a call was received from the client. It will be associated with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) RXRPC_USER_CALL_ID to indicate the call that's now complete.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) (#) RXRPC_NET_ERROR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) This is delivered to an application to indicate that an ICMP error message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) was encountered in the process of trying to talk to the peer. An
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) errno-class integer value will be included in the control message data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) affected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) (#) RXRPC_BUSY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) This is delivered to a client application to indicate that a call was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) rejected by the server due to the server being busy. It will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) associated with an RXRPC_USER_CALL_ID to indicate the rejected call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) (#) RXRPC_LOCAL_ERROR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) This is delivered to an application to indicate that a local error was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) encountered and that a call has been aborted because of it. An
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) errno-class integer value will be included in the control message data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) affected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) (#) RXRPC_NEW_CALL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) This is delivered to indicate to a server application that a new call has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) arrived and is awaiting acceptance. No user ID is associated with this,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) as a user ID must subsequently be assigned by doing an RXRPC_ACCEPT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) (#) RXRPC_ACCEPT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) This is used by a server application to attempt to accept a call and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) assign it a user ID. It should be associated with an RXRPC_USER_CALL_ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) to indicate the user ID to be assigned. If there is no call to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) accepted (it may have timed out, been aborted, etc.), then sendmsg will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) return error ENODATA. If the user ID is already in use by another call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) then error EBADSLT will be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) (#) RXRPC_EXCLUSIVE_CALL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) This is used to indicate that a client call should be made on a one-off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) connection. The connection is discarded once the call has terminated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) (#) RXRPC_UPGRADE_SERVICE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) This is used to make a client call to probe if the specified service ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) may be upgraded by the server. The caller must check msg_name returned to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) recvmsg() for the service ID actually in use. The operation probed must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) be one that takes the same arguments in both services.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) Once this has been used to establish the upgrade capability (or lack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) thereof) of the server, the service ID returned should be used for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) future communication to that server and RXRPC_UPGRADE_SERVICE should no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) longer be set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) (#) RXRPC_TX_LENGTH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) This is used to inform the kernel of the total amount of data that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) going to be transmitted by a call (whether in a client request or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) service response). If given, it allows the kernel to encrypt from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) userspace buffer directly to the packet buffers, rather than copying into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) the buffer and then encrypting in place. This may only be given with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) first sendmsg() providing data for a call. EMSGSIZE will be generated if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) the amount of data actually given is different.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) This takes a parameter of __s64 type that indicates how much will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) transmitted. This may not be less than zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) The symbol RXRPC__SUPPORTED is defined as one more than the highest control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) message type supported. At run time this can be queried by means of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) RXRPC_SUPPORTED_CMSG socket option (see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) SOCKET OPTIONS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) AF_RXRPC sockets support a few socket options at the SOL_RXRPC level:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) (#) RXRPC_SECURITY_KEY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) This is used to specify the description of the key to be used. The key is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) extracted from the calling process's keyrings with request_key() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) should be of "rxrpc" type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) The optval pointer points to the description string, and optlen indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) how long the string is, without the NUL terminator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) (#) RXRPC_SECURITY_KEYRING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) Similar to above but specifies a keyring of server secret keys to use (key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) type "keyring"). See the "Security" section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) (#) RXRPC_EXCLUSIVE_CONNECTION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) This is used to request that new connections should be used for each call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) made subsequently on this socket. optval should be NULL and optlen 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) (#) RXRPC_MIN_SECURITY_LEVEL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) This is used to specify the minimum security level required for calls on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) this socket. optval must point to an int containing one of the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) (a) RXRPC_SECURITY_PLAIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) Encrypted checksum only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) (b) RXRPC_SECURITY_AUTH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) Encrypted checksum plus packet padded and first eight bytes of packet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) encrypted - which includes the actual packet length.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) (c) RXRPC_SECURITY_ENCRYPT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) Encrypted checksum plus entire packet padded and encrypted, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) actual packet length.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) (#) RXRPC_UPGRADEABLE_SERVICE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) This is used to indicate that a service socket with two bindings may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) upgrade one bound service to the other if requested by the client. optval
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) must point to an array of two unsigned short ints. The first is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) service ID to upgrade from and the second the service ID to upgrade to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) (#) RXRPC_SUPPORTED_CMSG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) This is a read-only option that writes an int into the buffer indicating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) the highest control message type supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) SECURITY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) Currently, only the kerberos 4 equivalent protocol has been implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) (security index 2 - rxkad). This requires the rxkad module to be loaded and,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) on the client, tickets of the appropriate type to be obtained from the AFS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) kaserver or the kerberos server and installed as "rxrpc" type keys. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) normally done using the klog program. An example simple klog program can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) found at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) http://people.redhat.com/~dhowells/rxrpc/klog.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) The payload provided to add_key() on the client should be of the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) form::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) struct rxrpc_key_sec2_v1 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) uint16_t security_index; /* 2 */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) uint16_t ticket_length; /* length of ticket[] */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) uint32_t expiry; /* time at which expires */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) uint8_t kvno; /* key version number */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) uint8_t __pad[3];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) uint8_t session_key[8]; /* DES session key */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) uint8_t ticket[0]; /* the encrypted ticket */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) Where the ticket blob is just appended to the above structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) For the server, keys of type "rxrpc_s" must be made available to the server.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) They have a description of "<serviceID>:<securityIndex>" (eg: "52:2" for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) rxkad key for the AFS VL service). When such a key is created, it should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) given the server's secret key as the instantiation data (see the example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) add_key("rxrpc_s", "52:2", secret_key, 8, keyring);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) A keyring is passed to the server socket by naming it in a sockopt. The server
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) socket then looks the server secret keys up in this keyring when secure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) incoming connections are made. This can be seen in an example program that can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) be found at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) http://people.redhat.com/~dhowells/rxrpc/listen.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) EXAMPLE CLIENT USAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) A client would issue an operation by:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) (1) An RxRPC socket is set up by::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) client = socket(AF_RXRPC, SOCK_DGRAM, PF_INET);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) Where the third parameter indicates the protocol family of the transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) socket used - usually IPv4 but it can also be IPv6 [TODO].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) (2) A local address can optionally be bound::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) struct sockaddr_rxrpc srx = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) .srx_family = AF_RXRPC,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) .srx_service = 0, /* we're a client */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) .transport_type = SOCK_DGRAM, /* type of transport socket */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) .transport.sin_family = AF_INET,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) .transport.sin_port = htons(7000), /* AFS callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) .transport.sin_address = 0, /* all local interfaces */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) bind(client, &srx, sizeof(srx));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) This specifies the local UDP port to be used. If not given, a random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) non-privileged port will be used. A UDP port may be shared between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) several unrelated RxRPC sockets. Security is handled on a basis of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) per-RxRPC virtual connection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) (3) The security is set::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) const char *key = "AFS:cambridge.redhat.com";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) setsockopt(client, SOL_RXRPC, RXRPC_SECURITY_KEY, key, strlen(key));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) This issues a request_key() to get the key representing the security
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) context. The minimum security level can be set::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) unsigned int sec = RXRPC_SECURITY_ENCRYPT;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) setsockopt(client, SOL_RXRPC, RXRPC_MIN_SECURITY_LEVEL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) &sec, sizeof(sec));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) (4) The server to be contacted can then be specified (alternatively this can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) be done through sendmsg)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) struct sockaddr_rxrpc srx = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) .srx_family = AF_RXRPC,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) .srx_service = VL_SERVICE_ID,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) .transport_type = SOCK_DGRAM, /* type of transport socket */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) .transport.sin_family = AF_INET,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) .transport.sin_port = htons(7005), /* AFS volume manager */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) .transport.sin_address = ...,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) connect(client, &srx, sizeof(srx));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) (5) The request data should then be posted to the server socket using a series
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) of sendmsg() calls, each with the following control message attached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) RXRPC_USER_CALL_ID specifies the user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) MSG_MORE should be set in msghdr::msg_flags on all but the last part of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) the request. Multiple requests may be made simultaneously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) An RXRPC_TX_LENGTH control message can also be specified on the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) sendmsg() call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) If a call is intended to go to a destination other than the default
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) specified through connect(), then msghdr::msg_name should be set on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) first request message of that call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) (6) The reply data will then be posted to the server socket for recvmsg() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) pick up. MSG_MORE will be flagged by recvmsg() if there's more reply data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) for a particular call to be read. MSG_EOR will be set on the terminal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) read for a call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) All data will be delivered with the following control message attached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) RXRPC_USER_CALL_ID - specifies the user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) If an abort or error occurred, this will be returned in the control data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) buffer instead, and MSG_EOR will be flagged to indicate the end of that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) A client may ask for a service ID it knows and ask that this be upgraded to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) better service if one is available by supplying RXRPC_UPGRADE_SERVICE on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) first sendmsg() of a call. The client should then check srx_service in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) msg_name filled in by recvmsg() when collecting the result. srx_service will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) hold the same value as given to sendmsg() if the upgrade request was ignored by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) the service - otherwise it will be altered to indicate the service ID the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) server upgraded to. Note that the upgraded service ID is chosen by the server.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) The caller has to wait until it sees the service ID in the reply before sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) any more calls (further calls to the same destination will be blocked until the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) probe is concluded).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) Example Server Usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) A server would be set up to accept operations in the following manner:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) (1) An RxRPC socket is created by::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) server = socket(AF_RXRPC, SOCK_DGRAM, PF_INET);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) Where the third parameter indicates the address type of the transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) socket used - usually IPv4.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) (2) Security is set up if desired by giving the socket a keyring with server
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) secret keys in it::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) keyring = add_key("keyring", "AFSkeys", NULL, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) KEY_SPEC_PROCESS_KEYRING);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) const char secret_key[8] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) 0xa7, 0x83, 0x8a, 0xcb, 0xc7, 0x83, 0xec, 0x94 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) add_key("rxrpc_s", "52:2", secret_key, 8, keyring);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) setsockopt(server, SOL_RXRPC, RXRPC_SECURITY_KEYRING, "AFSkeys", 7);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) The keyring can be manipulated after it has been given to the socket. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) permits the server to add more keys, replace keys, etc. while it is live.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) (3) A local address must then be bound::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) struct sockaddr_rxrpc srx = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) .srx_family = AF_RXRPC,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) .srx_service = VL_SERVICE_ID, /* RxRPC service ID */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) .transport_type = SOCK_DGRAM, /* type of transport socket */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) .transport.sin_family = AF_INET,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) .transport.sin_port = htons(7000), /* AFS callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) .transport.sin_address = 0, /* all local interfaces */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) bind(server, &srx, sizeof(srx));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) More than one service ID may be bound to a socket, provided the transport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) parameters are the same. The limit is currently two. To do this, bind()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) should be called twice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) (4) If service upgrading is required, first two service IDs must have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) bound and then the following option must be set::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) unsigned short service_ids[2] = { from_ID, to_ID };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) setsockopt(server, SOL_RXRPC, RXRPC_UPGRADEABLE_SERVICE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) service_ids, sizeof(service_ids));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) This will automatically upgrade connections on service from_ID to service
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) to_ID if they request it. This will be reflected in msg_name obtained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) through recvmsg() when the request data is delivered to userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) (5) The server is then set to listen out for incoming calls::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) listen(server, 100);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) (6) The kernel notifies the server of pending incoming connections by sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) it a message for each. This is received with recvmsg() on the server
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) socket. It has no data, and has a single dataless control message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) attached::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) RXRPC_NEW_CALL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) The address that can be passed back by recvmsg() at this point should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) ignored since the call for which the message was posted may have gone by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) the time it is accepted - in which case the first call still on the queue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) will be accepted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) (7) The server then accepts the new call by issuing a sendmsg() with two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) pieces of control data and no actual data:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) ================== ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) RXRPC_ACCEPT indicate connection acceptance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) RXRPC_USER_CALL_ID specify user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) ================== ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) (8) The first request data packet will then be posted to the server socket for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) recvmsg() to pick up. At that point, the RxRPC address for the call can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) be read from the address fields in the msghdr struct.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) Subsequent request data will be posted to the server socket for recvmsg()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) to collect as it arrives. All but the last piece of the request data will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) be delivered with MSG_MORE flagged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) All data will be delivered with the following control message attached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) RXRPC_USER_CALL_ID specifies the user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) (9) The reply data should then be posted to the server socket using a series
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) of sendmsg() calls, each with the following control messages attached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) RXRPC_USER_CALL_ID specifies the user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) MSG_MORE should be set in msghdr::msg_flags on all but the last message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) for a particular call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) (10) The final ACK from the client will be posted for retrieval by recvmsg()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) when it is received. It will take the form of a dataless message with two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) control messages attached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) RXRPC_USER_CALL_ID specifies the user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) RXRPC_ACK indicates final ACK (no data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) MSG_EOR will be flagged to indicate that this is the final message for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) this call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) (11) Up to the point the final packet of reply data is sent, the call can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) aborted by calling sendmsg() with a dataless message with the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) control messages attached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) RXRPC_USER_CALL_ID specifies the user ID for this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) RXRPC_ABORT indicates abort code (4 byte data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) ================== ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) Any packets waiting in the socket's receive queue will be discarded if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) this is issued.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) Note that all the communications for a particular service take place through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) the one server socket, using control messages on sendmsg() and recvmsg() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) determine the call affected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) AF_RXRPC Kernel Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) The AF_RXRPC module also provides an interface for use by in-kernel utilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) such as the AFS filesystem. This permits such a utility to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) (1) Use different keys directly on individual client calls on one socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) rather than having to open a whole slew of sockets, one for each key it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) might want to use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) (2) Avoid having RxRPC call request_key() at the point of issue of a call or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) opening of a socket. Instead the utility is responsible for requesting a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) key at the appropriate point. AFS, for instance, would do this during VFS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) operations such as open() or unlink(). The key is then handed through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) when the call is initiated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) (3) Request the use of something other than GFP_KERNEL to allocate memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) (4) Avoid the overhead of using the recvmsg() call. RxRPC messages can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) intercepted before they get put into the socket Rx queue and the socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) buffers manipulated directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) To use the RxRPC facility, a kernel utility must still open an AF_RXRPC socket,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) bind an address as appropriate and listen if it's to be a server socket, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) then it passes this to the kernel interface functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) The kernel interface functions are as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) (#) Begin a new client call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) struct rxrpc_call *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) rxrpc_kernel_begin_call(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) struct sockaddr_rxrpc *srx,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) struct key *key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) unsigned long user_call_ID,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) s64 tx_total_len,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) gfp_t gfp,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) rxrpc_notify_rx_t notify_rx,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) bool upgrade,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) bool intr,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) unsigned int debug_id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) This allocates the infrastructure to make a new RxRPC call and assigns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) call and connection numbers. The call will be made on the UDP port that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) the socket is bound to. The call will go to the destination address of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) connected client socket unless an alternative is supplied (srx is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) non-NULL).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) If a key is supplied then this will be used to secure the call instead of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) the key bound to the socket with the RXRPC_SECURITY_KEY sockopt. Calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) secured in this way will still share connections if at all possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) The user_call_ID is equivalent to that supplied to sendmsg() in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) control data buffer. It is entirely feasible to use this to point to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) kernel data structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) tx_total_len is the amount of data the caller is intending to transmit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) with this call (or -1 if unknown at this point). Setting the data size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) allows the kernel to encrypt directly to the packet buffers, thereby
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) saving a copy. The value may not be less than -1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) notify_rx is a pointer to a function to be called when events such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) incoming data packets or remote aborts happen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) upgrade should be set to true if a client operation should request that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) the server upgrade the service to a better one. The resultant service ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) is returned by rxrpc_kernel_recv_data().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) intr should be set to true if the call should be interruptible. If this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) is not set, this function may not return until a channel has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) allocated; if it is set, the function may return -ERESTARTSYS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) debug_id is the call debugging ID to be used for tracing. This can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) obtained by atomically incrementing rxrpc_debug_id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) If this function is successful, an opaque reference to the RxRPC call is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) returned. The caller now holds a reference on this and it must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) properly ended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) (#) End a client call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) void rxrpc_kernel_end_call(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) struct rxrpc_call *call);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) This is used to end a previously begun call. The user_call_ID is expunged
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) from AF_RXRPC's knowledge and will not be seen again in association with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) the specified call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) (#) Send data through a call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) typedef void (*rxrpc_notify_end_tx_t)(struct sock *sk,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) unsigned long user_call_ID,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) int rxrpc_kernel_send_data(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) struct msghdr *msg,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) size_t len,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) rxrpc_notify_end_tx_t notify_end_rx);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) This is used to supply either the request part of a client call or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) reply part of a server call. msg.msg_iovlen and msg.msg_iov specify the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) data buffers to be used. msg_iov may not be NULL and must point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) exclusively to in-kernel virtual addresses. msg.msg_flags may be given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) MSG_MORE if there will be subsequent data sends for this call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) The msg must not specify a destination address, control data or any flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) other than MSG_MORE. len is the total amount of data to transmit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) notify_end_rx can be NULL or it can be used to specify a function to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) called when the call changes state to end the Tx phase. This function is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883) called with the call-state spinlock held to prevent any reply or final ACK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) from being delivered first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) (#) Receive data from a call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) int rxrpc_kernel_recv_data(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) void *buf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) size_t size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) size_t *_offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) bool want_more,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894) u32 *_abort,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) u16 *_service)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) This is used to receive data from either the reply part of a client call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) or the request part of a service call. buf and size specify how much
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899) data is desired and where to store it. *_offset is added on to buf and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) subtracted from size internally; the amount copied into the buffer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) added to *_offset before returning.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) want_more should be true if further data will be required after this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904) satisfied and false if this is the last item of the receive phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) There are three normal returns: 0 if the buffer was filled and want_more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) was true; 1 if the buffer was filled, the last DATA packet has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) emptied and want_more was false; and -EAGAIN if the function needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) called again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) If the last DATA packet is processed but the buffer contains less than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) the amount requested, EBADMSG is returned. If want_more wasn't set, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) more data was available, EMSGSIZE is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) If a remote ABORT is detected, the abort code received will be stored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916) ``*_abort`` and ECONNABORTED will be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) The service ID that the call ended up with is returned into *_service.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) This can be used to see if a call got a service upgrade.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) (#) Abort a call??
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) void rxrpc_kernel_abort_call(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) u32 abort_code);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) This is used to abort a call if it's still in an abortable state. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) abort code specified will be placed in the ABORT message sent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) (#) Intercept received RxRPC messages::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) typedef void (*rxrpc_interceptor_t)(struct sock *sk,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) unsigned long user_call_ID,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) void
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) rxrpc_kernel_intercept_rx_messages(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) rxrpc_interceptor_t interceptor);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) This installs an interceptor function on the specified AF_RXRPC socket.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) All messages that would otherwise wind up in the socket's Rx queue are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) then diverted to this function. Note that care must be taken to process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) the messages in the right order to maintain DATA message sequentiality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947) The interceptor function itself is provided with the address of the socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) and handling the incoming message, the ID assigned by the kernel utility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) to the call and the socket buffer containing the message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) The skb->mark field indicates the type of message:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) =============================== =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) Mark Meaning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955) =============================== =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956) RXRPC_SKB_MARK_DATA Data message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) RXRPC_SKB_MARK_FINAL_ACK Final ACK received for an incoming call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958) RXRPC_SKB_MARK_BUSY Client call rejected as server busy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) RXRPC_SKB_MARK_REMOTE_ABORT Call aborted by peer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960) RXRPC_SKB_MARK_NET_ERROR Network error detected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) RXRPC_SKB_MARK_LOCAL_ERROR Local error encountered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) RXRPC_SKB_MARK_NEW_CALL New incoming call awaiting acceptance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) =============================== =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) The remote abort message can be probed with rxrpc_kernel_get_abort_code().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) The two error messages can be probed with rxrpc_kernel_get_error_number().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) A new call can be accepted with rxrpc_kernel_accept_call().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969) Data messages can have their contents extracted with the usual bunch of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) socket buffer manipulation functions. A data message can be determined to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971) be the last one in a sequence with rxrpc_kernel_is_data_last(). When a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972) data message has been used up, rxrpc_kernel_data_consumed() should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973) called on it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) Messages should be handled to rxrpc_kernel_free_skb() to dispose of. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) is possible to get extra refs on all types of message for later freeing,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977) but this may pin the state of a call until the message is finally freed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979) (#) Accept an incoming call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) struct rxrpc_call *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982) rxrpc_kernel_accept_call(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) unsigned long user_call_ID);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) This is used to accept an incoming call and to assign it a call ID. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986) function is similar to rxrpc_kernel_begin_call() and calls accepted must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987) be ended in the same way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) If this function is successful, an opaque reference to the RxRPC call is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990) returned. The caller now holds a reference on this and it must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) properly ended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) (#) Reject an incoming call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995) int rxrpc_kernel_reject_call(struct socket *sock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) This is used to reject the first incoming call on the socket's queue with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) a BUSY message. -ENODATA is returned if there were no incoming calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999) Other errors may be returned if the call had been aborted (-ECONNABORTED)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) or had timed out (-ETIME).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) (#) Allocate a null key for doing anonymous security::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) struct key *rxrpc_get_null_key(const char *keyname);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) This is used to allocate a null RxRPC key that can be used to indicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) anonymous security for a particular domain.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) (#) Get the peer address of a call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011) void rxrpc_kernel_get_peer(struct socket *sock, struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) struct sockaddr_rxrpc *_srx);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) This is used to find the remote peer address of a call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) (#) Set the total transmit data size on a call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) void rxrpc_kernel_set_tx_length(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) s64 tx_total_len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) This sets the amount of data that the caller is intending to transmit on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) call. It's intended to be used for setting the reply size as the request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) size should be set when the call is begun. tx_total_len may not be less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025) than zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) (#) Get call RTT::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029) u64 rxrpc_kernel_get_rtt(struct socket *sock, struct rxrpc_call *call);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) Get the RTT time to the peer in use by a call. The value returned is in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) nanoseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034) (#) Check call still alive::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) bool rxrpc_kernel_check_life(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) u32 *_life);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) void rxrpc_kernel_probe_life(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) struct rxrpc_call *call);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) The first function passes back in ``*_life`` a number that is updated when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043) ACKs are received from the peer (notably including PING RESPONSE ACKs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) which we can elicit by sending PING ACKs to see if the call still exists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045) on the server). The caller should compare the numbers of two calls to see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) if the call is still alive after waiting for a suitable interval. It also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047) returns true as long as the call hasn't yet reached the completed state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049) This allows the caller to work out if the server is still contactable and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050) if the call is still alive on the server while waiting for the server to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051) process a client operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053) The second function causes a ping ACK to be transmitted to try to provoke
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054) the peer into responding, which would then cause the value returned by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055) first function to change. Note that this must be called in TASK_RUNNING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056) state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) (#) Get reply timestamp::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060) bool rxrpc_kernel_get_reply_time(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062) ktime_t *_ts)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064) This allows the timestamp on the first DATA packet of the reply of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) client call to be queried, provided that it is still in the Rx ring. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066) successful, the timestamp will be stored into ``*_ts`` and true will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067) returned; false will be returned otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069) (#) Get remote client epoch::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071) u32 rxrpc_kernel_get_epoch(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072) struct rxrpc_call *call)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074) This allows the epoch that's contained in packets of an incoming client
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) call to be queried. This value is returned. The function always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076) successful if the call is still in progress. It shouldn't be called once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077) the call has expired. Note that calling this on a local client call only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078) returns the local epoch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080) This value can be used to determine if the remote client has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081) restarted as it shouldn't change otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083) (#) Set the maxmimum lifespan on a call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) void rxrpc_kernel_set_max_life(struct socket *sock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086) struct rxrpc_call *call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087) unsigned long hard_timeout)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089) This sets the maximum lifespan on a call to hard_timeout (which is in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090) jiffies). In the event of the timeout occurring, the call will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091) aborted and -ETIME or -ETIMEDOUT will be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093) (#) Apply the RXRPC_MIN_SECURITY_LEVEL sockopt to a socket from within in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094) kernel::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096) int rxrpc_sock_set_min_security_level(struct sock *sk,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) unsigned int val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099) This specifies the minimum security level required for calls on this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100) socket.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103) Configurable Parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1104) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1106) The RxRPC protocol driver has a number of configurable parameters that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1107) adjusted through sysctls in /proc/net/rxrpc/:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1109) (#) req_ack_delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1111) The amount of time in milliseconds after receiving a packet with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1112) request-ack flag set before we honour the flag and actually send the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1113) requested ack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1115) Usually the other side won't stop sending packets until the advertised
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1116) reception window is full (to a maximum of 255 packets), so delaying the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1117) ACK permits several packets to be ACK'd in one go.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1119) (#) soft_ack_delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1121) The amount of time in milliseconds after receiving a new packet before we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1122) generate a soft-ACK to tell the sender that it doesn't need to resend.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1124) (#) idle_ack_delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1126) The amount of time in milliseconds after all the packets currently in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1127) received queue have been consumed before we generate a hard-ACK to tell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1128) the sender it can free its buffers, assuming no other reason occurs that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1129) we would send an ACK.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1131) (#) resend_timeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1133) The amount of time in milliseconds after transmitting a packet before we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1134) transmit it again, assuming no ACK is received from the receiver telling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1135) us they got it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1137) (#) max_call_lifetime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1139) The maximum amount of time in seconds that a call may be in progress
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1140) before we preemptively kill it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1142) (#) dead_call_expiry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1144) The amount of time in seconds before we remove a dead call from the call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1145) list. Dead calls are kept around for a little while for the purpose of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1146) repeating ACK and ABORT packets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1148) (#) connection_expiry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1150) The amount of time in seconds after a connection was last used before we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1151) remove it from the connection list. While a connection is in existence,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1152) it serves as a placeholder for negotiated security; when it is deleted,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1153) the security must be renegotiated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1155) (#) transport_expiry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1157) The amount of time in seconds after a transport was last used before we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1158) remove it from the transport list. While a transport is in existence, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1159) serves to anchor the peer data and keeps the connection ID counter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1161) (#) rxrpc_rx_window_size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1163) The size of the receive window in packets. This is the maximum number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1164) unconsumed received packets we're willing to hold in memory for any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1165) particular call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1167) (#) rxrpc_rx_mtu
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1169) The maximum packet MTU size that we're willing to receive in bytes. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1170) indicates to the peer whether we're willing to accept jumbo packets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1172) (#) rxrpc_rx_jumbo_max
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1174) The maximum number of packets that we're willing to accept in a jumbo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1175) packet. Non-terminal packets in a jumbo packet must contain a four byte
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1176) header plus exactly 1412 bytes of data. The terminal packet must contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1177) a four byte header plus any amount of data. In any event, a jumbo packet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1178) may not exceed rxrpc_rx_mtu in size.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags