|
|
AC_AuthCompute(3)
Contents |
AC_AuthCompute - Compute authorization (CDSA)
# include <cdsa/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)
Common Security Services Manager library (libcssm.so)
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 certain 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 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. 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" 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>). 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 twoelement
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.
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.
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 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.
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
BaseAuthorizations 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 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: 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. Transfer the certificates
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 computation. If 0, then the
requestors were not authorized.
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 are described in the CDSA technical standard. See
CDSA_intro(3). 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
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
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)
[ Back ] |
