Function Call Definitions

The aznAPI naming convention assigns each function name a prefix describing its general class. This ensures that the alphabetical listing in this section groups functions in the same class together.

NAME

azn_attrlist_add_entry - adds a name/string-value entry to an attribute list.

SYNOPSIS

azn_status_t
azn_attrlist_add_entry(
    azn_attrlist_h_t  attr_list     /* in */,
    azn_string_t      attr_name     /* in */,
    azn_string_t      string_value  /* in */
);

DESCRIPTION

This call adds an entry to the attribute list attr_list. The added entry will have name attr_name and value string_value.

Note that this call can be issued multiple times with the same attr_list and the same attr_name, but with different string_values. If this is done, the resulting attr_list will contain multiple values for the specified name.

The attr_name and string_value input parameters are copied into a new attrlist entry by the aznAPI implementation; changes to the values of the input parameters after the call completes will have no effect on the newly added attrlist entry, and in fact the attr_name and string_value parameters' storage should be released by the calling application when their values are no longer needed.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

attr_list (in)

Handle to an attribute list.

attr_name (in)

Name attribute of the entry to be added.

string_value (in)

Value (string) attribute of the entry to be added.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_ATTR_NAME]

The attribute name is invalid.

[AZN_S_INVALID_STRING_VALUE]

The attribute value is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_add_entry_buffer - adds a name/buffer-value entry to an attribute list.

SYNOPSIS

azn_status_t
azn_attrlist_add_entry(
    azn_attrlist_h_t  attr_list     /* in */,
    azn_string_t      attr_name     /* in */,
    azn_buffer_t      buffer_value  /* in */
);

DESCRIPTION

This call adds an entry to the attribute list, attr_list. The added entry will have name attr_name and value buffer_value.

Note that this call can be issued multiple times with the same attr_list and the same attr_name, but with different buffer_values. If this is done, the resulting attr_list will contain multiple values for the specified name.

The attr_name and buffer_value input parameters are copied into a new attrlist entry by the aznAPI implementation; changes to the values of the input parameters after the call completes will have no effect on the newly added attrlist entry, and in fact the attr_name and buffer_value parameters' storage should be released by the calling application when their values are no longer needed.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

attr_list (in)

Handle to an attribute list.

attr_name (in)

Name attribute of the entry to be added.

buffer_value (in)

Value (buffer) attribute of the entry to be added.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_ATTR_NAME]

The attribute name is invalid.

[AZN_S_INVALID_BUFFER]

The attribute buffer is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_create - creates a valid, empty attribute list, assigns it a handle, and returns the handle.

SYNOPSIS

azn_status_t
azn_attrlist_create(
    azn_attrlist_h_t  *new_attrlist   /* out */
);

DESCRIPTION

This call creates a new, empty attribute list, assigns it a handle new_attrlist, and returns the handle.

When new_attrlist is no longer needed, its storage should be released by calling azn_attrlist_delete().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

new_attrlist (out)

A reference to the new attribute list handle which will be returned.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_delete - deletes the attribute list associated with the attribute list handle.

SYNOPSIS

azn_status_t
azn_attrlist_delete(
    azn_attrlist_h_t  *old_attrlist   /* in, out */
);

DESCRIPTION

This call deletes the attribute list associated with the handle old_attrlist. The call may set the input attribute list handle to an invalid value to ensure that it cannot be used in future calls.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

old_attrlist (in, out)

On input an existing attribute list handle.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_get_entry_buffer_value - returns a single specified value attribute for a name attribute with multiple values (within an attribute-list whose entries' value attributes are buffers).

SYNOPSIS

azn_status_t
azn_attrlist_get_entry_buffer_value(
    azn_attrlist_h_t  attr_list      /* in */,
    azn_string_t      attr_name      /* in */,
    unsigned int      value_index    /* in */,
    azn_buffer_t      *buffer_value  /* out */
);

DESCRIPTION

This call returns one buffer-type value attribute in buffer_value. The returned value attribute will be the one at position value_index within set of value attributes belonging to the name attribute specified by attr_name. The first value attribute for any particular name attribute within an attribute list has index 0.

When buffer_value is no longer needed, its storage should be released by calling azn_release_buffer().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

attr_list (in)

Handle to an existing attribute list.

attr_name (in)

Name attribute of the entry from which the value attribute is to be returned.

value_index (in)

Index within the entry of the value attribute to be returned.

buffer_value (out)

Pointer to a buffer which will hold the returned value attribute.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_ATTR_NAME]

The name attribute is invalid.

[AZN_S_INVALID_BUFFER_REF]

The buffer reference is invalid.

[AZN_S_ATTR_VALUE_NOT_BUFFER_TYPE]

The value attributes of this entry are not of type buffer.

[AZN_S_ATTR_INVALID_INDEX]

The index is not valid (no value exists for this index).

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_get_entry_string_value - returns a single specified value attribute for a name attribute with multiple values (within an attribute-list whose entries' value attributes are strings).

SYNOPSIS

azn_status_t
azn_attrlist_get_entry_string_value(
    azn_attrlist_h_t  attr_list      /* in */,
    azn_string_t      attr_name      /* in */,
    unsigned int      value_index    /* in */,
    azn_string_t      *string_value  /* out */
);

DESCRIPTION

This call returns one string-type value attribute in string_value. The returned value attribute will be the one at position value_index within set of value attributes belonging to the name attribute specified by attr_name. The first value attribute for any particular name attribute within an attribute list has index 0.

When string_value is no longer needed, its storage should be released by calling azn_release_string().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

attr_list (in)

Handle to an existing attribute list.

attr_name (in)

Name attribute of the entry from which the value attribute is to be returned.

value_index (in)

Index within the entry of the value attribute to be returned.

string_value (out)

Pointer to a string which will hold the returned value attribute.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_ATTR_NAME]

The name attribute is invalid.

