Org.eclipse.higgins.icard

This page describes the base I-Card interface and the TokenCard interfaces that all types of Higgins-compatible I-Cards must implement, as well as the optional additional URICard interface.

ICard Interface

All I-Cards must implement the ICard Interface:

// Return the human friendly name of the card
String getDisplayName();

// Return true if this card only manages information about a
// exactly one Digital Subject
boolean isSingle();
 
// Returns if 'isSingle()' is true, an optional contextually-unique 
// identifier for the Digital Subject
// Otherwise return null.
String getCUID();

// A card identifier that is unique to the card issuer. Or at least that
// is what we believe the semantics that Microsoft intended and we currently
// see no reason not to follow
// Return the identifier string   
String getCardID();

// Returns the human friendly name of the card issuer
String getIssuerName();

// Returns the URI of the issuer
String getIssuer();

// Returns a background image of the card
Image getCardImage();

// Return the mime type of the background image (JPEG or GIF)
String getImageMimeType();

// Returns when the card was first issued, created, orginated
Date getTimeIssued();

// Returns (optionally) the time after which the card should
// be considered expired, invalid. Otherwise returns null
Date getExpiredTime();

// If card handles only simple claim types then 
// return a list of all possible types of claims that are supported
// throw exception otherwise
// This is here for backward compatibility with CardSpace cards
//
// Note: this is a convenience method that does the equivalent of
// c = getContext(); and then (presuming c has a simple schema)
// does creates a linear list of claim/attribute types from 
// the schema of c (retrieved by c.getSchema()) 
List getSupportedSimpleClaimTypes() throws ComplexSchemaException;

// Returns a read-only Context whose Digital Subject(s) can be queried for 
// attribute values that are displayed in the card UI (e.g. the
// I-Card Selector Service or I-Card Manager. 
// See also isSingle() retreive the CUID of the singleton Digital Subject
// If a card does not support a display context it throws the 
// NoDisplayContextException. In this case the user cannot see
// the values of the supported claim types, only the claim types 
// themselves.
IContext getDisplayContext() throws NoDisplayContextException;

// Retrieve the value of a simple claim type (on a 'single' card)
// Note 1: Implementations of this method will likely retrieve and cache all 
// supported simple claim type values in a single operation 
// Note 2: This is a convenience method that performs a getContext()
// to get the context, finds the singleton DS, and reads the claimType
// attribute specified
// Returns the value of the claim type ClaimType
String getClaimValue(String claimType) throws ComplexSchemaException;

// Return whether the user wishes to be asked for explicit release of
// this card's information (i) every time it is requested (ii) only 
// the first time it is requested (iii) never 
ReleasePolicy getReleasePolicy();

// Set the release policy of this card
void setReleasePolicy(ReleasePolicy) throws CardNotOpenException;

// Return a list of the types of expored card data stream formats supported
// ?? presumably a CardFormat also mentions XML language and/or version number
List getSupportedExportFormats();

// Return a data stream containing a serialization of the card
// The format depends on the kind of card 
// E.g. CardSpace I-Cards will export CardSpace format data
String export(CardFormat format);

// UPDATE-RELATED METHODS

// Open the card itself for update. These methods are
// used during the creation of a new self-issued card.
// Pass the URI of the agent that intends to update the card. 
// If the editorID matches the issuerID of the card then 
// update operations are allowed
// Throws CardNotOpenException if 'editorID' does not match the 
// value of getIssuerURI()
final void open(String editorID);

// Return true if card is open for update
boolean isOpen();

// Close a card for update.
void close() throws CardNotOpenException;

// Set the human friendly name of the card
// throws: CardUpdateException if card has not been opened
void setDisplayName(String name) throws CardNotOpenException;

// Sets the card's human friendly name of the card issuer
void setIssuerName(String name) throws CardNotOpenException;
 
// Sets the background image of the card
void setCardImage(Image image) throws CardNotOpenException;

// Set the expiration date and time
void setExpiredTime(Date date) throws CardNotOpenException;

To Do

• Future: we may want to add methods to the a human friendly text name and an icon that informs the user about the kind of data access "protocol" used (if any) to retrieve the underlying data. Examples of strings might be "LDIF", "OpenID", "WS-Trust", etc.
• Future: we may want to add methods (analogous to the ones mentioned above) to inform the user about the format of the underlying data (e.g. LDAP, RDF, RDBMS, email contacts, etc.)

ITokenCard Interface

All I-Cards must implement this interface.

// If card is of type (1) then return a Digital Identity 
// that satisfies the policy policy
// The credential parameter used to authenticate to the 
// Token Issuer–-may be null if Token Issuer policy doesn’t require it
DigitalIdentity requestDigitalIdentity(Policy policy, DigitalIdentity credential);

// Return the EPR of the card issuer
// For CardSpace cards this is either the local STS endpoint (for
// self-asserted cards) or a remote STS (for managed cards)
EndpointReference getCardIssuerEndpoint();

// Return a list of {endpoint references, credential hint, credential selector}
List getTokenServices()

// Return a list of supported token types
List getSupportedTokenTypes(); 

// Is the RP identity required in the token request message?
boolean getRequireAppliesTo()

// Returns the issuer that is referenced in the returned RSTR 
// (or null if no issuer is listed)
String getIssuedTokenIssuer();

IURICard Interface

Some types of I-Cards may implement this interface. The card object includes a ContextRef URI (which may be an XRI) that refers to an identity attribute-providing service (usually a network endpoint).

The I-Card Providers developed as part of the Higgins project use the Identity Attribute Service to connect to the remote (or local) Context data referenced by this ContextRef

Note: If ICard.isSingle() is true, then implementations can invoke ICard.getCUID() to retreive the CUID of the Digital Subject with the Context returned by .getContextRef() below.

// Return the ContextRef of the card
String getContextRef();

// Returns an IContext
// Consumers of this method may or may not be able to edit the contents of 
// the returned Context. 
IContext getContext();

See Also

• Higgins Home
• I-Card Provider
• I-Card Registry
• Higgins Wiki