 |
Index for
Section 3 |
|
 |
Alphabetical
listing for A |
|
 |
Bottom of
page |
|
AC_AuthCompute(3)
NAME
AC_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 *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 (libcssm.so)
PARAMETERS
ACHandle (input)
The handle that describes the authorization computation module used
to perform this function.
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.
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.
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 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>).
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.
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.
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_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
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for A |
|
 |
Top of
page |
|