Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

Authorization Computation Interface

Classes of Certificates and Other Credentials

Loren Kohnfelder defined a certificate, in 1978, as a digitally signed data record binding a name to a public key. Since then, other forms of certificate have been defined. We define three categories of data that may be contained in a certificate:

Names
Keys
Permissions (or authorizations, attributes, etc.)

A permission, X, records a keyholder's permission or authority to perform some action on a given resource and potentially also the permission to delegate that permission to others. The key, S, is the means by which the keyholder authenticates himself to the entity doing the verification. The name, N, is some text string that people find useful in referring to the keyholder. These three items of information can be related in pairs. There are credentials of various kinds that express each of these pairs, as shown in Credential Classes.

Figure: Credential Classes

To answer the authorization question:

: "Is S allowed to do X?"

we need the relation found on the base of the triangle. That is, we need the permission, X, to be associated with a key, S. The permission speaks to the question being asked and the key is the mechanism by which a remote entity is verified. There are two ways to connect S and X, shown in Credential Classes as arrows: (1) directly, and (2) via names.

Direct Authorization

Direct authorization is a mechanism found in a few credential types. There are both ACL and certificate forms for these credentials, depending on whether the credential is retained in a trusted memory at the verifier or must be protected from tampering while being held elsewhere, respectively.

Direct authorization (XŽS) is used in the certificate definitions of SPKI, SET, and KeyNote. It is also found in the ACL definitions of SSH, AADS and X9.59. It is also assumed, implicitly, in SSL.

Authorization via Name

When using a name certificate, the permission, X, flows around the top of the triangle shown in Credential Classes through an ACL entry to empower a name, N, and then down an ID certificate to a key, S. This method of operation remains possible.

In the early 1990's, the X9 community defined an attribute certificate, which maps some attribute, X, to a name, N. The X.509 community is now adopting attribute certificates as well. With an attribute certificate, the permission flow is XŽNŽS. This means there are two certificates to be validated, not just one.

Credential Format Options

For each of the three sides in the triangle shown in Credential Classes, it is possible to define both ACL and certificate mechanisms. An ACL differs from a certificate, in that it is not digitally signed and has no issuer.

In general, the data items useful in building credentials are (see Credential Classes):

I: Issuer - the signer of a certificate
N: Name - the name assigned by the issuer to a keyholder, when that name is being defined in the credential, rather than used as a subject
S: Subject - the subject of the credential: a public key or a name for a public key. Other subjects are possible but need not be considered for the purposes of this specification
D: Delegation - the permission to delegate the permissions contained in the credential
X: Permission - the permission granted by this credential
V: Validity conditions - the conditions under which the credential is valid, typically not-before and not-after dates, but also possibly instructions to perform some on-line test such as a CRL.

Using these data items, different types of credentials can be constructed. Different credential types are fit for different purposes. The following is a non-exhaustive list of useful credential types. The types are defined by the data items they contain <I,N,S,D,X,V>. If a credential does not contain an issuer, then it is assumed that it is an ACL form.

XŽN ACL <-,-,S,D,X,->

This describes a traditional ACL entry. The subject, S, is assumed here to be a name for a key that will be used for authentication or verification. There is no standard for constructing an ACL. In general, ACL formats do not need to be standardized since an ACL is not transmitted between machines. This specification defines a structure for ACL entries so they can be passed across the CDSA interfaces on a single system.

XŽN Attribute Certificate <I,-,S,D,X,V>

This describes an attribute certificate as standardized in the X9 community and now in X.509. There is also an attribute certificate standard under SPKI. In all of these cases, the subject, S, is a name (expected to be the name of some key that will be used in verification).

NŽS ID Certificate <I,N,S,-,-,V>

This describes the standard ID certificate. Examples include:

X.509, and its derivative forms
PGP
SDSI 1.0"
SPKI (after the merger with SDSI)"

XŽS ACL <-,-,S,D,X,->

This describes a direct authorization ACL. Examples include:

