1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 1999-2003
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Mitchell Stoltz <mstoltz@netscape.com>
24 * Christopher A. Aillon <christopher@aillon.com>
25 *
26 * Alternatively, the contents of this file may be used under the terms of
27 * either of the GNU General Public License Version 2 or later (the "GPL"),
28 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
29 * in which case the provisions of the GPL or the LGPL are applicable instead
30 * of those above. If you wish to allow use of your version of this file only
31 * under the terms of either the GPL or the LGPL, and not to allow others to
32 * use your version of this file under the terms of the MPL, indicate your
33 * decision by deleting the provisions above and replace them with the notice
34 * and other provisions required by the GPL or the LGPL. If you do not delete
35 * the provisions above, a recipient may use your version of this file under
36 * the terms of any one of the MPL, the GPL or the LGPL.
37 *
38 * ***** END LICENSE BLOCK ***** */
39
40 /* Defines the abstract interface for a principal. */
41
42 #include "nsISerializable.idl"
43
44 %{C++
45 struct JSContext;
46 struct JSPrincipals;
47 %}
48
49 interface nsIURI;
50
51 [ptr] native JSContext(JSContext);
52 [ptr] native JSPrincipals(JSPrincipals);
53
54 /**
55 * WARNING!! The JEP needs to call GetOrigin() to support
56 * JavaScript-to-Java LiveConnect. So every change to the nsIPrincipal
57 * interface (big enough to change its IID) also breaks JavaScript-to-Java
58 * LiveConnect on mac.
59 *
60 * If you REALLY have to change this interface, please mark your bug as
61 * blocking bug 293973.
62 */
63 [scriptable, uuid(b8268b9a-2403-44ed-81e3-614075c92034)]
64 interface nsIPrincipal : nsISerializable
65 {
66 /**
67 * Values of capabilities for each principal. Order is
68 * significant: if an operation is performed on a set
69 * of capabilities, the minimum is computed.
70 */
71 const short ENABLE_DENIED = 1;
72 const short ENABLE_UNKNOWN = 2;
73 const short ENABLE_WITH_USER_PERMISSION = 3;
74 const short ENABLE_GRANTED = 4;
75
76 /**
77 * Returns the security preferences associated with this principal.
78 * prefBranch will be set to the pref branch to which these preferences
79 * pertain. id is a pseudo-unique identifier, pertaining to either the
80 * fingerprint or the origin. subjectName is a name that identifies the
81 * entity this principal represents (may be empty). grantedList and
82 * deniedList are space-separated lists of capabilities which were
83 * explicitly granted or denied by a pref. isTrusted is a boolean that
84 * indicates whether this is a codebaseTrusted certificate.
85 */
86 [noscript] void getPreferences(out string prefBranch, out string id,
87 out string subjectName,
88 out string grantedList,
89 out string deniedList,
90 out boolean isTrusted);
91
92 /**
93 * Returns whether the other principal is equivalent to this principal.
94 * Principals are considered equal if they are the same principal,
95 * they have the same origin, or have the same certificate fingerprint ID
96 */
97 boolean equals(in nsIPrincipal other);
98
99 /**
100 * Returns a hash value for the principal.
101 */
102 [noscript] readonly attribute unsigned long hashValue;
103
104 /**
105 * Returns the JS equivalent of the principal.
106 * @see JSPrincipals.h
107 */
108 [noscript] JSPrincipals getJSPrincipals(in JSContext cx);
109
110 /**
111 * The domain security policy of the principal.
112 */
113 // XXXcaa should this be here? The script security manager is the only
114 // thing that should care about this. Wouldn't storing this data in one
115 // of the hashtables in nsScriptSecurityManager be better?
116 // XXXbz why is this writable? Who should have write access to this? What
117 // happens if this principal is in our hashtable and we pass it out of the
118 // security manager and someone writes to this field? Especially if they
119 // write garbage? If we need to give someone other than the security
120 // manager a way to set this (which I question, since it can increase the
121 // permissions of a page) it should be a |void clearSecurityPolicy()|
122 // method.
123 [noscript] attribute voidPtr securityPolicy;
124
125 // XXXcaa probably should be turned into {get|set}CapabilityFlags
126 // XXXbz again, what if this lives in our hashtable and someone
127 // messes with it? Is that OK?
128 [noscript] short canEnableCapability(in string capability);
129 [noscript] void setCanEnableCapability(in string capability,
130 in short canEnable);
131 [noscript] boolean isCapabilityEnabled(in string capability,
132 in voidPtr annotation);
133 [noscript] void enableCapability(in string capability,
134 inout voidPtr annotation);
135 [noscript] void revertCapability(in string capability,
136 inout voidPtr annotation);
137 [noscript] void disableCapability(in string capability,
138 inout voidPtr annotation);
139
140 /**
141 * The codebase URI to which this principal pertains. This is
142 * generally the document URI.
143 */
144 [noscript] readonly attribute nsIURI URI;
145
146 /**
147 * The domain URI to which this principal pertains.
148 * This is congruent with HTMLDocument.domain, and may be null.
149 * Setting this has no effect on the URI.
150 */
151 [noscript] attribute nsIURI domain;
152
153 /**
154 * The origin of this principal's codebase URI.
155 * An origin is defined as: scheme + host + port.
156 */
157 // XXXcaa this should probably be turned into an nsIURI.
158 // The system principal's origin should be some caps namespace
159 // with a chrome URI. All of chrome should probably be the same.
160 [noscript] readonly attribute string origin;
161
162 /**
163 * Whether this principal is associated with a certificate.
164 */
165 readonly attribute boolean hasCertificate;
166
167 /**
168 * The fingerprint ID of this principal's certificate.
169 * Throws if there is no certificate associated with this principal.
170 */
171 // XXXcaa kaie says this may not be unique. We should probably
172 // consider using something else for this....
173 readonly attribute AUTF8String fingerprint;
174
175 /**
176 * The pretty name for the certificate. This sort of (but not really)
177 * identifies the subject of the certificate (the entity that stands behind
178 * the certificate). Note that this may be empty; prefer to get the
179 * certificate itself and get this information from it, since that may
180 * provide more information.
181 *
182 * Throws if there is no certificate associated with this principal.
183 */
184 readonly attribute AUTF8String prettyName;
185
186 /**
187 * Returns whether the other principal is equal to or weaker than this
188 * principal. Principals are equal if they are the same object, they
189 * have the same origin, or they have the same certificate ID.
190 *
191 * Thus a principal always subsumes itself.
192 *
193 * The system principal subsumes itself and all other principals.
194 *
195 * A null principal (corresponding to an unknown, hence assumed minimally
196 * privileged, security context) is not equal to any other principal
197 * (including other null principals), and therefore does not subsume
198 * anything but itself.
199 *
200 * Both codebase and certificate principals are subsumed by the system
201 * principal, but no codebase or certificate principal yet subsumes any
202 * other codebase or certificate principal. This may change in a future
203 * release; note that nsIPrincipal is unfrozen, not slated to be frozen.
204 *
205 * XXXbz except see bug 147145!
206 *
207 * Note for the future: Perhaps we should consider a certificate principal
208 * for a given URI subsuming a codebase principal for the same URI? Not
209 * sure what the immediate benefit would be, but I think the setup could
210 * make some code (e.g. MaybeDowngradeToCodebase) clearer.
211 */
212 [noscript] boolean subsumes(in nsIPrincipal other);
213
214 /**
215 * Checks whether this principal is allowed to load the network resource
216 * located at the given URI under the same-origin policy. This means that
217 * codebase principals are only allowed to load resources from the same
218 * domain, the system principal is allowed to load anything, and null
219 * principals are not allowed to load anything.
220 *
221 * If the load is allowed this function does nothing. If the load is not
222 * allowed the function throws NS_ERROR_DOM_BAD_URI.
223 *
224 * NOTE: Other policies might override this, such as the Access-Control
225 * specification.
226 * NOTE: The 'domain' attribute has no effect on the behaviour of this
227 * function.
228 *
229 *
230 * @param uri The URI about to be loaded.
231 * @param report If true, will report a warning to the console service
232 * if the load is not allowed.
233 * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed.
234 */
235 [noscript] void checkMayLoad(in nsIURI uri, in boolean report);
236
237 /**
238 * The subject name for the certificate. This actually identifies the
239 * subject of the certificate. This may well not be a string that would
240 * mean much to a typical user on its own (e.g. it may have a number of
241 * different names all concatenated together with some information on what
242 * they mean in between).
243 *
244 * Throws if there is no certificate associated with this principal.
245 */
246 readonly attribute AUTF8String subjectName;
247
248 /**
249 * The certificate associated with this principal, if any. If there isn't
250 * one, this will return null. Getting this attribute never throws.
251 */
252 readonly attribute nsISupports certificate;
253 };