001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : AuthorizationHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip.header;
022:
023: import java.text.ParseException;
024: import javax.sip.address.URI;
025:
026: /**
027: * The Authorization header is used when a user agent wishes to authenticate
028: * itself with a server - usually, but not necessarily, after receiving an
029: * UNAUTHORIZED Response - by including an AuthorizationHeader with the
030: * Request. The AuthorizationHeader consists of credentials
031: * containing the authentication information of the user agent for the
032: * realm of the resource being requested.
033: * <p>
034: * This header field, along with Proxy-Authorization, breaks the general
035: * rules about multiple header field values. Although not a comma-
036: * separated list, this header field name may be present multiple times,
037: * and MUST NOT be combined into a single header line.
038: * <p>
039: * For Example:<br>
040: * <code>Authorization: Digest username="Alice", realm="atlanta.com",<br>
041: * nonce="84a4cc6f3082121f32b42a2187831a9e",<br>
042: * response="7587245234b3434cc3412213e5f113a5432"</code>
043: *
044: * @see Parameters
045: * @see WWWAuthenticateHeader
046: * @see ProxyAuthorizationHeader
047: * @author BEA Systems, NIST
048: * @version 1.2
049: *
050: */
051:
052: public interface AuthorizationHeader extends Parameters, Header {
053:
054: /**
055: * Sets the scheme of the Response information for this AuthorizationHeader.
056: * For example, Digest.
057: *
058: * @param scheme - the new string value that identifies the response
059: * information scheme.
060: */
061: public void setScheme(String scheme);
062:
063: /**
064: * Returns the scheme of the Response information for this AuthorizationHeader.
065: *
066: * @return the string value of the response information.
067: */
068: public String getScheme();
069:
070: /**
071: * Sets the Realm of the AuthorizationHeader to the <var>realm</var>
072: * parameter value. Realm strings MUST be globally unique. It is
073: * RECOMMENDED that a realm string contain a hostname or domain name.
074: * Realm strings SHOULD present a human-readable identifier that can be
075: * rendered to a user.
076: *
077: * @param realm the new Realm String of this AuthorizationHeader.
078: * @throws ParseException which signals that an error has been reached
079: * unexpectedly while parsing the realm.
080: */
081: public void setRealm(String realm) throws ParseException;
082:
083: /**
084: * Returns the Realm value of this AuthorizationHeader. This convenience
085: * method returns only the realm of the complete Response.
086: *
087: * @return the String representing the Realm information, null if value is
088: * not set.
089: */
090: public String getRealm();
091:
092: /**
093: * Sets the Username of the AuthorizationHeader to the <var>username</var>
094: * parameter value.
095: *
096: * @param username the new Username String of this AuthorizationHeader.
097: * @throws ParseException which signals that an error has been reached
098: * unexpectedly while parsing the username.
099: */
100: public void setUsername(String username) throws ParseException;
101:
102: /**
103: * Returns the Username value of this AuthorizationHeader. This convenience
104: * method returns only the username of the complete Response.
105: *
106: * @return the String representing the Username information, null if value is
107: * not set.
108: */
109: public String getUsername();
110:
111: /**
112: * Sets the Nonce of the AuthorizationHeader to the <var>nonce</var>
113: * parameter value.
114: *
115: * @param nonce - the new nonce String of this AuthorizationHeader.
116: * @throws ParseException which signals that an error has been reached
117: * unexpectedly while parsing the nonce value.
118: */
119: public void setNonce(String nonce) throws ParseException;
120:
121: /**
122: * Returns the Nonce value of this AuthorizationHeader.
123: *
124: * @return the String representing the nonce information, null if value is
125: * not set.
126: */
127: public String getNonce();
128:
129: /**
130: * Sets the URI of the AuthorizationHeader to the <var>uri</var>
131: * parameter value.
132: *
133: * @param uri - the new URI of this AuthorizationHeader.
134: */
135: public void setURI(URI uri);
136:
137: /**
138: * Returns the DigestURI value of this AuthorizationHeader.
139: *
140: * @return the URI representing the URI information, null if value is
141: * not set.
142: *
143: * @note The syntax allows also non-URI strings, though it is not commonly
144: * used with SIP. To avoid parsing the string and treat it as opaque,
145: * applications should use getParameter("uri") instead of this method
146: */
147: public URI getURI();
148:
149: /**
150: * Sets the Response of the AuthorizationHeader to the new <var>response</var>
151: * parameter value.
152: *
153: * @param response - the new response String of this AuthorizationHeader.
154: * @throws ParseException which signals that an error has been reached
155: * unexpectedly while parsing the Response.
156: */
157: public void setResponse(String response) throws ParseException;
158:
159: /**
160: * Returns the Response value of this AuthorizationHeader.
161: *
162: * @return the String representing the Response information.
163: */
164: public String getResponse();
165:
166: /**
167: * Sets the Algorithm of the AuthorizationHeader to the new
168: * <var>algorithm</var> parameter value.
169: *
170: * @param algorithm - the new algorithm String of this AuthorizationHeader.
171: * @throws ParseException which signals that an error has been reached
172: * unexpectedly while parsing the algorithm value.
173: */
174: public void setAlgorithm(String algorithm) throws ParseException;
175:
176: /**
177: * Returns the Algorithm value of this AuthorizationHeader.
178: *
179: * @return the String representing the Algorithm information, null if the
180: * value is not set.
181: */
182: public String getAlgorithm();
183:
184: /**
185: * Sets the CNonce of the AuthorizationHeader to the <var>cNonce</var>
186: * parameter value.
187: *
188: * @param cNonce - the new cNonce String of this AuthorizationHeader.
189: * @throws ParseException which signals that an error has been reached
190: * unexpectedly while parsing the cNonce value.
191: */
192: public void setCNonce(String cNonce) throws ParseException;
193:
194: /**
195: * Returns the CNonce value of this AuthorizationHeader.
196: *
197: * @return the String representing the cNonce information, null if value is
198: * not set.
199: */
200: public String getCNonce();
201:
202: /**
203: * Sets the Opaque value of the AuthorizationHeader to the new
204: * <var>opaque</var> parameter value.
205: *
206: * @param opaque - the new Opaque string of this AuthorizationHeader.
207: * @throws ParseException which signals that an error has been reached
208: * unexpectedly while parsing the opaque value.
209: */
210: public void setOpaque(String opaque) throws ParseException;
211:
212: /**
213: * Returns the Opaque value of this AuthorizationHeader.
214: *
215: * @return the String representing the Opaque information, null if the
216: * value is not set.
217: */
218: public String getOpaque();
219:
220: /**
221: * Sets the MessageQop value of the AuthorizationHeader to the new
222: * <var>qop</var> parameter value.
223: *
224: * @param qop - the new Qop string of this AuthorizationHeader.
225: * @throws ParseException which signals that an error has been reached
226: * unexpectedly while parsing the Qop value.
227: */
228: public void setQop(String qop) throws ParseException;
229:
230: /**
231: * Returns the Qop value of this AuthorizationHeader.
232: *
233: * @return the string representing the Qop information, null if the
234: * value is not set.
235: */
236: public String getQop();
237:
238: /**
239: * Sets the Nonce Count of the AuthorizationHeader to the <var>nonceCount</var>
240: * parameter value.
241: *
242: * @param nonceCount - the new nonceCount integer of this AuthorizationHeader.
243: * @throws ParseException which signals that an error has been reached
244: * unexpectedly while parsing the nonceCount value.
245: */
246: public void setNonceCount(int nonceCount) throws ParseException;
247:
248: /**
249: * Returns the Nonce Count value of this AuthorizationHeader.
250: *
251: * @return the integer representing the nonceCount information, -1 if value is
252: * not set.
253: */
254: public int getNonceCount();
255:
256: /**
257: * Name of AuthorizationHeader
258: */
259: public final static String NAME = "Authorization";
260:
261: }
|