John Kozell

Creating Security Descriptors for MOSS 2007 Managed Protocol Handlers

Long ago (July 2006) I posted an article entitled Creating Security Descriptors for SPS 2003 Managed Protocol Handlers which was supplemental to my original version of the SPS 2003 Managed Protocol explaining how to build a Win32 security descriptor using a GotDotNet library called “Microsoft.Win32.Security”. The bad news is this library is no longer available, the good news is that you don’t need it because support for building security descriptors has been built into the .NET Framework since v2.0. Unfortunately v2.0 was released in January of 2006, which was after all the work I had done building the sample.

Since then several of you have reached out to me and I’ve guided you individually to the System.Security.AccessControl namespace where goodies such as the CommonSecurityDescriptor class can be found, leaving the exercise of figuring out the precise classes, methods and properties to substitute up to the curious and motivated (sorry). In October of 2008 Chris Givens of Architecting Connected Systems was nice enough to send me his adaptation of my original SecurityDescriptor.cs file using the new managed classes (thanks Chris). Here is a peek at the important snippets from that code:

Class members:

CommonSecurityDescriptor csd;
DiscretionaryAcl dacl;

GetBuffer:

byte[] buffer = new byte[csd.BinaryLength];
csd.GetBinaryForm(buffer, 0);
return buffer;

LoadSecurity:

SecurityIdentifier LocalAdminGroup = new SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, null);
csd = new CommonSecurityDescriptor(false, false, ControlFlags.DiscretionaryAclPresent, LocalAdminGroup, null, null, dacl);
SetOwner(owner);
AddUsers(users);

SetOwner:

NTAccount acct = new NTAccount(sOwnerLoginName);
sid = (SecurityIdentifier)acct.Translate(typeof(SecurityIdentifier)); 
csd.Owner = sid;

Add Users:

dacl = new DiscretionaryAcl(false,false,100);
foreach (string user in users)
{ 
    NTAccount acct = new NTAccount(user);
    SecurityIdentifier sid = (SecurityIdentifier)acct.Translate(typeof(SecurityIdentifier));
    dacl.AddAccess(AccessControlType.Allow, sid, (int)(FileSystemRights.ReadData | FileSystemRights.ReadAttributes), InheritanceFlags.None, PropagationFlags.None);                       
} 

UPDATE: I have revised my sample to include the code necessary to create and return a security descriptor based on the new .NET Framework 2.0 classes. Check it out here and download the code: http://mossph.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=24456

-John

New Update to the MOSS 2007 C# Managed Protocol Handler (2007.4)

Heads up, I've released an update to my protocol handler sample on CodePlex: http://www.codeplex.com/MOSSPH/Release/ProjectReleases.aspx?ReleaseId=23453

This release includes several fixes and enhancements that makes building a Protocol Handler even easier than before. If you've tried to use the sample and gave up, take a look at the new sample as the new improvements may get you past some of the difficulties you encountered:

