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!

ISecurityEncodable interface

Any security object that needs to be XML encoded by the security system must implement this interface. These System.Security classes implement this interface: permissions, permission sets, policy level, code groups, and membership conditions.

Application code developers need to implement this interface for the following kinds of objects that may extend the standard security system types:

  1. new permission types
  2. new policy types: new membership condition or code group types
interface ISecurityEncodable
{
        void ToXML (SecurityElement RootElement) ;
        void FromXML (SecurityElement RootElement) ;
}

The XML format for encoding consists of an outer element corresponding to a class instance – for example <Permission …> element for each permission, and so forth – that contains text and arbitrary elements representing the state of the object. Code in the corresponding class can only add sub-elements to the container element for the object, and only sub-elements are looked at later in reconstituting the object.

The following subsections describe what objects do to support the methods of this interface.

For examples, we will discuss the FooPermission that has three fields to represent its state. The fields and the XML template representation are shown here to illustrate:

Boolean flag; String str;

<Permission class=”FooPermission” assembly=”name”>

text contents of String str …

<flag/>

</Permission>

ToXML

ToXML(element) puts information in the element to create a representation of the state of the security object (this). For instance the FooPermission might do this:

SecurityElement ToXML ()
{
   SecurityElement e = new SecurityElement ("Permission");
   Type type = this.GetType();
   String assemblyName = type.Module.Assembly.FullName;
   assemblyName = assemblyName.Replace( '\"', '\'' );
   element.AddAttribute( "class", type.FullName + ", " + assemblyName );
   e.AddAttribute("Version","1");
   if(flag) e.AddChild(new SecurityElement(“flag”));   // add <flag/> iff true
   e.Text = str;   // text of the element 
   return e;
}

FromXML

The encoded XML representation can subsequently be used to reconstruct an identical object. The FromXML() method handles the type-specific interpretation of the XML created by the corresponding ToXML(), and should result in an identical (for purposes of the particular security object semantics) valued object. For instance the FooPermission might do this:

void FromXML (SecurityElement e)
// pseudocode sans error checking
{
   flag = (NULL != SearchForChildByTag(“flag”));  // any <flag/>?
   str = e.Text;   // text of the element 
}

How ToXML/FromXML are called

This section describes how the security system calls ToXML and FromXML. While custom code that extends security objects will need to implement the ToXML and FromXML methods to make the objects security-encodable, application code never actually needs to call these methods directly. Nonetheless, a description of how the ISecurityEncodable methods are called is useful in understanding how to implement them.

The following pseudo-code shows how the encoding and decoding process works for a permission. These are not public APIs but just examples of how ToXML and FromXML are used by the security system.

EncodeSecurityObject(Object obj, Stream stream)
// Example shows how security object obj is encoded in XML to stream.
// Actual implementation is different but equivalent calling ToXML().
{
   SecurityElement e = obj.ToXML();   // add object contents to the object model
   e.ToStream(stream); // writes the XML object model to the stream
}

Object DecodeSecurityObject(Stream stream)
// Example shows how security object obj is encoded in XML to stream.
// Actual implementation is different but equivalent calling FromXML().
   SecurityElement e = SecurityElement.FromStream (stream);   // Get XML
   if (e.Tag != “Permission”)
      raise SerializationException(“wrong kind of serialized data”);
      // error case of say policy level where perm set data expected
   String classname = e.Attribute(“class);
   if (classname==NULL)
      raise SerializationException(“require class attribute”);
      // error case of unexpected class
   obj = CreateInstance(GetType(classname));
   // construct instance from the object model
   obj.FromXML(e);   
   return obj;
}