Skip to main content
Jump to: navigation, search

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

(Base ICard Interface)
(See Also)
 
(47 intermediate revisions by 6 users not shown)
Line 1: Line 1:
__NOTOC__
+
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}
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:
+
This page describes the base ''ICard'' interface that all types of Higgins-compatible i-cards must implement, as well as several other optional interfaces implemented by specific [[I-Card Provider]]s.
* TokenCard
+
* URICard
+
  
==Base ICard Interface==
+
These interfaces are in a state of continuous evolution. We're trying to support real world demos (recently, for example on CardSpace-compatible interoperability) on the one hand, while also trying to build a robust abstraction layer around the i-card metaphor (e.g. as described here [http://en.wikipedia.org/wiki/I-card Wikipedia i-card]), on the other. What's shown below on this page "works" (supports certain interop use cases), but some lower level implementation dependences are leaking up through the abstraction that will limit things we want to do in the future.
 +
 
 +
==ICard Interface==
  
 
All [[I-Card]]s must implement the ICard Interface:
 
All [[I-Card]]s must implement the ICard Interface:
  
  // Return the human friendly name of the card
+
  //Returns the type of this i-card (e.g. "m-card", "p-card", "r-card", "z-card" etc.)
String getDisplayName();
+
  String getType();
   
+
// Set the human friendly name of the card
+
void setDisplayName(String);
+
 
   
 
   
// 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
 
  // 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
 
  // 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 getId();
 
   
 
   
// Returns the human friendly name of the card issuer, originator, creator
 
String getIssuerName();
 
 
   
 
   
  // Sets the card's human friendly name of the card issuer, originator, creator
+
  // The unique identifier of the i-card in the i-card registry.
  void setIssuerName(String name);
+
// Because different i-card providers could contains i-cards with the same
 +
// ID, it could be difficult to retrieve the same i-card from the i-card
 +
// registry again using i-card ID.
 +
// The UUID must be unique over all i-card providers in the i-card registry
 +
// to allow retrieve the same i-card from the i-card registry multiple times.
 +
  CUID getCUID();
 
   
 
   
// Returns a background image of the card
 
Image getCardImage();
 
 
 
// Sets the background image of the card
 
void setCardImage(Image image);
 
 
   
 
   
  // Return the mime type of the background image (JPEG or GIF)
+
  // The version of the card. Useful in subsequent import operations,
  String getImageMimeType();
+
// so that cards can be updated or overwritten.
 +
  String getVersion();
 
   
 
   
  // Returns when the card was first issued, created, orginated
+
 +
//the human friendly name of the card. The only thing that will be
 +
// possible to modify after the import.
 +
String getName();
 +
 +
 +
// Representation of a background image of the card.
 +
byte[] getImage();
 +
 +
 +
// The mime type of the background image (JPEG or GIF).
 +
String getImageType();
 +
 +
 +
// Name of the issuer of the card. Used to match the required issuer, if a relying party specifies an issuer in the policy.
 +
String getIssuer();
 +
 +
 +
// The human friendly name of the card issuer
 +
String getIssuerName();
 +
 +
 +
  // Returns when the card was first issued, created, originated
 
  Date getTimeIssued();
 
  Date getTimeIssued();
 +
 
   
 
   
 
  // Returns (optionally) the time after which the card should
 
  // Returns (optionally) the time after which the card should
 
  // be considered expired, invalid. Otherwise returns null
 
  // be considered expired, invalid. Otherwise returns null
  Date getExpiredTime();
+
  Date getTimeExpires();
 
   
 
   
// 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
 
// return a data structure containing nested lists of claim types and
 
// string values (this needs work!)
 
TBD getSupportedComplexClaimSchema();
 
 
   
 
   
  // Retrieve the value of a simple claim type
+
  // List of all possible types of claims (as String) that are supported.
// Note: Implementations of this method will likely retrieve and cache all
+
  public List getSupportedClaimTypesUris();
// supported simple claim type values in a single operation
+
  // Returns the value of the claim type ClaimType
