155 lines
5.9 KiB
Racket
155 lines
5.9 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.rkt")
|
|
|
|
@title[#:tag "securityguards"]{Security Guards}
|
|
|
|
@defproc[(security-guard? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a security guard value as created
|
|
by @racket[make-security-guard], @racket[#f] otherwise.}
|
|
|
|
|
|
A @deftech{security guard} provides a set of access-checking
|
|
procedures to be called when a thread initiates access of a file,
|
|
directory, or network connection through a primitive procedure. For
|
|
example, when a thread calls @racket[open-input-file], the thread's
|
|
current security guard is consulted to check whether the thread is
|
|
allowed read access to the file. If access is granted, the thread
|
|
receives a port that it may use indefinitely, regardless of changes to
|
|
the security guard (although the port's custodian could shut down the
|
|
port; see @secref["custodians"]).
|
|
|
|
A thread's current security guard is determined by the
|
|
@racket[current-security-guard] parameter. Every security guard has a
|
|
parent, and a parent's access procedures are called whenever a child's
|
|
access procedures are called. Thus, a thread cannot increase its own
|
|
access arbitrarily by installing a new guard. The initial security
|
|
guard enforces no access restrictions other than those enforced by the
|
|
host platform.
|
|
|
|
@defproc[(make-security-guard [parent security-guard?]
|
|
[file-guard (symbol?
|
|
(or/c path? #f)
|
|
(listof symbol?)
|
|
. -> . any)]
|
|
[network-guard (symbol?
|
|
(or/c (and/c string? immutable?) #f)
|
|
(or/c (integer-in 1 65535) #f)
|
|
(or/c 'server 'client)
|
|
. -> . any)]
|
|
[link-guard (or/c (symbol? path? path? . -> . any) #f)
|
|
#f])
|
|
security-guard?]{
|
|
|
|
Creates a new security guard as child of @racket[parent].
|
|
|
|
The @racket[file-guard] procedure must accept three arguments:
|
|
|
|
@itemize[
|
|
|
|
@item{a symbol for the primitive procedure that triggered the access
|
|
check, which is useful for raising an exception to deny access.}
|
|
|
|
@item{a path (see @secref["pathutils"]) or @racket[#f] for
|
|
pathless queries, such as @racket[(current-directory)],
|
|
@racket[(filesystem-root-list)], and @racket[(find-system-path
|
|
_symbol)]. A path provided to @racket[file-guard] is not expanded or
|
|
otherwise normalized before checking access; it may be a relative
|
|
path, for example.}
|
|
|
|
@item{a list containing one or more of the following
|
|
symbols:
|
|
|
|
@itemize[
|
|
|
|
@item{@indexed-racket['read] --- read a file or directory}
|
|
|
|
@item{@indexed-racket['write] --- modify or create a file or
|
|
directory}
|
|
|
|
@item{@indexed-racket['execute] --- execute a file}
|
|
|
|
@item{@indexed-racket['delete] --- delete a file or directory}
|
|
|
|
@item{@indexed-racket['exists] --- determine whether a file or
|
|
directory exists, or that a path string is well-formed}
|
|
|
|
]
|
|
|
|
The @racket['exists] symbol is never combined with other symbols in
|
|
the last argument to @racket[file-guard], but any other combination is
|
|
possible. When the second argument to @racket[file-guard] is @racket[#f],
|
|
the last argument always contains only @racket['exists].}
|
|
|
|
]
|
|
|
|
The @racket[network-guard] procedure must accept four arguments:
|
|
|
|
@itemize[
|
|
|
|
@item{a symbol for the primitive operation that triggered the access
|
|
check, which is useful for raising an exception to deny access.}
|
|
|
|
@item{an immutable string representing the target hostname for a
|
|
client connection or the accepting hostname for a listening server;
|
|
@racket[#f] for a listening server or UDP socket that accepts
|
|
connections at all of the host's address; or @racket[#f] an unbound
|
|
UDP socket.}
|
|
|
|
@item{an exact integer between @racket[1] and @racket[65535]
|
|
(inclusive) representing the port number, or @racket[#f] for an
|
|
unbound UDP socket. In the case of a client connection, the port
|
|
number is the target port on the server. For a listening server, the
|
|
port number is the local port number.}
|
|
|
|
@item{a symbol, either @indexed-racket['client] or
|
|
@indexed-racket['server], indicating whether the check is for the
|
|
creation of a client connection or a listening server. The opening of
|
|
an unbound UDP socket is identified as a @racket['client] connection;
|
|
explicitly binding the socket is identified as a @racket['server]
|
|
action.}
|
|
|
|
]
|
|
|
|
The @racket[link-guard] argument can be @racket[#f] or a procedure of
|
|
three arguments:
|
|
|
|
@itemize[
|
|
|
|
@item{a symbol for the primitive procedure that triggered the access
|
|
check, which is useful for raising an exception to deny access.}
|
|
|
|
@item{a complete path (see @secref["pathutils"]) representing the
|
|
file to create as link.}
|
|
|
|
@item{a path representing the content of the link, which may be
|
|
relative the second-argument path; this path is not expanded or
|
|
otherwise normalized before checking access.}
|
|
|
|
]
|
|
|
|
If @racket[link-guard] is @racket[#f], then a default
|
|
procedure is used that always raises @racket[exn:fail].
|
|
|
|
The return value of @racket[file-guard], @racket[network-guard], or
|
|
@racket[link-guard] is ignored. To deny access, the procedure must
|
|
raise an exception or otherwise escape from the context of the
|
|
primitive call. If the procedure returns, the parent's corresponding
|
|
procedure is called on the same inputs, and so on up the chain of
|
|
security guards.
|
|
|
|
The @racket[file-guard], @racket[network-guard], and
|
|
@racket[link-guard] procedures are invoked in the thread that called
|
|
the access-checked primitive. Breaks may or may not be enabled (see
|
|
@secref["breakhandler"]). Full continuation jumps are blocked going
|
|
into or out of the @racket[file-guard] or @racket[network-guard] call
|
|
(see @secref["prompt-model"]).}
|
|
|
|
|
|
@defparam[current-security-guard guard security-guard?]{
|
|
|
|
A @tech{parameter} that determines the current security guard that controls
|
|
access to the filesystem and network.}
|
|
|
|
|