1 module soup.AuthDomain; 2 3 private import glib.Str; 4 private import gobject.ObjectG; 5 private import soup.Message; 6 private import soup.c.functions; 7 public import soup.c.types; 8 9 10 /** 11 * A #SoupAuthDomain manages authentication for all or part of a 12 * #SoupServer. To make a server require authentication, first create 13 * an appropriate subclass of #SoupAuthDomain, and then add it to the 14 * server with soup_server_add_auth_domain(). 15 * 16 * In order for an auth domain to have any effect, you must add one or 17 * more paths to it (via soup_auth_domain_add_path() or the 18 * %SOUP_AUTH_DOMAIN_ADD_PATH property). To require authentication for 19 * all ordinary requests, add the path "/". (Note that this does not 20 * include the special "*" URI (eg, "OPTIONS *"), which must be added 21 * as a separate path if you want to cover it.) 22 * 23 * If you need greater control over which requests should and 24 * shouldn't be authenticated, add paths covering everything you 25 * <emphasis>might</emphasis> want authenticated, and then use a 26 * filter (soup_auth_domain_set_filter()) to bypass authentication for 27 * those requests that don't need it. 28 */ 29 public class AuthDomain : ObjectG 30 { 31 /** the main Gtk struct */ 32 protected SoupAuthDomain* soupAuthDomain; 33 34 /** Get the main Gtk struct */ 35 public SoupAuthDomain* getAuthDomainStruct(bool transferOwnership = false) 36 { 37 if (transferOwnership) 38 ownedRef = false; 39 return soupAuthDomain; 40 } 41 42 /** the main Gtk struct as a void* */ 43 protected override void* getStruct() 44 { 45 return cast(void*)soupAuthDomain; 46 } 47 48 /** 49 * Sets our main struct and passes it to the parent class. 50 */ 51 public this (SoupAuthDomain* soupAuthDomain, bool ownedRef = false) 52 { 53 this.soupAuthDomain = soupAuthDomain; 54 super(cast(GObject*)soupAuthDomain, ownedRef); 55 } 56 57 58 /** */ 59 public static GType getType() 60 { 61 return soup_auth_domain_get_type(); 62 } 63 64 /** 65 * Checks if @msg contains appropriate authorization for @domain to 66 * accept it. Mirroring soup_auth_domain_covers(), this does not check 67 * whether or not @domain <emphasis>cares</emphasis> if @msg is 68 * authorized. 69 * 70 * This is used by #SoupServer internally and is probably of no use to 71 * anyone else. 72 * 73 * Params: 74 * msg = a #SoupMessage 75 * 76 * Returns: the username that @msg has authenticated 77 * as, if in fact it has authenticated. %NULL otherwise. 78 */ 79 public string accepts(Message msg) 80 { 81 auto retStr = soup_auth_domain_accepts(soupAuthDomain, (msg is null) ? null : msg.getMessageStruct()); 82 83 scope(exit) Str.freeString(retStr); 84 return Str.toString(retStr); 85 } 86 87 /** 88 * Adds @path to @domain, such that requests under @path on @domain's 89 * server will require authentication (unless overridden by 90 * soup_auth_domain_remove_path() or soup_auth_domain_set_filter()). 91 * 92 * You can also add paths by setting the %SOUP_AUTH_DOMAIN_ADD_PATH 93 * property, which can also be used to add one or more paths at 94 * construct time. 95 * 96 * Params: 97 * path = the path to add to @domain 98 */ 99 public void addPath(string path) 100 { 101 soup_auth_domain_add_path(soupAuthDomain, Str.toStringz(path)); 102 } 103 104 /** 105 * Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg, 106 * requesting that the client authenticate, and sets @msg's status 107 * accordingly. 108 * 109 * This is used by #SoupServer internally and is probably of no use to 110 * anyone else. 111 * 112 * Params: 113 * msg = a #SoupMessage 114 */ 115 public void challenge(Message msg) 116 { 117 soup_auth_domain_challenge(soupAuthDomain, (msg is null) ? null : msg.getMessageStruct()); 118 } 119 120 /** 121 * Checks if @msg authenticates to @domain via @username and 122 * @password. This would normally be called from a 123 * #SoupAuthDomainGenericAuthCallback. 124 * 125 * Params: 126 * msg = a #SoupMessage 127 * username = a username 128 * password = a password 129 * 130 * Returns: whether or not the message is authenticated 131 */ 132 public bool checkPassword(Message msg, string username, string password) 133 { 134 return soup_auth_domain_check_password(soupAuthDomain, (msg is null) ? null : msg.getMessageStruct(), Str.toStringz(username), Str.toStringz(password)) != 0; 135 } 136 137 /** 138 * Checks if @domain requires @msg to be authenticated (according to 139 * its paths and filter function). This does not actually look at 140 * whether @msg <emphasis>is</emphasis> authenticated, merely whether 141 * or not it needs to be. 142 * 143 * This is used by #SoupServer internally and is probably of no use to 144 * anyone else. 145 * 146 * Params: 147 * msg = a #SoupMessage 148 * 149 * Returns: %TRUE if @domain requires @msg to be authenticated 150 */ 151 public bool covers(Message msg) 152 { 153 return soup_auth_domain_covers(soupAuthDomain, (msg is null) ? null : msg.getMessageStruct()) != 0; 154 } 155 156 /** 157 * Gets the realm name associated with @domain 158 * 159 * Returns: @domain's realm 160 */ 161 public string getRealm() 162 { 163 return Str.toString(soup_auth_domain_get_realm(soupAuthDomain)); 164 } 165 166 /** 167 * Removes @path from @domain, such that requests under @path on 168 * @domain's server will NOT require authentication. 169 * 170 * This is not simply an undo-er for soup_auth_domain_add_path(); it 171 * can be used to "carve out" a subtree that does not require 172 * authentication inside a hierarchy that does. Note also that unlike 173 * with soup_auth_domain_add_path(), this cannot be overridden by 174 * adding a filter, as filters can only bypass authentication that 175 * would otherwise be required, not require it where it would 176 * otherwise be unnecessary. 177 * 178 * You can also remove paths by setting the 179 * %SOUP_AUTH_DOMAIN_REMOVE_PATH property, which can also be used to 180 * remove one or more paths at construct time. 181 * 182 * Params: 183 * path = the path to remove from @domain 184 */ 185 public void removePath(string path) 186 { 187 soup_auth_domain_remove_path(soupAuthDomain, Str.toStringz(path)); 188 } 189 190 /** 191 * Adds @filter as an authentication filter to @domain. The filter 192 * gets a chance to bypass authentication for certain requests that 193 * would otherwise require it. Eg, it might check the message's path 194 * in some way that is too complicated to do via the other methods, or 195 * it might check the message's method, and allow GETs but not PUTs. 196 * 197 * The filter function returns %TRUE if the request should still 198 * require authentication, or %FALSE if authentication is unnecessary 199 * for this request. 200 * 201 * To help prevent security holes, your filter should return %TRUE by 202 * default, and only return %FALSE under specifically-tested 203 * circumstances, rather than the other way around. Eg, in the example 204 * above, where you want to authenticate PUTs but not GETs, you should 205 * check if the method is GET and return %FALSE in that case, and then 206 * return %TRUE for all other methods (rather than returning %TRUE for 207 * PUT and %FALSE for all other methods). This way if it turned out 208 * (now or later) that some paths supported additional methods besides 209 * GET and PUT, those methods would default to being NOT allowed for 210 * unauthenticated users. 211 * 212 * You can also set the filter by setting the %SOUP_AUTH_DOMAIN_FILTER 213 * and %SOUP_AUTH_DOMAIN_FILTER_DATA properties, which can also be 214 * used to set the filter at construct time. 215 * 216 * Params: 217 * filter = the auth filter for @domain 218 * filterData = data to pass to @filter 219 * dnotify = destroy notifier to free @filter_data when @domain 220 * is destroyed 221 */ 222 public void setFilter(SoupAuthDomainFilter filter, void* filterData, GDestroyNotify dnotify) 223 { 224 soup_auth_domain_set_filter(soupAuthDomain, filter, filterData, dnotify); 225 } 226 227 /** 228 * Sets @auth_callback as an authentication-handling callback for 229 * @domain. Whenever a request comes in to @domain which cannot be 230 * authenticated via a domain-specific auth callback (eg, 231 * #SoupAuthDomainDigestAuthCallback), the generic auth callback 232 * will be invoked. See #SoupAuthDomainGenericAuthCallback for information 233 * on what the callback should do. 234 * 235 * Params: 236 * authCallback = the auth callback 237 * authData = data to pass to @auth_callback 238 * dnotify = destroy notifier to free @auth_data when @domain 239 * is destroyed 240 */ 241 public void setGenericAuthCallback(SoupAuthDomainGenericAuthCallback authCallback, void* authData, GDestroyNotify dnotify) 242 { 243 soup_auth_domain_set_generic_auth_callback(soupAuthDomain, authCallback, authData, dnotify); 244 } 245 246 /** */ 247 public bool tryGenericAuthCallback(Message msg, string username) 248 { 249 return soup_auth_domain_try_generic_auth_callback(soupAuthDomain, (msg is null) ? null : msg.getMessageStruct(), Str.toStringz(username)) != 0; 250 } 251 }