github.com/jlmucb/cloudproxy@v0.0.0-20170830161738-b5aa0b619bc4/go/tao/proto/attestation.proto

//  Copyright (c) 2014, Kevin Walsh.  All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto2";

package tao;

// Statements:
//
// A statement conveys:
//   issuer from time until exp says message
// In Go, a statement is represented in Go using cloudproxy/tao/auth.Says. By
// itself, a statement can't be verified as it does not include a signature.
//
// Delegation Statements:
//
// Tao uses simple delegation statements internally. This is the only kind of
// statement that Tao generates or interprets. A simple delegation statement is
// a statement conveying a particular message:
//   issuer ... says (delegate speaksfor issuer)
// Here, delegate is the name of some principal, usually a (non-tpm) Tao key
// principal, i.e. key("...") where "..." is a hashed, serialized public key as
// produced by Signer.ToPrincipal() or Verifier.ToPrincipal(). If time
// restrictions are met, from a delegation statement we can derive:
//   issuer says (delegate speaksfor issuer)
// and further:
//   delegate speaksfor issuer
// That is to say, a delegation statement conveys a speaks-for relationship.
//
// Delegation Statement Example:
//
// Suppose some program Prog(...), running on some OS PCRs(...), running on some
// TPM K_aik where H_aik = Hash(K_aik), generates a key and wants to arrange for
// that key to speak for itself. It can express as much with this statement:
//  H_aik.PCRs(...).Prog(...) says (H_prog speaksfor H_aik.PCRs(...).Prog(...))
//
// Other Statements:
//
// Statements can convey a variety of other messages beyond just a delegation.
// For example:
//   issuer says Pred(arg_1, ..., arg_n)
// Here, 'Pred' is the name of some predicate that is meaningful to the issuer
// (and to other principals that trust the issuer), and the arg_i are values
// such as strings, integers, or names of principals or subprincipals. 
//
// Other Statement Examples:
//
// Following the above delegation example, the policy key might want to express
// that the TPM identified by H_aik = H(K_aik) is a trusted platform, and the OS
// identified by PCRs(...) is a trusted OS. It can do so with these statements:
//  H_policy says IsTrustedPlatform(H_aik)
//  H_policy says IsTrustedOS("PCRs(...)")

