AC_AuthCompute

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

AC_PassThrough

AC_AuthCompute

Library
Description
Errors

Parameters
Return Value
See Also

NAME

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` (input)
		The handle that describes the authorization computationmodule used to perform this function.
`BaseAuthorizations` (input)
		A pointer to a CSSM_TUPLEGROUP containing at leastone ACL certificate, specifying the authorization granted to certainroot keys, named entities or combinations thereof. A NULL groupof `BaseAuthorizations` always results in a NULL `AuthorizationResult`.
`Credentials` (input/optional)
		A pointer to a CSSM_TUPLEGROUP containing a groupof certificates, in TUPLE form. The tuple-certificates define thedelegation of authorizations from the `BaseAuthorizations` tothe `Requestors`. If no additional authorization-grantingtuples are provided, then this value is NULL and the `BaseAuthorizations` arethe only source of trusted authorizations used as input to the authorizationcomputation.
`NumberOfRequestors` (input)
		The number of entries in the `Requestors` array.
`Requestors` (input)
		A pointer to a list of requestors that define the"who" portion of the request. The list can be of type CSSM_LIST_TYPE_SEXPR.Typical exhibits include: Public keys Hashes of keys Hashes of other objects offered for proof.
`RequestedAuthorizationPeriod` (input/optional)
		A list defining a validity period or NULL (implying"all time"). This is the "when" portion of the request. If the list is of type CSSM_LIST_TYPE_SEXPR, then the validityinterval is specified as a two-element list containing the values((not-before <date1>)(not-after <date2 >)).Note that each element is a two-element sublist. The <date> isrepresented by an ASCII byte-string, in the format (for example)"1998-11-24_15:06:16" and is assumed to be GMT. Open-ended timeintervals are specified by omitting either of the interval ends.For example, ((not-before 1997-1-1_00:00:0)) specifies all datesand times beginning on January 1, 1997 going forward indefinitely.For programming convenience, when testing for authorization at asingle point in time, the date is represented by a one-element listcontaining (<date>).
`RequestedAuthorization` (input)
		A list defining the "what" portion of the authorizationbeing requested. If the list is of type CSSM_LIST_TYPE_SEXPR, then the listpresents an authorization request in SPKI format. If a specificauthorization is being requested, then this input is a two-elementSEXPR list containing (tag <req>). The valid valuesfor <req> are application-specific. If this isa request to derive all possible authorizations based on the `BaseAuthorizations`, `Credentials`,and `Requestors`, then this input value must bethe two-element list containing (tag (*)). This list correspondsto "all authorizations". With this input, the function tests theprovided ACL and certificates against the `Requestors` (and possibly `RequestedAuthorizationPeriod`)to yield all authorizations for which the provided `Exhibits` qualify.
`AuthorizationResult` (output)
		A CSSM_TUPLEGROUP structure, giving the result ofthe authorization computation. Typically there will be one result,but there could be as many as there are entries in the `BaseAuthorizations`.Each of these results says, in effect: "for this machine, underthis ACL and the provided certificates, relative to the specified `Requestors`,the following authorizations have been deduced". Those authorizationsare available only on the current platform (and possibly only forthe application providing the ACL), and are therefore in the formof an ACL. They are not intended to be used by any other machineor application instance, necessarily, and need to be converted intocertificates signed by some private key available to the callerif they are to be so used.

DESCRIPTION

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

Requestors One or more items that identify the requestor. Theseitems 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 usesthese fields to compare against Subject fieldsof TUPLES but does not interpret them, so it does not need to beaware of these extensions. Requestors, takentogether with RequestedAuthorization and RequestedAuthorizationPeriod,form request tuples of the form "who requests what, when." Requestors canbe public keys that verify some signed request, hashes of objectssubmitted for proof of permission, etc. In general, there will be onlyone Requestor, typically the public key of somekeyholder signing a request or authenticating a connection.

RequestedAuthorization

The authorization against which the Requestors arebeing 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 togrant authorizations to the Requestors.

Kindof Subject Example Requestor

Public key
(public-key(rsa-pkcs1-sha1 (e #03#) (n ##)))

Hashof object, key, template, etc.
(hash md5 #900150983cd24fb0d6963f7d28e17f72#)

The most likely Requestor is a public keythat signs a request. In common practice there will be one Requestorper computation, but it is possible for an ACL or certificate torequire multiple signatures or other forms of identification beforean 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 specificrequest, backed up by specific Requestors

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

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

Requested AuthorizationExample

(httphttp://private.cdsa.hp.com/local-data.html )

(ftpftp://private.cdsa.hp.com/users/cme/private/test.txt write)

Requested AuthorizationPeriod 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 possibleauthorizations from a set of credentials, rather than to verifya specific access request, the inputs should be of the followingform:

RequestedAuthorizationPeriod iseither an empty list or the list "valid", indicating"all time".

RequestedAuthorization is thelist "*", indicating all possible authorizations.

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

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

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

Transfer the certificates to the target environment.

Use the signed certificates as input Credentials tothis function in the target scope/environment.

If the function is successful, check (*AuthorizationResult)->NumCerts todetermine 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 particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_AC_INVALID_BASE_ACLSCSSMERR_AC_INVALID_ENCODINGCSSMERR_AC_INVALID_REQUESTORCSSMERR_AC_INVALID_REQUEST_DESCRIPTORCSSMERR_AC_INVALID_TUPLE_CREDENTIALSCSSMERR_AC_INVALID_VALIDITY_PERIOD