AUTHOPEN(1)               BSD General Commands Manual              AUTHOPEN(1)

NAME
     authopen -- open file with authorization

SYNOPSIS
     authopen [-stdoutpipe] [-extauth] filename
     authopen [-stdoutpipe] [-extauth] -w [-a] filename
     authopen [-stdoutpipe] [-extauth] -c [-x -m mode -w] filename
     authopen [-stdoutpipe] [-extauth] -o flags filename
     authopen -h

DESCRIPTION
     authopen provides authorization-based file opening services.  In its sim-
     plest form, authopen verifies that it is allowed to open filename (using
     an appropriate sys.openfile.* authorization right) and then writes the
     file to stdout.  If -w is specified, authopen will read from stdin and
     write to the file.

     authopen is designed to be used both from the command line and program-
     matically.  The -stdoutpipe flag allows a parent process to receive an
     open file descriptor pointing to the file in question.

     Before opening filename, authopen will make an authorization request for
     a right of the form:

     sys.openfile.[readonly|readwrite|readwritecreate]./fully/qualified/path
     `.readonly' rights only allow for read-only file descriptors.
     `.readwrite' rights allow for read/write file descriptors.
     `.readwritecreate' rights allow for read/write descriptors and the cre-
     ation of new files.

     The -extauth option can be used to provide an AuthorizationRef con-
     structed by the client.  This generally prevents authopen from presenting
     an authorization dialog containing its own name.

OPTIONS
      -stdoutpipe specifies that STDOUT_FILENO has been dup2()'d onto a pipe
              to a parent process and that an open file descriptor to filename
              (with the appropriate access mode) should be sent back across it
              using the SCM_RIGHTS extension to sendmsg(2) rather than having
              the file itself written to or read from stdin / stdout.

      -extauth specifies that authopen should read one AuthorizationExternal-
              Form structure from stdin, convert it to an AuthorizationRef,
              and attempt to use it to authorize the open(2) operation.  The
              authorization should refer to the sys.apenfile right correspond-
              ing to the requested operation.  The authorization data will be
              read before any additional data supplied on stdin, and will not
              be included in data written with -w.

      -w      instructs authopen to open filename read/write and truncate it.
              If -stdoutpipe has not been specified, authopen will then copy
              stdin to filename until stdin is closed.

      -a      append to filename rather than truncating it (truncating is the
              default).

      -c      create the file if it doesn't exist.  -m requires -c.

      -m mode specify the mode bits if a file is created.

      -o flags numerically specify the flags that should be passed to open(2).

      -x      require that the file being created not exist.

EXAMPLES
     To replace /etc/hostconfig (assuming
     sys.openfile.readwrite./etc/hostconfig or better can be obtained):

           $ cat tmpdata | authopen -w /etc/hostconfig

ERRORS
     authopen will fail if an appropriate sys.openfile.readonly.*,
     sys.openfile.readwrite.*, or sys.openfile.readwritecreate.* right cannot
     be obtained or if the named path does not exist.

BUGS
     authopen should support prefix path authentication such that the right
     sys.openfile.*./dev/ could give access to all /dev entries and
     sys.openfile.*./dev/disk1 could give access to all disk1-related /dev
     entries.

     authopen should use getopt(3).

LOCATION
     /usr/libexec/authopen

SEE ALSO
     open(2), Security/Authorization.h, realpath(3), recvmsg(2).

     W. Richard Stevens, "Passing File Descriptors", Advanced Programming in
     the UNIX Environment.

HISTORY
     authopen appeared in Mac OS X 10.1 to assist with the manipulation of
     disk devices.

Darwin                            28 Feb 2013                           Darwin