+
String getClaimValue(String ClaimType);
+
 
   
 
   
// TBD: how to retrieve the value of complex claim types
 
 
   
 
   
  // Given a relying party policy ''Policy'', return true
+
  // List of claims provided by this ICard.
// if this card can provide the claims required/desired by the relying party
+
  Iterator getClaims();
// 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
 
// 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
+
  // Retrieve the value of a simple claim type
  void setReleasePolicy(ReleasePolicy);
+
  IClaim getClaim(String type);
 
   
 
   
// 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
+
IClaim getClaimByShortName(String shortTypeName);
  // The format depends on the kind of card  
+
  // E.g. CardSpace I-Cards will export CardSpace format data
+
  String export(CardFormat format);
+
  // Provider of this card
 +
ICardProvider getProvider();
 +
 +
 +
//
 +
String getDescription();
 +
 +
 +
//
 +
void setName(String newName) throws CardException;
 +
 +
 +
//
 +
void setImage(byte[] newImage, String newImageType) throws CardException;
 +
 +
 +
//
 +
void setIssuerName(String name) throws CardException;
 +
 +
 +
//
 +
void setExpiredTime(Date date) throws CardException;
 +
 +
 +
  // The list of token types could be issued using this card (this method was moved from ITokenCard)
 +
List getSupportedTokenTypes();
 +
 +
 +
  // Indicates that this card has been issued by user (claim values can be editable)
 +
  public boolean isSelfIssued();
 +
 +
 +
// Date when the card was last updated
 +
Date getTimeLastUpdated() throws CardException;
 +
 
 +
 
 +
 
  
 
===To Do===
 
===To Do===
  
* Need methods to get/set the access control list idea (see [[I-Card]])
+
* 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.)
 +
 
 +
==IInformationCard Interface (extends ICard interface)==
  
==TokenCard Interface==
+
All CardSpace-interoperable cards must implement this interface.
  
Some types of [[I-Card]]s may implement this interface.
+
// Random entropy used for computing the PPID claim value for the card
 +
byte[] getHashSalt();
 
   
 
   
// 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
+
  // Used as the entropy to generate the token signing key
  // For CardSpace cards this is either the local STS endpoint (for
+
  byte[] getMasterKey();
// 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
+
  // XML representation of the card in RoamingInformationCard format. This Element should be created within the passed Document
  List getSupportedTokenTypes();  
+
Element toXML(Document doc) throws CardException;
 +
 
 +
 
 +
==IManagedInformationCard Interface (extends IInformationCard interface)==
 +
 
 +
All Managed CardSpace-interoperable cards must implement this interface.
 +
 
 +
// An ordered list of security token services
 +
  List getTokenServices();
 +
 +
 +
// Indicates that RST must include information identifying the relying
 +
Boolean getRequireAppliesTo();
 
   
 
   
// 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)
+
  // PrivacyNotice XML element as it was imported from xml file
  String getIssuedTokenIssuer();
+
  Element getPrivacyNotice();
  
==URICard Interface==
 
  
Some types of [[I-Card]]s 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).
+
==IPersonalInformationCard Interface (extends IInformationCard interface)==
  
The [[I-Card Provider]]s 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]]
+
All Personal CardSpace-interoperable cards must implement this interface.
  
(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.)
+
// The base64 encoded bytes of the SHA1 hash of the pin code
 +
byte[] getPinDigest();
 
   
 
   
  // Return a URI --the [[ContextRef]]
+
  String getContextRef();
+
// Used to edit claim values of the card
 +
void setClaimList(List claims) throws CardException;
 +
 +
 +
// Used to set/remove pin protection
 +
void setPinCode(String pinCode) throws CardException;
 +
 +
 +
  // URI of the context where DigitalSubject with claim values of the card is stored
 +
URI getClaimListContextID();
 +
 +
 +
// ID of DigitalSubject which holds claim values of the card
 +
  String getClaimListSubjectID();
 +
 
 +
 
 +
 
 +
 
  
 
==See Also==
 
