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
1 – ACHandle
(input)
The handle that describes the authorization computation module
used to perform this function.
2 – BaseAuthorizations
(input)
A pointer to a CSSM_TUPLEGROUP containing at least one ACL
certificate, specifying the authorization granted to certain
root keys, named entities or combinations thereof. A NULL group
of BaseAuthorizations always results in a NULL
AuthorizationResult.
3 – Credentials
(input/optional)
A pointer to a CSSM_TUPLEGROUP containing a group of
certificates, in TUPLE form. The tuple-certificates define
the delegation of authorizations from the BaseAuthorizations
to the Requestors. If no additional authorization-granting
tuples are provided, then this value is NULL and the
BaseAuthorizations are the only source of trusted
authorizations used as input to the authorization computation.
4 – NumberOfRequestors
(input)
The number of entries in the Requestors array.
5 – 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.
6 – 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 validity
interval 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> is represented
by an ASCII byte-string, in the format (for example)
"1998-11-24_15:06:16" and is assumed to be GMT. Open-ended time
intervals are specified by omitting either of the interval ends.
For example, ((not-before 1997-1-1_00:00:0)) specifies all dates
and times beginning on January 1, 1997 going forward
indefinitely. For programming convenience, when testing for
authorization at a single point in time, the date is represented
by a one-element list containing (<date>).
7 – RequestedAuthorization
(input)
A list defining the "what" portion of the authorization being
requested.
If the list is of type CSSM_LIST_TYPE_SEXPR, then the list
presents an authorization request in SPKI format. If a
specific authorization is being requested, then this input is
a two-element SEXPR list containing (tag <req>). The valid
values for <req> are application-specific. If this is a request
to derive all possible authorizations based on the
BaseAuthorizations, Credentials, and Requestors, then this
input value must be the two-element list containing (tag (*)).
This list corresponds to "all authorizations". With this input,
the function tests the provided ACL and certificates against
the Requestors (and possibly RequestedAuthorizationPeriod) to
yield all authorizations for which the provided Exhibits
qualify.
8 – AuthorizationResult
(output)
A CSSM_TUPLEGROUP structure, giving the result of the
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, under this ACL 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, necessarily, and need to be
converted into certificates signed by some private key
available to the caller if they are to be so used.