// An Attestation is a key, a signature, and a statement, and it conveys:
//   signer says statement
// i.e.
//   signer says (issuer from time until exp says message)
// A valid Attestation encodes a public key, and it carries a signature that
// anyone can verify to (eventually) conclude:
//   issuer from time' until exp' says message
// Note: Because of time restrictions within attached delegations, restrictions
// time' and exp' here do not necessarily exactly match the restrictions time
// and exp on the original serialized statement. 
// If the modified time restriction is met, then we can derive the same
// conclusion as we would for the included statement, e.g.:
//   delegate speaksfor issuer               (for a delegation statement)
// or:
//   issuer says Pred(arg_1, ..., arg_n)     (for a predicate statement)
// That is to say, a valid Attestation that meets its time restriction conveys
// exactly the same meaning as conveyed by the included statement.
// 
// There are two categories of valid Attestations:
//
// (1) In cases where issuer is a subprincipal of (or identical to) signer, no
// delegation will be present. In these cases, signer speaksfor issuer, so from
// the attestation:
//   signer says (issuer says ...)
// we can derive:
//   issuer says (issuer says ...)
// and further:
//   issuer says ...
//
// Example of a category (1) attestation:
//   Attestation = {
//     statement = "H_aik.PCRs(...) says (H_os speaksfor H_aik.PCRs(...))"
//     signer = K_aik
//     signature = ...
//     delegation = nil
//   }
// Here, an OS has published a delegation statement establishing that key K_os
// speaks for the OS, and this statement was signed by the TPM K_aik on behalf
// of the OS. Note that the OS is a subprincipal of the TPM, so the TPM speaks
// for the OS. 
//      
// (2) In all other cases, a delegation will be present that, if valid, conveys:
//   issuer0 from time0 until exp0 says (delegate speaksfor issuer0)
// where issuer is a subprincipal of (or identical to) issuer0 and delegate is a
// subprincipal of (or identical to) signer. Such a valid
// delegation can be combined with:
//   signer says (issuer from time until exp says ...)
// to derive:
//   issuer0 from time0 until exp0 says (issuer from time until exp says ...)
// And because issuer0 speaks for issuer, we can further derive:
//   issuer from time' until exp' says ...
// where time' = max(time, time0) and exp = min(exp, exp0).
//
// Example of a category (2) attestation:
//   Attestation = {
//     statement = "H_aik.PCRs(...).Prog(...) says H_app speaksfor H_aik.PCRs(...).Prog(...)"
//     signer = K_os
//     signature = ...
//     delegation = {
//       statement = H_aik.PCRs(...) says H_os speaksfor H_aik.PCRs(...)
//       signer = K_aik
//       signature = ...
//       delegation = nil
//     }
//   }
// Here, the OS identified by H_aik.PCRs(...) has signed, using a
// seemingly unrelated key K_os, a statement on behalf of one of its hosted
// programs, H_aik.PCRs(...).Prog(...). The embedded delegation statement,
// signed by K_aik, binds that seemingly unrelated key K_os to the OS's actual
// identity, H_aik.PCRs(...).
//
// Verifying an attestation signature requires knowing how the signature was
// produced. We currently define two signature schemes:
//
// TODO(kwalsh): add tpm2 signature scheme here and in attestation.go
//
// (a) Some signatures are produced by the TPM, so here we are bound by the
// mechanisms implemented by the TPM. In this case, we encode the signer name as
//   tpm("..H..") where "..H.." is the hashed, serialized public half
// of the TPM's RSA key K. The TPM only ever signs things on behalf of its
// hosted programs, so the issuer used in the serialized statement will always
// have the form:
//   tpm("..H..").PCRs("..i..", "..h..")...
// where "..i.." is a sorted, comma-separated list of PCR numbers, and "..h.."
// is the corresponding, comma-separated list of hex-encoded PCR values. The
// signature is computed roughly as:
//   sig = rsa_sign(K, H( H(message) | pcrbuf(i, h) ))
// Here, we first hash the statement in a tpm-specific way, then sign the
// hash with RSA key K. To obtain the statement hash, first hash the serialized
// statement, including issuer, time, expiration and other information. This
// intermediate hash is then re-hashed with a tpm-specific encoding of the PCR
// numbers ("..i..") and values ("..h..") extracted from issuer. 
//
// Note: The PCR values are effectively hashed twice, once as part of statement,
// and separately as part of the pcrbuf datastructure. See optimization note
// below.
// 
// (b) Other signatures are produced in software, and here we have flexibility
// to use simpler signature schemes. In this case, we encode the signer name as
//   key("..H..") where "..H.." is the hashed, serialized public half
// of a DSA key K. The issuer used in the serialized statement can have any
// form. The signature is roughly:
//   sig = dsa_sign(K, H(context|message))
// Here, we simply hash the serialized statement, along with some context, then
// sign it with the private DSA key K. The context used for attestations is
// defined in Tao.AttestationSigningContext.
//
// Together, this results in four possible combinations:
//
// (1a) No delegation, Tao signature.
//      Historical note: This is the old "ROOT" attestation type.
//      Typically exaample: signer is the "domain policy" key.
//      The signer is always key("..H..").
// (1b) No delegation, TPM signature.
//      This is produced by tpm_tao.
//      The signer is always tpm("..H..") and the statement issuer is
//      always a tpm("..H..").PCRs("..i..", "..h..")... principal.
// (2a) Delegation, Tao signature.
//      Historical note: This is the old "INTERMEDIATE" attestation type. 
//      The signer is always key("..H..").
//      The delegation is the head of a chain that eventually terminates in a
//      type (1a) or (1b) attestation.
// (2b) Delegation, TPM signature.
//      Historical note: This is the old "TPM_1_2_QUOTE" attestation type.
//      This combination is no longer used. If it were, the signer would be
//      tpm("..H..") and the statement issuer would be something like
//      H_policy.TrustedPlatform. The delegation would be the head of a chain
//      that eventually terminates in a type (1a) or (1b) attestation. The
//      issuer at the head of the chain would always be a
//      tpm("..H..").PCRs("..i..", "..h..") principal.
message Attestation {
  // A serialized statement. This is serialized to avoid canonicalization issues
  // when signing and verifying signatures. In Go, this is obtained using
  // cloudproxy/tao/auth.Marshal().
  required bytes serialized_statement = 1;

  // The signature type, either "tpm", "tpm2", or "key". This must match
  // the type of the signer key, and it is also used to determine how to verify
  // signatures.
  required string signer_type = 2;

  // The signer's public key, i.e. the un-hashed key material used within 
  // cloudproxy/tao/auth.New*Prin().
  required bytes signer_key = 3;

  // Signature over the serialized statement using TPM or Tao signing.
  required bytes signature = 4;

  // A delegation attestation that conveys (eventually) that signer speaks for
  // the issuer in the serialized statement. If this is empty, then it must be
  // self evident that signer speaks for the issuer in the serialized statement.
  // This can be added, removed, or replaced without changing the attestation
  // signature, but verification may fail if a required delegation is missing.
  optional bytes serialized_delegation = 5;

  // An optional set of further attestations that may pertain, in some way, to
  // the the issuer or signer of this attestation. These can be added or removed
  // without changing the attestation signature. This allows attestations to be
  // piggy-backed, e.g. when an authorization guard requires multiple
  // attestations to check a policy.
  repeated bytes serialized_endorsements = 6;

  // This is the quote structure actually signed by the tpm 2.0.
  // TODO(kwalsh) remove this -- as for tpm1.2, the quote structure should be
  // recoverable from the principal names in the serialized statement.
  optional bytes tpm2_quote_structure = 7;

  // This is a DER encoded X509 certificate certifying the key signing the
  // attestation. This is included in attestations signed by a root Tao
  // i.e. a TPM (1.2 or 2.0) Tao or a soft Tao, and forms the root of the
  // attestation chain. This certificate is signed by the policy key.
  // TODO(kwalsh) remove this -- endorsements, and especially x509 certificates,
  // do not belong in attestations; an x509 "endorsement" in fact *is* a kind of
  // attestation.
  optional bytes root_endorsement = 8;
}

// TODO(kwalsh) Consider moving issuer (and expiration times) out of serialized
// statement and into Attestation. Non-tpm signature scheme would just hash the
// issuer separately. This would eliminate the double-hashing of PCR values, and
// it would let us do some trivial space optimizations: if issuer is empty, then
// issuer = signer, if issuer key is empty (i.e. starts with "."), then signer
// gets prepended to issuer, etc.

// TODO(kwalsh) Previously, names were not always included in statements and
// attestations, nor did names always include serialized public keys. That makes
// signed statements more compact. Now, the same public key might appear several
// times within a single attestation. The problem arises because each
// attestation is really a collection of statements and nested attestations. We
// should revisit how to efficiently encode these structures.