One document matched: draft-brashear-afs3-pts-extended-names-09.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc1964 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.1964.xml'>
<!ENTITY rfc2119 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2743 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml'>
<!ENTITY rfc4120 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4120.xml'>
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc iprnotified="yes" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<?rfc sortrefs="no" ?>
<?rfc colonspace='yes' ?>
<rfc category="info"
docName="draft-brashear-afs3-pts-extended-names-09"
submissionType="independent"
ipr="trust200902">
<front>
<title abbrev="AFS-3 PTS extended auth names">Authentication Name Mapping extension for AFS-3 Protection Service</title>
<author fullname="Derrick J. Brashear" initials="D." surname="Brashear">
<organization>OpenAFS Project</organization>
<address>
<postal>
<street>2829 Larkins Way</street>
<city>Pittsburgh</city>
<region>PA</region>
<code>15203</code>
<country>USA</country>
</postal>
<email>shadow@openafs.org</email>
</address>
</author>
<date year="2011" />
<area>AFS3</area>
<workgroup>N/A</workgroup>
<keyword>I-D</keyword>
<keyword>Internet-Draft</keyword>
<keyword>AFS3</keyword>
<keyword>AFS-3</keyword>
<keyword>PTS</keyword>
<keyword>authentication</keyword>
<keyword>GSSAPI</keyword>
<keyword>Kerberos</keyword>
<abstract>
<t>This document describes the extension of the format, use
and communication of authentication names in the AFS-3 protocol
to allow for additional authentication mechanisms to be
represented and mapped to AFS IDs, independent of the AFS
usernames currently used for management of PRDB entries.
The new interface provides mechanisms for adding, removing, and
listing mappings, and to allow the fileserver to map an
authentication name to a PTS identity.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>AFS-3 provides an authentication ID mapping service to map
authentication system names in Kerberos Version 4 format to
AFS-3 numeric identifiers. An augmented Kerberos 4 server was
historically part of the AFS-3 protocol and service suite.</t>
<t>Security issues with Kerberos 4 as well as additional development
in the space of authentication systems has created the need to
map authentication names from other deployed systems to AFS
identifiers. Some deployments provide several mechanisms to
obtain AFS authentication. While mappings between Kerberos 4
and <xref target="RFC4120">Kerberos 5</xref> authentication names
allow use of most Kerberos 5 deployments with AFS, supporting more
than a single realm requires matching usernames in all realms.
Additionally, support for other systems is not provided at all.</t>
<t>An administrator or a user may know which authentication
identities belong to the same individual, service, or role. However,
not all deployments need to support interactive remapping; one use
case could involve re-exporting another naming service via the
AFS-3 PTS protocol, in which case only the name to identifier and
identifier to name services would be provided.</t>
<t>The deployment implications for a mapping service are described
below in <xref target="recommended_usage"></xref>.</t>
</section>
<section title="Conventions Used in this Document">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref
target="RFC2119"></xref>.</t>
</section>
<section title="Background information on operation of AFS">
<t>AFS is a distributed file system organized administratively
into cells. In current practice, each AFS cell consists of one or
more Volume Location Database (VLDB) servers, one or more
Protection Service (PTS) servers, and one or more pairs of file
servers and volume servers, plus possibly additional services
not relevant to this document. Data stored in AFS is divided
into collections of files called volumes. An AFS protocol client,
when accessing a file within a specific AFS cell, first contacts
a VLDB server for that cell to determine the file server for the
AFS volume in which that file is located, and then contacts that
file server directly to access the file. A client may also need
to contact a PTS server for that cell to register before accessing
files in that cell. All communication is via remote procedure
calls ('RPCs'), both between component servers and between clients
and servers.</t>
<t>Because AFS provides for authenticated access to data, it is
necessary to map authentication entities, generally corresponding
to users of the AFS file service ('users') or services requiring
access to data via the AFS file service ('services'), collectively
clients of the AFS file service ('clients'), to AFS authentication
identifiers ('AFS IDs'). The PTS service is used to provide this
service to the file server when required, typically when a client
first contacts a file server with a new authentication context,
including unauthenticated. AFS originally included a Kerberos
authentication (KA) server implementing the Kerberos 4 protocol
as well as the AFS-3 KA protocol for obtaining authentication
information. Because of this, PTS authentication names take the
format typically used to represent a Kerberos 4 authentication
identity as a string, namely, principal name, followed by a dot
and instance if there is an instance, followed by an at-sign and
the cell name if the cell is not the local cell.</t>
</section>
<section title="Error Codes">
<t>AFS uses a library (com_err) and a tool from the MIT Project
Athena suite (compile_et) to generate unique error codes
protocol-wide. Codes are generated from a base value computed
using a 4 or fewer character string known as an error table,
identifying the subset of functionality which generated the
error. All error codes are represented as signed 32 bit integers.
The base value for PTS errors is 267264, generated from the
error table name 'PT'. All RPCs when implemented are expected
to return PTS errors. It is also possible for an implementation
to support only part of this proposal. As such, any unimplemented
RPCs should return error -455 (RXGEN_OPCODE), the error indicating
an RPC is unsupported. No new errors are defined as part
of this draft.</t>
<t>The existing error code PRPERM shall be used for permission
errors due to insufficient privilege when attempting any
of the described RPCs.</t>
</section>
<section title="Existing Protocol Constants">
<t>When it is necessary to represent an identity which has
provided either no authentication information, or information
which does not include a corresponding AFS ID, an anonymous
ID is defined and used.</t>
<figure><artwork><![CDATA[
#define ANONYMOUSID 32766
]]></artwork></figure>
<t>The AFS ID 32766 shall be returned when an authentication
name is unknown.</t>
</section>
<section title="Existing Per-Identity Permission Flags">
<t>The PTS service includes a basic security model based
around defined access flags. The flags are represented as
5 fields, each of which can have 3 values. One of these fields,
the "s" field, is used to control who can get information
about the entity. Valid values are 'S', which maps to PRP_STATUS_ANY,
meaning anyone can get the information; 's', which maps to
PRP_STATUS_MEM, meaning only members, the entity owner,
and administrators can get the information; and '-' (or unset),
meaning only the entity owner and administrators can get
the information.</t>
</section>
<section anchor="rpcs_defined" title="RPC Interface">
<t>Six new RPCs are defined for the AFS PTS service. Five of these
are used to manipulate data related to authentication names, while
the sixth is a general-purpose RPC to be used for capabilities
indication. Additionally, several new data types are defined to
allow representation of authentication names and identifiers in
these new RPCs.</t>
<section title="New Data Types">
<t>In order to represent a set of AFS IDs, the nidlist type
is defined. AFS IDs are expected to be enhanced to allow
a larger set of IDs concurrently with this advancement of
this proposal.</t>
<figure><artwork><![CDATA[
typedef afs_int64 nidlist<>;
]]></artwork></figure>
<t>A list of AFS IDs, represented as 64 bit integers.</t>
<t>Authentication names are expected to be mechanism-specific.
Thus an authentication-type agnostic data structure must
be provided to represent these names. An implementing server
MUST be able to use a bitwise comparison operation on
the data portion of a PrAuthName. Support for all available
name types is not expected.</t>
<figure><artwork><![CDATA[
#define AUTHDATAMAX 2048
#define AUTHPRINTABLEMAX 2048
struct PrAuthName {
afs_int32 kind;
opaque data<AUTHDATAMAX>;
opaque display<AUTHPRINTABLEMAX>; };
]]></artwork></figure>
<t>It is expected that some mechanisms will provide name data which is
not human-readable, or is any single format is sufficient to represent
all possible mechanism authentication names. Therefore the PrAuthName
data structure includes an integer tag denoting type, and an opaque data
object representing the mechanism-specific authentication name data.
The display portion is to be used for display to end-users, and MUST NOT
be used for comparison purposes. If a display portion is not provided,
the data portion MUST NOT be used directly for user display
purposes. A client with knowledge of the particular name type
used MAY use the data portion to derive a suitable display name,
if none is provided.</t>
<figure><artwork><![CDATA[
typedef struct PrAuthName authnamelist<>;
]]></artwork></figure>
<t>Each AFS ID is expected to have more than one name mapped to it,
possibly with more than one name of each type assigned to each.
It is therefore necessary to support a list of PrAuthNames.</t>
</section>
<section title="Authentication Name Types">
<t>The PrAuthName data type includes a 32 bit integer field
to represent the kind of authentication being mapped. It
is proposed that in addition to mappings for legacy Kerberos
4 based AFS names, that the first version of this additionally
include mappings for Kerberos 5-based and GSSAPI-based authentication
names.</t>
<figure><artwork><![CDATA[
#define PRAUTHTYPE_KRB4 1
#define PRAUTHTYPE_GSS 2
]]></artwork></figure>
</section>
<section title="GetCapabilities RPC">
<t>As with other AFS services, the PTS service could be enhanced
with the ability to represent new abilities to file servers
and clients. We propose a new general-purpose RPC of the
type implemented by other AFS services, namely, a bit stream.
It is proposed that the first 32 bits be allocated to capabilities
flags, while the remainder be reserved for future standardisation.</t>
<t>A complying server MUST implement GetCapabilities.</t>
<figure><artwork><![CDATA[
const PTSCAPABILITIESMAX = 196;
typedef afs_uint32 PrCapabilities<PTSCAPABILITIESMAX>;
const PTS_CAPABILITY_AUTHNAMEMAPPING = 1;
GetCapabilities(
PrCapabilities *prcapabilities
) multi = 65536;
]]></artwork></figure>
<t>An implementing server should return
any capabilities data it wishes to advertise. A server may
choose to not advertise the same capabilities to all callers;
For instance, the set of capabilities advertised to an authenticated
caller may be different than the set advertised to an anonymous
caller. In addition to the bitstream, return value is 0 for
success, or a PTS error in the event of error.</t>
</section>
<section title="Authentication name mapping RPCs">
<t>In addition to the general-purpose (GetCapabilities) RPC
needed to represent this extended functionality, a complying
server will include RPCs to represent the mapping of extended
names to AFS IDs.</t>
<section title="AuthNameToID">
<t>A complying server MUST implement the AuthNameToID RPC.
This RPC is used to convert one or more authentication names,
obtained by a file server or client in a mechanism-specific
manner, to AFS IDs.</t>
<figure><artwork><![CDATA[
AuthNameToID(IN authnamelist *alist,
OUT nidlist *ilist) = 65537;
]]></artwork></figure>
<t>For each authname provided in alist, an AFS ID will be
provided in ilist at the corresponding position. Where an
authentication name cannot be looked up, the AFS ID in list
will be ANONYMOUSID.</t>
<t>On success of the call, 0 shall be returned. Success includes
calls where none of the identities provided in authnamelist
can be mapped to AFS IDs.</t>
<t>A client being used to manipulate mappings SHOULD use this RPC to
discover the existing mapping, if any, for a given authentication
name. A caller using the mapping service for service operation
SHOULD instead call AuthNameToIDFallback.
</t>
</section>
<section title="AuthNameToIDFallback">
<t>A complying server MUST implement the AuthNameToIDFallback RPC.
This RPC is used to convert one or more authentication names,
obtained by a file server or client in a mechanism-specific
manner, to AFS IDs to be used in making authorization decisions
related to the named authentication identities.</t>
<figure><artwork><![CDATA[
AuthNameToIDFallback(IN authnamelist *alist,
OUT nidlist *ilist) = 65538;
]]></artwork></figure>
<t>For each authname provided in alist, an AFS ID will be
provided in ilist at the corresponding position. Implicit
fallback mappings will be used to map identities where no explicit
mapping is provided. Where neither an explicit nor implicit mapping
is available, the AFS ID in ilist will be ANONYMOUSID.</t>
<t>An explicit mapping is one that can be configured, represented, and
returned by the protocol defined in this document. An implicit mapping
is site- or implementation-specific. Examples of implicit mapping would
be translation of a client authenticating as Kerberos 5 principal
user@REALM to a PTS name of user, and of a client authenticating as
Kerberos 5 principal</t>
<t>On success of the call, 0 shall be returned. Success includes
calls where none of the identities provided in authnamelist
can be mapped to AFS IDs.</t>
<t>A caller using the mapping service for service operation SHOULD
use this RPC. A client being used to manipulate
mappings SHOULD use AuthNameToID instead.</t>
</section>
<section title="ListAuthNames">
<t>A complying server SHOULD implement the ListAuthNames RPC.
This RPC is used to list all authentication names attached
to the provided AFS ID.</t>
<figure><artwork><![CDATA[
ListAuthNames(IN afs_int64 id, OUT authnamelist *alist)
= 65539;
]]></artwork></figure>
<t>On success, 0 shall be returned, along with the list of
authentication names in alist corresponding to the AFS ID
provided in id.</t>
</section>
<section title="WhoAmI">
<t>A complying server SHOULD implement the WhoAmI RPC.
This RPC is used to return the current authentication
name and AFS ID for a caller to the caller.</t>
<figure><artwork><![CDATA[
WhoAmI(OUT afs_int64 id, OUT struct PrAuthName *alist) = 65540;
]]></artwork></figure>
<t>On success, 0 shall be returned, along with the identity and
authentication name corresponding to the caller of the RPC.</t>
</section>
<section title="AddAuthName">
<t>A complying server MAY implement the AddAuthName RPC.
This RPC is used to add an authentication name to an existing
AFS ID.</t>
<figure><artwork><![CDATA[
AddAuthName(IN afs_int64 id, IN PrAuthName *aname) = 65541;
]]></artwork></figure>
<t>On success, 0 shall be returned. If the authentication
name provided is already mapped to another AFS ID, PREXIST
shall be returned. If the AFS ID specified does not exist,
PRNOENT shall be returned.</t>
</section>
<section title="RemoveAuthName">
<t>A complying server MAY implement the RemoveAuthName RPC.
This RPC is used to remove an authentication name from an
existing AFS ID.</t>
<figure><artwork><![CDATA[
RemoveAuthName(IN PrAuthName *aname) = 65542;
]]></artwork></figure>
<t>On success, 0 shall be returned. If the authentication
name provided is not mapped, PRNOENT shall be returned.</t>
</section>
</section>
</section>
<section anchor="recommended_usage" title="Recommended Usage">
<t>Two classes of service providers are possible. In one, where
data is provided in a read-only fashion from an alternate
authorization service, only the AuthNameToID and ListAuthNames
RPCs are required. In the other, all RPCs are needed, such that
mappings can be constructed and maintained.</t>
<t>The ListAuthNames operation should be permitted for administrators
as well as for the owner of the entry to be listed. If the
'S' (PRP_STATUS_ANY) bit is set on the entry, then other
users may also perform this operation.</t>
<t>The AddAuthName and RemoveAuthName operations should always be
permitted for administrators, and should normally also be
permitted for the owner of the entry to be updated. For RemoveAuthName,
the entry being updated is always the one to which the specified
name currently maps, and should be an identity which is not the one
being removed. Regardless, any given authentication name can map only
to one ID; attempting to add (via AddAuthName) a second mapping for
the same authentication name MUST fail.</t>
<t>The AuthNameToID operation is analogous to the existing
NameToID operation, and like that, should be able to be used
by anyone.</t>
</section>
<section title="Compatibility">
<t>An implementation of the AFS protection service protocol
implementing these extensions shall indicate this by including
in the response to a GetCapabilities PTS RPC the capability
flag PTS_CAPABILITY_AUTHNAMEMAPPING.
</t>
</section>
<section title="Authentication Name Types">
<t>While the authentication name is an opaque type with respect
to the AFS-3 protocol, it is recommended that the following
definitions be used for the proposed types described herein.</t>
<section title="Kerberos V4">
<t>The format of the Kerberos V4 name type is either name@REALM
or name.inst@REALM, depending on whether a non-null instance
is present. In both cases the trailing NUL character is *not*
part of the authentication name data.</t>
</section>
<section title="GSSAPI Export Names">
<t>The format of the GSSAPI name type is that described in
section 3.2 of <xref target="RFC2743"></xref>.
The data opaque object will contain the GSSAPI canonical
name as generated by GSS_Export_name after GSS_Canonicalize_name.
The display opaque object will contain the GSSAPI display name type
and name string as generated by GSS_Display_name. The display name
MUST only be used for printing; the canonical name MUST NOT be used
for printing.</t>
</section>
<section title="Authentication Name Type Rewriting">
<section title="Kerberos 4 Name Rewriting">
<t>When Kerberos 4 is used, the Kerberos name type must be used.
In particular, Kerberos 4 principal names MUST NOT be represented
as Kerberos 5 names or vice versa.
</t>
</section>
<section title="Kerberos 5 Name Rewriting">
<t>When Kerberos 5 is used, with or without the GSSAPI, Kerberos 5 principal
names MUST be represented using the GSSAPI export name type with the
Kerberos mechanism OID. Servers accepting Kerberos 5 without GSSAPI
MUST convert to a GSSAPI Kerberos 5 export name using the Kerberos mechanism OID
before calling AuthNameToID. This is intended to allow all users of Kerberos
5 as an authentication mechanism, regardless of bindings, to use the same
authentication name.
Implementations which do not support GSSAPI can support this by preparing
a name as specified in section 2.1.1 of <xref target="RFC1964"></xref>,
subject to the constraints in section 2.1.3. This string, when prefixed
with the sequence of octets <figure><artwork><![CDATA[
04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 HX XX XX XL
]]></artwork></figure>where
<figure><artwork><![CDATA[
HX XX XX XL
]]></artwork></figure> represent the network byte order
hex encoding of the length of the string, can be treated as the canonicalized
export name, while the string itself can be treated as the display name.
</t>
</section>
</section>
</section>
<section title="Security Considerations">
<t>Allowing AuthNameToID to be used by any caller exposes information
about whether an authentication name is mapped at all, or, indeed,
exists. In some environments, this information may be considered
privileged.</t>
<t>Allowing a user to add arbitrary mappings to their identity via
AddAuthName may allow unintended permissions to be granted if the
user makes a mistake when mapping identities to the AFS identity
in question.</t>
<t>Because a server is not required to know about all available name types,
display names are provided by the caller to AddAuthName. It is possible
to provide an erroneous display name whether for malicious or benign
reasons. In either case, making a decision based on the display name
may result in problems.</t>
</section>
<section title="IANA Considerations">
<t>This document doesn't require any IANA registrations.</t>
</section>
<section title="AFS-3 Registry Considerations">
<t>This document requires the registration of the new RPCs
as provided in the section <xref target="rpcs_defined"></xref> above,
as well as new registries for PTS capabilities and for name types,
also as above.</t>
</section>
<section title="AFS3 Status">
<t>This document has been adopted by the AFS3 Standards Group as
experimental.</t>
</section>
<section title="Acknowledgments">
<t>The author thanks Magnus Ahltorp, Love Hörnquist Åstrand,
and Jeffrey T. Hutzelman for their work on the scope of this
enhancement, the attendees of the 2009 AFS hackathon
in Edinburgh, notably Marcus Watts and Simon Wilkinson, for
their assistance in defining the name object for GSSAPI, and Jeffrey T.
Hutzelman and Simon Wilkinson discussion of an acceptable means for
representing Kerberos 5 names consistently regardless of mechanism.</t>
</section>
</middle>
<!-- REFERENCES (the environment variable XML_LIBRARY must point to the directory where the citations (references) can be found; unzip them from http://xml.resource.org/ -->
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119" ?>
</references>
<references title="Informational References">
<?rfc include="reference.RFC.1964" ?>
<?rfc include="reference.RFC.2743" ?>
<?rfc include="reference.RFC.4120" ?>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-21 10:30:27 |