GAA API functions

The gaa_get_object_policy_info function is called to obtain the security policy associated with the object.

• Input:
  • Reference to the object to be accessed. The identifier for the object is from an application-dependent name space, it can be represented as unique object identifier, or symbolic name local to the application.
  • Pointer to application specific Authorization Database.
  • Upcall function for the retrieval of the object policy. The application maintains authorization information in a form understood by the application. It can be stored in a file, database, directory service or in some other way. The upcall function provided for the GAA API retrieves this information and translates it into the internal representation understood by the GAA API.
• Output:
  • Object policy handle

The gaa_check_authorization function tells the application server whether the requested operations are authorized, or if additional application-specific checks are required.

• Input:
  • Object policy handle, returned by gaa_get_object_policy_info
  • Principal's security context (see section 3.5.1)
  • Operations for authorization. This argument indicates requested operations.
• Output:
  • YES (indicating authorization) is returned if all requested operations are authorized.
  • NO (indicating denial of authorization) is returned if at least one operation is not authorized.
  • MAYBE (indicating a need for application-specific checks) is returned if there are some unevaluated conditions and additional application-specific checks are needed, or if continuous evaluation of conditions is required.
  • detailed answer contains:
    • Authorization valid time period. The time period during which the authorization is granted is returned as condition to be checked by the application. Expiration time is calculated by the GAA API, based on:
      1. Time-related conditions in the object policy, e.g. EACL matching entries.
      2. Restrictions in the authentication and authorization credentials.
    • The requested operations are returned marked as granted or denied along with a list of corresponding conditions, if any. Each condition is marked as evaluated or not evaluated, and if evaluated marked as met, not met or further evaluation or enforcement is required. This tells application which policies must be enforced.
    • Information about additional security attributes required. Additional credentials might be required from clients to perform certain operations, e.g. group membership or delegated credentials.
• gaa_inquire_object_policy_info

  This function allows the application to discover access control policies associated with the targeted object applied to a particular principal. It returns a list of rights that the principal is authorized for and corresponding conditions, if any. The application must understand the conditions that are returned unevaluated, or it must reject the request. If understood, the application checks the conditions against information about the request, the target object, or environmental conditions to determine whether the conditions are met. Actual enforcement of policies expressed through conditions is the responsibility of the application and is outside of the scope of this paper.