Initial general design document.

1 files changed, 365 insertions, 0 deletions

diff --git a/docs/design b/docs/design
new file mode 100644
index 0000000..dc4d05c
--- /dev/null
+++ b/docs/design
@@ -0,0 +1,365 @@
+                           Wallet System Design
+
+Introduction
+
+    The wallet system provides a mechanism for storing and retrieving
+    security-sensitive data such as system credentials and private keys
+    from a secure host, applying ACLs to that data, and supporting
+    automatic creation of certain types of security data on demand (such
+    as Kerberos keytabs).
+
+    The initial implementation of the wallet is targetted at Kerberos
+    keytab distribution and the replacement of Stanford University's
+    legacy Kerberos-v4-based sysctl system for distributing srvtabs and
+    keytabs.  After that initial implementation, additional data types
+    will be added.  SSL certificates, ssh private keys, and database
+    passwords are likely early candidates.  The implementation of keytabs
+    is described in detail below, and similar detailed designs for other
+    data types will be added as part of the later phases of the design.
+
+    This design document is not entirely complete in the area of exact
+    protocol commands, supported arguments, and the details of the ACL
+    manipulation protocol.  These areas of the design are still being
+    developed.
+
+Assumptions
+
+    For the rest of this document, the term "object" will be used for a
+    piece of security-sensitive data stored in the wallet.  The object
+    "metadata" is the authorization and history information around that
+    object.  Be aware that an object "stored" in the wallet may not be
+    physically present on the wallet server; instead, the object may be a
+    type of object that can be dynamically generated on demand by the
+    wallet server or retrieved from elsewhere.  For example, most Kerberos
+    keytabs stored in the wallet will exist in the wallet only in the form
+    of metadata and will be generated dynamically on demand when
+    requested.
+
+    Wallet uses remctl for its network protocol, which provides Kerberos
+    v5 GSS-API authentication and encryption of all data.  The rest of
+    this design document will assume the connection from a wallet client
+    to the wallet server is handled via the remctl protocol, that the
+    wallet server therefore knows the authenticated Kerberos principal of
+    the client, and that data passed between the server and the client is
+    encrypted.  For more information about the remctl protocol, see:
+
+        <http://www.eyrie.org/~eagle/software/remctl/protocol.html>
+
+    remctl requires Kerberos v5 authentication, and therefore all clients
+    using the wallet to retrieve data will use Kerberos v5 authentication.
+
+    We assume the wallet server is itself a secure host.  Compromise of
+    this host will compromise all stored data it has and will allow an
+    attacker to perform any operation possible via the wallet.  In order
+    to limit the effectiveness of such an attack, certain keys may be
+    excluded from the wallet's management purview (via kadm5.acl rules on
+    the KDCs, for example) and require management by Kerberos
+    administrators with kadmin.  However, compromise of the wallet system
+    would have a significant security impact and the system should be
+    managed with the sort of security precautions as one would apply to a
+    Kerberos KDC.
+
+Server Design
+
+  Protocol Operations
+
+    The wallet server supports the following protocol operations on an
+    object:
+
+        create          Create a new wallet entry for an object
+        delete          Delete the wallet entry for a given object
+        owner           Set the owner of an object
+        acl             Set the ACL on an object
+        flag            Set or clear flags on an object
+        show            Show the metainformation about the object
+
+        get             Retrieve the named object from the wallet
+        store           Store the named object in the wallet
+
+        group-add       Add a principal to an ACL group
+        group-remove    Remove a principal from an ACL group
+        group-list      List the members of an ACL group
+
+    The first six operations manipulate or display the metadata of the
+    object.  The next two operations store or retrieve the object itself.
+    The last three operations allow manipulation of krb5-group ACLs (see
+    below).
+
+    The owner and acl operations are only available to wallet
+    administrators.  Even if one is the listed owner of an object, one may
+    not change the owner or ACL on that object.  (This may be reconsidered
+    later to permit the owner to set the ACLs on an object.  This design
+    mirrors the existing Stanford University srvtab distribution system
+    and is maximally conservative.)
+
+    Objects are created with a store command, a get command on a object
+    type that supports data generation, or a create command (which creates
+    the metadata without storing any data).  New objects will be created
+    owned by the user running get, store, or create, no special ACLs, and
+    no flags.  Each backend can decide at its discretion whether a user
+    can get, store, or create an object that doesn't already exist.  The
+    default behavior in the absence of backend-specific configuration is
+    to only allow wallet administrators to do so.
+
+  ACLs
+
+    Each ACL consists of zero or more lines, each of which has a scheme
+    and an identifier.  Initially, three schemes will be supported: krb5,
+    krb5-group, and netdb.
+
+    An ACL line of scheme krb5 will have a single fully-qualified
+    principal name as an identifier; only that principal will be
+    authorized by that ACL line.
+
+    An ACL line of scheme krb5-group will have a group name as an
+    identifier.  That group will have an owner and a list of Kerberos
+    principals.  Any Kerberos principals on the list (not including the
+    separate owner) will be authorized by that ACL line.  The owner is
+    itself a reference to another ACL, which may include the group for a
+    self-owning ACL.  Anyone on the ACL referenced by the owner attribute
+    may list the principals in that group and add or remove a principal
+    from that group.
+
+    An ACL line of scheme netdb will have an identifier naming a specific
+    machine.  The user will be authorized if that user has a role of
+    "admin" or "team" for that machine.  See netdb-role-api for the
+    specific remctl API for performing that query.
+
+    For all ACLs, each ACL line is tried against the user principal.  If
+    any ACL line authorizes the user, that user is authorized.  If no ACL
+    line authorizes the user, permission to perform the operation is
+    refused.
+
+    For more details and other ACL types that will be supported in the
+    future, see design-acl.
+
+    There will be one general system ACL that identifies wallet
+    administrators, who are permitted to perform any operation.
+
+  Metadata
+
+    Each object stored in the wallet has the following metadata associated
+    with it (with examples for a keytab for
+    host/windlord.stanford.edu@stanford.edu that should be retrievable by
+    the Kerberos principal rra/root@stanford.edu):
+
+    * The type and name of the object.  The name must be unique within
+      that type.  For example, the type would be "keytab" and the name
+      would be "host/windlord.stanford.edu@stanford.edu".
+
+    * The owner of the object.  The owner by default has get, store, and
+      show permissions on the object in the lack of more specific ACLs.
+      An owner is a reference to an ACL.  In this case, this would be a
+      reference to an ACL of one line, that line having scheme "krb5" and
+      identifier "rra/root@stanford.edu".
+
+    * Optional ACLs for get, store, show, delete, and flag operations.
+      If there is an ACL for get, store, or show, that overrides the
+      normal permissions of the owner.  In the absence of an ACL for
+      delete or flag, only wallet administrators can delete an object or
+      set flags on that object.  This entry would need no special ACLs.
+
+    * Trace fields storing the user, remote host, and timestamp for when
+      this object was last created, stored, and downloaded.
+
+  Keytab-Specific Metadata
+
+    Objects of type keytab have one additional piece of metadata: an
+    optional list of enctypes for which keys should be generated for that
+    principal.  This list can be used to restrict the Kerberos enctypes
+    for a particular keytab to only those supported by that application.
+    In the absence of a list associated with a keytab, the default enctype
+    list in the KDC will be used.
+
+  Flags
+
+    Each object can have flags set on it.  Currently, the only defined
+    flags are:
+
+        locked          Nothing permitted regardless of ACL except show
+        unchanging      Use existing data, don't regenerate
+
+    The unchanging flag will only have meaning for those types where the
+    backend can support either generating new data or using the existing
+    stored data.
+
+  History
+
+    The wallet server will keep a history log of every operation performed
+    against an object, keyed by object type and name (for object changes).
+    A remctl interface will be provided so that wallet administrators can
+    query this log and see the history of a given object.
+
+    In addition, the wallet server will log to syslog every operation
+    performed, not only on objects but on ACLs, Kerberos principal groups,
+    keytab enctype metadata, and so forth.
+
+Keytab Server Backend
+
+  Basic Operation
+
+    The keytab backend will not support the store operation, only the get
+    operation.  Normally, a get will result in the generation of a new
+    keytab (possibly constrained by the list of enctypes for that keytab)
+    and hence the invalidation of any existing keytabs for that principal.
+
+    The wallet server will only have kadmin ACLs to manage a specific set
+    of principals to prevent the wallet from being used to change core
+    Kerberos keys or to change user accounts.
+
+  NetDB Default ACLs
+
+    If a user attempts to get a keytab for which no entry had previously
+    been created with create and that keytab is one of a specific set of
+    host-bound principals as configured by the local wallet server
+    deployment (generally things like host/*), we will check the principal
+    against an ACL of scheme netdb and identifier equal to the host name
+    for the principal (after chasing CNAMEs).  If that ACL authorizes the
+    user, we will automatically create a wallet entry for this host, owned
+    by an ACL of scheme netdb and identifier equal to the fully qualified
+    name of the system.  This will allow anyone with NetDB ownership of
+    the system to manage the keytabs.
+
+    Note that this does leave the system open to a potential attack via
+    DNS by spoofing a CNAME return and hence fooling the wallet into
+    thinking that a particular host is an alias for a host that the user
+    has NetDB roles to manage when it actually isn't.  This attack can
+    only allow the user to create a keytab that doesn't already exist,
+    however, so the impact seems slight given the difficulty of the
+    attack.
+
+  Retrieving Existing Keytabs
+
+    The flag unchanging can be set on keytabs to indicate that, rather
+    than generating a new key on a get operation on that keytab object,
+    the existing key should be extracted from the KDC and returned.  This
+    removes some protection around abuse of the wallet system since it
+    allows one to get access to an existing key without invalidating the
+    system key and then forge authentication to that service.
+    Accordingly, this flag may only be set by wallet administrators unless
+    a flag ACL is created on that object, and as a matter of policy it
+    should only be granted when there's a compelling reason for it.
+
+    When a keytab with the unchanging flag set is retrieved with get,
+    rather than generating a new keytab, the wallet server requests the
+    current keys in keytab form from the KDC via a separate interface.
+    The KDC will return only keys for principals matching a set
+    specifically configured on the KDC.  All strongly privileged keytabs
+    should be excluded from this (and ideally, only those keytabs known to
+    require caching should be listed here).  The keys will be extracted
+    from the KDC using kadmin.local with the -norandkey option, added with
+    a Stanford-local patch (but expected to be in MIT Kerberos 1.7).
+
+Client Design
+
+  Basic Operation
+
+    The client will use the remctl libraries for all communication with
+    the wallet server.  The wallet server name will be determined by a
+    compile-time default, overridden by configuration in krb5.conf or by a
+    command-line option.  It should support the get, store, and show
+    operations (although we will skip store for the initial implementation
+    since it's not required for keytabs).  Other wallet protocol
+    operations can be done via direct remctl calls or through later
+    additions to the client.
+
+    When retrieving a keytab, the client should support either creating a
+    new keytab file or adding the keys from the downloaded keytab to an
+    existing keytab so that multiple keys can be merged into the same
+    keytab.  This is useful for services that expect all their keys to be
+    in krb5.keytab, or for adding keys for all a host's aliases to its
+    krb5.keytab.
+
+  Srvtab Generation
+
+    For backward compatibility with a Kerberos v4 realm, the wallet
+    client, when downloading a keytab, should also be able to optionally
+    create a srvtab with the DES key extracted from that keytab (if any).
+    In order to get the Kerberos v4 kvno for the key (which may differ
+    from the Kerberos v5 kvno), it will obtain a Kerberos v4 service
+    ticket for that principal and extract the kvno from that service
+    ticket.
+
+Security Considerations
+
+  System Compromise
+
+    By its nature, the wallet is an obvious attack target target.  It has
+    access to generate arbitrary keytabs for many different service
+    principals, it will eventually store a variety of high-value
+    privileged data, and it has to be accessible over the wallet protocol
+    to clients.
+
+    This risk can be reduced by running minimal accessible services on
+    this system, co-located this service only with other high-security
+    applications if anything, and closely monitored for security issues.
+    In addition, the wallet should only have access on the KDC to those
+    principal classes that are managed by the wallet, specifically not
+    including any core Kerberos administrative principals, any user
+    accounts, and any administrator accounts.
+
+    The system should use iptables and similar firewall mechanisms to
+    limit all access only to those ports providing known public services,
+    and there to as few IP addresses as possible.
+
+    The wallet database should be stored locally on the system running the
+    wallet server and not be accessible from any other system.
+
+    Administration of the wallet should be done over protocol.  Logging on
+    to the wallet system should be done only in the case of emergency,
+    upgrade, or system maintenance and should not be done for any routine
+    task.
+
+  Protocol Compromise
+
+    The security of the wallet is dependent on the security of the
+    underlying remctl protocol.  The remctl code has been carefully
+    audited for security issues and is already in widespread use and
+    should be treated as a core security component.
+
+    Most communications between the wallet and the KDC are done over the
+    kadmin protocol, which is Kerberos-authenticated and encrypts the
+    network communications.  The other communication with the KDC is done
+    via remctl.  Extracting existing keys from the KDC can only be done on
+    the KDC using kadmin.local and access can therefore be tightly
+    controlled by the KDC remctl interface.
+
+  Retrieving Existing Keytabs
+
+    One key security concern is the wallet's ability to retrieve existing
+    keytabs.  The normal Kerberos key management system has some built-in
+    defense against an attacker obtaining a keytab for a service
+    principal: since that invalidates the existing keytab, the attacker
+    will still not be able to authenticate to a service that uses that
+    service principal, and any authentication done by the service
+    principal will start failing.  Compromise attacks are therefore often
+    converted to denial of service attacks, and it's very difficult to
+    launch a silent attack.
+
+    This changes when access is granted to existing keys.  An attacker who
+    obtains the existing keys can silently forge authentication to a
+    service protected by that service principal, or can silently
+    impersonate that service principal to other services without
+    interfering with normal operations.
+
+    The unchanging flag should therefore only be set when there is a clear
+    need, and the backend on the KDC that allows the wallet system to
+    retrieve existing keys should be as restrictive as possible about
+    which keys can be retrieved.  Using this system is, however, better
+    from a security standpoint than saving a copy of a keytab and
+    installing it as part of a build process or copying it between
+    multiple systems since the wallet at least maintains an audit trail of
+    downloads and doesn't keep a local copy of the keytab, only the means
+    for retrieving it.  So, for example, a compromise that makes available
+    only the backup image of the wallet server and not its credentials
+    cannot obtain existing keytabs since they're not stored on its disk.
+
+  Auditing
+
+    The wallet server audits operations in three ways.  First, an
+    authenticated principal, hostname, and timestamp is kept up to date
+    for each object for the last creation, modification, and retrieval
+    date for that object.  Second, an audit trail is kept for all
+    operations on an object to allow retrieval of the complete history of
+    an object.  Third, all wallet operations are logged to syslog and
+    therefore suitable for archiving, analysis, and forensics.