SSH, in the file ~/.ssh/authorized_keys
AADS
X9.59
The list of root keys for SSL, maintained in any browser capable of SSL

XŽS Authorization Certificate <I,-,S,D,X,V>

This describes direct authorization certificates. Examples include:

SPKI (as originally designed)
KeyNote
X.509 SSL - in which the permission is implicitly "(*)" - it is not possible to delegate a subset of the permissions.
X.509 SET

The Logic of Authorization

There are two methods for computing an authorization decision:

Direct authorization based on ACLs and certificates
Indirect authorization via names

Direct, Delegated Authorization

An authorization must be made with reference to at least one base authorization, an ACL entry. The ACL serves as an anchor for the authorization. It is required since there is no absolute truth or absolutely powerful public key on which to base a decision. Rather, there are only assumptions, sometimes called executable policies, on the basis of which logical inferences can be made.

All authorizations can be made by ACL, but the resulting ACL might get very large. Alternatively, the ACL can grant delegation permission to a key that can then issue certificates to cover what would have been a large set of ACL entries.

The authorization certificates thus generated may carry implicit or explicit permission. The intermediate form (TUPLE) used in AuthCompute carries explicit permission. If permission is implicit, then it must have been made explicit in translation to TUPLE.

Figure: Logic of Authorization

In the example, the ACL grants three kinds of permission ("X, Y, Z") to public key K1. Each permission is expressed as a list of parameters, each being a byte string or a sublist. Most ACLs grant only a single permission, but multiple permissions are possible.

The ACL states that key K1 has those three permissions plus the permission to delegate them. K1 delegates permissions X and Y to key K2 by issuing a certificate A with those rights to the key K2. In turn, K2 issues a certificate, B, granting permissions W and X to key K3. Permission W is not relevant to this computation, but is shown here to point out that no intermediate issuer can get away with granting extra permissions. The certificate B does not give permission to delegate, therefore certificate B must always be right-most in a chain of certificates. The logical reduction of this chain of certificates is that the verifier (the agent running the access control test and holding the ACL) concludes that it knows that K3 is permitted to do X. Since that is what the condition in Logic of Authorization is testing, this authorization test succeeds.

The authorization computation function CSSM_AC_AuthCompute() provide resource managers with a basic authorization computation enginer for making authorization decisions.

Authorization via Names

An authorization computation can also be performed by traversing path 2 in the triangle. This requires a pair of credentials:

An attribute certificate that binds a permission to a name
An ID certificate that binds a name to a key

This pair can exist as two certificates or as an ACL entry (giving permission to a name) and an ID certificate.

For use in AuthCompute, names are assumed to be fully qualified. That is, they are made globally unique by inclusion of the public key (or its hash) of the namespace that issues the ID certificates defining that name. An example of a fully qualified name is (name K₁ "Fred Jones"), where K₁ is the hash of a public key.

The Authorization Reduction Process

The first step in performing an authorization computation is to replace name references with public keys. This is achieved by applying all name definitions with keys for subjects to all intermediate forms with that name. For example, if there is a TUPLE with a subject of the form (K₁ "Fred Jones") and there is a name certificate TUPLE <K₁, "Fred Jones", K₂, -, -, V>, then that subject is replaced by K₂. The validity date ranges of the two TUPLEs involved are also intersected.

The name reduction process produces authorization 5-tuples, mapping permissions to keys. The reduction rule for combining all of the input credentials is:

: <I1,S1,D1,X1,V1> <I2,S2,D2,X2,V2> Ž <I1,S2,D2,auth_intersect(X1,X2),date_interse ct(V1,V2)>

provided D1=true, S1=I2, and the two intersections are non-empty.

Date intersection is based on comparing not-before and not-after dates and times expressed as ASCII strings of the form 1999-04-24_23:57:39. If the not-before date is greater than the not-after date, then the intersection is empty.

