system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-10-01 14:14:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

libcasper: document that most libcasper functions are not thread-safe

Browse source 
And neither are most libcasper services' functions, because internally
they all use cap_xfer_nvlist.  cap_xfer_nvlist sends and then receives
data over a unix domain socket and associated with the cap_channel_t
argument.  So absent synchronization, two threads may not use the same
cap_channel_t argument or they risk receiving the other's reply.

MFC after:	2 weeks
Sponsored by:	Axcient
Reviewed by:	oshogbo
Differential Revision: https://reviews.freebsd.org/D42928
This commit is contained in:
Alan Somers 2023-12-05 16:24:28 -07:00
parent 3494f7c019
commit cf037972ea
8 changed files with 76 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
lib/libcasper/libcasper/libcasper.3
View file

@ -26,7 +26,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 6, 2023
.Dd December 6, 2023
.Dt LIBCASPER 3
.Os
.Sh NAME
@ -94,7 +94,6 @@ The
.Fn cap_init
function instantiates a capability to allow a program to access
the casper daemon.
It must be called from a single-threaded context.
.Pp
The
.Fn cap_wrap
@ -235,6 +234,21 @@ provides a
.Xr syslog 3
compatible API
.El
.Pp
.Fn cap_init
must be called from a single-threaded context.
.Fn cap_clone ,
.Fn cap_close ,
.Fn cap_limit_get ,
.Fn cap_limit_set ,
.Fn cap_send_nvlist ,
.Fn cap_recv_nvlist ,
and
.Fn cap_service_open
are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh RETURN VALUES
The
.Fn cap_clone ,

14
lib/libcasper/services/cap_fileargs/cap_fileargs.3
View file

@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 10, 2021
.Dd December 6, 2023
.Dt CAP_FILEARGS 3
.Os
.Sh NAME
@ -169,6 +169,18 @@ The function
.Fn fileargs_realpath
is equivalent to
.Xr realpath 3 .
.Pp
.Fn fileargs_open ,
.Fn fileargs_lstat ,
.Fn fileargs_realpath ,
.Fn fileargs_cinitnv ,
.Fn fileargs_initnv ,
and
.Fn fileargs_fopen
are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh LIMITS
This section describe which values and types should be used to pass arguments to the
.Fa system.fileargs

7
lib/libcasper/services/cap_grp/cap_grp.3
View file

@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 5, 2020
.Dd December 6, 2023
.Dt CAP_GRP 3
.Os
.Sh NAME
@ -152,6 +152,11 @@ The
and
.Fa ngids
variables provide numbers of limited names and gids.
.Pp
All of these functions are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh EXAMPLES
The following example first opens a capability to casper and then uses this
capability to create the

19
lib/libcasper/services/cap_net/cap_net.3
View file

@ -21,7 +21,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 5, 2023
.Dd December 6, 2023
.Dt CAP_NET 3
.Os
.Sh NAME
@ -84,22 +84,31 @@
The functions
.Fn cap_bind ,
.Fn cap_connect ,
.Fn cap_getaddrinfo ,
.Fn cap_getnameinfo ,
.Fn cap_gethostbyname ,
.Fn cap_gethostbyname2 ,
.Fn cap_gethostbyaddr
and
.Fn cap_getnameinfo
.Fn cap_gethostbyaddr
provide a set of APIs equivalent to
.Xr bind 2 ,
.Xr connect 2 ,
.Xr getaddrinfo 3 ,
.Xr getnameinfo 3 ,
.Xr gethostbyname 3 ,
.Xr gethostbyname2 3 ,
.Xr gethostbyaddr 3
and
.Xr getnameinfo 3
.Xr gethostbyaddr 3
except that a connection to the
.Nm system.net
service needs to be provided.
.Pp
These functions, as well as
.Fn cap_net_limit ,
are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh LIMITS
By default, the cap_net capability provides unrestricted access to the network
namespace.

6
lib/libcasper/services/cap_netdb/cap_netdb.3
View file

@ -21,7 +21,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 29, 2022
.Dd December 6, 2023
.Dt CAP_NETDB 3
.Os
.Sh NAME
@ -43,6 +43,10 @@ is equivalent to
except that the connection to the
.Nm system.netdb
service needs to be provided.
It is reentrant but not thread-safe.
That is, it may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh EXAMPLES
The following example first opens a capability to casper and then uses this
capability to create the

7
lib/libcasper/services/cap_pwd/cap_pwd.3
View file

@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 5, 2020
.Dd December 6, 2023
.Dt CAP_PWD 3
.Os
.Sh NAME
@ -158,6 +158,11 @@ The
and
.Fa nuids
variables provide numbers of limited names and uids.
.Pp
All of these functions are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh EXAMPLES
The following example first opens a capability to casper and then uses this
capability to create the

11
lib/libcasper/services/cap_sysctl/cap_sysctl.3
View file

@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 1, 2022
.Dd December 6, 2023
.Dt CAP_SYSCTL 3
.Os
.Sh NAME
@ -64,6 +64,15 @@ except that they are implemented by the
service and require a corresponding
.Xr libcasper 3
capability.
.Pp
All of these functions, with the exceptions of
.Fn cap_sysctl_limit_init
and
.Fn cap_sysctl_limit_mib ,
are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh LIMITS
By default, the
.Nm

7
lib/libcasper/services/cap_syslog/cap_syslog.3
View file

@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 5, 2020
.Dd December 6, 2023
.Dt CAP_SYSLOG 3
.Os
.Sh NAME
@ -63,6 +63,11 @@ are respectively equivalent to
except that the connection to the
.Nm system.syslog
service needs to be provided.
.Pp
All of these functions are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh EXAMPLES
The following example first opens a capability to casper and then uses this
capability to create the