• XML based test content source - once compiled and installed this version will actually crawl content! I've created an XML file that is used as a content source (TestData.xml) and this serves as nested containers and items. Learn by example as to where to place what code based on where I've injected the XML specific code. Then turn on tracing and see exactly what a typical output should be. All XML specific code in the ContentEnumerator class is bracketed with #regions, including the usual TODO comments. Play around with the TestData.xml to:
• Add custom properties
• Experiment with the last modified date/time's for incremental crawling.
• Change the content to see modified documents reflected in the search results.
• Note: the content of a pretend document is written locally to a temporary file and that filename is crawled.
• PreserveSig - the interfaces are now decorated with the PreserveSig attribute which eliminates all the kluge around throwing exceptions to return HR codes. All methods which needed to return an HRESULT now do so and the implementer need only consider what HRESULT to return, not HOW to return it. This has the effect of eliminating the annoying error messages in the crawl log.
• IContentEnumerator - it's easier than ever to abstract your custom logic away from the sample. With the introduction of IContentEnumerator the communications between the ProtocolHandler/Accessor class and the ContentEnumerator are more formal, thus allowing you to have multiple ContentEnumerators for different content sources or for experimentation (such as the supplied XML source). Note: the ContentEnumerator class no longer inherits from Uri.
• Support for custom properties - the ContentEnumerator class now exposes a property that can be populated with an array of custom properties for the container or item. There should be no need to create a custom IFilter to chunk the custom properties to the gatherer. I've also cleaned up the existing properties and grouped them together into classes for more readability. The custom properties may also be of a variety of data types.
• More efficient incremental crawling - the accessor now chunks a container's URLs with the date/time using the DIRLINK_WITH_TIME ID. In this way accessors won't even be created by the gatherer if the date is not newer than the last crawl. (see http://msdn.microsoft.com/en-us/library/aa965720.aspx)
• Container URLs now return a date last modified as well, so if the container has not changed its URLs don't need to be emitted.

At this point I think it's pretty solid in terms of functionality and layout, let me know if you have any further suggestions.

Please access the new source using the "Source" tab. I haven't modified any of the documentation, so if you still need that please refer to release 2007.2

Let me know how it goes. Good luck and happy crawling!

 -John

Microsoft Office SharePoint Server 2007 - C# Protocol Handler, moved to CodePlex!

Please take advantage of the rich release, and tracking features of CodePlex.

From this point forward I'll be maintaining the code base there. This change will allow me to respond to questions/bugs/updates much more efficiently and timely.

 -John

Microsoft Office SharePoint Server 2007 - C# Protocol Handler

Do any of these sound familiar?

"Writing a SharePoint Protocol Handler is way to hard!"

"We have no one on staff that is proficient in C++."

"I've found very little documentation on writing a Protocol Handler."

"The BDC doesn't do everything we need."

Well, then you've come to the right place. With this sample code you can write a Microsoft Office SharePoint Server 2007 Protocol Handler in managed code (C#) using the .NET framework. This is not a 'shim' or 'wrapper', it is 100% pure managed code.

Protocol Handlers are COM components (in-proc servers), traditionally written in C++. .NET allows you to create a class library and expose it as a COM component. Therefore it is possible to create a .NET COM component which will be consumed by the SharePoint search engine (Filter Daemon specifically). This sample is an instance of that approach and contains all classes and declarations necessary to build and register a Protocol Handler written in C#.

That's only the beginning. The interfaces used for a protocol handler can be confusing and tedious. I have created an abstraction class (ContentEnumerator) which insulates Protocol Handler communications from the actual work of accessing your content source by exposing simple enumeration interfaces. It should be possible to populate the 'guts' of your Protocol Handler by simply replacing the 'TODO' comments with actual calls to your data source. But if that does not meet your needs you have the freedom to modify any portion of the project - it's your project!

[Update: I've officially moved this to CodePlex. Please pick up the source and documentation there going forward.]

Good luck and happy crawling!

-John

C# Protocol Handler Sample Source Code

If you’re interested in getting the source code to the managed protocol handler discussed in this blog, please download the SharePoint Utility Suite v2.5, it has many tremendously useful tools and the 2.5 version has the C# protocol handler source included. Note, the tools and protocol handler included in this package are for the 2003 version of Windows SharePoint Services and the 2003 version of SharePoint Portal Server.

 

I’m currently working on porting this sample over to the emerging Microsoft Office SharePoint Server 2007. Once I have that working I’ll likely post that source code here.

Creating Security Descriptors for SPS 2003 Managed Protocol Handlers

Are you asking yourself “How do I create a security descriptor for my Managed Protocol Handler?”
Then first – congratulations, you’ve gotten far enough along in your Protocol Handler to worry about security!
Second, don’t worry there’s an easy answer; see my recent article on How to add support for creating Security Descriptors, to your C# Protocol Handler.

Updated Protocol Handler Documentation

I’ve updated the documentation for the protocol handler to correct an error regarding the installation of the content source. Basically, the content source needs to be added via CSInstaller (or custom code of your choice) so that the proper properties are initialized on the content source. The OOB UI doesn’t seem to do that.

 

http://blogs.msdn.com/johnkoz/articles/Managed_Protocol_Handler_Documentation.aspx