The authorization intersection operation is rigidly defined. The authorizations X and Y are non-empty lists such that the first element is a byte string, called the name or type of the list. The intersection of two lists is computed by pairwise-intersecting each element in the list. List elements can be either byte strings or non-empty sublists. Byte strings intersect only if they are equal. Sublists are intersected by applying the rules for lists to each sublist. If any intersection is empty, then the pair of tuples under consideration can not be reduced. If two lists are of different length but intersect in a non-null set of common elements, then the intersection includes all the elements of the longer list.

Authorization computation based on reductions is defined only when using a set of CSSM_TUPLE structures. Other forms of credentials, such as X.509 certificates, PGP certificates, etc. can be converted to a set of CSSM_TUPLE structures. Translations are performed by using the appropriate Trust Policy service provider and invoking the function CSSM_TP_CertGroupToTupleGroup(). The resulting tuples can be used as input to the AuthCompute service. The inverse translation is provided by the appropriate Trust Policy service provider by invoking the function CSSM_TP_TupleGroupToCertGroup().

Example Authorization Request

Consider a web server that needs to restrict access to its contents. The server would manage one or more ACLs to define the base authorizations of the system. For instance, the server might have an ACL that says that Bob can access all data in the subtree http://www.bob.com/sensitiveData. Furthermore, Bob can delegate this authorization to other users by signing authorization certificates for them. Thus, the base authorization ACL held by the server might look something like this.


 

