LionShare P2P Profile of SAML

Date: 20 April, 2005

Table of Contents

1 Introduction
    1.1 Notation
2 Architectural Overview
    2.1 Outstanding Questions
    2.2 Overview of the Flow
    2.3 LionShare's Use of PKI Credentials
    2.4 LionShare Client
    2.5 Authentication Mechanism
      2.5.1 Kerberos
    2.6 SASL-CA
    2.7 (Shibboleth) Identity Provider -- Attribute Authority
    2.8 LionShare Peer
3 Protocols and Profiles
    3.1 Obtaining Certificates
      3.1.1 Required Information
      3.1.2 Message Format and Transmission
      3.1.3 Processing Rules
      3.1.4 Example
    3.2 Attribute Request and Response
      3.2.1 Attribute Request
        3.2.1.1 Required Information
        3.2.1.2 Message Format and Transmission
        3.2.1.3 Processing Rules
        3.2.1.4 Example
      3.2.2 Attribute Response
        3.2.2.1 Required Information
        3.2.2.2 Message Format and Transmission
        3.2.2.3 Processing Rules
        3.2.2.4 Example
    3.3 (Pseudo) Browser/Post Response
    3.4 Transient Name Identifier
    3.5 LionShare Attribute Profile
4 Security and Privacy Considerations
5 References
    5.1 Normative

1 Introduction

This specification defines a set of related profiles of SAML 1.1 and additional messages and protocols that make up the LionShare security architecture. This specification builds on the [ShibArch] specification, which in turn builds on the OASIS SAML 1.1 specification [SAML]. The LionShare profile uses only a portion of the SAML 1.1 protocol (Attribute Query and Response). However, this profile specifies additions to the SAML 1.1 protocol, in the Attribute Exchange protocol and the use of Assertions by non-browser clients. This profile also references an additional, non-SAML protocol, the SASL-CA protocol, which is used to dynamically obtain short-lived PKI-credentials (where short-lived means on the order of Kerberos tickets).

Unless specifically noted, nothing in this document should be taken to conflict with the SAML 1.1 specification, or any bindings and profiles referenced within it. Readers are advised to familiarize themselves with those specifications first. 

1.1 Notation

2 Architectural Overview

2.1 Definitions

2.2 Outstanding Questions (this needs to be renamed)

Broadly speaking, the LionShare security architecture defines a set of interactions between a local, desktop-resident LionShare Peer and a remote LionShare Peer. LionShare uses a hybrid peer-to-peer/client-server design. LionShare peers within a LionShare network communicate using a peer-to-peer protocol based on the open-source Gnutella protocol [Gnutella]. Individual files are transferred in a peer-to-peer fashion. However, much of LionShare's security is obtained by using several enterprise-operated servers which provide authentication credentials and digitally signed attributes. LionShare builds on open standards, such as the OASIS SAML [SAML] and XACML [XACML] standards, and is designed to integrate with existing Internet2 middleware initiatives, such as Shibboleth.

[ShibArch] defines the architecture, components, and protocols used by the Shibboleth system. Shibboleth is built on the OASIS SAML v1.1 Specification [SAML]. That specification, however, was developed from a set of browser-based use cases. There are a number of significant differences between the SAML use cases and LionShare use cases:

1. The SAML domain model defines a number of components. The user agent is a web browser; all of the other components are organizationally managed entities with permanently assigned names. With LionShare, the LionShare client (the user agent) is a desktop client. The LionShare Peer (acting in the role of the SAML Target) also runs in a desktop. Neither of these entities are organizationally managed or have permanently assigned names.
2. The LionShare client obtains SAML assertions from a Shibboleth Identity Provider - Attribute Authority, and forwards them to a LionShare Peer. There is no SAML or Shibboleth use case describing this situation.

To address these differences, LionShare introduces a new component -- the SASL-CA. It is roughly equivalent to the Shib Single-Sign-On Service; it authenticates the user and provides evidence of that authentication in the form of PKI certificates. The PKI credentials are then used to a) sign metadata accompanying resources, and b) prove that SAML assertions refer to the entity that is presenting them. The SASL-CA protocol is seperate from any SAML protocol.

The LionShare Peer is an entity that operates in the role of Service Provider. It receives file retrieval requests from a LionShare client; often, these requests will be accompanied by SAML Attribute Assertions intended to prove eligibility under the access control policy associated with the requested resource. The LionShare Peer validates the assertions, makes an access control decision (if required), and returns the requested resource.

2.3 Overview of the Flow

