AC_AuthCompute - Compute authorization (CDSA)

 SYNOPSIS

   # include <cssm.h>

     API:
        CSSM_RETURN CSSMACI CSSM_AC_AuthCompute
        (CSSM_AC_HANDLE ACHandle,
        const CSSM_TUPLEGROUP *BaseAuthorizations,
        const CSSM_TUPLEGROUP *Credentials,
        uint32 NumberOfRequestors,
        const CSSM_LIST *Requestors,
        const CSSM_LIST *RequestedAuthorizationPeriod,
        const CSSM_LIST *RequestedAuthorization,
        CSSM_TUPLEGROUP_PTR AuthorizationResult)

     SPI:
        CSSM_RETURN CSSMACI AC_AuthCompute
        (CSSM_AC_HANDLE ACHandle,
        const CSSM_TUPLEGROUP *BaseAuthorizations,
        const CSSM_TUPLEGROUP *Credentials,
        uint32 NumberOfRequestors,
        const CSSM_LIST *Requestors,
        const CSSM_LIST *RequestedAuthorizationPeriod,
        const CSSM_LIST *RequestedAuthorization,
        CSSM_TUPLEGROUP_PTR AuthorizationResult)

 LIBRARY

   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS

   ACHandle, BaseAuthorizations, Credentials, NumberOfRequestors,
   Requestors, RequestedAuthorizationPeriod, RequestedAuthorization,
   AuthorizationResult

 DESCRIPTION

   This function performs an authorization computation and returns the
   results as a group of tuple certificates. The computation is based on
   the following input values:

   Requestors

           One or more items that identify the requestor. These
           items are matched against subject fields in
           BaseAuthorizations or Credentials.  These will be of
           any form that occurs in an ACL or certificate, and the
           class of entries is extensible.  AuthCompute uses these
           fields to compare against Subject fields of TUPLES but
           does not interpret them, so it does not need to be
           aware of these extensions.  Requestors, taken together
           with RequestedAuthorization and
           RequestedAuthorizationPeriod, form request tuples of
           the form "who requests what, when." Requestors can be
           public keys that verify some signed request, hashes of
           objects submitted for proof of permission, etc. In
           general, there will be only one Requestor, typically
           the public key of some keyholder signing a request or
           authenticating a connection.

   RequestedAuthorization
           The authorization against which the Requestors are
           being tested in this computation.

   RequestedAuthorizationPeriod
           The time range of an authorization computation.

   BaseAuthorizations
           The group of ACL entries (unsigned certificates) provided as the
           basis for this computation.

   Credentials
           A group of tuple-certificates used with the
           BaseAuthorizations to grant authorizations to the Requestors.

           ___________________________________________________________
           Kind of Subject  Example Requestor
           ___________________________________________________________
           Public key    (public-key (rsa-pkcs1-sha1 (e #03#) (n ##)))
                         (hash md5 #900150983cd24fb0d6963f7d28e17f72#)

           Hash of object,
           key, template,
           etc.
           ___________________________________________________________

   The most likely Requestor is a public key that signs a request.
   In common practice there will be one Requestor per computation,
   but it is possible for an ACL or certificate to require
   multiple signatures or other forms of identification before an
   action is authorized. In that case, there must be multiple
   Requestors. This function can be used in the following modes:

     ·  To verify the authorization of a specific request, backed up by
        specific Requestors

     ·  To compute the set of authorizations that a particular set of
        Requestors has been granted by the BaseAuthorizations and
        Credentials.

   When using this function to verify an authorization, the
   RequestedAuthorization is the specific authorization being
   requested and the RequestedAuthorizationPeriod gives the date
   and time of that request (typically the current date and time)
   using both NOT_BEFORE and NOT_AFTER dates. The result, if any,
   should be an ACL entry with the same authorization that was
   requested. If such an ACL entry is produced by the computation,
   then the request is authorized.

   Requested Authorization Example
   (http http://private.cdsa.hp.com/local-data.html )
   (ftp ftp://private.cdsa.hp.com/users/cme/private/test.txt write)
   Requested Authorization Period Example

   (valid (not-before "1999-07-28_17:00:44") (not-after "1999-07-
   28_17:00:44"))

   When using this function to compute the full set of possible
   authorizations from a set of credentials, rather than to verify a
   specific access request, the inputs should be of the following form:

     ·  RequestedAuthorizationPeriod is either an empty list or the list
        "valid", indicating "all time".

     ·  RequestedAuthorization is the list "*", indicating all possible
        authorizations.

   The result of this computation, if any, will be one or more ACL entries
   representing all the granted authorizations for the indicated requestor.

   The scope of ACLs output from this function is limited to the local
   system.  Each ACL should be interpreted to mean: "for this machine,
   under these base authorization ACLs and the provided certificates,
   relative to the specified requestors, the following authorizations have
   been deduced". Those authorizations are available only on the current
   platform (and possibly only for the application providing the ACL) and
   are therefore in the form of an ACL. They are not intended to be used by
   any other machine or application instance. However, the resulting ACLs
   can be transferred and used outside of the local scope by an entity with
   authority in the target scope/environment. The transfer and use is a
   three-step process:

    1.  Convert the ACL into one or more certificates. The certificates
        must be signed by some private key with appropriate authority
        in the target scope/environment.

    2.  Transfer the certificates to the target environment.

    3.  Use the signed certificates as input Credentials to this
        function in the target scope/environment.

   If the function is successful, check (*AuthorizationResult)->NumCerts
   to determine the precise number of authorizations granted by this
   computation.  If 0, then the requestors were not authorized.

 RETURN VALUE

   A CSSM_RETURN value indicating success or specifying a
   particular error condition. The value CSSM_OK indicates
   success. All other values represent an error condition.

 ERRORS

   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_AC_INVALID_BASE_ACLS
        CSSMERR_AC_INVALID_ENCODING
        CSSMERR_AC_INVALID_REQUESTOR
        CSSMERR_AC_INVALID_REQUEST_DESCRIPTOR
        CSSMERR_AC_INVALID_TUPLE_CREDENTIALS
        CSSMERR_AC_INVALID_VALIDITY_PERIOD

 SEE ALSO

   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_TP_CertGroupToTupleGroup
       CSSM_TP_TupleGroupToCertGroup

   Functions for the AC SPI:

       TP_CertGroupToTupleGroup
       TP_TupleGroupToCertGroup