 |
HP Open Source Security for OpenVMS Volume 1: Common Data Security Architecture > CDSA API Functions
AC_AuthCompute
NAMEAC_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) |
LIBRARYCommon Security Services Manager library (cdsa$incssm300_shr.exe) 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: 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. |
DESCRIPTIONThis 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
of object, key, template, etc. | (hash md5 #900150983cd24fb0d6963f7d28e17f72#) |
|
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. RETURN VALUEA CSSM_RETURN value indicating success or specifying a particular
error condition. The value CSSM_OK indicates success. All other
values represent an error condition. ERRORSErrors are described in the CDSA Technical Standard. 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 ALSOBooksIntel CDSA Application Developer's Guide Reference PagesFunctions for the CSSM API: CSSM_TP_CertGroupToTupleGroup, CSSM_TP_TupleGroupToCertGroup Functions for the AC SPI: TP_CertGroupToTupleGroup, TP_TupleGroupToCertGroup |
|
