Skip to main content
Jump to: navigation, search

Difference between revisions of "Org.eclipse.higgins.icard"

(Base ICard Interface)
(Base ICard Interface)
Line 10: Line 10:
 
  // Return the human friendly name of the card
 
  // Return the human friendly name of the card
 
  String getDisplayName();
 
  String getDisplayName();
 
// Set the human friendly name of the card
 
void setDisplayName(String);
 
 
   
 
   
 
  // Return true if this card only manages information about a
 
  // Return true if this card only manages information about a
Line 25: Line 22:
 
  // is what we believe the semantics that Microsoft intended and we currently
 
  // is what we believe the semantics that Microsoft intended and we currently
 
  // see no reason not to follow
 
  // see no reason not to follow
  // Return the identifier   
+
  // Return the identifier string    
 
  String getCardID();
 
  String getCardID();
 
   
 
   
  // Returns the human friendly name of the card issuer, originator, creator
+
  // Returns the human friendly name of the card issuer
 
  String getIssuerName();
 
  String getIssuerName();
+
 
  // Sets the card's human friendly name of the card issuer, originator, creator
+
  // Returns the URI of the issuer
  void setIssuerName(String name);
+
  String getIssuer();
 
   
 
   
 
  // Returns a background image of the card
 
  // Returns a background image of the card
 
  Image getCardImage();
 
  Image getCardImage();
 
 
// Sets the background image of the card
 
void setCardImage(Image image);
 
 
   
 
   
 
  // Return the mime type of the background image (JPEG or GIF)
 
  // Return the mime type of the background image (JPEG or GIF)
Line 50: Line 44:
 
  Date getExpiredTime();
 
  Date getExpiredTime();
 
   
 
   
// Set the expiration date and time
 
void setExpiredTime(Date date);
 
 
// Return the date and time after which the card should be
 
// treated as expired and invalid. If there is no expiration
 
 
  // If card handles only simple claim types then  
 
  // If card handles only simple claim types then  
 
  // return a list of all possible types of claims that are supported
 
  // return a list of all possible types of claims that are supported
 
  // throw exception otherwise
 
  // throw exception otherwise
 
  // This is here for backward compatibility with CardSpace cards
 
  // This is here for backward compatibility with CardSpace cards
  List getSupportedSimpleClaimTypes();
+
//
 +
// 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;
 
   
 
   
  // If card handles complex claim/attribute types then
+
  // Returns a read-only Context whose Digital Subject(s) can be queried for
  // return a data structure containing nested lists of claim types and
+
// attribute values that are displayed in the card UI (e.g. the
  // string values (this needs work!)
+
  // I-Card Selector Service or I-Card Manager.
  TBD getSupportedComplexClaimSchema();
+
// 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.
 +
  Context getDisplayContext() throws NoDisplayContextException;
 
   
 
   
  // Retrieve the value of a simple claim type
+
  // Retrieve the value of a simple claim type (on a 'single' card)
  // Note: Implementations of this method will likely retrieve and cache all  
+
  // Note 1: Implementations of this method will likely retrieve and cache all  
 
  // supported simple claim type values in a single operation  
 
  // 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
 
  // Returns the value of the claim type ClaimType
  String getClaimValue(String ClaimType);
+
  String getClaimValue(String claimType) throws ComplexSchemaException;
+
// TBD: how to retrieve the value of complex claim types
+
+
// Given a relying party policy ''Policy'', return true
+
// if this card can provide the claims required/desired by the relying party
+
// else return false
+
// Note: we have discussed the need (esp for Idemix support) to indicate the
+
// degree of match, not just a boolean.
+
boolean isMatch(Policy);
+
 
   
 
   
 
  // Return whether the user wishes to be asked for explicit release of
 
  // Return whether the user wishes to be asked for explicit release of
Line 87: Line 80:
 
   
 
   
 
  // Set the release policy of this card
 
  // Set the release policy of this card
  void setReleasePolicy(ReleasePolicy);
+
  void setReleasePolicy(ReleasePolicy) throws CardNotOpenException;
 
   
 
   
 
  // Return a list of the types of expored card data stream formats supported
 
  // Return a list of the types of expored card data stream formats supported
Line 97: Line 90:
 
  // E.g. CardSpace I-Cards will export CardSpace format data
 
  // E.g. CardSpace I-Cards will export CardSpace format data
 
  String export(CardFormat format);
 
  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()
 +
void open(String editorID);
 +
 +
// 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===
 
===To Do===

Revision as of 23:57, 8 December 2006

This page describes the one mandatory I-Card interface that all types of Higgins-compatible I-Cards must implement, as well as these optional interfaces:

  • TokenCard
  • URICard

Base 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.
Context 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()
void open(String editorID);
// 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

  • Need methods to get/set the access control list idea (see I-Card)

TokenCard Interface

Some types of I-Cards may 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();

URICard Interface

Some types of I-Cards may implement this interface. The card object encapsulates a ContextRef URI (that 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 a URI --the ContextRef 
String getContextRef();

See Also

Back to the top