==See Also==
* [http://www.eclipse.org/higgins Higgins Home]
 
 
* [[I-Card Provider]]
 
* [[I-Card Provider]]
 
* [[I-Card Registry]]
 
* [[I-Card Registry]]
* [[Higgins Wiki]]
+
 
 +
[[Category:Higgins Components]]

Latest revision as of 23:41, 10 July 2009

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}} This page describes the base ICard interface that all types of Higgins-compatible i-cards must implement, as well as several other optional interfaces implemented by specific I-Card Providers.

These interfaces are in a state of continuous evolution. We're trying to support real world demos (recently, for example on CardSpace-compatible interoperability) on the one hand, while also trying to build a robust abstraction layer around the i-card metaphor (e.g. as described here Wikipedia i-card), on the other. What's shown below on this page "works" (supports certain interop use cases), but some lower level implementation dependences are leaking up through the abstraction that will limit things we want to do in the future.

ICard Interface

All I-Cards must implement the ICard Interface:

//Returns the type of this i-card (e.g. "m-card", "p-card", "r-card", "z-card" etc.)
String getType();


// 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 getId();


// The unique identifier of the i-card in the i-card registry.
// Because different i-card providers could contains i-cards with the same
// ID, it could be difficult to retrieve the same i-card from the i-card
// registry again using i-card ID.
// The UUID must be unique over all i-card providers in the i-card registry
// to allow retrieve the same i-card from the i-card registry multiple times.
CUID getCUID();


// The version of the card. Useful in subsequent import operations,
// so that cards can be updated or overwritten.
String getVersion();


//the human friendly name of the card. The only thing that will be
// possible to modify after the import.
String getName();


// Representation of a background image of the card.
byte[] getImage();


// The mime type of the background image (JPEG or GIF).
String getImageType();


// Name of the issuer of the card. Used to match the required issuer, if a relying party specifies an issuer in the policy.
String getIssuer();


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


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


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


// 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;


// List of all possible types of claims (as String) that are supported.
public List getSupportedClaimTypesUris();


// List of claims provided by this ICard.
Iterator getClaims();


// Retrieve the value of a simple claim type 
IClaim getClaim(String type);


IClaim getClaimByShortName(String shortTypeName);


// Provider of this card
ICardProvider getProvider();


// 
String getDescription();


//
void setName(String newName) throws CardException;


// 
void setImage(byte[] newImage, String newImageType) throws CardException;


// 
void setIssuerName(String name) throws CardException;


// 
void setExpiredTime(Date date) throws CardException;


// The list of token types could be issued using this card (this method was moved from ITokenCard) 
List getSupportedTokenTypes();


// Indicates that this card has been issued by user (claim values can be editable)
public boolean isSelfIssued();


// Date when the card was last updated
Date getTimeLastUpdated() throws CardException;



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.)

IInformationCard Interface (extends ICard interface)

All CardSpace-interoperable cards must implement this interface.

// Random entropy used for computing the PPID claim value for the card
byte[] getHashSalt();


// Used as the entropy to generate the token signing key
byte[] getMasterKey();


// XML representation of the card in RoamingInformationCard format. This Element should be created within the passed Document
Element toXML(Document doc) throws CardException;


IManagedInformationCard Interface (extends IInformationCard interface)

All Managed CardSpace-interoperable cards must implement this interface.

// An ordered list of security token services
List getTokenServices();


// Indicates that RST must include information identifying the relying
Boolean getRequireAppliesTo();


// PrivacyNotice XML element as it was imported from xml file
Element getPrivacyNotice();


IPersonalInformationCard Interface (extends IInformationCard interface)

All Personal CardSpace-interoperable cards must implement this interface.

// The base64 encoded bytes of the SHA1 hash of the pin code
byte[] getPinDigest();


// Used to edit claim values of the card
void setClaimList(List claims) throws CardException;


// Used to set/remove pin protection
void setPinCode(String pinCode) throws CardException;


// URI of the context where DigitalSubject with claim values of the card is stored
URI getClaimListContextID();


// ID of DigitalSubject which holds claim values of the card
String getClaimListSubjectID();



See Also

Back to the top