[AZN_S_INVALID_STRING_REF]

The string reference is invalid.

[AZN_S_ATTR_VALUE_NOT_STRING_TYPE]

The value attributes of this entry are not of type string.

[AZN_S_ATTR_INVALID_INDEX]

The index is not valid (no value exists for this index).

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_get_names - returns the list of all name attributes appearing in entries of the attribute list.

SYNOPSIS

azn_status_t
azn_attrlist_get_names(
    azn_attrlist_h_t  attr_list      /* in */,
    azn_string_t      *attr_names[]  /* out */
);

DESCRIPTION

This call returns a list of name attributes as a NULL-terminated array azn_string_t values. When the attr_names array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

attr_list (in)

Handle to existing attribute list.

attr_names (out)

Pointer to a null-terminated azn_string_t array to hold the returned list of name attributes.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_STRING_REF]

The pointer to the string array is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_attrlist_name_get_num - returns the number of value attributes for a given name attribute in a given attribute list.

SYNOPSIS

azn_status_t
azn_attrlist_name_get_num(
  azn_attrlist_h_t  attr_list       /* in */,
  azn_string_t      attr_name       /* in */,
  unsigned int      *num_values     /* out */
);

DESCRIPTION

This function returns the number of value attributes for a given name attribute in a given attribute list.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

attr_list (in)

Handle to an existing attribute list.

attr_name (in)

Name attribute for which the number of value attributes is to be returned.

num_values (out)

Pointer to an integer through which the number of value attributes will be returned.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_ATTR_NAME]

The attribute name is invalid.

[AZN_S_ATTR_INVALID_INTEGER_REF]

The integer reference is not valid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_authority_get_authorities - returns a list of the authorization authority IDs supported by the aznAPI implementation.

SYNOPSIS

azn_status_t
azn_authority_get_authorities(
    azn_string_t  *azn_authorities[]    /* out */
); 

DESCRIPTION

This call returns all the authorization authority IDs supported by the implementation.

An authorization authority is the component of an aznAPI implementation which supports the azn_id_get_creds() call.

Authority IDs can subsequently be used to find supported services and mechanisms using azn_authority_get_*(), and to acquire credentials chains with azn_id_get_creds().

When the azn_authorities array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

authzn_authorities (out)

A NULL-terminated array of azn_string_t values which will contain the returned authorization authority IDs.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_INVALID_STRING_REF]

The string reference is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation; all calls requiring an authorization authority ID should use the default value by passing AZN_NULL_ID through the authority ID argument.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_authority_get_entitlements_svcs - returns a list of the entitlements service IDs supported by the implementation.

SYNOPSIS

azn_status_t
azn_authority_get_entitlements_svcs(
    azn_string_t   *entitlements_svc_ids[]  /* out */
); 

DESCRIPTION

This call returns all the entitlements service IDs supported by implementation. These services can subsequently be used in azn_entitlement_get_entitlements().

When the entitlements_svc_ids array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

entitlements_svc_ids (out)

A NULL-terminated array of azn_string_t values which will contain the returned entitlements service IDs.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The entitlements service string reference is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation; all calls requiring an entitlements service ID should use the default value by passing AZN_NULL_ID through the entitlements service ID argument.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_authority_get_labeling_schemes - returns a list of the labeling scheme IDs supported by the implementation.

SYNOPSIS

azn_status_t
azn_authority_get_labeling_schemes(
    azn_string_t   *labeling_scheme_ids[]  /* out */
); 

DESCRIPTION

This call returns all the labeling scheme IDs supported by implementation. These labeling scheme IDs can subsequently be used in the data classification functions azn_entitlement_get_labels() and azn_decision_has_clearance().

When the labeling_scheme_ids array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

labeling_scheme_ids (out)

A NULL-terminated array of azn_string_t values which will contain the returned labeling_scheme IDs.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The labeling scheme ID string reference is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation; all calls requiring an labeling scheme ID should use the default value by passing AZN_NULL_ID through the labeling scheme ID argument.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_authority_get_mechanisms - returns a list of the authentication mechanism IDs supported by the specified authorization authority.

SYNOPSIS

azn_status_t
azn_authority_get_mechanisms(
    azn_string_t   authority         /* in */,
    azn_string_t   *mechanism_ids[]  /* out */
); 

DESCRIPTION

This call returns all the authentication mechanism IDs supported by the named authorization authority. These mechanisms can subsequently be used in azn_id_get_creds().

When the mechanism_ids array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

authority (in)

An azn_string_t value containing the authorization authority ID of the authority whose supported authentication mechanism IDs are to be returned.

mechanism_ids (out)

A NULL-terminated array of azn_string_t values which will contain the returned authentication mechanism IDs.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The mechanism ID string reference is invalid.

[AZN_S_INVALID_AUTHORITY]

The authorization authority ID is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation; all calls requiring a mechanism ID should use the default value by passing AZN_NULL_ID through the mechanism ID argument.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_authority_get_mod_svcs - returns a list of the credential modification service IDs supported by the specified authorization authority.

SYNOPSIS

azn_status_t
azn_authority_get_mod_svcs(
    azn_string_t   authority       /* in */,
    azn_string_t   *mod_svc_ids[]  /* out */
); 

DESCRIPTION

This call returns all the credential modification service IDs supported by the specified authorization authority. These services can subsequently be used in azn_creds_modify().

When the mod_svc_ids array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

authority (in)

An azn_string_t value containing the authorization authority ID of the authority whose supported credential modification service IDs are to be returned.

mod_svc_ids (out)

A NULL-terminated array of azn_string_t values which will contain the returned credential modification service IDs.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The credential modification service string reference is invalid.

[AZN_S_INVALID_AUTHORITY]

The authorization authority ID is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation; all calls requiring a credential modification service ID should use the default value by passing AZN_NULL_ID through the credential modification service ID argument.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_authority_get_pac_svcs - returns a list of the privilege attribute certificate (PAC) service IDs supported by the specified authorization authority.

SYNOPSIS

azn_status_t
azn_authority_get_pac_svcs(
    azn_string_t   azn_authority    /* in */,
    azn_string_t   *pac_svc_ids[]   /* out */
);

DESCRIPTION

This call returns all the privilege attribute certificate service IDs supported by the specified authorization authority. These services can subsequently be used in azn_creds_get_pac() and azn_pac_get_creds() to convert credentials chains to certificates and back.

Multiple PAC services might be provided by an aznAPI implementation for several reasons. Different PAC services might generate differently formatted PACs (for example, X.509 attribute certificates versus SESAME PACs). Different PAC services might generate identical PAC formats, but use different (or no) signature mechanisms to assert their validity. Different PAC services might encode chained credentials in different orders in the PACs they generate. aznAPI implementations are not required to support multiple PAC services.

When the pac_svc_ids array is no longer required, its storage should be released by calling azn_release_strings().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

authority (in)

An azn_string_t value containing the authorization authority ID of the authority whose supported authorization PAC service IDs are to be returned.

pac_svc_ids (out)

A NULL-terminated array of azn_string_t values which will contain the returned authorization PAC service IDs.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The authorization PAC service string reference is invalid.

[AZN_S_INVALID_AUTHORITY]

The authorization authority ID is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation; all calls requiring an authorization PAC service ID should use the default value by passing AZN_NULL_ID through the PAC service ID argument.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_combine - combines two credentials chains and returns a handle to the resulting combined credentials chain.

SYNOPSIS

azn_status_t
azn_creds_combine(
    azn_creds_h_t  creds             /* in */,
    azn_creds_h_t  creds_to_add      /* in */,
    azn_creds_h_t  *combined_creds   /* out */
);

DESCRIPTION

This call takes a credential handle creds, which refers to a credentials chain, and appends to it a credentials chain referred to by another credential handle creds_to_add.

The credentials chain referred to by creds must contain as its first indexed credential the credential of the initiator; it may contain the (previously combined) credentials of one or more of the initiator's proxies. A handle to the combined credentials chain is returned through combined_creds.

The input credential handles (and the credentials chains to which they refer) are not modified in any way by this call, and later changes to these structures (including releasing their storage) will have no effect on the combined_creds returned by this call.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to credentials chain whose first indexed entry is the credential of the intiator of a request.

creds_to_add (in)

Handle to credentials chain to be appended to creds.

combined_creds (out)

Pointer to the returned new credentials chain, which will include the credentials chain referred to by creds followed by the credentials chain referred to by creds_to_add.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle passed as creds is invalid.

[AZN_S_INVALID_ADDED_CREDS_HDL]

The credential handle passed as creds_to_add is invalid.

[AZN_S_INVALID_COMB_CREDS_HDL]

The credential handle passed as combined_creds is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_create - creates a new, empty credentials chain, assigns it a handle, and returns the handle.

SYNOPSIS

azn_status_t
azn_creds_create(
    azn_creds_h_t   *creds   /* out */
);

DESCRIPTION

This call creates a new, empty credentials chain, assigns it a handle, and returns the handle.

When creds is no longer required, its storage should be released by calling azn_creds_delete().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (out)

Pointer to the new credential handle which will be returned.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_delete - deletes the credentials chain associated with the credential handle.

SYNOPSIS

azn_status_t
azn_creds_delete(
    azn_creds_h_t   *creds   /* in, out */
);

DESCRIPTION

This call deletes the credentials chain associated with the handle creds.

The call may set the input credential handle to an invalid value to ensure that it cannot be used in future calls.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

Creds (in, out)

Pointer to the handle of the credentials chain to be deleted. The call may set the creds handle to an invalid value on output to prevent use in future calls.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_for_subject - returns a handle to a credentials chain; used to extract a individual subject's credentials chain from a longer chain containing the combined credentials chains of several subjects.

SYNOPSIS

azn_status_t
azn_creds_for_subject(
    azn_creds_h_t  creds          /* in */,
    unsigned int   subject_index  /* in */,
    azn_creds_h_t  *new_creds     /* out */
);

DESCRIPTION

This call returns a handle, new_creds, to a credentials chain for the individual subject at index subject_index within a longer credentials chain creds which contains the combined credentials chains of several subjects.

The input handle creds (and the credentials chain to which it refers) is not modified in any way by this call, and later changes to this structure (including releasing its storage) will have no effect on the new_creds returned by this call.

Combined credentials chains are created by the azn_creds_combine() function. The first credentials chain in a combined credentials chain will be that of the initiator, and its index will be zero (0); callers can retrieve the credentials chain of the initiator by passing the constant AZN_C_INITIATOR_INDEX as the value of subject_index.

When new_creds() is no longer required, its storage should be released by calling azn_creds_delete().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to a credentials chain representing the combined credentials chains of several subjects, which contains a list of 1 or more individual credentials chains. When the call returns, the structure referred to by this argument is unchanged; subsequent changes to the credentials chain returned through new_creds do not affect the structure referred to by this argument.

subject_index (in)

The index of the requested individual credentials chain within the combined credentials chain. The index of the first credentials chain in the combined credentials chain, which should be that of the initiator, is zero (0). The total number of credentials chains in a combined credentials chain can be found by calling azn_creds_num_of_subjects().

new_creds (out)

Pointer to the new credentials chain which will be returned.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied as creds is invalid.

[AZN_S_INVALID_NEW_CREDS_HDL]

The pointer to the credential handle supplied as new_creds is invalid.

[AZN_S_INVALID_SUBJECT_INDEX]

The supplied index is not valid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_get_attrlist_for_subject - returns information from a specific subject's credentials chain within a specified (possibly combined) credentials chain.

SYNOPSIS

