.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "RXRPC 7" .TH RXRPC 7 "2023-02-05" "0.5-4" "kafs-client" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" rxrpc \- Linux RxRPC (AFS) protocol implementation .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& #include \& #include \& \& socket = socket(AF_RXRPC, SOCK_DGRAM, PF_INET); \& socket = socket(AF_RXRPC, SOCK_DGRAM, PF_INET6); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Linux optionally implements the RxRPC transport protocol, as used by the \s-1AFS\s0 network filesystem. Both client and server ends are support \- even on the same socket \- and authentication is supported at both ends. .PP This can be used through the \s-1BSD\s0 socket interface, using the \&\fBsendmsg\fR(2) and \fBrecvmsg\fR(2) system calls with control data to multiplex calls over the socket and to provide or retrieve call metadata. \fBrequest_key\fR(2) is used to find the authentication keys to use in the calling process's keyrings. .PP The \s-1AF_RXRPC\s0 driver uses \fBudp\fR(7) sockets underneath, either IPv4\-only or IPv6 (with IPv4), for transport. Under certain circumstances, the underlying transport sockets may be shared between client-only sockets (but are never shared if a socket is implementing a server). .SS "Address format" .IX Subsection "Address format" .Vb 11 \& struct sockaddr_rxrpc { \& sa_family_t srx_family; /* AF_RXRPC */ \& uint16_t srx_service; /* The service identifier */ \& uint16_t transport_type; /* The type of transport */ \& uint16_t transport_len; /* Transport address length */ \& union { \& sa_family_t family; /* Transport address family */ \& struct sockaddr_in sin; /* IPv4 transport address */ \& struct sockaddr_in6 sin6; /* IPv6 transport address */ \& } transport; \& }; .Ve .PP Where \f(CW\*(C`srx_family\*(C'\fR is always set to \f(CW\*(C`AF_RXRPC\*(C'\fR ; \f(CW\*(C`srx_service\*(C'\fR is set to the service \s-1ID\s0 of the desired service; \fItransport_type\fR is set to the transport type, which is always \fB\s-1SOCK_DGRAM\s0\fR for now; \&\fItransport_len\fR says how big the address in \fItransport\fR is. .PP Inside the transport address part, and appropriate address for the underlying socket should be set, including things like family, port and address as appropriate. Note that it may be permissible to use IPv4 addresses on an IPv6 socket. .SS "Socket Options" .IX Subsection "Socket Options" \&\s-1AF_RXRPC\s0 provides a number of socket options that can be set with \&\fBsetsockopt\fR(2) and read with \fBgetsockopt\fR(2). The socket option level for IPv6 is \fB\s-1SOL_RXRPC\s0\fR. .IP "\fB\s-1RXRPC_SECURITY_KEY\s0\fR" 4 .IX Item "RXRPC_SECURITY_KEY" The option value is a string that specifies the name of a key to pass to \fBrequest_key\fR(2) to get an appropriate authentication key. Such keys are expected to be of \fIrxrpc\fR type. .Sp If this isn't set, \s-1AF_RXRPC\s0 will perform an unauthenticated, unencrypted call to the server. .IP "\fB\s-1RXRPC_SECURITY_KEYRING\s0\fR" 4 .IX Item "RXRPC_SECURITY_KEYRING" The option value is a string that specifies the name of a keyring to pass to \&\fBrequest_key\fR(2) to specify the keys used by the server end to authenticate connections. .Sp The service keys in the ring should be of type rxrpc_s and their descriptions should be of the form \*(L":\*(R" and each should be given an 8\-byte secret. .IP "\fB\s-1RXRPC_EXCLUSIVE_CONNECTION\s0\fR" 4 .IX Item "RXRPC_EXCLUSIVE_CONNECTION" The option value should be empty. This causes each call made on this socket to get its own virtual connection and thus its own negotiated security context. .IP "\fB\s-1RXRPC_MIN_SECURITY_LEVEL\s0\fR" 4 .IX Item "RXRPC_MIN_SECURITY_LEVEL" The option value should be a 4\-byte unsigned integer. This can be one of the following constants: \fB\s-1RXRPC_SECURITY_PLAIN\s0\fR, \&\fB\s-1RXRPC_SECURITY_AUTH\s0\fR, or \fB\s-1RXRPC_SECURITY_ENCRYPT\s0\fR ; the first indicating the packets should be securely checksummed only, the second that packets should be authenticated and the third that full encryption should be employed. .IP "\fB\s-1RXRPC_UPGRADEABLE_SERVICE\s0\fR" 4 .IX Item "RXRPC_UPGRADEABLE_SERVICE" The option value should be a 2\-slot array of 2\-byte unsigned integers. To use this, the socket must be a server socket and must have been bound to more than one address with different \fIsrx_service\fR specifiers. .Sp Slot[0] in the array specified the service \s-1ID\s0 to upgrade from; slot[1] specifies the service \s-1ID\s0 to upgrade to. This allows a client to find out if there's a 'better' version of the service available on the same address, but a different service \s-1ID.\s0 .Sp If the client follows the correct protocol for probing an upgradeable service, the kernel will automatically upgrade the service \s-1ID\s0 on the connection and this will be reflected in the address returned by \&\fBrecvmsg\fR(2). .IP "\fB\s-1RXRPC_SUPPORTED_CMSG\s0\fR" 4 .IX Item "RXRPC_SUPPORTED_CMSG" The option buffer should have room for a 4\-byte integer. The maximum control buffer message type supported by the kernel is written into the buffer. This allows an application to find out what control messages it may use so that it can avoid getting an error if it tries to use something unsupported. .SS "Message flags" .IX Subsection "Message flags" \&\s-1AF_RXRPC\s0 communicates certain information by way of the message flags passed to and received from \fBsendmsg\fR(2) and \fBrecvmsg\fR(2). .IP "\fB\s-1MSG_MORE\s0\fR" 4 .IX Item "MSG_MORE" This is passed to \fBsendmsg()\fR to indicate that there is more data to be transmitted as part of the request phase of a client call or the reply phase of a service operation. \fB\s-1MSG_EOR\s0\fR \fBrecvmsg()\fR sets this to indicate that the call has been terminated (the control messages must be parsed for information as to why) and that the kernel has discarded the user call \s-1ID\s0 tag. The tag may now be reused. \fB\s-1MSG_PEEK\s0\fR This is passed to \fBrecvmsg()\fR to look at the front of the message queue without removing any messages or changing the state of any outstanding calls. \&\fB\s-1MSG_WAITALL\s0\fR This is passed to \fBsendmsg()\fR to instruct it not to return for a signal if it is still loading up the message queue and progress is being made at the other side in emptying it. This works around the problem of \fBsendmsg()\fR getting interrupted after partially queuing its data, but not then being able to return how much it has consumed. \fB\s-1MSG_DONTWAIT\s0\fR This is passed to \fBrecvmsg()\fR to indicate that it shouldn't wait if the message queue is empty. .SS "Control messages" .IX Subsection "Control messages" \&\s-1AF_RXRPC\s0 communicates metadata to the caller through the ancillary data buffer (msg_control) in the messages passed to and fro using \&\fBsendmsg\fR(2) and \fBrecvmsg\fR(2). When building a control message buffer for \fBsendmsg()\fR, the \s-1RXRPC_SUPPORTED_CMSG\s0 value should be consulted to make sure that the control message type is supported. .IP "\fB\s-1RXRPC_USER_CALL_ID\s0\fR" 4 .IX Item "RXRPC_USER_CALL_ID" The data for this is an arbitrary long integer/pointer\-sized tag that represents the call to the kernel. It may, for example, hold a pointer to some userspace structure representing the call to the process. .Sp [sendmsg] This is passed to \fBsendmsg()\fR when the message proposed will create a client call. It must thereafter be included in all future \&\fBsendmsg()\fR calls pertaining to that call. .Sp [recvmsg] \fBrecvmsg()\fR includes the tag in all messages pertaining to a call until the final termination message is reached \- which \fBrecvmsg()\fR will mark by setting \s-1MSG_EOR.\s0 .IP "\fB\s-1RXRPC_ABORT\s0\fR" 4 .IX Item "RXRPC_ABORT" The data for this is a 32\-bit integer that is the abort code. .Sp [sendmsg] When passed to \fBsendmsg()\fR, this causes the operation matching the tag to be aborted; this will be followed up by \fBrecvmsg()\fR indicating \s-1MSG_EOR\s0 and a local error of \s-1ECONNABORTED,\s0 thereby terminating the tag. .Sp [recvmsg] When obtained from \fBrecvmsg()\fR, this indicates that a remote abort was received from the peer and the data gives the code for that abort. .IP "\fB\s-1RXRPC_ACK\s0\fR" 4 .IX Item "RXRPC_ACK" [recvmsg] This conveys no data. It indicates the final acknowledgement to a service call has been received. .IP "\fB\s-1RXRPC_NET_ERROR\s0\fR" 4 .IX Item "RXRPC_NET_ERROR" [recvmsg] This conveys a 32\-bit integer into which the network error that terminated a call will have been placed. .IP "\fB\s-1RXRPC_BUSY\s0\fR" 4 .IX Item "RXRPC_BUSY" [recvmsg] This conveys no data. It indicates that the operation has been rejected because the server is busy. .IP "\fB\s-1RXRPC_LOCAL_ERROR\s0\fR" 4 .IX Item "RXRPC_LOCAL_ERROR" [recvmsg] This conveys a 32\-bit integer into which the local error that terminated a call will have been placed. .IP "\fB\s-1RXRPC_NEW_CALL\s0\fR" 4 .IX Item "RXRPC_NEW_CALL" [recvmsg] This conveys no data. It indicates that a new service call has arrived at a server socket and is in need of a tag. \s-1RXRPC_ACCEPT\s0 is must be used for that. .IP "\fB\s-1RXRPC_ACCEPT\s0\fR" 4 .IX Item "RXRPC_ACCEPT" The data for this is an arbitrary long integer/pointer\-sized tag that represents the call to the kernel with the same semantics as for \&\s-1RXRPC_USER_CALL_ID.\s0 .Sp [sendmsg] Supply a user call \s-1ID\s0 tag to a new service call. .IP "\fB\s-1RXRPC_EXCLUSIVE_CALL\s0\fR" 4 .IX Item "RXRPC_EXCLUSIVE_CALL" [sendmsg] Indicate that this particular call should be made on its own connection with an unshared negotiated security context. This requires no additional data. .IP "\fB\s-1RXRPC_UPGRADE_SERVICE\s0\fR" 4 .IX Item "RXRPC_UPGRADE_SERVICE" [sendmsg] Indicate that this call should attempt to probe the service \&\s-1ID\s0 on the other side to see if it gets upgraded. The answer can be found in the srx_service value of the peer address \fBrecvmsg()\fR returns for this call. This requires no additional data. .IP "\fB\s-1RXRPC_TX_LENGTH\s0\fR" 4 .IX Item "RXRPC_TX_LENGTH" The data for this is a signed 64\-bit integer. .Sp [sendmsg] Specify the exact total transmit size. This allows \s-1AF_RXRPC\s0 to work out in advance how big encrypted packets are going to be (under some circumstances, there's a data length encrypted inside the packet). .Sp If this is set, it may allow \s-1AF_RXRPC\s0 to be more efficient at filling packets. If the wrong amount of data is given (too little or too much), then the call will be aborted. .IP "\fB\s-1RXRPC_SET_CALL_TIMEOUT\s0\fR" 4 .IX Item "RXRPC_SET_CALL_TIMEOUT" The data for this is an array of 1\-3 32\-bit integers. .Sp [sendmsg] Specify various call timeouts. The first timeout is the \&\fIhard\fR timeout for the call in seconds: the call will be aborted if it takes longer than this amount of time in total. .Sp The second timeout is the \efIidle\efP timeout for the call in milliseconds: the call will be aborted if we don't receive the next \&\s-1DATA\s0 packet within that amount of time during the reception phase. .Sp The third timeout is the \efInormal\efP timeout for the call in milliseconds: the call will be aborted if we go for that amount of time without receiving any type of packet pertaining to the call. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBkafs\fR(7), \fBrequest_key\fR(2) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2019 Red Hat, Inc. All Rights Reserved. .PP Written by David Howells (dhowells@redhat.com) .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.