Document Level Security Fields

Chapter 9-4

Document-Level Security Fields

Introduction

This chapter explains how HCL C API programs for Domino and Notes can append document-level security fields to documents. It examines the sample program AUTH_FLD, which demonstrates how to append document-level security fields. The program appends items with data types Names, Author Names, and Reader Names.

Document-Level Security Fields

HCL Domino provides several levels of security in documents. Document-level security does not override the access control list; it only refines it.

Editor access control over a document is supported via a field of type Author Names. A document may store a list of names (user names, group names, and access roles) to whom Domino will grant editor access.

Any document that contains an Author Names type field also contains an internal field called $UpdatedBy, of type Names. This field stores a list of all the document's editors.

Reader access control over a document is supported via a field of type Reader Names. A document may store a list of names (user names, group names, and access roles) to whom Domino will grant reader access.


Data Type: Names

In the Notes user interface, when you compose a document using a form with a field of type Names, the result is an item of TYPE_TEXT (or TYPE_TEXT_LIST) with the NAMES flag set. The NAMES flag is the distinguished names flag. At the C API level, the NAMES flag corresponds to the ITEM_NAMES bit in the item flags.

The NAMES flag itself does not make the field a document-level security field. Instead it tells Domino or Notes that this field normally contains distinguished (hierarchical) names. The Notes editor simplifies these otherwise long names to display them. The simpler version of distinguished names is known as the "abbreviated" distinguished name. However, internally, Domino and Notes still stores these values in unabbreviated format.


Data Type: Author Names

When you compose a document using a form with a field of type Author Names, the internal (C API level) result is an item of TYPE_TEXT (or TYPE_TEXT_LIST) with both the NAMES flag and the READ/WRITE-ACCESS flag set. As with other text fields, the SUMMARY flag is also set. The READ/WRITE-ACCESS flag corresponds to the ITEM_READWRITERS bit in the item flags.

The READ/WRITE-ACCESS flag tells Domino that this is an Author Names type field.

Domino takes several actions in response to this field. First, it grants editor access to the entities named in the field. Since this new author field is TYPE_TEXT or TYPE_TEXT_LIST, it may contain multiple names, which may be user names, group names, or access roles.

Second, Domino and Notes automatically appends the special field $UpdatedBy to any document that has an Author Name type field. $UpdatedBy is a TEXT_LIST field that tracks all the users who created or modified a document. This preserves the functionality of the Document Author type field of earlier versions of Notes. Note that $UpdatedBy has the NAMES flag set. The @Author function returns the contents of the $UpdatedBy field.

In Notes 1.x and Notes 2.x, the Document Author field data type corresponded to items of type TYPE_USERID in the C API. Notes 3.x and later does not append items of type TYPE_USERID to documents. However, Notes 3.x and later recognizes items of type TYPE_USERID in documents. It treats such items as Notes 1.x/2.x Document Author type fields.


Data Type: Reader Names

HCL Domino and Notes also provide the field data type Reader Names. Domino grants reader access to entities named in a field of type Reader Names. Internally, fields of this type are TYPE_TEXT or TYPE_TEXT_LIST items with the SUMMARY, NAMES, and READ-ACCESS flags set. At the C API level, the READ-ACCESS flag corresponds to the ITEM_READERS bit in the item flags.


Writing Names Fields

Store distinguished names in fields with external data type Names. The Notes editor will display such fields in abbreviated format.

The special $UpdatedBy field is an example of a field with external data type Names. Domino and Notes maintains a list of the distinguished names of each user who created or modified the document in the $UpdatedBy field.

The sample program AUTH_FLD contains a subroutine, AppendUpdatedByItem, that appends an $UpdatedBy item to an open note. At the C API level the item has TYPE_TEXT or TYPE_TEXT_LIST with the ITEM_NAMES flag set. Since the C API function NSFItemSetText does not set the ITEM_NAMES flag, AppendUpdatedByItem, shown below, uses NSFItemAppend.

auth_fld.c - Writing Names Fields

/**********

    FUNCTION:   AppendUpdatedByItem

**********/

STATUS LNPUBLIC AppendUpdatedByItem (NOTEHANDLE hNote, char * szAuthor)
{
   STATUS  error;

    if (error = NSFItemAppend ( hNote,
                               ITEM_SUMMARY | ITEM_NAMES,
                               DISCUSS_ITEM_UPDATEDBY,  / "$UpdatedBy" */
                               (WORD) strlen(DISCUSS_ITEM_UPDATEDBY),
                               TYPE_TEXT,
                               szAuthor,
                               strlen(szAuthor)))
   {
       printf ("Error: unable to append $UpdatedBy field.\n");
   }
   return (error);
}


