| < wallet To-Do List | Russ Allbery > Software > wallet | wallet ACL 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 automatically creating 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:
<https://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:
autocreate Create an object with default ACLs
check Determine whether an object exists
create Create a new wallet entry for an object
destroy Delete the wallet entry for a given object
owner Set the owner of an object
acl Set an ACL on an object
expires Set the expiration of 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
The first nine operations manipulate or display the metadata of the
object. The next two operations store or retrieve the object itself.
The create, owner, acl, and expires operations are only available to
wallet administrators. Even if one is the listed owner of an object,
one may not change the owner, ACL, or expiration date 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 an autocreate or a create command (which
creates the metadata without storing any data). Administrators can
create objects with the create command. Object creation via
autocreate. When someone attempts to get or store an object that
doesn't already exist, as determined by the check call, the wallet
client attempts autocreate. On the server, the type and name of the
object and the operation is passed to a policy function, which returns
an ACL. If the user is authorized by that ACL, the object is created
and that ACL becomes the object's new owner.
ACLs
Each ACL consists of zero or more lines, each of which has a scheme
and an identifier. Initially, two schemes will be supported: krb5 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 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 with the special name ADMIN that
identifies wallet administrators. Administrators are permitted to
perform any operation except get and store, and can add themselves to
ACLs to get and store objects. (Requiring that they add themselves to
the ACLs first is not a security measure but a requirement to not be
sloppy with ACLs when one is an administrator.)
Metadata
Each object stored in the wallet has the following metadata associated
with it (with examples for a keytab for host/windlord.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".
* 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, destroy, 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 flag,
only wallet administrators can 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.
Type-Specific Attributes
Object types may support additional attributes, which are keys and
lists of values. The acceptable keys and values are determined by the
individual object implementations. For many object types, no
attributes are supported.
Objects of type keytab support two attributes: an optional list of
enctypes for which keys should be generated for that principal, and an
optional list of external systems with which the keytab is
synchronized. The enctype list 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. The sync attribute
currently only supports a value of kaserver, which means that the DES
key in the keytab is set as the key for a corresponding principal in
an AFS kaserver.
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. The wallet
server will also keep a history log of every operation performed
against an ACL, keyed by the ACL ID.
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
For Stanford's purposes, if a user attempts to autocreate 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. 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.
This is implemented via a Stanford-specific wallet configuration file
that uses the server autocreate support. See examples/stanford.conf
to see how this is implemented.
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), and in general should pass any
command on to the server so that we can add new commands later without
modifying the client code. When called with a get or store command,
it should check whether the object already exists with the check
command and, if not, attempt autocreation with the autocreate command.
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.
Similarly, whenever a keytab is created or changed, the server needs
to synchronize the key with Kerberos v4 (using the sync attribute on
keytab objects).
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.
License
Copyright 2007-2008, 2013
The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. This file is offered as-is,
without any warranty.
SPDX-License-Identifier: FSFAP
| < wallet To-Do List | Russ Allbery > Software > wallet | wallet ACL Design > |