(
    (subject Key-Bob)
    (propagate)
    (tag (http (* prefix http://www.bob.com/sensitiveData)))
)

Bob delegates his permission to Alice by creating and signing an authorization certificate for her, as follows:


 

(
    (issuer Key-Bob)
    (subject Key-Alice)
    (tag (http (* prefix http://www.bob.com/sensitiveData/forAlice)))
)

Now when Alice wants to access the data on Bob's web server, she submits the certificate that was issued by Bob. The server challenges her to prove who she is by, for example, sending a large random number for her to digitally sign with her private key (matching Key-Alice) and return to the server. The server checks that signature, using Key-Alice, and if the signature is correct, the server knows that the entity making the request has control over the private key for Key-Alice.

The server then calls AuthCompute to determine whether Alice's request to access the data on Bob's web server should be honored. It provides the ACL controlling that resource (the base authorization), the certificates (credentials) Alice provided (if any) and a description of the current request. That description has three parts:

Requestors:
the authentications that were performed - in this case, Key-Alice - in the form of one or more subject fields
RequestedAuthorizationPeriod:
the current time or a time range for which the request is being made
RequestedAuthorization:
the access being desired,
e.g. (http http://www.bob.com/sensitiveData/forAlice/index.html)

The output of AuthCompute will be a set of TUPLEs, giving the intersection of ACL, certificates and requested authorization information, assuming all of the requestors have been authenticated. These TUPLEs are in the form of ACL entries and can be:

Examined to see if it is null - in which case the request was not authorized
Added to the caller's ACL (if not null) so that the caller can make future requests without presenting certificates;
Turned into a certificate and given back to the requesting party, if this one authorization certificate is smaller than the set of certificates originally provided.

Data Structures

CSSM_SPI_AC_FUNCS

This structure defines the function table for all the authorization computation service functions that a service module can return to CSSM. CSSM uses these function pointers to dispatch corresponding application programming interface functions to the service module for processing.


typedef struct cssm_spi_ac_funcs {
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *PassThrough)
        (CSSM_AC_HANDLE ACHandle,
        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DL_DB_LIST *DBList,
        uint32 PassThroughId,
        const void *InputParams,
        void **OutputParams);
} CSSM_SPI_AC_FUNCS, *CSSM_SPI_AC_FUNCS_PTR;

Authorization Computation Operations

The man-page definitions for Authorization Computation operations are presented in this section. Previous section.

Click here to return to the publication details.

NAME

AC_AuthCompute

SYNOPSIS


CSSM_RETURN CSSMAPI AC_AuthCompute
    (CSSM_TP_HANDLE TPHandle,
    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)

DESCRIPTION

This function performs an authorization computation and returns the results as a group of tuple-certificates. The computation is based on five input values:

Requestors - one or more items that identify the requestor. These items are matched against subject fields in the 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 two 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.

EXAMPLE REQUESTED AUTHORIZATIONS
(http http://private.jf.intel.com/local-data.html )
(ftp ftp://private.jf.intel.com/users/cme/private/test.txt write)

EXAMPLE REQUESTED AUTHORIZATION PERIOD
(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 thanto 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(s).
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.

KIND OF SUBJECT	EXAMPLE REQUESTOR
Public key	(public-key (rsa-pkcs1-sha1 (e #03#) (n #^Ĺ#)))
Hash of object, key, template, etc.	(hash md5 #900150983cd24fb0d6963f7d28e17f72#
)

EXAMPLE REQUESTED AUTHORIZATIONS
(http http://private.jf.intel.com/local-data.html )
(ftp ftp://private.jf.intel.com/users/cme/private/test.txt write)

EXAMPLE REQUESTED AUTHORIZATION PERIOD
(valid (not-before "1999-07-28_17:00:44") (not-after "1999-07-28_17:00:44"))

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 of is 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 of is 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.

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

See the corresponding function call definition in Part 2 of this document.

Extensibility Functions

functionality is presented at the end of this chapter. The man-page definition for the Authorization Computation extensibility functionality is presented in this section. Previous section.

NAME

CSSM_AC_PassThrough

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_AC_PassThrough
    (CSSM_AC_HANDLE ACHandle,
    CSSM_TP_HANDLE TPHandle,
    CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DL_DB_LIST *DBList,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

DESCRIPTION

This function allows applications to call authorization computation module-specific operations that have been exported. Such operations may include queries or services specific to the domain represented by the AC module.

PARAMETERS

ACHandle (input)

The handle that describes the authorization computation module used to perform this function.

TPHandle (input/optional)

The handle that describes the trust policy module that can be used by the authorization computation service to implement this function. If no trust policy module is specified, the AC module uses an assumed TP module, if required.

CLHandle (input/optional)

The handle that describes the add-in certificate library module that can be used to manipulate the subject certificate and anchor certificates. If no certificate library module is specified, the AC module uses an assumed CL module, if required.

CCHandle (input/optional)

The handle that describes the cryptographic context containing a handle that describes the add-in cryptographic service provider module that can be used to perform cryptographic operations as required to perform the requested operation. If no cryptographic context is specified, the AC module uses an assumed cryptographic context and CSP module, if required.

DBList (input/optional)

A list of handle pairs specifying a data storage library module and a data store managed by that module. These data stores can contain certificates, CRLs, and policy objects for use by the AC module. If no DL and DB handle pairs are specified, the AC module can use an assumed DL module and an assumed data store for this operation.

PassThroughId (input)

An identifier assigned by the AC module to indicate the exported function to perform.

InputParams (input)

A pointer to a module, implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested AC module. If the passthrough function requires access to a private key located in the CSP referenced by CSPHandle, then InputParams should contain a passphrase, or a callback or cryptographic context that can be used to obtain the passphrase.

OutputParams (output/optional)

A pointer to a module, implementation-specific structure containing the output data. The service provider will allocate the memory for this structure. The application must free the memory for the structure.

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

See the corresponding section in Part2 of this document.

Contents

Next section

Index

Authorization Computation Interface

Classes of Certificates and Other Credentials

Direct Authorization

Authorization via Name

Credential Format Options

XŽN ACL <-,-,S,D,X,->

XŽN Attribute Certificate <I,-,S,D,X,V>

NŽS ID Certificate <I,N,S,-,-,V>

XŽS ACL <-,-,S,D,X,->

XŽS Authorization Certificate <I,-,S,D,X,V>

The Logic of Authorization

Direct, Delegated Authorization

Authorization via Names

The Authorization Reduction Process

Example Authorization Request

Data Structures

CSSM_SPI_AC_FUNCS

Authorization Computation Operations

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

Extensibility Functions

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS