Source code: net/jxta/credential/Credential.java
1 /*
2 * Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
14 * distribution.
15 *
16 * 3. The end-user documentation included with the redistribution,
17 * if any, must include the following acknowledgment:
18 * "This product includes software developed by the
19 * Sun Microsystems, Inc. for Project JXTA."
20 * Alternately, this acknowledgment may appear in the software itself,
21 * if and wherever such third-party acknowledgments normally appear.
22 *
23 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA"
24 * must not be used to endorse or promote products derived from this
25 * software without prior written permission. For written
26 * permission, please contact Project JXTA at http://www.jxta.org.
27 *
28 * 5. Products derived from this software may not be called "JXTA",
29 * nor may "JXTA" appear in their name, without prior written
30 * permission of Sun.
31 *
32 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
33 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
34 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
35 * DISCLAIMED. IN NO EVENT SHALL SUN MICROSYSTEMS OR
36 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
37 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
38 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
39 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
40 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
41 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
42 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
43 * SUCH DAMAGE.
44 * ====================================================================
45 *
46 * This software consists of voluntary contributions made by many
47 * individuals on behalf of Project JXTA. For more
48 * information on Project JXTA, please see
49 * <http://www.jxta.org/>.
50 *
51 * This license is based on the BSD license adopted by the Apache Foundation.
52 *
53 * $Id: Credential.java,v 1.16 2004/05/11 18:37:56 bondolo Exp $
54 */
55
56 package net.jxta.credential;
57
58 import net.jxta.document.MimeMediaType;
59 import net.jxta.document.StructuredDocument;
60 import net.jxta.id.ID;
61 import net.jxta.service.Service;
62
63 /**
64 * Credentials provide the basic mechanisms for securly establishing and
65 * communicating identity within JXTA. Credentials have three different roles
66 * within JXTA:
67 *
68 * <ul>
69 * <li>Authentication credentials are associated with authentication methods
70 * and are used to provide information required for authentication. Each
71 * {@link net.jxta.credential.AuthenticationCredential AuthenticationCredential}
72 * implementation is specific to its associated
73 * {@link net.jxta.membership.Authenticator Authenticator}. Authentication
74 * Credentials are normally created by constructing a document which follows
75 * a schema provided by the authentication method.</li>
76 *
77 * <li>Identity credentials associate an identity with a peer. The peer may
78 request operations to be performed using that identity. Identity Credentials
79 are created by successfully completing authentication with a Membership
80 * Service.</li>
81 *
82 * <li>Priviledged operations associate an operation with an identity. To
83 * request a remote peer to perform some operation an application or service
84 * provides a {@link net.jxta.credential.PrivilegedOperation} and an
85 * identity credential along with the request. The remote peer determines if
86 * the operation is permitted for the specified identity and if it is permitted,
87 * completes the operation.</li>
88 * </ul>
89 *
90 * <p/>The XML representation of a Credential uses the following very simple
91 * schema. Credential implementations extend this schema as needed.
92 *
93 * <p/><pre>
94 * <xs:complexType name="Cred">
95 * <xs:all>
96 * </xs:all>
97 * </xs:complexType>
98 * </pre>
99 **/
100 public interface Credential {
101
102 /**
103 * Returns the peerGroupID associated with this credential
104 *
105 * @return the peerGroupID associated with this credential
106 **/
107 public ID getPeerGroupID();
108
109 /**
110 * Returns the peerID associated with this credential
111 *
112 * @return the peerID associated with this credential
113 **/
114 public ID getPeerID();
115
116 /**
117 * Returns the service which generated this credential.
118 *
119 * @return the service which generated this credential.
120 **/
121 public Service getSourceService();
122
123 /**
124 * If true then the credential is expired. Some credential implementations
125 * may never epxire.
126 **/
127 public boolean isExpired();
128
129 /**
130 * Returns true if this credential is currently valid.
131 *
132 * @return boolean true if the credential is currently valid, otherwise
133 * false.
134 **/
135 public boolean isValid();
136
137 /**
138 * Returns the subject of this credential. The Objects returned <b>must</b>
139 * support {@link Object#equals(Object)} and {@link Object#hashCode()}.
140 *
141 * @return the subject of the credential as an abstract object.
142 **/
143 public Object getSubject();
144
145 /**
146 * Write credential into a document. <code>asMimeType</code> is a mime
147 * media-type specification and provides the form of the document which is
148 * being requested. Two standard document forms are defined.
149 * <code>"text/plain"</code> encodes the document in a "pretty-print"
150 * format for human viewing and <code>"text/xml"<code> which provides an
151 * XML format.
152 *
153 * <p/>Depending on the credential format this document may be
154 * cryptographically signed to prevent alteration.
155 *
156 * @param asMimeType MimeMediaType format representation requested
157 * @return Document the document to be used in the construction
158 **/
159 public StructuredDocument getDocument( MimeMediaType asMimeType ) throws Exception;
160 }