azn_status_t 
azn_creds_get_attrlist_for_subject (
    azn_creds_h_t     creds            /* in */,
    unsigned int      subject_index    /* in */,
    azn_attrlist_h_t  *creds_attrlist  /* out */
);

DESCRIPTION

This function returns an attribute list containing privilege attribute information from the credentials chain for the individual subject at index subject_index within a (possibly combined) credentials structure creds.

Combined credentials chains are created by the azn_creds_combine() function. The first credentials chain in a combined credentials chain will be that of the initiator, and its index will be zero (0); callers can retrieve the attributes for the credentials chain of the initiator by passing the constant AZN_C_INITIATOR_INDEX as the value of subject_index.

The input creds handle (and the credentials chain to which it refers) is not modified in any way by this call, and later changes to this structure (including releasing its storage) will have no effect on the creds_attrlist returned by this call.

Note that some attribute information returned by this call may not be portable across aznAPI implementations.

Callers can use the azn_attrlist_*() calls to retrieve individual attribute values from creds_attrlist.

The audit identifier associated with the specified credentials chain will be present in the returned attribute list; it will be the value attribute of an entry whose name attribute is [AZN_C_AUDIT_ID].

When creds_attrlist is no longer required, its storage should be released by calling azn_attrlist_delete().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to a credentials chain.

subject_index (in)

The index of the requested individual subject within the credentials chain. The index of the first credentials chain in a combined credentials chain, which should be that of the initiator, is zero (0). If creds is an individual credentials chain rather than a combined credentials chain, the index zero (0) specifies the entire credentials chain.

creds_attrlist (out)

Pointer to the handle of an attribute which will hold the specified subject's attribute information on return.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_INVALID_SUBJECT_INDEX]

The supplied index is not valid.

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle supplied is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this function.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_get_pac - creates and returns a privilege attribute certificate (PAC) by invoking a specified PAC service on the supplied credentials chain.

SYNOPSIS

azn_status_t 
azn_creds_get_pac(
    azn_creds_h_t  creds         /* in */,
    azn_string_t   pac_svc_id    /* in */,
    azn_buffer_t   *pac          /* out */
);

DESCRIPTION

This call uses the PAC service whose ID is supplied to build a new PAC. The PAC service uses the information in the supplied credentials chain to build the PAC. Different PAC services may produce PACs with different formats. Some PAC services may cryptographically protect or sign the PACs they produce.

The input creds handle (and the creds to which it refers) is not modified in any way by this call, and later changes to this structure (including releasing its storage) will have no effect on the pac returned by this call.

When pac is no longer required, its storage should be released by calling azn_buffer_release().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain whose information will be used to build the PAC.

pac_svc_id (in)

id of the PAC service which will produce the PAC.

pac (out)

Pointer to the buffer structure which will hold returned PAC.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_INVALID_PAC_SVC]

The privilege attribute certificate service identifier is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this function.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_modify - modifies an existing credentials chain and returns a handle to an new credentials chain containing the modifications.

SYNOPSIS

azn_status_t 
azn_creds_modify(
    azn_creds_h_t     creds        /* in */,
    azn_string_t      mod_svc_id   /* in */,
    azn_attrlist_h_t  mod_info     /* in */,
    azn_creds_h_t     *new_creds   /* out */
);

DESCRIPTION

This function uses the specified modification service and (optionally) an attribute list mod_info containing modification information provided by the caller to modify a copy of the supplied credentials chain. The function returns a handle to a new credentials chain containing the requested modifications. The supplied credentials chain, creds, is unchanged.

If the input creds handle references a combined credentials chain with more than one element, only the first element will be modified. In this case, the output chain will consist of the modified first element followed by unmodified copies of the remaining elements in the input combined credentials chains; the elements in the output credentials chain will be in the same order as their counterparts in the input credentials chain.

aznAPI implementations are not required to support credential modification. Implementations might use credential modification to support a variety of functions; for example, a credential modification service could allow its caller to remove privilege attributes from a credentials chain prior to using the credential.

When new_creds is no longer required, its storage should be released by calling azn_creds_delete().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain to be modified.

mod_svc_id (in)

ID of the credential modification service.

mod_info (in)

Attribute list containing modification-service-specific or application-specific data describing the desired credential modifications. This list may be empty (that is, contain no attributes). Implementation documentation must describe the behavior of this function when it is passed an empty mod_info list.

new_creds (out)

Pointer to a new, empty credentials chain; will hold the modified credentials chain upon return.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle referring to the input creds is invalid.

[AZN_S_INVALID_MOD_FUNCTION]

The supplied modification service identifier is not valid.

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle is invalid.

[AZN_S_INVALID_NEW_CREDS_HDL]

The pointer to the credential handle referring to the output new credentials chain is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this function.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_creds_num_of_subjects - returns the number of individual subjects' credentials chains in a combined credentials chain.

SYNOPSIS

azn_status_t
azn_creds_num_of_subjects(
    azn_creds_h_t  creds             /* in */,
    unsigned int   *num_of_subjects  /* out */
);

DESCRIPTION

This call returns the number of individual subjects, num_of_subjects, whose credentials appear in a (possibly combined) credentials chain creds. Combined credentials chains are created by the azn_creds_combine() function.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to a credentials chain.

num_of_subjects (out)

Pointer to the number of subjects whose credentials chains appear in the input credentials chain.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The creds() handle supplied is invalid.

[AZN_S_ATTR_INVALID_INTEGER_REF]

The integer reference is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_decision_access_allowed - makes an access control decision.

SYNOPSIS

azn_status_t
azn_decision_access_allowed(
    azn_creds_h_t  creds               /* in */,
    azn_string_t   protected_resource  /* in */,
    azn_string_t   operation           /* in */,
    int            *permission         /* out */
);

DESCRIPTION

This function decides whether the initiator specified by creds is authorized to perform the operation operation on the target protected_resource. The decision is returned through permission.

