001: /* Copyright 2001 The JA-SIG Collaborative. All rights reserved.
002: * See license distributed with this file and
003: * available online at http://www.uportal.org/license.html
004: */
005:
006: package org.jasig.portal.security;
007:
008: import java.io.Serializable;
009: import java.util.Enumeration;
010:
011: /**
012: * This is the main interface for the JASIG portal effort's security
013: * mechanism. We endeavor here to provide considerable encapsulation of
014: * the data we are trying to present.
015: *
016: * @author Andrew Newman, newman@yale.edu
017: * @version $Revision: 34783 $
018: * @author Don Fracapane (df7@columbia.edu)
019: * Added getSubContextNames() to support principal and credential tokens
020: */
021: public interface ISecurityContext extends Serializable {
022:
023: /**
024: * Returns the canonical authentication type for this flavor of
025: * authentication. Each value returned should be either a globally registered
026: * auth flavor or a local variant.
027: *
028: * @return The unique authentication value identifier. Values with the
029: * high order 16 bits clear are local (0x0000 - 0x00FF) where values with the
030: * high order 16 bits set (0xFF00 - 0xFFFF are foundation types distributed
031: * by JASIG. All other should be registered and globally unique.
032: */
033: public int getAuthType();
034:
035: /**
036: * Returns an empty object reference to an object implementing the
037: * Principal interface. By operating on this returned object the
038: * implementation class for the credentials type will be able to access
039: * any values set in the instance without exposing an interface method that
040: * would allow others (inappropriate) acces to the fields.
041: *
042: * @return An empty principal container.
043: *
044: * @see IPrincipal
045: */
046: public IPrincipal getPrincipalInstance();
047:
048: /**
049: * Returns an empty object reference to an object implementing the
050: * IOpaqueCredentials interface. By operating on this returned object
051: * the implementation class for the credentials type will be able to
052: * access any values set in the Opaque credentials without exposing an
053: * interface method that would allow others to access the fields.
054: *
055: * @return An empty credentials container.
056: *
057: * @see IOpaqueCredentials
058: */
059: public IOpaqueCredentials getOpaqueCredentialsInstance();
060:
061: /**
062: * Performs the operation of authentication. To perform this operation, the
063: * values set in the Principal object (whose reference is
064: * returned by <code>getPrincipalInstance()</code>) and the
065: * OpaqueCredentials object (whose reference is returned
066: * by <code>getOpaqueCredentialsInstance()</code>).
067: *
068: * @see #getPrincipalInstance
069: * @see #getOpaqueCredentialsInstance
070: */
071: public void authenticate() throws PortalSecurityException;
072:
073: /**
074: * Returns the currently authenticated principal if we are currently
075: * authenticated. Note that merely testing this for a non-null pointer
076: * is not sufficient to verify authenticated status. The isAuthenticated()
077: * call should be used. In some authentication schemes, an asyncronous
078: * event could potentially change one's authentication status.
079: *
080: * @return The currently authenticated principal.
081: */
082: public IPrincipal getPrincipal();
083:
084: /**
085: * Returns any credentials that an authenticated principal currently
086: * has. Note that opaque credentials don't have any methods for examination
087: * of the credentials contents. This call would primarily be useful to
088: * chain authentication manually within the same authentication schem.
089: *
090: * @return The currently authenticated credentials object.
091: *
092: * @see IOpaqueCredentials
093: */
094: public IOpaqueCredentials getOpaqueCredentials();
095:
096: /**
097: * Returns any additional descriptor information that might have been acquired
098: * during the process of authentication. Note that this interface has no
099: * methods and the object returned will have to be cast to some concrete
100: * type or alternate interface to be useful.
101: *
102: * @return An object containing any additional descriptor information.
103: *
104: * @see IAdditionalDescriptor
105: */
106: public IAdditionalDescriptor getAdditionalDescriptor();
107:
108: /**
109: * Returns a boolean status as to whether the descriptor corresponds to an
110: * authenticated principal. Note that the get(Principaal|OpaqueCredentials)
111: * calls return null until isAuthenticated first returns <code>true</code>.
112: */
113: public boolean isAuthenticated();
114:
115: /**
116: * Returns an <code>ISecurityContext</code> for the named subserviant security
117: * context.
118: *
119: * @return The security context object reference associated with the
120: * name specified as the first parameter.
121: *
122: * @param ctx The non-compound name of the subserviant security context.
123: */
124: public ISecurityContext getSubContext(String ctx)
125: throws PortalSecurityException;
126:
127: /**
128: * Returns an enumeration of the security contexts currently registered as
129: * being subserviant to this one.
130: *
131: * @return The enumeration object containing all of the contexts.
132: */
133: public Enumeration getSubContexts();
134:
135: /**
136: * Returns an enumeration of the names of the security contexts currently
137: * registered as being subserviant to this one.
138: *
139: * @return The enumeration object containing all of the subcontext names.
140: */
141: public Enumeration getSubContextNames();
142:
143: /**
144: * Adds a named sub context to the list of subserviant subcontexts.
145: *
146: * @param name The non-compound name of the subserviant context. Note that
147: * under normal circumstances the establishment of the InitialSecurityContext
148: * will automatically register all subcontext.
149: *
150: * @param ctx The security context object to register.
151: *
152: */
153: public void addSubContext(String name, ISecurityContext ctx)
154: throws PortalSecurityException;
155: }
|