View Javadoc
1   /*
2    * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.net;
27  
28  import java.io.ObjectInputStream;
29  import java.io.IOException;
30  import java.util.List;
31  import java.util.ArrayList;
32  import java.util.Collections;
33  import java.security.Permission;
34  
35  /**
36   * Represents permission to access a resource or set of resources defined by a
37   * given url, and for a given set of user-settable request methods
38   * and request headers. The <i>name</i> of the permission is the url string.
39   * The <i>actions</i> string is a concatenation of the request methods and headers.
40   * The range of method and header names is not restricted by this class.
41   * <p><b>The url</b><p>
42   * The url string has the following expected structure.
43   * <pre>
44   *     scheme : // authority [ / path ]
45   * </pre>
46   * <i>scheme</i> will typically be http or https, but is not restricted by this
47   * class.
48   * <i>authority</i> is specified as:
49   * <pre>
50   *     authority = [ userinfo @ ] hostrange [ : portrange ]
51   *     portrange = portnumber | -portnumber | portnumber-[portnumber] | *
52   *     hostrange = ([*.] dnsname) | IPv4address | IPv6address
53   * </pre>
54   * <i>dnsname</i> is a standard DNS host or domain name, ie. one or more labels
55   * separated by ".". <i>IPv4address</i> is a standard literal IPv4 address and
56   * <i>IPv6address</i> is as defined in <a href="http://www.ietf.org/rfc/rfc2732.txt">
57   * RFC 2732</a>. Literal IPv6 addresses must however, be enclosed in '[]' characters.
58   * The <i>dnsname</i> specification can be preceded by "*." which means
59   * the name will match any hostname whose right-most domain labels are the same as
60   * this name. For example, "*.oracle.com" matches "foo.bar.oracle.com"
61   * <p>
62   * <i>portrange</i> is used to specify a port number, or a bounded or unbounded range of ports
63   * that this permission applies to. If portrange is absent or invalid, then a default
64   * port number is assumed if the scheme is {@code http} (default 80) or {@code https}
65   * (default 443). No default is assumed for other schemes. A wildcard may be specified
66   * which means all ports.
67   * <p>
68   * <i>userinfo</i> is optional. A userinfo component if present, is ignored when
69   * creating a URLPermission, and has no effect on any other methods defined by this class.
70   * <p>
71   * The <i>path</i> component comprises a sequence of path segments,
72   * separated by '/' characters. <i>path</i> may also be empty. The path is specified
73   * in a similar way to the path in {@link java.io.FilePermission}. There are
74   * three different ways as the following examples show:
75   * <table border>
76   * <caption>URL Examples</caption>
77   * <tr><th>Example url</th><th>Description</th></tr>
78   * <tr><td style="white-space:nowrap;">http://www.oracle.com/a/b/c.html</td>;
79   *   <td>A url which identifies a specific (single) resource</td>
80   * </tr>
81   * <tr><td>http://www.oracle.com/a/b/*</td>;
82   *   <td>The '*' character refers to all resources in the same "directory" - in
83   *       other words all resources with the same number of path components, and
84   *       which only differ in the final path component, represented by the '*'.
85   *   </td>
86   * </tr>
87   * <tr><td>http://www.oracle.com/a/b/-</td>;
88   *   <td>The '-' character refers to all resources recursively below the
89   *       preceding path (eg. http://www.oracle.com/a/b/c/d/e.html matches this
90   *       example).
91   *   </td>
92   * </tr>
93   * </table>
94   * <p>
95   * The '*' and '-' may only be specified in the final segment of a path and must be
96   * the only character in that segment. Any query or fragment components of the
97   * url are ignored when constructing URLPermissions.
98   * <p>
99   * As a special case, urls of the form, "scheme:*" are accepted to
100  * mean any url of the given scheme.
101  * <p>
102  * The <i>scheme</i> and <i>authority</i> components of the url string are handled
103  * without regard to case. This means {@link #equals(Object)},
104  * {@link #hashCode()} and {@link #implies(Permission)} are case insensitive with respect
105  * to these components. If the <i>authority</i> contains a literal IP address,
106  * then the address is normalized for comparison. The path component is case sensitive.
107  * <p><b>The actions string</b><p>
108  * The actions string of a URLPermission is a concatenation of the <i>method list</i>
109  * and the <i>request headers list</i>. These are lists of the permitted request
110  * methods and permitted request headers of the permission (respectively). The two lists
111  * are separated by a colon ':' character and elements of each list are comma separated.
112  * Some examples are:
113  * <pre>
114  *         "POST,GET,DELETE"
115  *         "GET:X-Foo-Request,X-Bar-Request"
116  *         "POST,GET:Header1,Header2"
117  * </pre>
118  * The first example specifies the methods: POST, GET and DELETE, but no request headers.
119  * The second example specifies one request method and two headers. The third
120  * example specifies two request methods, and two headers.
121  * <p>
122  * The colon separator need not be present if the request headers list is empty.
123  * No white-space is permitted in the actions string. The action strings supplied to
124  * the URLPermission constructors are case-insensitive and are normalized by converting
125  * method names to upper-case and header names to the form defines in RFC2616 (lower case
126  * with initial letter of each word capitalized). Either list can contain a wild-card '*'
127  * character which signifies all request methods or headers respectively.
128  * <p>
129  * Note. Depending on the context of use, some request methods and headers may be permitted
130  * at all times, and others may not be permitted at any time. For example, the
131  * HTTP protocol handler might disallow certain headers such as Content-Length
132  * from being set by application code, regardless of whether the security policy
133  * in force, permits it.
134  *
135  * @since 1.8
136  */
137 public final class URLPermission extends Permission {
138 
139     private static final long serialVersionUID = -2702463814894478682L;
140 
141     private transient String scheme;
142     private transient String ssp;                 // scheme specific part
143     private transient String path;
144     private transient List<String> methods;
145     private transient List<String> requestHeaders;
146     private transient Authority authority;
147 
148     // serialized field
149     private String actions;
150 
151     /**
152      * Creates a new URLPermission from a url string and which permits the given
153      * request methods and user-settable request headers.
154      * The name of the permission is the url string it was created with. Only the scheme,
155      * authority and path components of the url are used internally. Any fragment or query
156      * components are ignored. The permissions action string is as specified above.
157      *
158      * @param url the url string
159      *
160      * @param actions the actions string
161      *
162      * @exception IllegalArgumentException if url is invalid or if actions contains white-space.
163      */
164     public URLPermission(String url, String actions) {
165         super(url);
166         init(actions);
167     }
168 
169     private void init(String actions) {
170         parseURI(getName());
171         int colon = actions.indexOf(':');
172         if (actions.lastIndexOf(':') != colon) {
173             throw new IllegalArgumentException("invalid actions string");
174         }
175 
176         String methods, headers;
177         if (colon == -1) {
178             methods = actions;
179             headers = "";
180         } else {
181             methods = actions.substring(0, colon);
182             headers = actions.substring(colon+1);
183         }
184 
185         List<String> l = normalizeMethods(methods);
186         Collections.sort(l);
187         this.methods = Collections.unmodifiableList(l);
188 
189         l = normalizeHeaders(headers);
190         Collections.sort(l);
191         this.requestHeaders = Collections.unmodifiableList(l);
192 
193         this.actions = actions();
194     }
195 
196     /**
197      * Creates a URLPermission with the given url string and unrestricted
198      * methods and request headers by invoking the two argument
199      * constructor as follows: URLPermission(url, "*:*")
200      *
201      * @param url the url string
202      *
203      * @throws    IllegalArgumentException if url does not result in a valid {@link URI}
204      */
205     public URLPermission(String url) {
206         this(url, "*:*");
207     }
208 
209     /**
210      * Returns the normalized method list and request
211      * header list, in the form:
212      * <pre>
213      *      "method-names : header-names"
214      * </pre>
215      * <p>
216      * where method-names is the list of methods separated by commas
217      * and header-names is the list of permitted headers separated by commas.
218      * There is no white space in the returned String. If header-names is empty
219      * then the colon separator will not be present.
220      */
221     public String getActions() {
222         return actions;
223     }
224 
225     /**
226      * Checks if this URLPermission implies the given permission.
227      * Specifically, the following checks are done as if in the
228      * following sequence:
229      * <ul>
230      * <li>if 'p' is not an instance of URLPermission return false</li>
231      * <li>if any of p's methods are not in this's method list, and if
232      *     this's method list is not equal to "*", then return false.</li>
233      * <li>if any of p's headers are not in this's request header list, and if
234      *     this's request header list is not equal to "*", then return false.</li>
235      * <li>if this's url scheme is not equal to p's url scheme return false</li>
236      * <li>if the scheme specific part of this's url is '*' return true</li>
237      * <li>if the set of hosts defined by p's url hostrange is not a subset of
238      *     this's url hostrange then return false. For example, "*.foo.oracle.com"
239      *     is a subset of "*.oracle.com". "foo.bar.oracle.com" is not
240      *     a subset of "*.foo.oracle.com"</li>
241      * <li>if the portrange defined by p's url is not a subset of the
242      *     portrange defined by this's url then return false.
243      * <li>if the path or paths specified by p's url are contained in the
244      *     set of paths specified by this's url, then return true
245      * <li>otherwise, return false</li>
246      * </ul>
247      * <p>Some examples of how paths are matched are shown below:
248      * <table border>
249      * <caption>Examples of Path Matching</caption>
250      * <tr><th>this's path</th><th>p's path</th><th>match</th></tr>
251      * <tr><td>/a/b</td><td>/a/b</td><td>yes</td></tr>
252      * <tr><td>/a/b/*</td><td>/a/b/c</td><td>yes</td></tr>
253      * <tr><td>/a/b/*</td><td>/a/b/c/d</td><td>no</td></tr>
254      * <tr><td>/a/b/-</td><td>/a/b/c/d</td><td>yes</td></tr>
255      * <tr><td>/a/b/-</td><td>/a/b/c/d/e</td><td>yes</td></tr>
256      * <tr><td>/a/b/-</td><td>/a/b/c/*</td><td>yes</td></tr>
257      * <tr><td>/a/b/*</td><td>/a/b/c/-</td><td>no</td></tr>
258      * </table>
259      */
260     public boolean implies(Permission p) {
261         if (! (p instanceof URLPermission)) {
262             return false;
263         }
264 
265         URLPermission that = (URLPermission)p;
266 
267         if (!this.methods.get(0).equals("*") &&
268                 Collections.indexOfSubList(this.methods, that.methods) == -1) {
269             return false;
270         }
271 
272         if (this.requestHeaders.isEmpty() && !that.requestHeaders.isEmpty()) {
273             return false;
274         }
275 
276         if (!this.requestHeaders.isEmpty() &&
277             !this.requestHeaders.get(0).equals("*") &&
278              Collections.indexOfSubList(this.requestHeaders,
279                                         that.requestHeaders) == -1) {
280             return false;
281         }
282 
283         if (!this.scheme.equals(that.scheme)) {
284             return false;
285         }
286 
287         if (this.ssp.equals("*")) {
288             return true;
289         }
290 
291         if (!this.authority.implies(that.authority)) {
292             return false;
293         }
294 
295         if (this.path == null) {
296             return that.path == null;
297         }
298         if (that.path == null) {
299             return false;
300         }
301 
302         if (this.path.endsWith("/-")) {
303             String thisprefix = this.path.substring(0, this.path.length() - 1);
304             return that.path.startsWith(thisprefix);
305             }
306 
307         if (this.path.endsWith("/*")) {
308             String thisprefix = this.path.substring(0, this.path.length() - 1);
309             if (!that.path.startsWith(thisprefix)) {
310                 return false;
311             }
312             String thatsuffix = that.path.substring(thisprefix.length());
313             // suffix must not contain '/' chars
314             if (thatsuffix.indexOf('/') != -1) {
315                 return false;
316             }
317             if (thatsuffix.equals("-")) {
318                 return false;
319             }
320             return true;
321         }
322         return this.path.equals(that.path);
323     }
324 
325 
326     /**
327      * Returns true if, this.getActions().equals(p.getActions())
328      * and p's url equals this's url.  Returns false otherwise.
329      */
330     public boolean equals(Object p) {
331         if (!(p instanceof URLPermission)) {
332             return false;
333         }
334         URLPermission that = (URLPermission)p;
335         if (!this.scheme.equals(that.scheme)) {
336             return false;
337         }
338         if (!this.getActions().equals(that.getActions())) {
339             return false;
340         }
341         if (!this.authority.equals(that.authority)) {
342             return false;
343         }
344         if (this.path != null) {
345             return this.path.equals(that.path);
346         } else {
347             return that.path == null;
348         }
349     }
350 
351     /**
352      * Returns a hashcode calculated from the hashcode of the
353      * actions String and the url string.
354      */
355     public int hashCode() {
356         return getActions().hashCode()
357             + scheme.hashCode()
358             + authority.hashCode()
359             + (path == null ? 0 : path.hashCode());
360     }
361 
362 
363     private List<String> normalizeMethods(String methods) {
364         List<String> l = new ArrayList<>();
365         StringBuilder b = new StringBuilder();
366         for (int i=0; i<methods.length(); i++) {
367             char c = methods.charAt(i);
368             if (c == ',') {
369                 String s = b.toString();
370                 if (s.length() > 0)
371                     l.add(s);
372                 b = new StringBuilder();
373             } else if (c == ' ' || c == '\t') {
374                 throw new IllegalArgumentException("white space not allowed");
375             } else {
376                 if (c >= 'a' && c <= 'z') {
377                     c += 'A' - 'a';
378                 }
379                 b.append(c);
380             }
381         }
382         String s = b.toString();
383         if (s.length() > 0)
384             l.add(s);
385         return l;
386     }
387 
388     private List<String> normalizeHeaders(String headers) {
389         List<String> l = new ArrayList<>();
390         StringBuilder b = new StringBuilder();
391         boolean capitalizeNext = true;
392         for (int i=0; i<headers.length(); i++) {
393             char c = headers.charAt(i);
394             if (c >= 'a' && c <= 'z') {
395                 if (capitalizeNext) {
396                     c += 'A' - 'a';
397                     capitalizeNext = false;
398                 }
399                 b.append(c);
400             } else if (c == ' ' || c == '\t') {
401                 throw new IllegalArgumentException("white space not allowed");
402             } else if (c == '-') {
403                     capitalizeNext = true;
404                 b.append(c);
405             } else if (c == ',') {
406                 String s = b.toString();
407                 if (s.length() > 0)
408                     l.add(s);
409                 b = new StringBuilder();
410                 capitalizeNext = true;
411             } else {
412                 capitalizeNext = false;
413                 b.append(c);
414             }
415         }
416         String s = b.toString();
417         if (s.length() > 0)
418             l.add(s);
419         return l;
420     }
421 
422     private void parseURI(String url) {
423         int len = url.length();
424         int delim = url.indexOf(':');
425         if (delim == -1 || delim + 1 == len) {
426             throw new IllegalArgumentException("invalid URL string");
427         }
428         scheme = url.substring(0, delim).toLowerCase();
429         this.ssp = url.substring(delim + 1);
430 
431         if (!ssp.startsWith("//")) {
432             if (!ssp.equals("*")) {
433                 throw new IllegalArgumentException("invalid URL string");
434             }
435             this.authority = new Authority(scheme, "*");
436             return;
437         }
438         String authpath = ssp.substring(2);
439 
440         delim = authpath.indexOf('/');
441         String auth;
442         if (delim == -1) {
443             this.path = "";
444             auth = authpath;
445         } else {
446             auth = authpath.substring(0, delim);
447             this.path = authpath.substring(delim);
448         }
449         this.authority = new Authority(scheme, auth.toLowerCase());
450     }
451 
452     private String actions() {
453         StringBuilder b = new StringBuilder();
454         for (String s : methods) {
455             b.append(s);
456         }
457         b.append(":");
458         for (String s : requestHeaders) {
459             b.append(s);
460         }
461         return b.toString();
462     }
463 
464     /**
465      * restore the state of this object from stream
466      */
467     private void readObject(ObjectInputStream s)
468         throws IOException, ClassNotFoundException {
469         ObjectInputStream.GetField fields = s.readFields();
470         String actions = (String)fields.get("actions", null);
471 
472         init(actions);
473     }
474 
475     static class Authority {
476         HostPortrange p;
477 
478         Authority(String scheme, String authority) {
479             int at = authority.indexOf('@');
480             if (at == -1) {
481                     p = new HostPortrange(scheme, authority);
482             } else {
483                     p = new HostPortrange(scheme, authority.substring(at+1));
484             }
485         }
486 
487         boolean implies(Authority other) {
488             return impliesHostrange(other) && impliesPortrange(other);
489         }
490 
491         private boolean impliesHostrange(Authority that) {
492             String thishost = this.p.hostname();
493             String thathost = that.p.hostname();
494 
495             if (p.wildcard() && thishost.equals("")) {
496                 // this "*" implies all others
497                 return true;
498             }
499             if (that.p.wildcard() && thathost.equals("")) {
500                 // that "*" can only be implied by this "*"
501                 return false;
502             }
503             if (thishost.equals(thathost)) {
504                 // covers all cases of literal IP addresses and fixed
505                 // domain names.
506                 return true;
507             }
508             if (this.p.wildcard()) {
509                 // this "*.foo.com" implies "bub.bar.foo.com"
510                 return thathost.endsWith(thishost);
511             }
512             return false;
513         }
514 
515         private boolean impliesPortrange(Authority that) {
516             int[] thisrange = this.p.portrange();
517             int[] thatrange = that.p.portrange();
518             if (thisrange[0] == -1) {
519                 /* port not specified non http/s URL */
520                 return true;
521             }
522             return thisrange[0] <= thatrange[0] &&
523                         thisrange[1] >= thatrange[1];
524         }
525 
526         boolean equals(Authority that) {
527             return this.p.equals(that.p);
528         }
529 
530         public int hashCode() {
531             return p.hashCode();
532         }
533     }
534 }