github.com/jlmucb/cloudproxy@v0.0.0-20170830161738-b5aa0b619bc4/go/tao/hosted_program_factory.go (about)

     1  // Copyright (c) 2014, Google Inc.  All rights reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package tao
    16  
    17  import (
    18  	"io"
    19  	"os"
    20  
    21  	"github.com/jlmucb/cloudproxy/go/tao/auth"
    22  )
    23  
    24  // A HostedProgramSpec contains all of the information that might be needed to
    25  // start a hosted program. Some factories may not use all of this information,
    26  // and the semantics of each field vary by factory.
    27  type HostedProgramSpec struct {
    28  
    29  	// Id is an optional number to be included in the subprincipal name. If
    30  	// zero, it will be omitted.
    31  	Id uint
    32  
    33  	// Path specifies a file, e.g. an executable or a vm image, to be
    34  	// executed in some factory-specific way.
    35  	Path string
    36  
    37  	// Args are passed to the hosted program in some factory-specific way,
    38  	// e.g. as command line arguments.
    39  	Args []string
    40  
    41  	// ContainerArgs are used to configure the factory-specific container in
    42  	// which the hosted program is executed, e.g. by being passed as parameters
    43  	// to `docker run`.
    44  	ContainerArgs []string
    45  
    46  	// Uid is a the linux uid under which the hosted program is to be executed.
    47  	// Zero is not a legal value unless Superuser is set.
    48  	Uid int
    49  
    50  	// Gid is a the linux uid under which the hosted program is to be executed.
    51  	// Zero is not a legal value unless Superuser is set.
    52  	Gid int
    53  
    54  	// Superuser enables running the hosted program with Uid or Gid 0. This
    55  	// field is meant to prevent an accidentally omitted Uid from being
    56  	// interpreted as a request to run the hosted program as superuser. Instead,
    57  	// superuser must explicitly be set.
    58  	Superuser bool
    59  
    60  	// Stdin, Stdout, and Stderr are open file descriptors to be shared with the
    61  	// hosted program in a factory-specific way. If nil, factory-specific
    62  	// default values are used, e.g. perhaps /dev/null or inheriting from the
    63  	// tao host server. If not nil, these must have a File.Fd().
    64  	Stdin, Stdout, Stderr *os.File
    65  
    66  	// Dir is the directory in which to start the program. If empty, a
    67  	// factory-specific default will be used, e.g. perhaps the tao host server's
    68  	// directory, or perhaps dirname(Path).
    69  	Dir string
    70  
    71  	// Env specifies the environment of the hosted program. If Env is nil, a
    72  	// factory-specific default environment will be used. Some factories may
    73  	// modify the environment, e.g. to pass certain parameters across a fork.
    74  	Env []string
    75  }
    76  
    77  // A HostedProgram is an abstraction of a process. It is closely related to
    78  // os/exec.Cmd and github.com/docker/docker/daemon.Container.
    79  type HostedProgram interface {
    80  
    81  	// Spec returns the specification used to start the hosted program.
    82  	Spec() HostedProgramSpec
    83  
    84  	// Subprin returns the subprincipal representing the hosted program.
    85  	Subprin() auth.SubPrin
    86  
    87  	// Start starts the the hosted program and returns a tao channel to it.
    88  	Start() (io.ReadWriteCloser, error)
    89  
    90  	// Kill kills the hosted program and cleans up resources.
    91  	Kill() error
    92  
    93  	// Stop stops the hosted program and cleans up resources.
    94  	Stop() error
    95  
    96  	WaitChan() <-chan bool
    97  
    98  	// Cleanup cleans up resources, such as temporary files.
    99  	Cleanup() error
   100  
   101  	// Pid returns a factory-specific numeric identifier.
   102  	Pid() int
   103  
   104  	// ExitStatus returns a factory-specific exit status code if
   105  	// the hosted program has exited.
   106  	ExitStatus() (int, error)
   107  }
   108  
   109  // A HostedProgramFactory manages the creation of hosted programs. For example,
   110  // on Linux, it might create processes using fork, or it might create processes
   111  // running on docker containers. It might also start a virtual machine
   112  // containing a new instance of an operating system.
   113  type HostedProgramFactory interface {
   114  
   115  	// NewHostedProgram initializes, but does not start, a hosted program.
   116  	NewHostedProgram(spec HostedProgramSpec) (HostedProgram, error)
   117  }