NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Assert

Assert is a method that can be called on code access permission classes, which allows you to ensure that your code (and downstream callers) are allowed to do something that your code has permission to do, even if your code's callers don't have permission to do that thing. A security assertion changes the normal process that the runtime performs during a security check. When you assert a permission, it tells the security system not to check the callers of your code for the asserted permission; instead, when the assertion is encountered during a stack walk, the security check automatically succeeds. Assertions should be used only with great care because they can open security holes and undermine the runtime's mechanism for enforcing security restrictions. To perform assertions, your code needs to be granted both the permission you are asserting and the SecurityPermission that represents the right to do assertions; although you could assert a permission your code hasn't been granted, the assertion would be pointless because the security check would fail before the assertion would cause it to succeed.

Assertions are often used in class libraries, which are usually more highly trusted than the applications that call the library. If you are designing a class library and your class accesses a protected resource, you should, in most cases, make a security demand to require that the callers of your class have the appropriate permission. Then, if your class performs an operation that you know most of your callers will not have permission for, and if you are willing to take the responsibility for letting these callers call your code, you can assert the permission by calling the Assert method on a permission object that represents the operation you are performing. Using Assert in this way lets callers call your code that normally could not call it. Therefore, if you assert a permission, you should be sure to perform appropriate security checks before you do so to prevent your component from being misused.

For example, suppose your highly trusted library class has a method that deletes files; it accesses the file by calling an unmanaged Win32 function. A caller invokes your code's Delete method, passing in the name of the file to be deleted, "c:\test.txt". Within the Delete method, your code creates a FileIOPermission object representing write access to "c:\test.txt" (write access is required to delete a file). Then your code invokes an imperative security check by calling the FileIOPermission object's Demand method. If one of the callers in the call stack doesn't have this permission, a SecurityException is thrown. If no exception is thrown, you know that all callers have the right to access c:\test.txt. Because you believe that most of your callers will not have permission to access unmanaged code, your code then creates a SecurityPermission object that represents the right to call unmanaged code and calls the object's Assert method. Finally, it calls the unmanaged Win32 function to delete "c:\text.txt" and returns control to the caller.

Assertions can also be used in other situations, such as those in which your code accesses a resource in a way that is completely hidden from callers. For example, suppose your code does some calculations, and in the process of doing so, it looks up and uses data that resides in a file accessible to your application. In this case, you decide that it is not reasonable or necessary to require that callers of your code have permission to access that particular file, so you assert permission for reading that file.

Warning: You must be sure that you do not do assertions in situations where your code can be used by other code to access a resource that is protected by the permission you are asserting. For example, in code that writes to a file whose name is specified by the caller as a parameter, you would not assert the FileIOPermission for writing to files because your code would be open to misuse by a third party.