azn_decision_access_allowed is semantically equivalent to azn_decision_access_allowed_ext when app_context = NULL and permission_info = NULL.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain which will be used as initiator ADI to make the access decision.

protected_resource (in)

The name of the target of the request.

operation (in)

The name of the requested operation.

permission (out)

Pointer to the returned status value. If the returned status value is [AZN_S_COMPLETE], the value of the returned permission will be [AZN_C_PERMITTED] or [AZN_C_NOT_PERMITTED].

Note that additional information beyond a boolean result may be desired in some situations. Applications may be able to get additional information by calling azn_decision_access_allowed_ext().

Calling applications are bound by the decision returned using the permission argument only if the returned status code is [AZN_S_COMPLETE].

When the returned status code is not [AZN_S_COMPLETE], the returned permission value is undefined.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The creds handle supplied is invalid.

[AZN_S_INVALID_PROTECTED_RESOURCE]

The target name is invalid.

[AZN_S_INVALID_OPERATION]

The operation has no meaning for the specified target.

[AZN_S_INVALID_PERMISSION_REF]

The integer reference to return the permission is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_decision_access_allowed_ext - makes an access control decision using application-specific context information; returns information about why the decision was made.

SYNOPSIS

azn_status_t
azn_decision_access_allowed_ext(
    azn_creds_h_t     creds               /* in */,
    azn_string_t      protected_resource  /* in */,
    azn_string_t      operation           /* in */,
    azn_attrlist_h_t  app_context         /* in */,
    int               *permission         /* out */,
    azn_attrlist_h_t  *permission_info    /* in, out */
);

DESCRIPTION

This function decides whether the initiator specified by creds is authorized to perform the operation operation on the target protected_resource. Optionally, callers may supply application-specific context ACI using the app_context argument. The decision is returned through permission.

Optionally, the implementation may return implementation-specific information about the decision (for example, information indicating which rule or rules was responsible for granting or denying access) through permission_info.

The constants [AZN_C_REQUEST_TIME], [AZN_C_AUTHN_QUALITY], [AZN_C_REQUESTER_LOC], and [AZN_C_REQUEST_ROUTE_QOP] as defined in Attribute Name Constants, may be used as the name attributes of entries in the app_context attribute list to communicate common types of context.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain which will be used as initiator ADI to make the access decision.

protected_resource (in)

The name of the target resource.

operation (in)

The name of the requested operation.

app_context (in)

An attribute list containing application-specific context ACI. A NULL value indicates there is no context ACI.

permission (out)

Pointer to the returned status value.

If the returned status value is [AZN_S_COMPLETE], the value of the returned permission will be [AZN_C_PERMITTED] or [AZN_C_NOT_PERMITTED].

Calling applications are bound by the decision returned using the permission argument only if the returned status code is [AZN_S_COMPLETE].

When the returned status code is not [AZN_S_COMPLETE], the returned permission value is undefined.

permission_info (in, out)

Pointer to an attribute list through which the implementation may return implementation-specific information about the decision.

If a NULL pointer is passed as input, then no information will be returned.

permission_info may be used to return implementation-specific qualifiers to AZN_C_NOT_PERMITTED to assist the calling application and/or the initiator in formulating a request which will be authorized. Examples of such qualifiers might include not permitted yet, requires additional privilege attributes, or permissible with restrictions.

No portable values for permission_info attributes are defined in this specification, though portable values could be defined in a future revision.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The creds handle supplied is invalid.

[AZN_S_INVALID_PROTECTED_RESOURCE]

The target name is invalid.

[AZN_S_INVALID_OPERATION]

The operation has no meaning for the specified target.

[AZN_S_INVALID_PERMISSION_REF]

The integer reference to return the permission is invalid.

[AZN_S_INVALID_APP_CONTEXT_HDL]

The attribute list handle for the context ACI is invalid.

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle for the returned permission info is invalid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_decision_has_clearance - decides whether an initiator has the clearance necessary to operate on protected resources with a specified label.

SYNOPSIS

azn_status_t
azn_decision_has_clearance(
    azn_creds_h_t  creds               /* in */,
    azn_string_t   labeling_scheme_id  /* in */,
    azn_string_t   protected_resource  /* in */,
    azn_string_t   operation           /* in */,
    azn_string_t   label               /* in */,
    int            *permission         /* out */
);

DESCRIPTION

Using a classification defined by labeling_scheme_id, the call checks whether the initiator specified by creds has the clearance necessary to invoke operation on data labeled with label.

Note that this call is provided support access decisions in cases when the application is able to retrieve protected resource labels, but the aznAPI implementation is not able to retrieve them. If the aznAPI implementation has access to protected resource labels, then applications should use azn_decision_access_allowed() or azn_decision_access_allowed_ext() instead of azn_decision_has_clearance().

Note that AEFs invoking this function must pass label data as a string. If the label as retrieved by the application is not already in a suitable format (for example, XML or encoded ASN.1), the AEF may need to encode the label (using a procedure specific to the specified labeling scheme, and not defined in this specification) before passing it to this function.

The result of the access check is returned in permission.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain which will be used as initiator ADI to make the access decision.

labeling_scheme_id (in)

ID of the labeling to which label belongs.

protected_resource (in)

The name of the target resource.

operation (in)

The name of the requested operation. May be NULL.

label (in)

The label of the target of the request.

permission (out)

If the returned status value is [AZN_S_COMPLETE], the value of the returned permission will be [AZN_C_PERMITTED] or [AZN_C_NOT_PERMITTED].

If the label value is not recognized as valid for the resource, the returned status code will be [AZN_S_UNKNOWN_LABEL], and the value of permission will be [AZN_C_NOT_PERMITTED].

Calling applications are bound by the decision returned using the permission argument only if the returned status code is [AZN_S_COMPLETE] or [AZN_S_UNKNOWN_LABEL].