The following sequence diagram illustrates the set of required and optional interactions among the entities. Three separate sequences are described: Initialization, Obtaining Attributes, and Requesting the Resource. The phrase "Client Peer" refers to a LionShare Peer that is requesting a resource from another LionShare Peer. The phrase "Server Peer" refers to any LionShare Peer which is providing resources on a LionShare network. It is possibly (and very likely) that any given Peer will be acting in both the client and server roles simultaneously. 

Client Peer Initialization

1. In step 1, a LionShare Client Peer uses an authentication mechanism-specific library to acquire initial credentials (for instance, the Peer may need to acquire a Kerberos TGT and a service ticket for the SASL-CA). This step is optional and may not need to be performed depending on a site's SASL-CA configuration.
2. In step 2, a LionShare Client Peer connects to the SASL-CA and authenticates, possibly using the credentials obtained in step 1. The LionShare client generates two key pairs, and sends the two public keys to the SASL-CA. The SASL-CA creates and returns two certificates. One of these certificates contains an opaque handle containing the user's identity; this is the "opaque certificate." The other certificate contains the user's name, email-address and department in cleartext; this is the "identity certificate."

   Server Peer Initialization

3. In step 3, the LionShare Server Peer uses an authentication mechanism-specific library to acquire initial credentials (for instance, the Peer may need to acquire a Kerberos TGT and a service ticket for the SASL-CA). This step is optional and may not need to be performed depending on a site's SASL-CA configuration.
4. In step 4, a LionShare Server Peer connects to the SASL-CA and authenticates, possibly using the credentials obtained in step 1. The LionShare client generates two key pairs, and sends the two public keys to the SASL-CA. The SASL-CA creates and returns two certificates. One of these certificates contains an opaque handle containing the user's identity; this is the "opaque certificate." The other certificate contains the user's name, email-address and department in cleartext; this is the "identity certificate."

   Querying and Retrieving a Resource

5. In step 5, a LionShare Client Peer issues a Gnutella QUERY message.
6. In step 6, a LionShare Client Peer receives Gnutella QUERYHIT messages from Server Peers holding resources that match the QUERY message in step 5. Each QUERYHIT message contains signed metadata describing the associated resource. The metadata includes a version of the resource's Access Control Policy which lists which attributes which must be released in order to retrieve the resource. The metadata is signed with the Server Peer's Identity Certificate.
7. In step 7, the LionShare Client Peer opens a mutually authenticated SSL connection to the LionShare-Shibboleth Attribute Authority. The client Peer uses its Opaque Certificate to create the SSL tunnel. It sends a <samlp:AttributeQuery> message, asking for the attributes needed to prove eligibility to retrieve the desired resource. The AttributeQuery message will likely include AttributeDesignators to restrict the contents of the AttributeAssertion.
8. In step 8, the LionShare-Shibboleth AA validates the request, uses the handle (obtained from the opaque certificate) to identify the user and retrieve attribute values from the user's directory object. The AA creates, signs, and returns an <saml:AttributeAssertion> containing attributes that apply to the requesting user. This AttributeAssertion MUST contain a Holder-of-Key SubjectConfirmation method (which contains the Client Peer's Opaque Certificate).
9. In step 9, the LionShare client opens a mutually authenticated SSL connection with a LionShare Server Peer, using its Opaque Certificate. The LionShare Client Peer, using the LionShare/SAML, sends the <saml:AttributeStatement> obtained from its AA to the LionShare Server Peer via an HTTP GET request. This request MUST be sent over a mututally authenticated SSL connection because the AttributeStatement contains a Holder-of-Key SubjectConfirmation element.
10. In Step 10, the LionShare Server Peer validates the AttributeStatement using Holder-of-Key confirmation. The certificate contained in the Holder-of-Key element MUST match the certifcate the Client Peer used to initiate the SSL session with the Server Peer. The LionShare Server Peer then returns the requested resource over the SSL connection.

2.4 LionShare's Use of PKI Credentials

To use a LionShare network, users must authenticate with their home institution in order to establish their identity. However, a LionShare network will likely involve users from many different institutions. To allow users at multiple institutions to identify themselves and establish trust, LionShare uses a lightweight public key infrastructure (PKI) based on the Internet2 InQueue and InCommon federations. To participate in a LionShare network, each institution must run its own certificate authority (CA) software; this software is provided by the LionShare project. This CA software, called SASL-CA, allows users to obtain certificates on-demand using a variety of standard authentication mechanisms, such as Kerberos 5 or an existing PKI. The LionShare peer application will automatically obtain any needed certificates when it is started.

In a traditional PKI application, managing user certificates and private keys can impose serious burdens. LionShare solves this problem by using a dynamic, self-managing PKI. The LionShare software will automatically generate private keys and obtain certificates when it is launched. These credentials are only valid for a few hours, so they do not need to be stored and managed. When a user quits LionShare, his credentials are automatically destroyed. This approach significantly reduces the administrative burden of LionShare, while allowing it to take advantage of a PKI's benefits.