Writing Author Names Fields

Fields of external data type Author Names are stored as items of TYPE_TEXT or TYPE_TEXT_LIST with both the NAMES flag (ITEM_NAMES) and the READ/WRITE-ACCESS flag (ITEM_READWRITERS) set.

The sample program AUTH_FLD contains a subroutine, AppendAuthorItem, that appends an Author Names type item to an open note. At the C API level the item has TYPE_TEXT or TYPE_TEXT_LIST with the ITEM_NAMES flag and the ITEM_READWRITERS flag set. Since the C API function NSFItemSetText does not set the proper flag, AppendAuthorItem, shown below, uses NSFItemAppend.

auth_fld.c - Writing Author Names Fields

/**********
                                                                       
   FUNCTION:  AppendAuthorItem

    PURPOSE:   Append item named "Author" to the open note.
   
   DESCRIPTION:

    To mimic the behavior of the Notes 3.x and later data type "Author Names",
   this appends the item using TYPE_TEXT and sets the item flags
   ITEM_SUMMARY, ITEM_READWRITERS, and ITEM_NAMES. This requires use
   of NSFItemAppend rather than NSFItemSetText.
                                                                       
**********/

STATUS  LNPUBLIC  AppendAuthorItem (NOTEHANDLE  hNote, char * szAuthor)
{
   STATUS  error;

    if (error = NSFItemAppend ( hNote,
                               ITEM_SUMMARY | ITEM_READWRITERS | ITEM_NAMES,
                               DISCUSS_ITEM_AUTHOR,  / "Author" */
                               (WORD) strlen(DISCUSS_ITEM_AUTHOR),
                               TYPE_TEXT,
                               szAuthor,
                               strlen(szAuthor)))
   {
       printf ("Error: unable to append Author field.\n");
   }
   return (error);
}


Writing Reader Names Fields

Fields with external data type Reader Names are stored as items of TYPE_TEXT or TYPE_TEXT_LIST with both the NAMES flag (ITEM_NAMES) and the READ-ACCESS flag (ITEM_READERS) set.

The sample program AUTH_FLD contains a subroutine, AppendReadersItem, that creates an item named "Readers," containing two names, and appends it to an open note. The item has external data type Reader Names. At the C API level the item is of TYPE_TEXT_LIST with the ITEM_NAMES flag and the ITEM_READERS flag set. Since the C API function NSFItemSetText does not set the proper flag, AppendReadersItem, shown below, uses NSFItemAppend.

auth_fld.c - Writing Reader Names Fields

/**********
                                                                       
   FUNCTION:   AppendReadersItem

    PURPOSE:    Create and append the Readers item to the note.
                                                                       
**********/

STATUS  LNPUBLIC  AppendReadersItem (NOTEHANDLE  hNote)
{
   STATUS      error = NOERROR;
   DWORD       dwValueLen;
   void far   pvoidItemValue;
   LIST       pList;
   USHORT     pusLength;
   USHORT      usLen1, usLen2;
   char       pchStr;

    usLen1 = strlen(READERS1);
   usLen2 = strlen(READERS2);

    dwValueLen = sizeof(LIST) + (READERS_COUNT * sizeof(USHORT)) +
                usLen1 + usLen2 ;

    pvoidItemValue = (void far ) malloc ((size_t)dwValueLen);
   if (pvoidItemValue == NULL)
   {
       printf ("Error: unable to allocate %lu bytes memory.\n", dwValueLen);
       return(ERR_AUTH_FLD_MALLOC);
   }

    pList = (LIST)pvoidItemValue;
   pList->ListEntries = READERS_COUNT;
   pList++;
   pusLength = (USHORT)pList;
   pusLength = usLen1;
   pusLength++;
   pusLength = usLen2;
   pusLength++;
   pchStr = (char)pusLength;
   memcpy (pchStr, READERS1, usLen1);
   pchStr += usLen1;
   memcpy (pchStr, READERS2, usLen2);

    if (error = NSFItemAppend ( hNote,
                               ITEM_SUMMARY | ITEM_READERS | ITEM_NAMES,
                               DISCUSS_ITEM_READERS,  / "Readers" */
                               (WORD) strlen(DISCUSS_ITEM_READERS),
                               TYPE_TEXT_LIST,
                               pvoidItemValue,
                               dwValueLen))
   {
       printf ("Error: unable to append Readers field.\n");
   }
   free (pvoidItemValue);
   return (error);
}

---