Parameter Passing Conventions

The format and conventions are freely borrowed from The Open Group XDAS specifications.

Structured Data Types

String Data and Similar Data

Buffers

 

typedef struct
azn_buffer_desc_struct {
    size_t  length; 
    void    *value; 
} azn_buffer_desc, *azn_buffer_t;

Storage for buffer azn_buffer_desc objects is always allocated and released by the application. Newly created azn_buffer_desc objects may be initialized to the value AZN_C_EMPTY_BUFFER.

azn_buffer_t objects appear as "out" parameters in the azn_attrlist_get_entry_buffer_value() and azn_creds_get_pac() calls. In these cases, storage for the buffer array referred to by the value member of an azn_buffer_desc object is allocated by the aznAPI implementation. Buffer storage which is allocated by the aznAPI implementation must be freed (when it is no longer needed) by the application calling the aznAPI, using the azn_release_buffer() routine.

Character Strings

 

typedef char *azn_string_t;

This is a string data type designed to implement string-encoded tokens to identify capabilities, permissions and similar authorization concepts in an implementation independent portable format.

A "\0"-terminated UTF-8 character array is used for the string representation.

Credential Handles

 

azn_creds_h_t

A variable of type azn_creds_h_t is an opaque handle which refers to an implementation-specific credentials chain structure.

Before an application can use a credential handle, it must initialize the handle by calling azn_creds_create(), which allocates a new, empty credentials chain structure, associates it with a handle, and returns the handle.

When an application no longer needs a credentials chain structure, the application must release the credentials chain structure by calling azn_creds_delete() on its handle.

Attribute List Handle

 

azn_attrlist_h_t

A variable of type azn_attrlist_h_t is an opaque handle which refers to a list of name-value pairs maintained by the aznAPI implementation. The aznAPI provides interfaces for retrieving name-value pairs from attribute lists referred to by attribute list handles.

Before an application can use an attribute list handle, the application must initialize the handle by calling azn_attrlist_create(), which allocates a new, empty attribute list structure, associates it with a handle, and returns the handle.

When an application no longer needs an attribute list, the application must release the attribute list by calling azn_attrlist_delete() on its handle.

Status Values

 

azn_status_t

aznAPI implementations should implement azn_status_t using a type that can be cast to integer, because, in keeping with normal C language conditional test conventions, successful completion of an AZN-routine always results in a return value that equates to AZN_S_COMPLETE (0).

Encapsulated in the returned status code are major and minor error codes. The major error codes are defined in the standard and are implementation independent. The minor error codes are implementation dependent, and their values and meanings should be recorded in the implementation documentation.

Two functions are defined to extract the major and minor codes from the returned status: azn_error_major() and azn_error_minor().

The major error codes returned by azn_error_major() re listed in Major Error Codes.

Invalid Handle Error Status Returns

aznAPI implementations are not required to be able to detect invalid handles, but should return an invalid handle major status code whenever they are able to detect that an input handle argument is not valid.

aznAPI functions which release data referred to by handles have been designed in a way which permits implementations to set the handles to invalid values to facilitate detection of later invalid uses of handles which refer to structures which have previously been released.

Constants

The tables in this section enumerate the constants defined by the specification, and the values which those constants must be defined to have.

The azn_decision* functions return a signed integer permission argument. Legal values of that argument are shown in Permission Constants.

Name	Value	Meaning
[AZN_C_PERMITTED]	0	Operation by credentials chain holder is permitted.
[AZN_C_NOT_PERMITTED]	1	Operation by credentials chain holder is not permitted.

Parameters of the type azn_buffer_t can be assigned and compared with the constant values shown in Optional Parameter Constants.

Name	Value	Meaning
[AZN_C_EMPTY_BUFFER]	NULL	Empty data value-buffer.
[AZN_C_NO_BUFFER]	NULL	No value-buffer is supplied or returned.

A number of names have been defined in Attribute Name Constants for essential access control attributes, to ensure that applications can submit and/or request this information through the azn-interface in a portable way.

A credential handle refers to a credentials chain consisting of the credentials of the initiator and a series of (zero or more) intermediaries through which the initiator's request has passed.

aznAPI implementations must ensure that the credential at the first index in a credentials chain is the credential of the initiator of the request. The constant [AZN_C_INITIATOR_INDEX] can be used in the azn_creds_get_attrlist_for_subject() and azn_creds_for_subject() to refer to the initiator's credential.

The azn_creds_get_attrlist_for_subject() function allows aznAPI callers to retrieve attributes from a credential, but this specification does not define the complete set of attributes which may appear in a credential.

The only attribute which must be supported by an aznAPI implementation is an audit identifier. This attribute allows aznAPI callers to generate audit records which refer to the initiator of a request without violating privacy by placing personal identification information in the audit log. The initiator's audit ID can be obtained by retrieving the string value for the entry whose name attribute is specified by the constant [AZN_C_AUDIT_ID] from the attribute list returned by azn_creds_get_attrlist_for_subject(). Note (as Trust Relationships in an aznAPI System illustrates) that aznAPI callers are inside the Trusted Computing Base of the system, and are responsible for proper handling of audit ID information. Specifically, callers of the aznAPI must ensure that they do not reveal audit IDs to any application outside the system's TCB.