LionShare's policy states that anonymous file sharing is forbidden but anonymous searching is allowed. To support this, each LionShare Peer obtains two certificates, an opaque certificate and an identity certificate. The contents of these certificates are different in order to withhold or share the user's identity.

At startup, the client obtains two different certificates, with two different intended uses; each is described below:

1. The Identity Certificate: This is used when a LionShare Peer is acting as a server to establish SSL sessions and to sign metadata of shared files. This certificate has the user's identity in the subject field. The SASL-CA server can place the user's principal name, department, host instutition and e-mail address in this certificate. This information lets other users on the network identify the user's files. When a user "publishes" a resource, this certificate is used to sign the metadata. Validation of the signature would require ensuring that the timestamp in the metadata was during the period when the cert was valid. Thus, even if the cert has expired, this non-standard validation can occur. When a downloader was inspecting the metadata, the contents of the subject field in the certificate would be used to determine (and validate) "who" published the resource.

   A LionShare Peer would also use a server cert when an LionShare client connected and was trying to create an SSL tunnel. The LionShare client could, and probably will, look at the identity contained in the subject field of the server cert.

2. The LionShare client cert. This cert will contain a Shibboleth handle in the Subject field, and we recommend a lifetime on the order of a Kerberos ticket. The client certificate only contains the user's host institution; this lets the user search for files without revealing his or her identify, while allowing other peers on the network to still know that the user has authenticated.

   The LionShare client will use this certificate when creating an SSL tunnel with the Shibboleth Attribute Authority. Additionally, the client will use this certificate when creating an SSL tunnel with an LionShare Peer, when requesting a resource. There is nothing in the certificate that the Peer can use to identify the requestor; the Peer uses the presented certificate as proof that the client holds the matching private key. All SAML Assertions presented by the client MUST contain a HoK Confirmation Method element containing the public key from the certificate.

Both certificates are signed by the institution's SASL-CA. The "trustworthiness" of the SASL-CA's signing certificate may or may not derive from a federation's trust files.

All temporary certificates are stored in memory; they are not saved to disk. They MUST be discarded when the LionShare program terminates.

The LionShare Peer MUST NOT anonymously publish resources on the LionShare network. When a resource is made available, it is accompanied by metadata describing the resource. This metadata is accompanied by a digital signature which a) ensures the integrity of the metadata, and b) identifies the publisher. Additionally, the publisher can associate an access control policy with the resource. This policy can specify identities associated with previously obtained self-signed certificates; it can also specify attributes delivered via SAML Assertions. (A policy MAY require an identity attribute, but it could instead require attributes specifying role or association information.) 

2.5 LionShare Peer

A LionShare Peer is an application program (ie user agent) that runs in a user's desktop and attempts to retrieve a resource held by another LionShare Peer. The LionShare Peer uses local services (an Authentication Mechanism to obtain security credentials, a SASL-CA to map those credentials to short-lived PKI credentials, and an Shibboleth Identity Provider-Attribute Authority to obtain SAML Assertions). The LionShare client uses a modified version of the Gnutella P2P protocol to 1) QUERY to locate resources, and 2) retrieve resources from Peers. If a resource has an access control policy associated with it, the client will forward a signed SAML Attribute Assertion when it requests a resource.

LionShare clients are NOT assigned permanent identities (a providerId) that can be recognized by LionShare Peers. Instead, at startup clients obtain PKI credentials from a SASL-CA. 

2.6 Authentication Mechanism

The LionShare Peer uses an Authentication Mechanism to prove the user's identity to the SASL-CA. When communicating with the SASL-CA, the Peer uses SASL to negotiate and choose a mechanism at runtime. The strongest  mechanism supported by both the Peer and the SASL-CA SHOULD be used (the SASL libraries on the Peer and SASL-CA will make this determination). 

2.6.1 Kerberos

Kerberos is a well known authentication mechanism. Many campuses operate Kerberos systems for use by applications and services on the campus. 

2.7 SASL-CA

The SASL-CA is (roughly) equivalent to the Shibboleth Single-Sign-On Service; it receives and processes authentication requests sent by the LionShare client. The client provides a pair of public keys; the SASL-CA creates, signs, and returns a pair of certificates. The SASL-CA is NOT a HTTP resource; rather, it uses its own protocol, described in [???].

After authentication occurs, the SASL-CA uses the authenticated identity to retrieve attributes from the local attribute repository. The attribute values are used when constructing the certificates.

The SASL-CA builds and returns two certificates.

