github.com/jlmucb/cloudproxy@v0.0.0-20170830161738-b5aa0b619bc4/Doc/AuthTesting-Overview.txt (about)

     1  Overview of Authorization-Oriented Restructuring (auth-testing branch)
     2  ======================================================================
     3  
     4  Status:
     5  - All unit tests pass.
     6  - Install script and some small demo hosted programs work.
     7  - There is an ACL-based guard and a Datalog-based guard.
     8  - Policy key is only used offline, e.g. when authorizing new tpms or binaries.
     9  - Online "TaoCA" (aka policy server, keynego) is unused and no longer compiles.
    10  - "CloudProxy apps" (fserver, fclient, etc.) no longer compile.
    11  
    12  Tao interface (tao/tao.h)
    13  -------------------------
    14  
    15  This is the API used by *hosted programs* to talk to their host Tao.
    16  
    17  // Get my name, e.g. TPM("...")::PCRs("...")::Program("...")
    18  GetTaoName() -> string
    19  
    20  // Append a new component to my name, irreversibly (e.g. like chroot)
    21  ExtendTaoName(string ext)
    22  
    23  // Get random bytes
    24  GetRandomBytes(int n) -> bytes
    25  
    26  // Request an attestation, signed by my host tao on my behalf.
    27  Attest(Statement s) -> signed blob
    28  
    29  // Seal. Policy controls which principals (within same host Tao) can seal or
    30  // unseal, and caller must satsify this too.
    31  // Policy grammar and semantics are host-specific.
    32  Seal(string data, string policy) -> sealed blob
    33  
    34  // Unseal. Also returns policy (which sealer must have satisfied).
    35  Unseal(string blob) -> data, policy
    36  
    37  // Internal use: encode params, e.g. for passing over fork/exec boundary.
    38  SerializeToString() -> string
    39  
    40  Implementations of Tao API - RPCTao, TPMTao, SoftTao
    41  ----------------------------------------------------
    42  
    43  RPCTao (tao/rpc_tao.*) - This just passes all calls over a MessageChannel, e.g.
    44  to another process that is serving as the Tao host.
    45  
    46  TPMTao (tao/tpm_tao.*) - This passes calls over the trousers driver to the TPM.
    47  
    48  SoftTao (tao/soft_tao.*) - This does all operations locally. This was a mistake
    49  and it is no longer used. Use TaoRootHost (see below) instead.
    50  
    51  Tao Hosts
    52  ---------
    53  
    54  A "Tao Host" is something that hosts programs and implements all the services
    55  needed to provide the above Tao API for those hosted programs. A Tao Host is
    56  itself probably part of some bigger environment (e.g. embedded inside a kernel,
    57  a hypervisor, a jvm, or just a daemon or process). So I split the work into a
    58  generic TaoHost piece and an environment-specific part.
    59  
    60  TaoHost (tao/tao_host.h) - Generic helper interface that should work in any
    61  environment. It can do encrypt/Decrypt (without policies), Attest,
    62  GetRandomBytes, etc. 
    63  
    64  TaoStackedHost (tao/tao_stacked_host.*) - Helper for hosts that are stacked on
    65  top of another Tao (e.g. a TPM). It calls down to the underlying Tao for some
    66  things. It can be optionally configured with keys (sealed to the underlying Tao)
    67  so that it can do encrypt/decrypt/sign faster than the underlying Tao.
    68  
    69  TaoRootHost (tao/tao_root_host.*) - Helper for hosts that are not stacked on top
    70  of anything. It has password-protected keys and uses them to do
    71  encrypt/decrypt/sign.
    72  
    73  Implementation of Tao Host Environments - LinuxHost
    74  ---------------------------------------------------
    75  
    76  LinuxHost (tao/linux_host.*) defines all the environment-specific stuff for a
    77  host that uses linux processes as its hosted programs. It can be run in stacked
    78  mode (e.g. on a TPM, but with its own keys for performance) or as a standalone
    79  "root" Tao without an underlying Tao. It exports the Tao API to its children. It
    80  also has a unix-domain socket so that other programs can make requests for
    81  starting, stopping, or killing hosted programs, or shuting down the LinuxHost.
    82  
    83  The code is split into a few different files, e.g. LinuxProcessFactory
    84  (tao/linux_process_factory.*) for creating and killing processes, PipeFactory
    85  (tao/pipe_factory.*) for setting up the pipes between child and parent
    86  processes, and a factory for creating admin channels.
    87  
    88  LinuxHost enforces policy. It has a policy key that it consults when deciding if
    89  it should run a given hosted program. When in stacked mode, the policy key is
    90  embedded into its own name, by calling ExtendTaoName() on the underlying Tao
    91  early in Init(). And during seal/unseal it can (or could) implement policies
    92  that depend on program hash, PID, username, or other things that it knows about.
    93  Actually, currently it only implements 2 policies: "allow all siblings on same
    94  LinuxHost" or "allow any process with same name as caller", where name includes
    95  the program hash and any other info the child added via ExtendTaoName().
    96  
    97  Guards
    98  ------
    99  
   100  TaoGuard (tao/tao_guard.*) is the API for authorization, with 3 main methods:
   101  - AddRule(string) // Add a new authorization rule
   102  - RetractRule(string) // Retract a rule
   103  - Query(string) // Make a query
   104  The exact grammar for rules and queries is guard-specific for now, but there are
   105  some helpers for parsing/formatting rule and query strings for common
   106  operations like "authorize principal P to do operation Op with arguments
   107  A1, A2, ..." or "Does principal P have authorization to do Op(A1, A2, ...)".
   108  
   109  TrivialGuard (tao/trivial_guard.*) This guard always answers YES (or NO,
   110  depending on its configuration) to every query.
   111  
   112  ACLGuard (tao/acl_gaurd.*) provides a minimalistic guard. You configure it by
   113  providing a list of queries for which it should answer YES. If a query isn't on
   114  the list, it answers NO. Note: The principal names embedded in the queries are
   115  the *full* path from TPM AIK down to program hash. And there are no wildcards or
   116  other fancy features here... every combination of AIK, OS, Program hash,
   117  operation, etc., need to be listed individually.
   118  
   119  DatalogGuard (tao/datalog_guard.*) provides a smarter guard. It can do certain
   120  kinds of universal quantification and "conditional" rules, e.g. "If P is a
   121  subprincipal of X, and X is a trusted OS, and P's program hash is listed in set
   122  S, and if Op is either Read or Write, then P is authorized to do Op," where the
   123  definition of "X is a trusted OS" is set up by specifying other similar rules.
   124  
   125  
   126  
   127