When the returned status code is not [AZN_S_COMPLETE] or [AZN_S_UNKNOWN_LABEL], the returned permission value is undefined.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The creds handle supplied is invalid.

[AZN_S_INVALID_LABELING_SCHEME]

The labeling scheme ID is unknown or invalid.

[AZN_S_INVALID_PROTECTED_RESOURCE]

The target name is invalid.

[AZN_S_INVALID_OPERATION]

The name of the requested operation is invalid.

[AZN_S_UNKNOWN_LABEL]

The label value is not recognized as valid within the labeling scheme.

[AZN_S

The integer reference for the permission is not valid.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_entitlement_get_entitlements - returns entitlements of an initiator.

SYNOPSIS

azn_status_t
azn_entitlement_get_entitlements(
    azn_creds_h_t     creds                /* in */,
    azn_string_t      entitlements_svc_id  /* in */,
    azn_attrlist_h_t  app_context          /* in */,
    azn_attrlist_h_t  *entitlements        /* out */
);

DESCRIPTION

This uses an entitlements service identified by entitlements_svc_id to return the entitlements of an initiator specified by creds. The calling application may pass application-specific or entitlements-service-specific context data using an attribute list app_context.Theentitlementsarereturned using the attribute list entitlements.

The constants [AZN_C_REQUEST_TIME], [AZN_C_AUTHN_QUALITY], [AZN_C_REQUESTER_LOC], and [AZN_C_REQUEST_ROUTE_QOP] as defined in Attribute Name Constants, may be used as name attribute of entries in the app_context attribute list to communicate common types of context information.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain of the subject whose entitlements are to be returned.

entitlements_svc_id (in)

The ID of the entitlements service to be used.

app_context (in)

Handle to an attribute list containing application-specific or entitlements-service-specific context information. A NULL value should be used if no application state is passed.

entitlements (out)

Handle to the attribute list which will hold the entitlement information on return.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The creds handle supplied is invalid.

[AZN_S_INVALID_ENTITLEMENTS_SVC]

The entitlement service identifier is invalid.

[AZN_S_INVALID_APP_CONTEXT_HDL]

The attribute list handle for the application context is invalid.

[AZN_S_INVALID_ENTITLEMENTS_HDL]

The attribute list handle for the entitlements is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this function.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_entitlement_get_labels - returns the set of labels which the initiator specified by the supplied credentials chain is authorized to access.

SYNOPSIS

azn_status_t
azn_entitlement_get_labels(
    azn_creds_h_t  creds               /* in */,
    azn_string_t   labeling_scheme_id  /* in */,
    azn_string_t   operation           /* in */,
    azn_string_t   *labels[]           /* out */
);

DESCRIPTION

This call returns the set of labels labels within a labeling scheme identified by labeling_scheme_id. An initiator specified by creds will have clearance to perform the specified operation on any data labeled using only labels included in the returned set of labels.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain whose clearance is to be returned.

labeling_scheme_id (in)

The ID of the labeling whose labels should be returned.

operation (in)

The name of an operation which the returned labels will authorize the initiator specified by the supplied credentials chain to invoke. If the value of this argument is NULL, the set of labels returned will be those for which the credentials chain authorizes every operation.

labels (out)

Pointer to a NULL terminated array of strings. Upon successful completion, this argument will contain all the labels within the specified labeling scheme to which the initiator specified by creds has clearance. Memory for this argument must be released by the caller using azn_release_strings().

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_INVALID_LABELING_SCHEME]

The labeling scheme identifier is unknown or invalid.

[AZN_S_INVALID_STRING_REF]

The string reference for the returned labels is invalid.

[AZN_S_INVALID_OPERATION]

The name of the requested operation is invalid or not recognized by the specified labeling scheme.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this function (for example, because label values are themselves sensitive information which the caller is not entitled to see).

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_entitlement_get_operations - returns the list of operations permitted or forbidden to a specified initiator on a specified resource.

SYNOPSIS

azn_status_t
azn_entitlement_get_operations(
    azn_creds_h_t creds               /* in */,
    azn_string_t  protected_resource  /* in */, 
    int           permission          /* in */,
    azn_string_t  *operations[]       /* out */
);

DESCRIPTION

This function returns a list of operation names operations.

If the value of permission is [AZN_C_PERMITTED], operations will contain the names of all the operations the initiator specified by creds is permitted to perform on the target protected_resource.

If the value of permission is [AZN_C_NOT_PERMITTED], operations will contain the names of all the operations the initiator specified by creds is forbidden to perform on the target protected_resource.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain whose entitled operations are to be returned.

protected_resource (in)

The name of the target resource.

permission (in)

Indicates whether permitted or forbidden operations should be returned. Valid values are [AZN_C_PERMITTED] and [AZN_C_NOT_PERMITTED].

Implementations are not required to support retrieval of the list of NOT_PERMITTED operations; an implementation which does not support retrieval of NOT_PERMITTED operations must return the AZN_S_UNIMPLEMENTED_FUNCTION status code if the caller passes AZN_C_NOT_PERMITTED as the value of this argument.

Implementations may return the AZN_S_AUTHORIZATION_FAILURE status code if the caller is not authorized to receive information about NOT_PERMITTED operations.

operations (out)

A list of operation names, passed as a NULL-terminated array of azn_string_t. azn_release_strings must be used to release operations.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_INVALID_PROTECTED_RESOURCE]

The specified target name is invalid.

[AZN_S_STRING_REF]

The string reference for the returned operation names is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority to invoke this call, for example because the names of the operations are themselves sensitive information which the caller is not authorized to see.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_entitlement_get_operations_ext - returns the list of operations permitted or forbidden to a specified initiator on a specified resource using application-specific context information; returns information about why the decision was made.

SYNOPSIS