1. An Identity certificate, which contains the identity of the person operating the Peer.
2. An Opaque certificate, which does not contain identity; rather, it contains an encrypted handle in the Subject field). The encrypted handle MUST be generated using the same key(s) and algorithm(s) as a Shibboleth Handle Service (since the Attribute Authority will need to decrypt the handle).

2.8 (Shibboleth) Identity Provider -- Attribute Authority

The Shibboleth Attribute Authority entity is defined in [ShibArch]. It is a SAML-defined service that supports a SAML protocol binding and the processing of SAML <samlp:Request> messages containing the <samlp:AttributeQuery> element. This service issues attribute assertions to service providers in a mutually authenticated fashion. Implementations typically rely on SSL/TLS [RFC 2246] or SAML message signatures to mutually authenticate the exchange.

The definition of the LionShare-Shib Attribute Authority is built on the definition of the Shibboleth AA found in [ShibArch]. In addition to the requirements described in the [ShibArch], the LionShare-Shib AA:

1. MUST implement support for <saml:SubjectConfirmation> when processing queries.
2. the Query will NOT contain a providerId value.
3. LionShare requires the ability to query the Attribute Authority "about your own attributes." A LionShare-Shibboleth AA listens for LionShare requests on a different endpoint.  It should only allow requests over an SSL session created with a certificate signed by the institution's SASL-CA. Therefore, a Shibboleth attribute authority MUST have the ability to authenticate requests (via PKI).

3 Protocols and Profiles

3.1 Obtaining Certificates

3.1.1 Required Information

3.1.2 Message Encoding

3.1.3 Processing Rules

3.1.4 Example

3.2 Attribute Request and Response

3.2.1 Attribute Request

An Attribute Request message is a <samlp:Request> element containing a <samlp:AttributeQuery> element.

The Resource attribute in the Query will not contain the requesting service provider's unique identifier. This is because LionShare does not assign unique identifiers to every entity in the system. The Attribute Request SHOULD contain <AttributeDesignator> elements to restrict the contents of the requested attribute assertion.

3.2.1.1 Required Information

3.2.1.2 Message Format and Transmission

3.2.1.3 Processing Rules

The LionShare Client Peer opens a mutually authenticated SSL connection with the LionShare-Shibboleth Attribute Authority. The Peer uses its Opaque Certificate to create the SSL tunnel. The LionShare-Shibboleth Attribute Authority should have a provision for trusting certificates signed by the local SASL-CA.

The Peer MUST send a <samlp:AttributeQuery> (inside a <samlp:Request> message).

The <samlp:AttributeQuery> MUST contain a Subject element, which MUST contain a <saml:SubjectConfirmation> element, asking for Holder-of-Key confirmation method (see Section 5.1 of [SAMLBind]). The AA MUST validate that the handle in the Peer's certficate's Subject element matches the handle in the AttributeQuery's Subject element. The <samlp:AttributeQuery> SHOULD contain one or more <saml:AttributeDesignator> elements to specify which attributes are desired. 

3.2.1.4 Example

3.2.2 Attribute Response

An attribute response is a <samlp:Response> element containing a <samlp:Status> element and zero or more <saml:Assertion> elements. The assertions, if any, should contain only attribute statements. The Issuer attribute of the assertions MUST be set to the unique identifier of the identity provider whose attribute authority is issuing the assertion.

The <saml:Subject> element in the attribute statements MUST contain a <saml:SubjectConfirmation> element. This MUST specify the Holder-of-Key confirmation method, and MUST include the Opaque Certificate of the Peer requesting the assertion. 

3.2.2.1 Required Information

3.2.2.2 Message Format and Transmission

3.2.2.3 Processing Rules

The AA listens on a seperate endpoint for LionShare assertion requests. This endpoint does not perform the AA's normal ARP processing. The Client Peer's certificate is validated, and the Peer's principal name is extracted from the encrypted handle contained in the Client Peer's Opaque Certificate's Subject field. The AA uses the supplied <saml:AttributeDesignator> (if any) to determine which attributes are desired.

This endpoint will need to trust the local SASL-CA's signing certificate in order to validate the Client Peer's Opaque Certificate.

The AA creates, signs, and returns a <samlp:Response> message, which MUST contain a <saml:Subject> element containing a <SubjectConfirmation> element with a <ConfirmationMethod> of Holder-of-Key. The <SubjectConfirmationData> element MUST contain the certificate used to create the SSL tunnel. Additionally, the Response MAY contain one or more <saml:AttributeAssertions> containing attributes that apply to the principal. 

3.2.2.4 Example

3.3 Attribute Transfer Profile

3.3.1 Message Encoding

3.4 Transient Name Identifier

3.5 LionShare Attribute Profile

4 Security and Privacy Considerations

5 References

5.1 Normative