Several aznAPI functions accept context ACI as a parameter. Almost any kind of information could be used as context ACI, so the context ACI argument type in these functions is an attribute list. However, four types of context ACI are common to many authorization service implementations and are explicitly called for in the ISO 10181-3 specification, so portable attribute names and corresponding attribute value types have been defined to allow implementations to pass these context parameters to implementations.

[AZN_C_REQUEST_TIME], [AZN_C_AUTHN_QUALITY], [AZN_C_REQUESTER_LOC], and [AZN_C_REQUEST_ROUTE_QOP] can be used as the name attributes of attribute list entries carrying the values of these common types of context information.

Name	Value	Meaning
[AZN_C_INITIATOR_INDEX]	0	An integer representing the initiator's subject index within the credentials chain.
[AZN_C_AUDIT_ID]	"AZN_AUDIT_ID"	An attribute name; the corresponding string value will contain a subject's audit identifier.
[AZN_C_REQUEST_TIME]	"AZN_REQUEST_TIME"	An attribute name; the corresponding buffer value will contain a time_t structure representing time at which the access request occurred.
[AZN_C_AUTHN_QUALITY]	"AZN_AUTHN_QUALITY"	An attribute name; the corresponding string value will describe the strength and mechanism of authentication used to establish the initiator's identity.
[AZN_C_REQUESTER_LOC]	"AZN_REQUESTER_LOC"	An attribute name; the corresponding string value will contain the location (source address) from which the request was initiated. In the case of IP addresses, this will consist of a string containing a standard text representation of the numeric binary IP address.
[AZN_C_REQUEST_ROUTE_QOP]	"AZN_REQUEST_ROUTE_QOP"	An attribute name; the corresponding string value will describe the security characteristics of the connection over which the request was transmitted from the initiator to the AEF.

The azn_initialize() function can return a version number in an attribute list. The value of the name attribute of the entry in which the version number is returned is shown in Initialization Constants.

Name	Value	Meaning
[AZN_C_VERSION]	"AZN_VERSION"	An attribute name; the corresponding string value will contain a dotted-integer version number (for example, "3.3") passed back from initialization.

Authority and Mechanism IDs

Authority , Service, and Scheme IDs

• azn_id_get_creds():
  Provider is called an authority

• azn_decision_has_clearance() and azn_entitlement_get_labels():
  Provider is called a labelling scheme

• azn_creds_modify():
  Provider is called a credential modification service or mod_svc

• azn_creds_get_pac() and azn_pac_get_creds():
  Provider is called a pac service or pac_svc

• azn_entitlement_get_entitlements():
  Provider is called an entitlements service or entitlements_svc

Some of these services are optional. See Required Functionality and Portability for a list of required and optional services.

If an implementation supports multiple providers of a service, it must identify each provider using a unique OID. The implementation's documentation must provide a list of supported providers and their OIDs.

Additionally, implementations which support multiple providers of a service must implement the get_providers call for that service. The get_providers calls are:

azn_authority_get_authorities()
azn_authority_get_labeling_schemes()
azn_authority_get_mod_svcs()
azn_authority_get_pac_svcs()
azn_authority_get_entitlements_svcs()

aznAPI applications select providers at runtime by passing the string form of the provider's OID as an argument to the calls listed above.

No implementation is required to support multiple providers of any of these services (including required services). All implementations (including implementations which support multiple providers of these services) must designate a default provider of each supported service.

Applications can select the default provider of a service by passing the constant in Default ID as the value of the appropriate authority, service, or scheme ID argument to each call which requires a provider's OID.

Name	Value	Meaning
[AZN_NULL_ID]	""	The implementation should use the default provider of the invoked service.

Authentication Mechanism IDs

Examples of authentication mechanisms are SSL client authentication using an X.509 certificate, or Kerberos authentication using a Kerberos principal name and password.

The azn_id_get_creds() call takes an authentication mechanism identifier as an input parameter, to allow implementations which support multiple authentication mechanisms to determine which mechanism's authentication data is being passed through the mechanism_info argument. All implementations must designate a default mechanism for each authority id. aznAPI applications calling azn_id_get_creds() can select the default authentication mechanism for a provider by passing AZN_NULL_ID as the value of the mechanism_id argument.

Portability - Authentication Mechanism OIDs

Note:

Note that aznAPI implementations are free to use mechanisms with Object Identifiers which do not fall under the X/Open Object Identifier.

The organization of this registration system is as follows:

• The hierarchy above X/Open is:

  
   
  
  ISO (1); National Member Body (2); UK (826); National (0); X/Open (1050)
  
  
  
  

• The authorization API will extend X/Open's OID with arc specification reference number "12" and specification name "AZN Mechanisms".

• The description for "AZN Mechanisms" is:

  
   
  
  "Authentication mechanisms for authorization credential acquisition"
  
  
  
  

• Underneath "AZN Mechanisms", The Open Group maintains a sequential list of registered mechanisms, starting with reference number 1.

• The list of registered mechanisms is published on the Open Group's Web site (.Ur "http://www.opengroup.org/" http://www.opengroup.org/ ) at a location referenced from the on-line publication page for this aznAPI Technical Standard.

• Each mechanism includes a specification name, and a detailed description of the datatype that should be passed through the mechanism_info parameter of the azn_id_get_creds() function.

When an application calls azn_id_get_creds(), the string representation of the OID of the authentication mechanism which was used to create the data passed as the value of the mechanism_info argument (or AZN_NULL_ID, as noted above) should be passed as the value of the mechanism_id argument.