azn_status_t
azn_entitlement_get_operations_ext(
    azn_creds_h_t     creds               /* in */,
    azn_string_t      protected_resource  /* in */,
    azn_attrlist_h_t  app_context         /* in */,
    int               permission          /* in */,
    azn_string_t      *operations[]       /* out */,
    azn_attrlist_h_t  *permission_info    /* in, out */
);

DESCRIPTION

This function returns a list of operation names operations.

If the value of permission is [AZN_C_PERMITTED], operations will contain the names of all the operations the initiator specified by creds is permitted to perform on the target protected_resource.

If the value of permission is [AZN_C_NOT_PERMITTED], operations will contain the names of all the operations the initiator specified by creds is forbidden to perform on the target protected_resource.

Optionally, callers may supply application-specific context ACI using the app_context argument.

Optionally, the implementation may return implementation-specific information about the decision through permission_info.

The constants [AZN_C_REQUEST_TIME], [AZN_C_AUTHN_QUALITY], [AZN_C_REQUESTER_LOC], and [AZN_C_REQUEST_ROUTE_QOP] as defined in Attribute Name Constants, may be used as the name attributes of entries in the app_context attribute list to communicate common types of context.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

creds (in)

Handle to the credentials chain whose entitled operations are to be returned.

protected_resource (in)

The name of the target resource.

app_context (in)

An attribute list containing application-specific context ACI. A NULL value indicates there is no context ACI.

permission (in)

Indicates whether permitted or forbidden operations should be returned. Valid values are [AZN_C_PERMITTED] and [AZN_C_NOT_PERMITTED].

operations (out)

A list of operation names, passed as a NULL-terminated array of azn_string_t. azn_release_strings() must be used to release operations.

permission_info (in, out)

A pointer to an attribute list through which the implementation may return implementation-specific information about the permitted or forbidden operations. If a NULL value is passed as input, then no information will be returned.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_CREDS_HDL]

The credential handle supplied is invalid.

[AZN_S_INVALID_PROTECTED_RESOURCE]

The specified resource is invalid.

[AZN_S_INVALID_APP_CONTEXT_HDL]

The attribute list handle for the application context is invalid.

[AZN_S_INVALID_ATTRLIST_HDL]

The attribute list handle for the permission info is invalid.

[AZN_S_STRING_REF]

The string reference for the operations list is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this operation, for example because the names of the operations are themselves sensitive information which the caller is not authorized to see.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_error_major - returns major error code associated with a returned status code.

SYNOPSIS

unsigned int
azn_error_major(
    azn_status_t   status_code    /* in */
); 

DESCRIPTION

The major error code associated with a previously returned status code is returned.

PARAMETERS

status_code (in)

Previously returned status code by any of the azn_*() routines.

RETURN VALUE

Any of the defined major error codes, AZN_S_*, will be returned.

ERRORS

No other errors are defined.

NAME

azn_error_minor - returns implementation-specific minor error code associated with a returned status code.

SYNOPSIS

unsigned int
azn_error_minor(
    azn_status_t   status_code    /* in */
); 

DESCRIPTION

The minor error code associated with a previously returned status code is returned.

Note that applications are free to ignore minor error codes and need not call this function to retrieve them.

Minor error codes are provided for implementations which wish to take advantage of returned implementation-specific error status information.

PARAMETERS

status_code (in)

Previously returned status code by any of the azn_*() routines.

RETURN VALUE

An implementation-specific minor error code will be returned.

ERRORS

No other errors are defined.

NAME

azn_error_minor_get_string - returns a string describing the implementation-specific minor error.

SYNOPSIS

azn_status_t
azn_error_minor(
    unsigned int   minor_error          /* in */,
    azn_string_t   *minor_error_string  /* out */
); 

DESCRIPTION

A string describing the error corresponding to a previously returned minor error status code is returned.

When minor_error_string is no longer needed, its storage should be released by calling azn_release_string().

PARAMETERS

minor_error (in)

Minor error code previously returned by azn_error_minor().

minor_error_string (out)

Pointer to a string describing the condition which triggered the generation of the minor_error code.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_FAILURE]

The specified minor_error code is invalid, or no string describing the specified minor_error can be returned.

ERRORS

No other errors are defined.

NAME

azn_id_get_creds - returns a handle to the credentials chain associated by a specified authorization authority with a specified identity.

SYNOPSIS

azn_status_t
azn_id_get_creds(
    azn_string_t   authority        /* in */,
    azn_string_t   mechanism_id     /* in */,
    azn_buffer_t   mechanism_info   /* in */,
    azn_creds_h_t  *new_creds       /* out */
); 

DESCRIPTION

This function returns a handle new_creds to a newly constructed credentials chain for the identity corresponding to the initiator ACI mechanism_info produced by an authentication mechanism mechanism_id. If the implementation supports more than one authorization authority, the caller can specify which authority should be used by passing the ID of the desired authority in authority.

The Open Group maintains a list of registered mechanism IDs together with a description of their mechanism_info formats (see Portability - Authentication Mechanism OIDs).

Specifying a NULL value for authority causes the default authority to be used.

Specifying NULL values for mechanism_id and mechanism_info causes the default authentication mechanism and the default identity to be used.

The authorities supported by an implementation can be obtained using azn_authority_get_authorities(), while the mechanisms supported by an authority can be obtained using azn_authority_get_mechanisms().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

authority (in)

The ID of the authorization authority which should be used to build the credentials chain. A NULL input value selects a default authority.

mechanism_id (in)

The authentication mechanism which was used to generate the identity passed through mechanism_info.ANULL input value selects a default authentication mechanism.

mechanism_info (in)

A buffer containing initiator ACI consisting of identity information obtained from an authentication service. The authentication service used to produce this information should be identified using the mechanism_id argument.

A NULL input value directs the aznAPI implementation to retrieve the default identity for the selected authentication mechanism from the environment. If NULL is passed as the value of this argument and the implementation is not able to retrieve a default identity from the environment, AZN_S_INVALID_MECHANISM_INFO will be returned as the major status code.

