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

     1  CloudProxy
     2  ==========
     3  
     4  CloudProxy implements a system for trustworthy computing. The core abstraction
     5  of CloudProxy is the Tao, an API for trustworthy computing. The Tao can be
     6  implemented by diverse components, including hardware, operating systems,
     7  virtual-machine monitors, and applications. Any code that can make calls to an
     8  implementation of the Tao can provide the Tao as well. So, an implementation of
     9  the Tao can depend recursively on lower-level Tao implementations. Code that
    10  provides the Tao is called a _host_ and code running on a host is called a
    11  _hosted program_.
    12  
    13  The Tao provides three main operations: Seal, Unseal, and Attest. Seal and
    14  Unseal are like encryption and decryption, except that Seal and Unseal can have
    15  policies for unsealing sealed data. For example, a Tao implementation might
    16  be willing to unseal data only for the code that originally sealed the data. The
    17  Attest operation provides cryptographic evidence of the _code identity_ of a
    18  hosted program. For example, if the Tao host is a Trusted Platform Module, then
    19  attestation might be performed for a Linux operating system executing as a
    20  hosted program. In this case, the attestation would contain a signed TPM Quote2
    21  for appropriate Platform Configuration Registers (PCRs). In this case, the PCRs
    22  contain information about the hash of the operating-system code.
    23  
    24  Software components in a CloudProxy-based system execute in the context of a
    25  _security domain_. This domain is rooted in one or more cryptographic _policy
    26  keys_ and provides signed policy statements about the kinds of hosts and hosted
    27  programs that are allowed to run. These statements make use of the code identity
    28  of hosts and hosted programs; the hash of a binary often forms a large part of
    29  the code identity of the software component using the binary.
    30  
    31  Policy statements are managed by a _policy guard_, which interprets statements
    32  and provides answers to authorization queries. The current implementation of
    33  CloudProxy has an ACL-based guard and a Datalog one.
    34  
    35  Code
    36  ====
    37  
    38  The `tao` directory holds the Tao implementation, including subdirectories for
    39  an authorization language (`auth`) and networking (`net`). The `run/scripts`
    40  directory has scripts that are useful for setting up instances of example
    41  applications from `apps`. The `util` directory is a library of utilities used by
    42  the `tao` library.
    43  
    44  The `apps` directory also includes programs for Tao deployment and
    45  administration:
    46  
    47  - `linux_host` provides the Tao to three types of hosted program:
    48    1. processes running on Linux
    49    2. Docker containers running on Linux
    50    3. CoreOS virtual machines running on Linux/KVM
    51  - `tao_admin` can set up new domains, add and remove signed policy
    52      statements, query the policy guard, and generate keys.
    53  - `tao_launch` launches all supported types of hosted programs, given a
    54      path to the Unix domain socket for `linux_host`.
    55  - `tcca` is a certificate authority for Tao connections. It provides
    56    certificates and short attestations to hosted programs.
    57  
    58  Demo
    59  ====
    60  
    61  The simplest demo in CloudProxy consists of a client that sends messages to a
    62  server and a server that echoes the messages back. This application is
    63  implemented in `apps/demo`. The demo application requires a security domain and
    64  a policy that allows the `demo_server` and `demo_client` binaries to run. The
    65  policy statements in `run/scripts/domain_template.pb` are sufficient if
    66  CloudProxy is built and installed using `run/scripts/build_standalone.sh`.
    67  
    68  To create a domain, run the `run/scripts/set_up_domain.sh` script and supply the
    69  name of a guard type: `Datalog`, `ACLs`, or `AllowAll`. The last option (only
    70  for debugging) creates a guard that returns true for any authorization query.
    71  The opposite policy `DenyAll` is implemented but doesn't run, since the
    72  application stops due to authorization failure. The `set_up_domain.sh` script
    73  outputs the directory name of a domain that it created. This directory name is
    74  needed to run the demo. For example, to get a domain with policy based on
    75  Datalog, run the command
    76  
    77  	run/scripts/set_up_domain.sh Datalog Soft
    78  
    79  The `set_up_domain.sh` script uses `run/scripts/domain_template.pb` to configure
    80  the domain. This text-format protobuf structure contains rules and paths to
    81  binaries. Relative paths in the domain template are taken to be relative to
    82  `${GOPATH}/bin`; absolute paths are also permitted.
    83  
    84  There are three demo configurations: Linux processes, Docker containers, and
    85  KVM/CoreOS virtual machines. These correspond to the `run/scripts/run_*.sh`
    86  scripts. All three scripts require `sudo` privileges (to start `linux_host`) and
    87  require that the CloudProxy Go binaries were built in for a standalone
    88  environment and have been installed in `${GOPATH}/bin`. This can be accomplished
    89  using the script `run/scripts/build_standalone.sh`.
    90  
    91  Let the generated domain directory be `$TAO_DOMAIN`. Then to start the Linux
    92  process demo, run the command
    93  
    94  	run/scripts/run_processes.sh $TAO_DOMAIN Soft
    95  
    96  The Docker-based demo assumes that `$PATH` contains a Docker binary called
    97  `docker`. To start the Linux Docker demo, run the command
    98  
    99  	run/scripts/run_docker.sh $TAO_DOMAIN ${GOPATH/bin/demo_{client,server}.img.tgz 
   100  
   101  The KVM/CoreOS demo assumes that `$PATH` contains a QEMU binary called
   102  `qemu-system-x86_64`. It also requires a CoreOS virtual-machine image (call it
   103  `$IMG`), a file containing at least one SSH public key (call it `$KEYFILE`), and
   104  a running SSH agent that holds a private key corresponding to one of the keys in
   105  `$KEYFILE`. The CoreOS image should be referenced in `domain_template.pb` in
   106  `vm_paths`. If all these requirements are satisfied, then the Linux KVM/CoreOS
   107  demo can be started by running the command
   108  
   109  	run/scripts/run_kvm.sh $IMG $KEYFILE $TAO_DOMAIN