| < keytab-backend Manual Page | Russ Allbery > Software > wallet | wallet Thanks > |
Introduction
These are the naming conventions used at Stanford University for wallet objects. They may not be appropriate for every site using wallet, but they can serve as a starting point for your site-local conventions. They are the conventions enforced by Wallet::Policy::Stanford (to the extent it's possible to enforce them).
Object Naming
Keytab
Keytab object names correspond to the principal names in your Kerberos
database, so there's no need for a wallet-specific set of naming
conventions. Apply whatever conventions you apply to the names of
service principals in your KDC.
If you do not already have naming standards for service principals,
you may want to develop some as part of your wallet deployment. We
use the following:
* Per user principals for doing automated things related to an
individual user account are named as instances of the corresponding
user principal. For example, we manage CGI instances for users with
CGI service in the wallet and run CGI scripts with Kerberos tickets
and AFS tokens for that principal. If my account is rra, the CGI
instance is rra/cgi.
* Service principals for campus departments and groups are handled
similarly but start with dept- or group- prefixes respectively. If
there is a campus department named ITS, its CGI instance is
dept-its/cgi.
* Class principals start with class-, then the class code, the section
if relevant, and then the PeopleSoft quarter. So the class aa100,
section 01, in fall quarter of 2008 has a CGI principal named
class-aa100-01-1082/cgi.
* Host-based principals follow the standard naming convention in
Kerberos: service, followed by a slash, followed by the
fully-qualified hostname in all lowercase. For example, the webauth
service on windlord.stanford.edu is webauth/windlord.stanford.edu.
It's very useful to have wallet enforce fully-qualifying the
hostname and giving the hostname in all lowercase, since both are
common errors.
* Other, non-host-based principals that aren't tied to a particular
account and aren't CGI principals for a group, department, or class
have names like service/<service-name> where <service-name> is a
relatively short description of the service that ideally includes
some indication of the responsible department where appropriate. We
use - rather than _ as a separator between components of
<service-name>.
File
File objects pose the most significant challenge to naming since they
can contain just about anything. We require some discussion before
putting a new type of data into a wallet file object, both to see if
it should get its own object type first and to agree on a naming
convention for that type of thing.
There are two basic types of file objects: ones that are tied to a
particular system, and ones that are not. For the ones that are tied
to a particular system, we use a naming convention very similar to
host-based Kerberos principals so that we can set up default ACLs
based on the host. For ones that are not, we require an indication of
the repsonsible group in each file object, since the rest of the name
can often be ambiguous.
File objects are named with two or more slash-separated components
(again, similar to Kerberos principals). The first is the type of
file being stored. The rest vary based on the file type.
We previously instead used <group>-<server>-<type>, but that caused
various problems in parsing because groups, servers, and types all
also contained dashes. Slashes are much less ambiguous. This
document shows both the new and the old form.
Host-based:
htpasswd/<server>/<app>
An .htpasswd file for HTTP Basic Authentication for special-case
web configurations that require such a thing. <server> is the
server (or group of servers) on which the file will be stored
(OLD: <group>-<server>-htpasswd-<app>)
ssh-<type>/<server>
Stores the SSH private key for <server>. For shared private keys
across a pool, <server> should be the name of the pool, or
possibly some unambiguous name for the set of systems. <type> is
the type of SSH key (rsa or dsa, in lowercase).
(OLD: <group>-<server>-ssh-<type>)
ssl-key/<server>[/<application>]
Stores the SSL X.509 certificate private key for <server>. Used
for Apache, Postfix, LDAP, and similar cases where the certificate
should match the host name. The public certificate we manage
external to wallet since it doesn't need to be protected or
encrypted. <server> here should be the fully-qualified DNS name
from the CN of the certificate, which may be different than the
hostname (for hosts with multiple virtual hosts, for example, or
because the certificate is for a load-balanced name). For example,
ssl-key/ldap.stanford.edu for the X.509 private key for the
SSL certificate used across the ldap.stanford.edu load-balanced
pool.
An optional <application> component may be added if there are
multiple certificates with the same host name as the CN but with
different private keys. (This may happen if, for example,
multiple services are running on the same FQDN but should have
isolated security contexts.)
Use ssl-key/starYYYY.stanford.edu for the key for the
*.stanford.edu certificate, where YYYY is the expiration year.
(OLD: <group>-<server>-ssl-key)
ssl-keypair/<server>[/<application>]
Same as ssl-key except that the signed certificate is included in
the same file as the private key. This is used for convenience
with some applications that want to have both the signed
certificate and private key in the same file.
The meaning of <server> and <application> are the same as for
ssl-key.
tivoli-key/<server>
The Tivoli encryption key for this server. We previously stored
the whole /etc/adsm/TSM.PWD file in this object, but now we store
only the encryption key in password form, since the file contains
both it and the server password and the latter keeps changing.
(OLD: <group>-<server>-tivoli-key)
In all cases, <server> should be a fully-qualified domain name in the
new naming convention. In the old naming convention, .stanford.edu
was omitted, but this adds unnecessary ambiguity.
Service-based:
config/<group>/<service>/<name>
A configuration file named <name> that contains some secure
information, such as a database password. Ideally, the secure
data should be stored in a separate file and assembled into the
configuration file. This is reserved for configuration files that
hold nothing but authentication information. Only use this naming
convention if there is not a more specific one below.
(OLD: <group>-<service>-config-<name>)
db/<group>/<service>/<database>
Stores the database password for <service> access to the database
named <database>. This may be a file containing only the database
password or a Perl AppConfig configuration file with the database
connection information including the password.
(OLD: <group>-<service>-db-<database>)
gpg-key/<group>/<service>
Stores the GnuPG private key for a service that needs to do GnuPG
signing or encryption.
(OLD: <group>-<service>-gpg-key)
properties/<group>/<service>[/<name>]
The properties file for a Java application that contains some
secure data (such as SSL key passwords or database passwords).
This should only be used for a properties file that contains only
the password and closely-related information, such as database
connection information. For anything else, switch to storing the
password separately using the password type above and building the
properties file dynamically from the password and a template. The
optional <name> component is for when there are multiple files
stored for a particular service.
(OLD: <group>-<service>-properties)
ssl-keystore/<group>/<service>[/<name>]
The Java keystore file (containing both public and private key)
used by a service for authentication to other services. If a
given service uses more than one, use the optional <name>
component to distinguish.
(OLD: <group>-<service>-ssl-keystore)
ssl-pkcs12/<group>/<service>[/<name>]
The PKCS#12 file (containing both public and private key) used by
a service for authentication to other services. If a given
service uses more than one, use the optional <name> component to
distinguish.
(OLD: <group>-<service>-ssl-pkcs12)
If there are separate objects for different tiers, <service> should be
left unqualified for production and be qualified with a dash and the
tier for non-production. For example, ssl-keystore/idg/accounts would
be the production keystore for the Accounts application, and
ssl-keystore/idg/accounts-uat would be the keystore for the UAT
version.
We previously stored a wider variety of configuration files before
developing a way to dynamically substitute the password into a larger
configuration file during deployment. The following file types are
obsolete and should no longer be used; instead, the configuration file
should be constructed by substituting a password (usually stored as a
password or db type) into the configuration file.
Obsolete:
<group>-<server>-pam-<app>
<group>-<service>-puppetconf
<group>-<service>-shibboleth
<group>-<server>-password-ipmi
<group>-<server>-password-root
<group>-<server>-password-tivoli
<group>-<server>-password-<account>
Replaced by password objects:
password-ipmi/<server>
password-root/<server>
password-tivoli/<server>
password/<group>/<service>/<name> should be replaced by the password
service/<group>/<service>/<name> object if a single password, or by
the file object db/* or config/* format if the object contains more
than just the bare password.
Password
Passwords are a recent type and so most password data is actually
in file objects. However, we'd like to move things there both for
the added features of password objects to self-set, and because it
helps clean up the file namespace a little more.
Host-based:
ipmi/<server>
Stores the password for remote IPMI/iLO/ILOM access to the
system.
tivoli/<server>
Stores the Tivoli TSM backup password for a given server. See
also tivoli-key/<server> in the file section, but depending on
what one wants to do with the password, this may be a better
representation.
root/<server>
Stores the root password for a given server.
system/<server>/<account>
Stores the password for a non-root system account, such as a user
required for file uploads.
app/<server>/<application>
Stores an application password bound to a certain server.
Service-based:
service/<group>/<service>/<name>
A password for some account, service, keystore, or something
similar that is not covered by one of the more specific naming
conventions, such as a password used to connect to a remote ssh
service. <service> is the service that uses this password and
<name> is the thing the password is used for (such as the remote
account name). This should only be for something including the
password and nothing else. See the file password/ object name
for something that includes more data.
ACL Naming
Currently, there is no naming enforcement for ACLs, so ACL naming has to be done purely by policy. In a later version of wallet, there will be support for enforcing ACL naming conventions.
We use the following conventions:
host/<host>
Any object that should be downloadable by either any administrator of <host> or by the host key itself. An ACL named like this should have as its contents either:
netdb example.stanford.edu krb5 host/example.stanford.edu@stanford.eduor:
netdb-root example.stanford.edu krb5 host/example.stanford.edu@stanford.eduDon't use this ACL name for ACLs with other content. Instead, use one of the other ones below.
group/*
Groups of users. Each ACL line should probably have a scheme of krb5 and an identifier of a Kerberos principal (which must include the @stanford.edu portion). Eventually, wallet will support using PTS groups and Workgroup Manager groups, but for right now this is how groups are supported.
user/<username>
A keytab that's only downloadable by one particular person. Double-check that a host/<host> ACL or a group/* ACL wouldn't be more correct. If this is what's desired, it would have a single line of scheme krb5 and identifier equal to the user's full Kerberos principal.
service/<service>
Used for keytabs that should be downloadable by a service, as opposed to a group of people. Usually this ACL will have lines like krb5 service/<service>@stanford.edu to let the service principal download other associated keytabs, but it may contain other things as well, including administrators for that service so that they can bootstrap or test. This naming convention should also be used for ACLs that allow multiple hosts to download the same object, such as:
netdb-root example.stanford.edu krb5 host/example.stanford.edu@stanford.edu netdb-root example-dev.stanford.edu krb5 host/example-dev.stanford.edu@stanford.eduSuch an ACL would normally be named service/example.
License
Copyright 2008-2011, 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
| < keytab-backend Manual Page | Russ Allbery > Software > wallet | wallet Thanks > |