new_creds (out)

Pointer to a new, empty credentials chain; will hold the returned credentials chain.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_AUTHORITY]

The authorization authority ID is invalid.

[AZN_S_INVALID_MECHANISM]

The security mechanism ID is not supported by the selected authorization authority.

[AZN_S_INVALID_MECHANISM_INFO]

The security mechanism information is not valid.

[AZN_S_INVALID_NEW_CREDS_HDL]

The credential handle supplied for new_creds is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_initialize - initializes the authorization service.

SYNOPSIS

azn_status_t
azn_initialize(
    azn_attrlist_h_t  init_data   /* in */,
    azn_attrlist_h_t  *init_info  /* in, out */
);

DESCRIPTION

azn_initialize() must be called before any aznAPI functions other than azn_attrlist_*() and azn_error_*() are called.

The implementation may permit or require implementation-specific data to be passed in at initialization time using init_data.

The implementation may return implementation-specific information using ] init_info. Implementations must return the version number using the string value attribute of an entry whose name attribute is [AZN_C_VERSION] (unless the caller passes a null pointer as the input value of init_info).

When init_info is no longer required, its storage should be released by calling azn_attrlist_delete().

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

init_data (in)

A handle to an attribute list containing implementation-specific initialization data. If there is no initialization data, an attribute list with no entries should be passed as the value of this argument.

init_info (in, out)

Pointer to an attribute list containing through which implementation-specific information will be returned from initialization. If a NULL pointer is passed as input, then no information will be returned.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_API_ALREADY_INITIALIZED]

azn_initialize() has been called twice without an intervening call to azn_shutdown().

[AZN_S_INVALID_INIT_DATA_HDL]

The attribute list handle for the input initialization data is invalid.

[AZN_S_INVALID_INIT_INFO_HDL]

The attribute list handle for the output initialization information is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred.

ERRORS

No other errors are defined.

NAME

azn_pac_get_creds - returns a handle to new credentials chain derived from a privilege attribute certificate (PAC) by a specified PAC service.

SYNOPSIS

azn_status_t
azn_pac_get_creds(
    azn_buffer_t   pac             /* in */,
    azn_string_t   pac_svc_id      /* in */,
    azn_creds_h_t  *new_creds      /* out */
);

DESCRIPTION

This call uses the PAC service whose ID is supplied to build a new credentials chain using the information in the supplied PAC. Some PAC services may cryptographically verify the protection or signature on the received PAC, and return an error if the PAC cannot be verified.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

pac (in)

The buffer structure which holds the supplied PAC.

pac_svc_id (in)

ID of the PAC service which will produce the credentials chain.

new_creds (out)

Pointer to a new, empty credentials structure, which will hold the returned credentials chain.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_PAC]

The PAC is invalid or could not be verified by the PAC service.

[AZN_S_INVALID_PAC_SVC]

The ID of the PAC service is invalid.

[AZN_S_INVALID_NEW_CREDS_HDL]

The credential handle supplied for new_creds is invalid.

[AZN_S_AUTHORIZATION_FAILURE]

The caller does not possess the authority required to invoke this function, for example because the caller is not authorized to create credentials chains for initiators it has not authenticated.

[AZN_S_UNIMPLEMENTED_FUNCTION]

This function is not supported by the implementation.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_release_buffer - frees storage associated with a buffer.

SYNOPSIS

azn_status_t
azn_release_buffer(
    azn_buffer_t   *buffer   /* in, out */
);

DESCRIPTION

This call releases the specified azn_buffer_t structure.

The call may set the input buffer pointer to an invalid value to ensure that it cannot be used in future calls.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

buffer (in, out)

A pointer to the buffer whose memory is to be released.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_BUFFER]

The buffer is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_release_string - frees storage associated with a string.

SYNOPSIS

azn_status_t
azn_release_string(
    azn_string_t   *string   /* in, out */
);

DESCRIPTION

This call releases the specified azn_string_t structure.

The call may set the input string pointer to an invalid value to ensure that it cannot be used in future calls.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

string (in, out)

Pointer to the string to be released.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The string reference is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_release_strings - frees storage associated with an array of strings.

SYNOPSIS

azn_status_t
azn_release_strings(
    azn_string_t   *strings[]   /* in, out */
);

DESCRIPTION

This call releases a NULL-terminated array of azn_string_t structures.

The call may set the input array pointer to an invalid value to ensure that it cannot be used in future calls.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

strings (in)

Pointer to the array azn_string_t structures to be released.

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_INVALID_STRING_REF]

The reference to the array of strings is invalid.

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.

NAME

azn_shutdown - cleans up internal authorization service state in preparation for shutdown.

SYNOPSIS

azn_status_t
azn_shutdown(
    void
);

DESCRIPTION

An application which has initialized the aznAPI using the azn_initialize() function should call azn_shutdown() to clean up the aznAPI's memory and other internal implementation state before the application exits.

No aznAPI calls other than azn_attrlist_*() and azn_error_*() may be called after azn_shutdown() without an intervening call to azn_initialize().

All allocated storage should be discarded by calling the azn_*_delete() and azn_release_*() calls before azn_shutdown() is called.

If successful, the function returns [AZN_S_COMPLETE].

PARAMETERS

There are no arguments for azn_shutdown().

RETURN VALUE

[AZN_S_COMPLETE]

Successful completion.

If the returned status code is not equal to [AZN_S_COMPLETE], then the following major error codes can be derived from the returned status code with azn_error_major():

[AZN_S_API_UNINITIALIZED]

This function has been called before azn_initialize().

[AZN_S_FAILURE]

An implementation-specific error or failure has occurred. Implementation-specific minor error codes can be derived from the returned status code with azn_error_minor().

ERRORS

No other errors are defined.