AC_AuthCompute(3)AC_AuthCompute(3)NAMEAC_AuthCompute - Compute authorization (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMACI CSSM_AC_AuthCompute (CSSM_AC_HANDLE ACHandle,
const CSSM_TUPLEGROUP *BaseAuthorizations, const CSSM_TUPLEGROUP *Cre‐
dentials, uint32 NumberOfRequestors, const CSSM_LIST *Requestors, const
CSSM_LIST *RequestedAuthorizationPeriod, const CSSM_LIST *RequestedAu‐
thorization, CSSM_TUPLEGROUP_PTR AuthorizationResult)
SPI: CSSM_RETURN CSSMACI AC_AuthCompute (CSSM_AC_HANDLE ACHandle, const
CSSM_TUPLEGROUP *BaseAuthorizations, const CSSM_TUPLEGROUP *Creden‐
tials, uint32 NumberOfRequestors, const CSSM_LIST *Requestors, const
CSSM_LIST *RequestedAuthorizationPeriod, const CSSM_LIST *RequestedAu‐
thorization, CSSM_TUPLEGROUP_PTR AuthorizationResult)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The handle that describes the authorization computation module used to
perform this function. A pointer to a CSSM_TUPLEGROUP containing at
least one ACL certificate, specifying the authorization granted to cer‐
tain root keys, named entities or combinations thereof. A NULL group of
BaseAuthorizations always results in a NULL AuthorizationResult. A
pointer to a CSSM_TUPLEGROUP containing a group of certificates, in
TUPLE form. The tuple-certificates define the delegation of authoriza‐
tions 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. The number of entries
in the Requestors array. 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. A list defining a
validity period or NULL (implying "all time"). This is the "when" por‐
tion 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 val‐
ues ((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 indefi‐
nitely. For programming convenience, when testing for autho‐
rization at a single point in time, the date is represented by a
one-element list containing (<date>). 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-ele‐
ment 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 possi‐
bly RequestedAuthorizationPeriod) to yield all authorizations
for which the provided Exhibits qualify. 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 autho‐
rizations are available only on the current platform (and possi‐
bly only for the application providing the ACL), and are there‐
fore 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.
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: One or more items that identify the
requestor. These items are matched against subject fields in BaseAutho‐
rizations or Credentials. These will be of any form that occurs in an
ACL or certificate, and the class of entries is extensible. AuthCom‐
pute 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.
The authorization against which the Requestors are being tested in this
computation. The time range of an authorization computation. The
group of ACL entries (unsigned certificates) provided as the basis for
this computation. A group of tuple-certificates used with the BaseAu‐
thorizations to grant authorizations to the Requestors.
──────────────────────────────────────────────────────────────────
Kind of Subject Example Requestor
──────────────────────────────────────────────────────────────────
Public key (public-key (rsa-pkcs1-sha1 (e #03#) (n ##)))
Hash of object, (hash md5 #900150983cd24fb0d6963f7d28e17f72#)
key, template,
etc.
──────────────────────────────────────────────────────────────────
The most likely Requestor is a public key that signs a request. In com‐
mon 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 BaseAutho‐
rizations and Credentials.
When using this function to verify an authorization, the RequestedAu‐
thorization 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 authoriza‐
tions 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, rel‐
ative 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: Convert the ACL into one or more certifi‐
cates. The certificates must be signed by some private key with appro‐
priate authority in the target scope/environment. Transfer the cer‐
tificates to the target environment. 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 com‐
putation. 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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_AC_INVALID_BASE_ACLS CSSMERR_AC_INVALID_ENCOD‐
ING 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_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_TP_CertGroupToTupleGroup(3), CSSM_TP_TupleGroupToCertGroup(3)
Functions for the AC SPI:
TP_CertGroupToTupleGroup(3), TP_TupleGroupToCertGroup(3)AC_AuthCompute(3)