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 : WWWAuthenticateHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: * 1.2 13/06/2005 Phelim O'Doherty Deprecated get/set URI parameter
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip.header;
023:
024: import java.text.ParseException;
025: import javax.sip.address.URI;
026:
027: /**
028: * This interface represents the WWW-Authenticate response-header. A
029: * WWW-Authenticate header field value contains an authentication challenge.
030: * When a UAS receives a request from a UAC, the UAS MAY authenticate
031: * the originator before the request is processed. If no credentials
032: * (in the Authorization header field) are provided in the request, the
033: * UAS can challenge the originator to provide credentials by rejecting
034: * the request with a 401 (Unauthorized) status code. The WWW-Authenticate
035: * response-header field MUST be included in 401 (Unauthorized) response
036: * messages. The field value consists of at least one challenge that indicates
037: * the authentication scheme(s) and parameters applicable to the realm.
038: * <p>
039: * For Example:<br>
040: * <code>WWW-Authenticate: Digest realm="atlanta.com", domain="sip:boxesbybob.com",
041: * qop="auth", nonce="f84f1cec41e6cbe5aea9c8e88d359", opaque="", stale=FALSE,
042: * algorithm=MD5</code>
043: *
044: * @see Parameters
045: * @author BEA Systems, NIST
046: * @version 1.2
047: */
048:
049: public interface WWWAuthenticateHeader extends Parameters, Header {
050:
051: /**
052: * Sets the scheme of the challenge information for this WWWAuthenticateHeader.
053: * For example, Digest.
054: *
055: * @param scheme - the new string value that identifies the challenge
056: * information scheme.
057: */
058: public void setScheme(String scheme);
059:
060: /**
061: * Returns the scheme of the challenge information for this WWWAuthenticateHeader.
062: *
063: * @return the string value of the challenge information.
064: */
065: public String getScheme();
066:
067: /**
068: * Sets the Realm of the WWWAuthenicateHeader to the realm
069: * parameter value. Realm strings MUST be globally unique. It is
070: * RECOMMENDED that a realm string contain a hostname or domain name.
071: * Realm strings SHOULD present a human-readable identifier that can be
072: * rendered to a user.
073: *
074: * @param realm the new Realm String of this WWWAuthenicateHeader.
075: * @throws ParseException which signals that an error has been reached
076: * unexpectedly while parsing the realm.
077: */
078: public void setRealm(String realm) throws ParseException;
079:
080: /**
081: * Returns the Realm value of this WWWAuthenicateHeader. This convenience
082: * method returns only the realm of the complete Challenge.
083: *
084: * @return the String representing the Realm information, null if value is
085: * not set.
086: */
087: public String getRealm();
088:
089: /**
090: * Sets the Nonce of the WWWAuthenicateHeader to the nonce
091: * parameter value.
092: *
093: * @param nonce - the new nonce String of this WWWAuthenicateHeader.
094: * @throws ParseException which signals that an error has been reached
095: * unexpectedly while parsing the nonce value.
096: */
097: public void setNonce(String nonce) throws ParseException;
098:
099: /**
100: * Returns the Nonce value of this WWWAuthenicateHeader.
101: *
102: * @return the String representing the nonce information, null if value is
103: * not set.
104: */
105: public String getNonce();
106:
107: /**
108: * Sets the URI of the WWWAuthenicateHeader to the URI parameter value.
109: *
110: * @param uri - the new URI of this WWWAuthenicateHeader.
111: * @deprecated Since v1.2. URI is not a supported parameter for this header.
112: */
113: public void setURI(URI uri);
114:
115: /**
116: * Returns the URI value of this WWWAuthenicateHeader, for example DigestURI.
117: *
118: * @return the URI representing the URI information, null if value is
119: * not set.
120: * @deprecated Since v1.2. URI is not a supported parameter for this
121: * header. This method should return null.
122: */
123: public URI getURI();
124:
125: /**
126: * Sets the Algorithm of the WWWAuthenicateHeader to the new
127: * algorithm parameter value.
128: *
129: * @param algorithm - the new algorithm String of this WWWAuthenicateHeader.
130: * @throws ParseException which signals that an error has been reached
131: * unexpectedly while parsing the algorithm value.
132: */
133: public void setAlgorithm(String algorithm) throws ParseException;
134:
135: /**
136: * Returns the Algorithm value of this WWWAuthenicateHeader.
137: *
138: * @return the String representing the Algorithm information, null if the
139: * value is not set.
140: */
141: public String getAlgorithm();
142:
143: /**
144: * Sets the Qop value of the WWWAuthenicateHeader to the new
145: * qop parameter value.
146: *
147: * @param qop - the new Qop string of this WWWAuthenicateHeader.
148: * @throws ParseException which signals that an error has been reached
149: * unexpectedly while parsing the Qop value.
150: */
151: public void setQop(String qop) throws ParseException;
152:
153: /**
154: * Returns the Qop value of this WWWAuthenicateHeader.
155: *
156: * @return the string representing the Qop information, null if the
157: * value is not set.
158: */
159: public String getQop();
160:
161: /**
162: * Sets the Opaque value of the WWWAuthenicateHeader to the new
163: * opaque parameter value.
164: *
165: * @param opaque - the new Opaque string of this WWWAuthenicateHeader.
166: * @throws ParseException which signals that an error has been reached
167: * unexpectedly while parsing the opaque value.
168: */
169: public void setOpaque(String opaque) throws ParseException;
170:
171: /**
172: * Returns the Opaque value of this WWWAuthenicateHeader.
173: *
174: * @return the String representing the Opaque information, null if the
175: * value is not set.
176: */
177: public String getOpaque();
178:
179: /**
180: * Sets the Domain of the WWWAuthenicateHeader to the domain
181: * parameter value.
182: *
183: * @param domain - the new Domain string of this WWWAuthenicateHeader.
184: * @throws ParseException which signals that an error has been reached
185: * unexpectedly while parsing the domain.
186: */
187: public void setDomain(String domain) throws ParseException;
188:
189: /**
190: * Returns the Domain value of this WWWAuthenicateHeader.
191: *
192: * @return the String representing the Domain information, null if value is
193: * not set.
194: */
195: public String getDomain();
196:
197: /**
198: * Sets the value of the stale parameter of the WWWAuthenicateHeader to the
199: * stale parameter value.
200: *
201: * @param stale - the new boolean value of the stale parameter.
202: */
203: public void setStale(boolean stale);
204:
205: /**
206: * Returns the boolean value of the state paramater of this
207: * WWWAuthenicateHeader.
208: *
209: * @return the boolean representing if the challenge is stale.
210: */
211: public boolean isStale();
212:
213: /**
214: * Name of WWWAuthenticateHeader
215: */
216: public final static String NAME = "WWW-Authenticate";
217: }
|