Implementing Security

The levels of security that you may provide for your gateway are identified in the following table:

 


Security Level

Description

SECURE

Access requires authentication of users’ credentials.

ANONYMOUS

Authentication does not require credentials.

PUBLIC

Access does not require authentication.


Typically, you implement security with certificates that identify a user and an access control list (ACL) that identifies who is able to access specific documents. Your gateway driver creates a certificate for the user, whose information is compared with the ACL for a document.

A field in your repository contains the ACL for a document. This field is typically set up independently of your gateway driver; for example, the ACL for a document may be defined when the document is inserted into the repository.

The following sections describe the granularity of security that you can provide:

Repository-Level Security

 

Document-Level Security

 

Field-Level Security

 

Repository-Level Security

Repository-level security is implemented by your gateway driver’s VgwAuthenticateFnc function, which collects the user’s credentials and, if valid, creates a certificate of the specified type. The certificate is persistent and can be used across driver sessions.

The certificate contains the following information:

Security module ID, which is 0 if the repository is public. (For information about security modules, see The GDK Library).

 

Repository ID, which you define.

 

Certificate state, which identifies whether the certificate is currently valid, whether the user is anonymous, and so on.

 

Repository-defined data, which contains information required about the security module and information about the user.

 

The access rights information, such as groups or roles, is typically stored in the repository-defined data. It is this information in the certificate that is compared against the ACL for a document when checking document-level security. For the specific components of a certificate, see VSecCertificateRec Members.

Document-Level Security

Document-level security is the kind of security that enables authorized users to access specific documents; for example, if your repository contained human resources information, document-level security can control those whom you wish to provide access.

Your gateway driver’s VgwDocFieldReadFnc function retrieves a field that contains the access control list (ACL) for a document. This field could be stored as an internal field in a collection when the repository’s documents are indexed, improving the performance of searches. For an example, see Type Parameter File.

You must implement document-level security in both your gateway driver’s VgwStreamNew and VgwDocFieldReadFnc functions. One possible implementation would be for those functions to call your gateway driver’s VgwDocExist function or some similar function that encapsulates your gateway driver’s access-control rules.

Field-Level Security

Field-level security is the kind of security that enables authorized users to access specific fields or specific values or ranges of values. For example, if your repository contains human resources information, such as “offer” letters that propose an employment agreement in which the salary was an external field, you could restrict access to the salary field; or you could restrict access to values above a certain amount. You implement field-level security in your gateway driver’s VgwDocFieldReadFnc function; for example, you could restrict the fields that are retrieved when the Verity engine calls this function.

The GDK Library

The GDK Library provides transparent access to a Verity security module. It contains functions that allow you to set up and access the gateway driver’s security module. You call the GdkHandleNew function to create a handle with which to reference the gateway driver’s security module; this module links in the security functions described in Security Interface. You specify whether your gateway is public when you call the GdkHandleNew function.