technical standard authorization (azn) api - the … · world’s largest it buyers and vendors...

S

L

T

A

A

C

N

I

D

N

A

H

R

C

D

ET

Technical Standard

Authorization (AZN) API

[This page intentionally left blank]

Open Group Technical Standard


The Open Group

January 2000, The Open Group

All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, inany form or by any means, electronic, mechanical, photocopying, recording or otherwise,without the prior permission of the copyright owners.

Open Group Technical Standard


ISBN: 1-85912-266-3Document Number: C908

Published in the U.K. by The Open Group, January 2000.

Any comments relating to the material contained in this document may be submitted to:

The Open GroupApex PlazaForbury RoadReadingBerkshire, RG1 1AXUnited Kingdom

or by Electronic Mail to:

[email protected]

ii Open Group Technical Standard (2000)

Contents

Chapter 1 Introduction............................................................................................... 1

Chapter 2 Objectives ................................................................................................... 3 2.1 Goals .............................................................................................................. 3 2.2 Non-Goals .................................................................................................... 3

Chapter 3 Architectural Overview...................................................................... 5 3.1 ISO 10181-3 Access Control Framework................................................ 6 3.2 Access Control Service Components...................................................... 7 3.2.1 Access Control Decision Functions...................................................... 7 3.2.2 Access Control Enforcement Functions .............................................. 8 3.3 Access Control Information...................................................................... 9 3.3.1 Initiator Information ............................................................................... 9 3.3.2 Target Information................................................................................... 11 3.3.3 Request Information................................................................................ 12 3.3.4 Context Information................................................................................ 12 3.3.5 Retained Information.............................................................................. 13 3.3.6 Access Control Policy Information ...................................................... 13 3.3.7 Externalizing ADI .................................................................................... 14

Chapter 4 Authorization API Usage Model .................................................. 17 4.1 System Structure ......................................................................................... 17 4.2 Supported Functions.................................................................................. 18 4.3 State Machine............................................................................................... 19 4.4 Trust Model .................................................................................................. 21 4.4.1 Relationship between Authentication and Authorization.............. 21 4.4.2 TCB Boundary .......................................................................................... 23

Chapter 5 Required Functionality and Portability ................................... 25 5.1 Required Functionality .............................................................................. 25 5.1.1 Functions ................................................................................................... 25 5.1.2 Authorities, Services, Schemes, and Mechanisms ............................ 25 5.1.3 Attributes................................................................................................... 26 5.2 Portability ..................................................................................................... 26 5.2.1 Resource and Operation Names........................................................... 26

Chapter 6 Parameter Passing Conventions.................................................... 27 6.1 Structured Data Types ............................................................................... 27 6.2 String Data and Similar Data.................................................................... 27 6.2.1 Buffers......................................................................................................... 27 6.2.2 Character Strings...................................................................................... 27 6.2.3 Credential Handles.................................................................................. 28

Authorization (AZN) API iii

Contents

6.2.4 Attribute List Handle.............................................................................. 28 6.3 Status Values................................................................................................ 28 6.4 Constants ...................................................................................................... 30 6.5 Authority and Mechanism IDs ................................................................ 33 6.5.1 Authority , Service, and Scheme IDs ................................................... 33 6.5.2 Authentication Mechanism IDs............................................................ 34 6.5.3 Portability — Authentication Mechanism OIDs ............................... 34

Chapter 7 Function Call Definitions.................................................................. 37 azn_attrlist_add_entry( ).............................................................................. 38 azn_attrlist_add_entry_buffer( ).................................................................. 40 azn_attrlist_create( ) ..................................................................................... 42 azn_attrlist_delete( ) ..................................................................................... 43 azn_attrlist_get_entry_buffer_value( )........................................................ 44 azn_attrlist_get_entry_string_value( ) ....................................................... 46 azn_attrlist_get_names( ) ............................................................................. 48 azn_attrlist_name_get_num( )..................................................................... 49 azn_authority_get_authorities( ) ................................................................. 50 azn_authority_get_entitlements_svcs( ) ..................................................... 51 azn_authority_get_labeling_schemes( ) ...................................................... 52 azn_authority_get_mechanisms( ) ............................................................... 53 azn_authority_get_mod_svcs( ) ................................................................... 54 azn_authority_get_pac_svcs( )..................................................................... 55 azn_creds_combine( ) .................................................................................... 57 azn_creds_create( ) ........................................................................................ 59 azn_creds_delete( ) ........................................................................................ 60 azn_creds_for_subject( ) ............................................................................... 61 azn_creds_get_attrlist_for_subject( ) .......................................................... 63 azn_creds_get_pac( ) ..................................................................................... 65 azn_creds_modify( ) ...................................................................................... 67 azn_creds_num_of_subjects( ) ..................................................................... 69 azn_decision_access_allowed( ).................................................................... 70 azn_decision_access_allowed_ext( )............................................................. 72 azn_decision_has_clearance( )...................................................................... 74 azn_entitlement_get_entitlements( ) ........................................................... 76 azn_entitlement_get_labels( )....................................................................... 78 azn_entitlement_get_operations( )............................................................... 80 azn_entitlement_get_operations_ext( ) ....................................................... 82 azn_error_major( ) ........................................................................................ 84 azn_error_minor( ) ........................................................................................ 85 azn_error_minor_get_string( ) .................................................................... 86 azn_id_get_creds( ) ....................................................................................... 87 azn_initialize( ) ............................................................................................. 89 azn_pac_get_creds( ) ..................................................................................... 91 azn_release_buffer( )...................................................................................... 93 azn_release_string( ) ..................................................................................... 94 azn_release_strings( ).................................................................................... 95 azn_shutdown ( )............................................................................................ 96

iv Open Group Technical Standard (2000)

Contents

Appendix A Header File ................................................................................................. 97

Glossary ....................................................................................................... 105

Index............................................................................................................... 109

List of Figures

3-1 ISO 10181-3 Access Control Framework................................................... 63-2 Inputs to an Access Decision Function (ADF)......................................... 73-3 AEFs Use the Authorization API to Call ADFs ....................................... 83-4 A Capability .................................................................................................... 93-5 Transforming Initiator ACI into a Credential .......................................... 103-6 Externalization of Credentials into a PAC................................................ 143-7 Portable Entitlements.................................................................................... 153-8 Non-Portable Entitlements .......................................................................... 164-1 aznAPI System Structure ............................................................................. 174-2 aznAPI State Machine Summary................................................................ 194-3 Relationship between Authentication and Authorization.................... 214-4 Trust Relationships in an aznAPI System................................................. 23

List of Tables

4-1 aznAPI Functions........................................................................................... 184-2 aznAPI State Machine Transitions ............................................................. 195-1 Mandatory Function Calls in Conformant aznAPI Implementation.. 256-1 Major Error Codes ......................................................................................... 296-2 Permission Constants.................................................................................... 306-3 Optional Parameter Constants.................................................................... 316-4 Attribute Name Constants........................................................................... 316-5 Initialization Constants ................................................................................ 336-6 Default ID ........................................................................................................ 34

Authorization (AZN) API v

Contents

vi Open Group Technical Standard (2000)

Preface

The Open Group

The Open Group is a vendor and technology-neutral consortium which ensures that multi-vendor information technology matches the demands and needs of customers. It develops anddeploys frameworks, policies, best practices, standards, and conformance programs to pursue itsvision: the concept of making all technology as open and accessible as using a telephone.

The mission of The Open Group is to deliver assurance of conformance to open systemsstandards through the testing and certification of suppliers’ products.

The Open group is committed to delivering greater business efficiency and lowering the cost andrisks associated with integrating new technology across the enterprise by bringing togetherbuyers and suppliers of information systems.

Membership of The Open Group is distributed across the world, and it includes some of theworld’s largest IT buyers and vendors representing both government and commercialenterprises.

More information is available on The Open Group Web Site at http://www.opengroup.org.

Open Group Publications

The Open Group publishes a wide range of technical documentation, the main part of which isfocused on development of Technical and Product Standards and Guides, but which alsoincludes white papers, technical studies, branding and testing documentation, and businesstitles. Full details and a catalog are available on The Open Group Web Site athttp://www.opengroup.org/pubs.

• Product Standards

A Product Standard is the name used by The Open Group for the documentation that recordsthe precise conformance requirements (and other information) that a supplier’s product mustsatisfy. Product Standards, published separately, refer to one or more Technical Standards.

The ‘‘X’’ Device is used by suppliers to demonstrate that their products conform to therelevant Product Standard. By use of the Open Brand they guarantee, through the OpenBrand Trademark License Agreement (TMLA), to maintain their products in conformancewith the Product Standard so that the product works, will continue to work, and that anyproblems will be fixed by the supplier. The Open Group runs similar conformance schemesinvolving different trademarks and license agreements for other bodies.

• Technical Standards (formerly CAE Specifications)

Open Group Technical Standards, along with standards from the formal standards bodiesand other consortia, form the basis for our Product Standards (see above). The TechnicalStandards are intended to be used widely within the industry for product development andprocurement purposes.

Technical Standards are published as soon as they are developed, so enabling suppliers toproceed with development of conformant products without delay.

Anyone developing products that implement a Technical Standard can enjoy the benefits of asingle, widely supported industry standard. Where appropriate, they can demonstrateproduct compliance through the Open Brand.

Authorization (AZN) API vii

Preface

• CAE Specifications

CAE Specifications and Developers’ Specifications published prior to January 1998 have thesame status as Technical Standards (see above).

• Preliminary Specifications

Preliminary Specifications have usually addressed an emerging area of technology andconsequently are not yet supported by multiple sources of stable conformantimplementations. There is a strong preference to develop or adopt more stable specificationsas Technical Standards.

• Consortium and Technology Specifications

The Open Group has published specifications on behalf of industry consortia. For example, itpublished the NMF SPIRIT procurement specifications on behalf of the NetworkManagement Forum (now TMF). It also published Technology Specifications relating toOSF/1, DCE, OSF/Motif, and CDE.

In addition, The Open Group publishes Product Documentation. This includes productdocumentation—programmer’s guides, user manuals, and so on—relating to the DCE, Motif,and CDE. It also includes the Single UNIX Documentation, designed for use as common productdocumentation for the whole industry.

Versions and Issues of Specifications

As with all live documents, Technical Standards and Specifications require revision to align withnew developments and associated international standards. To distinguish between revisedspecifications which are fully backwards compatible and those which are not:

• A new Version indicates there is no change to the definitive information contained in theprevious publication of that title, but additions/extensions are included. As such, it replacesthe previous publication.

• A new Issue indicates there is substantive change to the definitive information contained inthe previous publication of that title, and there may also be additions/extensions. As such,both previous and new documents are maintained as current publications.

Corrigenda

Readers should note that Corrigenda may apply to any publication. Corrigenda information ispublished on The Open Group Web Site at http://www.opengroup.org/corrigenda.

Ordering Information

Full catalog and ordering information on all Open Group publications is available on The OpenGroup Web Site at http://www.opengroup.org/pubs.

This Document

This document is a Technical Standard.

A generally accepted definition of Authorization is ‘‘the granting of access rights to a subject —for example, a user, or a program.’’ Within this definition, we need to distinguish between theadministrative act of asserting that a subject should be granted access rights (which we define asa ‘‘set of privilege attributes’’), and the operational (control) act of allowing a subject to access aresource after determining that they hold the required set of privilege attributes.

viii Open Group Technical Standard (2000)

Preface

This Technical Standard defines a generic application programming interface (API) for accesscontrol, in systems whose access control facilities conform to the architectural frameworkdescribed in International Standard ISO 10181-3 (Access Control Framework).

The API defined in this document does not provide for privilege attribute administration,although it does provide facilities which allow a subject to control which of its privilegeattributes are used to authorize a particular access request (such facilities are often called ‘‘leastprivilege’’).

Typographical Conventions

The following typographical conventions are used throughout this document:

• Bold font is used in text for options to commands, filenames, keywords, type names, datastructures, and their members.

• Italic strings are used for emphasis or to identify the first instance of a word requiringdefinition. Italics in text also denote:

— Command operands, command option-arguments, or variable names; for example,substitutable argument prototypes

— Environment variables, which are also shown in capitals

— Utility names

— External variables, such as errno

— Functions; these are shown as follows: name( ); names without parentheses are C externalvariables, C function family names, utility names, command operands, or commandoption-arguments.

• Normal font is used for the names of constants and literals.

• The notation <file.h> indicates a header.

• The notation [EABCD] is used to identify an error value EABCD.

Authorization (AZN) API ix

Trademarks

Motif, OSF/1, UNIX, and the ‘‘X Device’’ are registered trademarks and IT DialToneTM andThe Open GroupTM are trademarks of The Open Group in the U.S. and other countries.

x Open Group Technical Standard (2000)

Acknowledgements

The Open Group gratefully acknowledges the the work of DASCOM Inc. in developing thisspecification. In particular, the main authors from DASCOM Inc. are:

Bob BlakleyWarwick BurrowsGreg ClarkAdam MurdochFrank Siebenlist

Members of The Open Group Security Program Group have contributed to this specification byreviewing drafts. In particular, thanks are due to the representatives from the followingcompanies:

Hewlett-Packard CompanyIBM CorporationSun Microsystems, Inc.Entrust TechnologiesBaltimore Technologies

Authorization (AZN) API xi

Referenced Documents

The following documents are referenced in this Technical Standard:

ACFAccess Control Framework for Distributed Applications, draft-ietf-cat-acc-frmw-01.txt,11/17/1998.

AZN_RqtsAuthorization Service API Requirements, Draft 0.3, The Open Group Security ProgramGroup, 10/16/1998.

COSCORBA Services: Common Object Services Specification, Chapter 15: Security ServiceSpecification, OMG.

DCE_DSSCAE Specification, August 1997, DCE 1.1: Authentication and Security Services (C311),published by The Open Group.

GAAGeneric Authorization and Access control Application Program Interface, C bindings,draft-ietf-cat-gaa-cbind-01.txt, 11/1998.

ISO/IEC 7498-2The ISO Security Architecture, ISO/IEC 7498.2.

ISO/IEC 10181-3The Access Control Framework, ISO/IEC 10181-3.

RFC1508Generic Security Service API, IETF-RFC 1508, J. Linn, 9/1993.

RFC1509Generic Security Service API: C-bindings, IETF-RFC 1509, J. Wray, 9/1993.

UTF-8UTF-8, a transformation format for Unicode and ISO 10646, ietf-rfc 2044, October 1996.

XDASPreliminary Specification, January 1997, Distributed Audit Service (XDAS)(ISBN: 1-85912-139-X, P441), published by The Open Group.

XGSSExtended Generic Security Service APIs: XGSS-APIs, Access control and delegationextensions, draft-ietf-cat-xgssapi-acc-cntrl-03.txt, 11/09/1998.

xii Open Group Technical Standard (2000)

Chapter 1

Introduction

Authorization is often defined as:

The granting of access rights to a subject (for example, a user, or program)

This definition, however, does not draw a strong enough distinction between:

1. The administrative act of asserting that a subject should be granted a set of privilegeattributes

and

2. The operational act of allowing a subject to access a resource after determining that he, she,or it has been granted the required set of privilege attributes

Acts 1 and 2 could both be described as ‘‘granting access rights to a subject’’.

Because of this ambiguity, it is useful to distinguish between privilege attribute administration andaccess control . Act 1 is a privilege attribute administration task, whereas act 2 is an access controltask.

ISO 7498-2, the ISO Security Architecture, defines access control as

The prevention of unauthorized use of a resource, including the prevention of use of a resourcein an unauthorized manner.

This document defines an Application Programming Interface (API) for access control. This APIis designed to be used in systems whose access control facilities conform to the architecturedescribed in ISO 10181-3 — Access Control Framework. The API defined in this document doesnot provide for privilege attribute administration, although it does provide facilities which allowa subject to control which of its privilege attributes are used to authorize a particular accessrequest (such facilities are often called least privilege).

The API defined in this document is called the aznAPI; ‘‘azn’’ is an abbreviation of‘‘AuthoriZatioN’’.

Authorization (AZN) API 1

Introduction

2 Open Group Technical Standard (2000)

Chapter 2

Objectives

2.1 GoalsThe following were design goals for this Authorization API:

• Define a simple, flexible Application Programming Interface through which authorizationfunctionality can be invoked by both providers of security components and developers ofsecurity-aware applications.

• Enable application-transparent evaluation of policy rules to arrive at access decisions.

• Enable central management of policy independent of applications.

• Transparently support a wide variety of authorization policy rule syntax and semantics (forexample, ACLs, capabilities, labels, logical predicates, and so on).

• Separate authentication from authorization.

• Permit derivation of authorization attributes from authentication data.

• Transparently support any reasonable authorization attribute type (for example, accessidentities, groups, roles, clearances, and so on).

• Facilitate authorization in multi-tiered applications.

• Permit externalization of authorization attributes for use in multi-tier applicationconfigurations.

• Enable applications to access security policy (entitlement) information applicable to theirresources.

• Support a variety of access control mechanisms as implementations of the API.

• Enable simultaneous use by a single application of multiple authentication and authorizationservices.

• Support application access to audit data related to the operation of the authorization service.

2.2 Non-GoalsThe following were not design goals for this API:

• Define an API for the administration of authorization policy.

• Specify a service, or semantics, for delegation of credentials.

• Specify an audit service API.

• Specify how and when authorization services should generate audit events.

• Define an interoperable PAC format for the exchange of credential information betweenheterogeneous aznAPI implementations. (This could be a goal of a future standardizationeffort or of a future revision of this standard.)


Non-Goals Objectives

• Support every possible authorization policy rule syntax and semantics. (Some policysemantics, for example, "four eyes" policies, may not be supportable by this version of theaznAPI.)


Chapter 3

Architectural Overview

The authorization API defined in this Technical Standard is intended to be used within thearchitectural framework defined in ISO 10181-3 — Access Control Framework. This chapterbriefly introduces that framework. Readers are encouraged to consult ISO 10181-3 for moredetailed information.

This authorization API defines a programmatic interface through which system components thatneed to control access to resources can request an access control decision from the system’s accesscontrol service.

The ISO 10181-3 access control framework supports access control in both standalone andnetworked systems. When this document refers to the system, it means ‘‘the computer orcollection of networked computers whose resources are protected by the access control servicewhich is invoked using the authorization API.’’


ISO 10181-3 Access Control Framework Architectural Overview

3.1 ISO 10181-3 Access Control FrameworkThe ISO 10181-3 Access Control Framework is illustrated in Figure 3-1.

The framework defines four roles for components participating in an access request:

• Initiators

• Targets

• Access Control Enforcement Functions (AEFs)

• Access Control Decision Functions (ADFs)

Initiators submit access requests. An access request specifies an operation to be performed on aTarget.

Access Control Enforcement Functions (AEFs) mediate access requests. AEFs submit decisionrequests to Access Control Decision Functions (ADFs). A decision request asks whether aparticular access request should be granted or denied.

ADFs decide whether access requests should be granted or denied.

Figure 3-1 ISO 10181-3 Access Control Framework


Architectural Overview Access Control Service Components

3.2 Access Control Service ComponentsThe access control service consists of the system components assuming the roles of ADFs andAEFs.

3.2.1 Access Control Decision Functions

ADFs make access control decisions based on Access Control Decision Information (ADI). ADIdescribes security-relevant properties of the initiator, the target, the access request, and thesystem and its environment. ADI is discussed in more detail in Section 3.3 on page 9.

Figure 3-2 shows the information an ADF uses to make an access control decision.

Figure 3-2 Inputs to an Access Decision Function (ADF)


Access Control Service Components Architectural Overview

3.2.2 Access Control Enforcement Functions

Access Control Enforcement Functions enforce access control decisions made by ADFs.

The authorization API (referred to hereafter as aznAPI) is the medium through which AEFs callon ADFs to obtain access control decisions. AEFs use the aznAPI to present Access ControlInformation (ACI) to ADFs. As Figure 3-3 illustrates, the implementation of the aznAPI isresponsible for deriving ADI from the ACI provided by an AEF and presenting the ADI to anADF. The ADF then uses this ADI, together with access control policy rules and with contextADI it derives from its environment, to make an access decision.

Figure 3-3 AEFs Use the Authorization API to Call ADFs


Architectural Overview Access Control Information

3.3 Access Control InformationAccess Control Information, or ACI, is the set of all the information available to an AEF whichmight be relevant to an access control decision. The aznAPI is responsible for:

• Determining which of the ACI presented by the AEF is relevant to the access control decisionthe AEF requested

• Transforming the ACI presented by the AEF into ADI in a form which can be used by theADF

• Presenting the resulting ADI to the ADF

There are several kinds of Access Control Information. The main kinds describeauthorization-relevant properties of the initiator, the target, the access request, and the contextwithin which the request was made.

3.3.1 Initiator Information

Initiator information describes security-relevant properties of the initiator of an access request:

• Initiator ACI is the initiator information which is available to AEFs.

• Initiator ADI is the initiator information which results from the aznAPI’s transformation ofinitiator ACI and is made available to ADFs.

Initiator ACI

An initiator ACI data structure which is produced by an authentication service is called (in thisspecification) an identity . Identities may be as simple as a string containing the initiator’s name,or they may be as complex as an X.509 digital certificate.

The aznAPI may also accept a capability as an Identity. A capability is a direct assertion by anauthentication service of the capability holder’s authorization to perform specific operations onspecific targets. As Figure 3-4 shows, a capability is asserted (using a signature, for example) bysome authority. A capability does not necessarily name its initiator; whoever possesses acapability can use it. In Figure 3-4, this is indicated by the dotted line around the initiatoridentity. Finally, a capability contains a list of policy entries. Each entry names a target objectand defines a rule which describes the operations which it allows the initiator to perform.

Note that aznAPI implementations are not required to support any particular identity format,and are specifically not required to support capabilities.


Access Control Information Architectural Overview

Figure 3-4 A Capability

An initiator ACI data structure which is produced by an authorization service (using theaznAPI’s credential externalization function) is called a PAC. Note that authorization servicesare not the only things which can create PACs. Authentication services also create PACs toassert users’ identities. In push-model environments, they are the user’s privilege attributes.(aznAPI implementations treat PACs created by authentication services as Identities in order todistinguish them from the authorization data structures they create themselves.) aznAPIimplementations might even use PAC data structures to contain their internal representations ofuser credential information, but these data structures are not exposed to AEFs through theaznAPI. PACs are discussed in more detail in Section 3.3.7 on page 14.

Initiator ADI

Initiator ADI is the authorization-relevant data which is derived from Initiator ACI, and passedto ADFs by the aznAPI. Initiator ADI is stored by the aznAPI in structures called ‘‘credentials’’chains. Since credentials chains are never passed to callers of the aznAPI, and since differentauthorization services may use different credentials chain formats, the format of credentialschain data structures is not defined or constrained by the aznAPI specification.

Although the aznAPI does not allow callers to access credentials chains directly, it does providefunctions through which attribute information may be retrieved from credentials chains.

Figure 3-5 shows how the aznAPI transforms Initiator ACI into credentials chains, and returns acredential handle to the caller. Note that the aznAPI can be used in systems which "push"privilege attributes from clients to AEFs, or in systems which require AEFs to "pull" privilegeattributes from a repository or service. In push-model environments, the Initiator ACI willcontain the privilege attributes pushed by the client, and will be translated into an internallyusable form by the aznAPI implementation. In pull-model environments, the Initiator ACItypically contains only a single privilege attribute (for example, the authenticated name of theInitiator), and the aznAPI implementation pulls the rest of the Initiator’s privilege attributesfrom the appropriate repository or structure during construction of the Initiator’s credentialschain.



Figure 3-5 Transforming Initiator ACI into a Credential

3.3.2 Target Information

Target information describes security-relevant properties of the target of an access request:

• Target ACI is the target information which is available to AEFs.

• Target ADI is the target information which results from the aznAPI’s transformation of targetACI.



Target ACI

Normally the only ACI data which the aznAPI requires is the name of the target.

Labels are an exception to this rule. The aznAPI has been designed to support access controldecisions based on ADI contained in security labels. In some label-based authorization systems,however, the authorization service may not know how label information is encoded into thetarget, or how it is stored as metadata associated with the target. In these cases, the AEF needsto retrieve the target’s labels and pass them to the aznAPI as target ACI. The aznAPI alsosupports implementations which can handle several different types of labels. Implementationswhich support multiple label types may require their callers to specify a labeling scheme IDidentifying which type of label is being used in a particular call.

Target ADI

Different authorization service implementations may have very different types and amounts oftarget ADI data. Target ADI data is generally not returned to callers of the aznAPI, so the formatof target ADI data is not defined or constrained by the aznAPI specification.

Some callers of the aznAPI may want to use authorization policy data for purposes other thanmaking access control decisions. For this reason, the aznAPI supports externalization of ADIdata into data structures called entitlements. Entitlements are discussed in more detail in Section3.3.7.

3.3.3 Request Information

Request information describes security-relevant properties of an access request:

• Request ACI is the request information which is available to AEFs.

• Request ADI is the request information which results from the aznAPI’s transformation ofrequest ACI.

Request ACI

The only ACI data which the aznAPI requires is the name of the operation which was requested.

Request ADI

Different authorization service implementations may have very different types and amounts ofrequest ADI data. Request ADI data is not returned to callers of the aznAPI, so the format ofrequest ADI data is not defined or constrained by the aznAPI specification.

3.3.4 Context Information

Context information describes security-relevant properties of the context in which an accessrequest occurs. Context ACI is the context information which is available to AEFs.

There are two sources of context ADI:

• The first source is the context information which results from the aznAPI’s transformation ofcontext ACI.

• The second source is context information which was not provided as ACI but which isdirectly accessible to the authorization service.



Context ACI

The aznAPI defines four Context ACI data types which can be used to pass context informationto authorization services:

• Time:The time at which the request occurred.

• Location:The location (source address) from which the request was initiated.

• Route:The security characteristics of the connection over which the request was transmitted fromthe initiator to the AEF.

• Quality of Authentication:The quality of authentication used to establish the initiator’s identity.

In addition, the aznAPI allows AEFs to pass application-specific or authorization-service-specificcontext information, not limited to the above types, to authorization services using anopaquely-typed parameter. Use of this functionality will result in applications which cannotportably use authorization services which do not support the particular context informationformat passed through the opaque parameter.

Context ADI

Different authorization service implementations may have very different types and amounts ofcontext ADI data. Context ADI data is not returned to callers of the aznAPI, so the format ofcontext ADI data is not defined or constrained by the aznAPI specification.

3.3.5 Retained Information

The authorization service may retain information to make access control decisions aboutsequences of operations requested by the same initiator. For example, an authorization serviceused by a bank’s Automated Teller Machine (ATM) network might retain information about howmuch money each user has withdrawn during the day in order to enforce a daily withdrawallimit policy.

Information retained by the authorization service for this purpose is ADI, and is never exposedto applications by the aznAPI. Therefore, the format of retained ADI is not defined orconstrained by the aznAPI specification (retained ADI might in some circumstances be ofinterest to applications, but exposing retained ADI is not supported by this version of aznAPI).

3.3.6 Access Control Policy Information

Access Control Policy Information consists of the rules which the ADF uses to evaluate the othertypes of ADI and make an access control decision. The aznAPI does not normally make accesscontrol policy information available to callers, and different authorization services may use verydifferent types and amounts of access control policy information, so the format of access controlpolicy information is not defined or constrained by the aznAPI specification. Authorizationservices can, however, externalize access control policy information in the form of entitlements,as described in Section 3.3.7.



3.3.7 Externalizing ADI

The aznAPI deliberately hides the details of initiator ADI and access control policy informationfrom its callers. However, this information can be useful to callers under some circumstances.Therefore, the aznAPI allows authorization services to externalize initiator ADI and accesscontrol policy information.

PACs

The aznAPI puts externalized initiator ADI into a structure called a PAC. Figure 3-6 illustratesthe creation of a PAC.

Figure 3-6 Externalization of Credentials into a PAC

Externalization of initiator ADI allows the authorization service to assert its view of thesecurity-relevant characteristics of the initiator, as distinct from the authentication service’s viewof the same initiator’s security-relevant characteristics.

An authorization service could (but is not required to) use this functionality to generate signedattribute certificates which other services could rely on as sources of authorization data.

Because this specification defines only an opaque PAC structure, PACs produced by oneauthorization service are not guaranteed to be usable by another authorization service.However, a standard PAC structure could be defined in a future specification as the basis forinteroperable assertion of initiators’ authorization attributes by authorization services.



Note: It is important to note that Signed PACs can be used as building blocks whenconstructing delegation protocols. The aznAPI does not, however, provide adelegation service. A delegation protocol must allow entities which wish to becomedelegates for requests received from an initiator to pass the following to a target:

1. The delegated request

2. A trustworthy indication that the request originally received from the initiatorwas authenticated

3. A trustworthy representation that the delegate is authorized to forward therequest to the target on the initiator’s behalf

4. A trustworthy representation of the initiator’s and the delegate’s credentialinformation

Although the authorization service may sign PACs to form trustworthy representations ofinitiators’ and delegates’ credential information, and may even include identity information(such as a certificate issuer identity and identity certificate serial number) in a signed PAC toestablish a link to the authentication data of the initiator, it does not bind PACs to requests(cryptographically or in any other way). AEFs which wish to impersonate or otherwise serve asdelegates for initiators must use a separate cryptographic facility or delegation service to bindthe PACs generated using the aznAPI to delegated request messages.

Note: The term delegation is used here in the sense in which the DCE and SESAME systemsuse the term. Delegation is thus the security function through which an intermediaryissues a request for access to a protected resource on behalf of an initiator fromwhich it has itself received an access request. Other documents, notably X.509, usethe term delegation with a different sense.

Entitlements

The aznAPI puts externalized access control policy information into structures calledentitlements.

Externalization of access control policy information allows applications to customize thebehavior of the system based on authorization policy. For example, it allows applications tomodify system menus to display only operations which an initiator is permitted to access, ratherthan displaying all system operations and responding to the initiator’s attempts to performprohibited operations with an access denied message. Entitlement information could also be usedby applications which want to make their own access decisions rather than relying on the ADFimplemented by the authorization service.

The aznAPI defines a portable format for entitlement data that every authorization service cansupport — a list of the operations a particular initiator may (or may not) perform on a particulartarget. Figure 3-7 shows this format. Note that the dotted line around the subject data indicatesthat the initiator information is implicit; it is not returned by the aznAPI as part of theentitlement data.



Figure 3-7 Portable Entitlements

The portable entitlement data representation is guaranteed to be supportable by allauthorization service implementations, but it is not very efficient. Some authorization servicesmay be able to express an initiator’s authorizations to many operations on many targets using asingle rule, or using a wildcarded expression. They may even be able to describe manyinitiators’ authorizations in a single rule or expression. However, different authorizationservices use different rule formats, and there is no single rule format which can express allauthorization services’ rules efficiently. For this reason, the aznAPI allows authorizationservices to return non-portable entitlement information through an opaquely-typed parameter.As Figure 3-8 illustrates, non-portable entitlement data may be in any rule format.

Figure 3-8 Non-Portable Entitlements

Use of non-portable entitlements requires the application calling the aznAPI to understand theauthorization service’s rule format, and prevents the application calling the aznAPI from usingother authorization services with different rule formats.


Chapter 4

Authorization API Usage Model

4.1 System StructureFigure 4-1 illustrates the structure of a system which uses the aznAPI.

Figure 4-1 aznAPI System Structure

Resource requests in a system using the aznAPI are mediated by Access Enforcement Functions(AEFs).

AEFs authenticate users (often using Authentication Services). They also authorize requests bypassing Access Control Information (ACI) to the Authorization API (aznAPI). They fulfillauthorized requests and reject unauthorized requests.

The aznAPI translates ACI received from AEFs into Access Control Decision Information (ADI).The aznAPI also uses Access Decision Functions (ADFs) to make access decisions.

ADFs use ADI and Access Policy Rules to decide whether an initiator’s request to perform anoperation on a target should be permitted or denied.


Supported Functions Authorization API Usage Model

4.2 Supported FunctionsTable 4-1 lists the families of functions provided by the aznAPI and briefly describes what eachfamily of functions does._______________________________________________________________________________________________

Interface Family Name Prefix Interface Family Supported Functions_______________________________________________________________________________________________Initialize aznAPI implementation

Clean up aznAPI implementation in preparation for shutdown

azn_initialize, azn_shutdown

_______________________________________________________________________________________________Create, delete, modify, and combine credentials chains

Get information from credentials chains

Build PAC based on credentials chain

azn_creds

_______________________________________________________________________________________________Build credentials chain based on authenticated identity produced byan authentication service

azn_id

_______________________________________________________________________________________________azn_decision Make an access decision_______________________________________________________________________________________________azn_entitlement Get access control policy information_______________________________________________________________________________________________

Build credentials chain based on PAC produced by an authorizationservice

azn_pac

_______________________________________________________________________________________________Retrieve error information from status values returned by aznAPIfunctions

azn_error

_______________________________________________________________________________________________Discover authentication, authorization, and credentials, label, and pacmechanisms supported by aznAPI implementation

azn_authority

_______________________________________________________________________________________________Create and delete attribute/value pair list

Write parameter data into attribute/value pair list

Read parameter data from attribute/value pair list

azn_attrlist

_______________________________________________________________________________________________azn_release Release data allocated by aznAPI implementation_______________________________________________________________________________________________LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

Table 4-1 aznAPI Functions


Authorization API Usage Model Supported Functions

4.3 State MachineFigure 4-2 summarizes the state machine of application (typically an AEF) which calls theaznAPI. AEFs should call aznAPI functions in the sequence indicated in Figure 4-2. Note thatthe state machine in Figure 4-2 is only a summary overview and does not enumerate all thestates the caller of an aznAPI implementation can take on. Note also that, since AEFs callauthentication service functions through APIs other than aznAPI, not every state transition inFigure 4-2 is caused by an aznAPI function call.

Table 4-2 indicates the aznAPI function calls or other AEF operations which cause transitionsfrom one state to another.

Figure 4-2 aznAPI State Machine Summary


State Machine Authorization API Usage Model

_________________________________________________________________________________________Transition Operation Causing Transition_________________________________________________________________________________________

AEF gets request whose initiator has been authenticated by authentication service1_________________________________________________________________________________________2 AEF gets request; AEF authenticates initiator_________________________________________________________________________________________

AEF gets request whose initiator is described by a PAC produced by an aznAPIimplementation

3

_________________________________________________________________________________________AEF calls azn_decision_access_allowed( ) to authorize request (credentials chain is builtimplicitly by authorization service using authentication service’s identity obtainedfrom environment)

4

_________________________________________________________________________________________AEF calls azn_id_get_creds( ) with null ID (authorization service uses authenticationservice’s identity obtained from environment)

5

_________________________________________________________________________________________AEF calls azn_id_get_creds( ) with ID AEF generated when it authenticated initiator6_________________________________________________________________________________________AEF calls azn_pac_get_creds( )7_________________________________________________________________________________________AEF calls azn_creds_combine( ) to add its credentials chain to that of the initiator8_________________________________________________________________________________________AEF calls azn_creds_modify( ) to change the attributes of the credentials chain9_________________________________________________________________________________________AEF calls azn_creds_modify( ) to change the attributes of the credentials chain10_________________________________________________________________________________________AEF calls azn_decision_access_allowed( )11_________________________________________________________________________________________AEF calls azn_creds_get_pac( )12_________________________________________________________________________________________AEF calls azn_creds_get_pac( )13_________________________________________________________________________________________AEF calls azn_decision_access_allowed( )14_________________________________________________________________________________________LL

LLLLLLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLLLLLLLL

Table 4-2 aznAPI State Machine Transitions

The state machine in Figure 4-2 is divided into three phases:

1. Credential EstablishmentDuring this phase, represented by the leftmost column of states after the start state, theAEF uses the aznAPI to establish credentials chain which the authorization service will useas the basis for later operations.

2. Credential ModificationDuring this phase, represented by the second column to the right of the start state, the AEFmodifies the initiator’s credentials chain, either by changing the attributes contained in it orby combining its own credentials chain with the initiator’s.

3. Credential UseDuring this phase, represented by the rightmost column, the AEF uses the credentialschain, either to make authorization decisions or to create PACs which it can pass to otherAEFs.

Functions Not Included in State Diagram

Figure 4-2 Some functions of the aznAPI have been omitted from the summary state diagramshown in Figure 4-2 for purposes of simplicity. The omitted functions include:

• HousekeepingThese include initialization and shutdown of the aznAPI. Initializaion must be done beforeany other aznAPI function is used. Shutdown should be done after the last call to an aznAPIfunction and before the AEF exits.

• Memory ManagementThese functions include creation and deletion of credentials chain and attribute list datastructures. These data structures must be created before they can be used. Note especially


Authorization API Usage Model State Machine

that the calls which build credentials chains (azn_id_get_creds( ) and azn_pac_get_creds( ))assume that memory for the credentials chain has already been allocated via a call toazn_creds_create( ). Memory for credentials chain and attribute data structures is not releasedby the authorization service; AEFs must release the memory by using the azn_release calls orazn_credential_delete( ).

• Error Information RetrievalThese calls should be used after an error status has been returned by a call to another aznAPIfunction.

• Credential Information RetrievalThese calls can be used any time after establishment of a credentials chain.

• EntitlementThese calls can be used any time after establishment of a credentials chain.

4.4 Trust ModelEach component of a secure system needs to know which other components can be trusted, andwhat they can be trusted to do. This section describes the trust relationships among thecomponents of a system which uses the aznAPI.

4.4.1 Relationship between Authentication and Authorization

The aznAPI separates authentication from authorization, as illustrated in Figure 4-3.

Figure 4-3 Relationship between Authentication and Authorization

The initiator may use an authentication service to create an "Identity" which is received by anAEF along with the initiator’s request to access a target.

The AEF calls the aznAPI to transform the initiator’s identity into a credentials chain, which canbe used to make access control decisions.


Trust Model Authorization API Usage Model

The AEF may, if it needs to pass the initiator’s request on to another AEF for fulfillment, call theaznAPI to transform the credentials chain into a PAC, which represents the authorizationservice’s view of the initiator (rather than the authentication service’s view, which wasrepresented by the Identity).

Another AEF receiving this PAC is able to transform it into a credentials chain, which can beused to make access control decisions.

In a system using the aznAPI, therefore:

• Authentication data is always represented by an Identity.

• Initiator ACI, which is authorization data about the initiator, is always represented inside theauthorization service as a credentials chain.

• Initiator ACI, which is authorization data about the initiator, is always represented outsidethe authorization service as a PAC.

It is therefore always possible to distinguish authentication data and authorization data, and theauthorization service never uses one type of data where another is required. In particular, theauthorization service never uses authentication data to make an access decision.

It is up to AEFs to make trust decisions about authentication data; an aznAPI implementationdoes not make trust or authenticity judgments about the identities passed to it by AEFs.


Authorization API Usage Model Trust Model

4.4.2 TCB Boundary

Figure 4-4 indicates that the AEF, the aznAPI, the ADF, the PAC Service, the authenticationservice, and any authentication mechanisms used by the authentication service, are all inside thetrusted computing base (TCB) of the system and thus need to be protected against unauthorizedmodification.

Figure 4-4 Trust Relationships in an aznAPI System

The components of the system have the following trust relationships:

• The owner of a target resource trusts the AEF, and implicitly the authentication andauthorization services (everything inside the outer dark gray box) to prevent unauthorizedinitiators from accessing the target.

• The authentication service trusts its authentication mechanisms to function correctly andprovide a correct identity for the initiator.

• The AEF trusts the authentication service, and implicitly its authentication mechanisms, toprovide a correct, authenticated identity for the initiator.

• The aznAPI trusts the AEF to provide correct ACI.

• The AEF trusts the aznAPI, and implicitly the authorization service, to make and returncorrect access decisions and to return correct PACs, entitlements, and credentials chainprivilege attributes.


Trust Model Authorization API Usage Model

• The aznAPI trusts its implementation (and the underlying initiator security attributerepository) to translate initiator identities into credentials chains correctly.

• The aznAPI trusts the PAC service to generate PACs from credentials chains correctly, and toreturn credentials chains’ privilege attributes correctly.

• The aznAPI implementation and the PAC service trust the security attribute repository tocontain correct information.

• The aznAPI trusts the authorization service’s ADF (and the underlying access control policyrepository) to make correct access decisions.

• The aznAPI trusts the authorization service’s entitlement service, or ES, and the underlyingaccess control policy repository, to return entitlements correctly.

• The ADF and the ES trust the access control policy repository to contain correct information.


Chapter 5

Required Functionality and Portability

5.1 Required FunctionalityAll aznAPI implementations are required to support the functionality described in this section.

5.1.1 Functions

The functions listed in Table 5-1 must be implemented as specified in the function call definitionsin Chapter 7 on page 37, by all conformant aznAPI implementations:

__________________________________________________________________azn_attrlist_* /* all attrlist calls */azn_creds_createazn_creds_deleteazn_decision_access_allowedazn_error_* /* all error calls */azn_id_get_credsazn_initializeazn_release_* /* all release calls */azn_shutdown__________________________________________________________________LLLLLLLLLLL

LLLLLLLLLLL

Table 5-1 Mandatory Function Calls in Conformant aznAPI Implementation

Functions defined in but not listed in Table 5-1 must be implemented but need not support all (orany) of the functionality described in Chapter 7; instead, they may returnAZN_S_UNIMPLEMENTED_FUNCTION in response to those calls.

5.1.2 Authorities, Services, Schemes, and Mechanisms

All aznAPI implementations must support the use of AZN_NULL_ID to specify a defaultauthority and to specify a default mechanism_id.

aznAPI implementations which provide entitlements services, labeling schemes, credentialmodification services, and/or pac services must support the use of AZN_NULL_ID to specifydefault providers of these services or schemes.

aznAPI implementations are not required to support any explicit authority, scheme, mechanism,or service IDs.

Future supplemental standards may define standard portable sets of authority, scheme,mechanism, and service IDs.


Required Functionality Required Functionality and Portability

5.1.3 Attributes

All aznAPI implementations must be able to return the AZN_C_VERSION attribute and itsstring value from azn_initialize( ).

5.2 PortabilityApplications which restrict their use of the aznAPI to the functionality described in the previoussection will be portable across aznAPI implementations if those implementations support theirresource and operation names.

5.2.1 Resource and Operation Names

This specification does not define standard namespaces or name syntaxes for protectedresources or operations. Future supplemental standards may define standard, portablenamespaces and/or name syntaxes for resources and operations. For example, a future standardmight mandate that all protected resource names must be expressed as URIs.

Until standard namespaces and name syntaxes for protected resources and operations aredefined, application developers will need to check their aznAPI documentation to ensure thattheir resource names and operations are supported by an aznAPI implementation.


Chapter 6

Parameter Passing Conventions

This chapter describes the data types and constants used by the aznAPI functions. It alsoexplains calling conventions for these functions.

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

6.1 Structured Data TypesThis chapter describes the structured data types required by aznAPI routines but not alreadydefined in C.

6.2 String Data and Similar Data

6.2.1 Buffers

A number of aznAPI routines take memory buffer arguments or return memory buffer values.Memory buffer data is passed between the aznAPI and the caller using a byte buffer describedby the azn_buffer_t data type. This data type is a pointer to a buffer descriptor consisting of alength field which contains the total number of bytes in the data, and a value field, whichcontains a pointer to the actual data:

typedef structazn_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 valueAZN_C_EMPTY_BUFFER.

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

6.2.2 Character Strings

A number of aznAPI routines take character strings as arguments or return character strings asvalues. Character string data is passed between the aznAPI and the caller using the azn_string_tdata type:

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 portableformat.

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


String Data and Similar Data Parameter Passing Conventions

6.2.3 Credential Handles

A number of aznAPI routines take credential handles as arguments or return credential handlesas values. Credential handles are passed between the aznAPI and the caller using theazn_creds_h_t data type:

azn_creds_h_t

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

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

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

6.2.4 Attribute List Handle

A number of aznAPI routines take attribute list handles as arguments or return attribute listhandles as values. Attribute list handles are passed between the aznAPI and the caller using theazn_attrlist_h_t data type:

azn_attrlist_h_t

A variable of type azn_attrlist_h_t is an opaque handle which refers to a list of name-value pairsmaintained by the aznAPI implementation. The aznAPI provides interfaces for retrievingname-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 handleby calling azn_attrlist_create( ), which allocates a new, empty attribute list structure, associates itwith a handle, and returns the handle.

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

6.3 Status ValuesaznAPI routines return a status code of type azn_status_t:

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 completionof 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 codesare defined in the standard and are implementation independent. The minor error codes areimplementation dependent, and their values and meanings should be recorded in theimplementation 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 Table 6-1.


Parameter Passing Conventions Status Values

Table 6-1 Major Error Codes________________________________________________________________________________________________

Name Value MeaningLL LL LL LL________________________________________________________________________________________________[AZN_S_COMPLETE] 0 Successful completion.________________________________________________________________________________________________

An implementation specific error or failure hasoccurred.

[AZN_S_FAILURE] 1

________________________________________________________________________________________________[AZN_S_AUTHORIZATION_FAILURE] 2 The caller does not possess the required authority.________________________________________________________________________________________________

The credential handle supplied does not point to avalid credentials chain.

[AZN_S_INVALID_CREDS_HDL] 3

________________________________________________________________________________________________The credential handle supplied does not point to avalid credentials chain.

[AZN_S_INVALID_NEW_CREDS_HDL] 4

________________________________________________________________________________________________The attribute entitlements service identifier isinvalid.

[AZN_S_INVALID_ENTITLEMENTS_SVC] 5

________________________________________________________________________________________________The credential handle supplied does not point to avalid credentials chain.

[AZN_S_INVALID_COMB_CREDS_HDL] 6

________________________________________________________________________________________________The supplied security mechanism information isnot valid or is in error.

[AZN_S_INVALID_MECHANISM_INFO] 7

________________________________________________________________________________________________[AZN_S_INVALID_MECHANISM] 8 The mechanism identifier is invalid.________________________________________________________________________________________________[AZN_S_INVALID_STRING_VALUE] 9 The supplied string value is invalid.________________________________________________________________________________________________[AZN_S_UNKNOWN_LABEL] 10 The label supplied is not valid.________________________________________________________________________________________________

The credential handle supplied does not point to avalid credentials chain.

[AZN_S_INVALID_ADDED_CREDS_HDL] 11

________________________________________________________________________________________________[AZN_S_INVALID_PROTECTED_RESOURCE] 12 The protected resource identifier is invalid.________________________________________________________________________________________________[AZN_S_INVALID_OPERATION] 13 The specified operation on the resource is invalid.________________________________________________________________________________________________

The privilege attribute certificate structure isinvalid.

[AZN_S_INVALID_PAC] 14

________________________________________________________________________________________________The privilege attribute certificate service identifieris invalid.

[AZN_S_INVALID_PAC_SVC] 15

________________________________________________________________________________________________- 16 Unused.________________________________________________________________________________________________

The credential modification function identifier isinvalid.

[AZN_S_INVALID_MOD_FUNCTION] 17

________________________________________________________________________________________________The number used to index an individual credentialis invalid.

[AZN_S_INVALID_SUBJECT_INDEX] 18

________________________________________________________________________________________________The functionality of this function is notimplemented by the underlying implementation.

[AZN_S_UNIMPLEMENTED_FUNCTION] 19

________________________________________________________________________________________________[AZN_S_INVALID_ATTRLIST_HDL] 20 The attribute list handle is invalid.________________________________________________________________________________________________[AZN_S_INVALID_ATTR_NAME] 21 The attribute name is invalid.________________________________________________________________________________________________[AZN_S_INVALID_BUFFER] 22 The buffer is invalid.________________________________________________________________________________________________[AZN_S_INVALID_BUFFER_REF] 23 The buffer reference is invalid.________________________________________________________________________________________________[AZN_S_INVALID_STRING_REF] 24 The string reference is invalid.________________________________________________________________________________________________[AZN_S_ATTR_VALUE_NOT_STRING_TYPE] 25 The returned entry value is not type string.________________________________________________________________________________________________

The index value for the multi- valued attribute isinvalid.

[AZN_S_ATTR_INVALID_INDEX] 26

________________________________________________________________________________________________[AZN_S_INVALID_INTEGER_REF] 27 The integer reference is not valid.________________________________________________________________________________________________

The integer reference for the permission is notvalid.

[AZN_S_INVALID_PERMISSION_REF] 28

________________________________________________________________________________________________LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL




Status Values Parameter Passing Conventions

________________________________________________________________________________________________Name Value MeaningLL LL LL LL________________________________________________________________________________________________

[AZN_S_INVALID_AUTHORITY] 29 The authorization authority ID is invalid.________________________________________________________________________________________________The attribute list handle for the application contextis invalid.

[AZN_S_INVALID_APP_CONTEXT_HDL] 30

________________________________________________________________________________________________The attribute list handle for the entitlements isinvalid.

[AZN_S_INVALID_ENTITLEMENTS_HDL] 31

________________________________________________________________________________________________The labeling scheme identifier is unknown orinvalid.

[AZN_S_INVALID_LABELING_SCHEME] 32

________________________________________________________________________________________________The attribute list handle for the initialization datais invalid.

[AZN_S_INVALID_INIT_DATA_HDL] 33

________________________________________________________________________________________________The attribute list handle for the returnedinitialization info is invalid.

[AZN_S_INVALID_INIT_INFO_HDL] 34

________________________________________________________________________________________________[AZN_S_ATTR_VALUE_NOT_BUFFER_TYPE] 35 The returned entry value is not type buffer.________________________________________________________________________________________________

A function other than azn_attrlist_*( ) orazn_error_*( ) has been called before azn_initialize( ).

[AZN_S_API_UNINITIALIZED] 36

________________________________________________________________________________________________azn_initialize( ) has been called twice without anintervening call to azn_shutdown ( ).

[AZN_S_API_ALREADY_INITIALIZED] 37

________________________________________________________________________________________________LLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLL



Invalid Handle Error Status Returns

Many aznAPI function calls can return major status codes indicating that they have been passedan invalid handle (AZN_S_INVALID_CREDS_HDL is an example of such a major status code).

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

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

6.4 ConstantsVarious aznAPI routine arguments accept parameters for which standard values are defined asconstants in this specification.

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

The azn_decision* functions return a signed integer permission argument. Legal values of thatargument are shown in Table 6-2.______________________________________________________________________________________________

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.______________________________________________________________________________________________LL

LLL

LLLLL

LLLLL

LLLLL

Table 6-2 Permission Constants


Parameter Passing Conventions Constants

Parameters of the type azn_buffer_t can be assigned and compared with the constant valuesshown in Table 6-3.______________________________________________________________________________________________

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

LLL

LLLLL

LLLLL

LLLLL

Table 6-3 Optional Parameter Constants

A number of names have been defined in Table 6-4 for essential access control attributes, toensure that applications can submit and/or request this information through the azn-interface ina portable way.

A credential handle refers to a credentials chain consisting of the credentials of the initiator and aseries 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 chainis the credential of the initiator of the request. The constant [AZN_C_INITIATOR_INDEX] canbe used in the azn_creds_get_attrlist_for_subject( ) and azn_creds_for_subject( ) to refer to theinitiator’s credential.

The azn_creds_get_attrlist_for_subject( ) function allows aznAPI callers to retrieve attributes froma credential, but this specification does not define the complete set of attributes which mayappear 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 arequest 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 nameattribute is specified by the constant [AZN_C_AUDIT_ID] from the attribute list returned byazn_creds_get_attrlist_for_subject( ). Note (as Figure 4-4 on page 23 illustrates) that aznAPI callersare inside the Trusted Computing Base of the system, and are responsible for proper handling ofaudit ID information. Specifically, callers of the aznAPI must ensure that they do not revealaudit IDs to any application outside the system’s TCB.

Several aznAPI functions accept context ACI as a parameter. Almost any kind of informationcould be used as context ACI, so the context ACI argument type in these functions is an attributelist. However, four types of context ACI are common to many authorization serviceimplementations and are explicitly called for in the ISO 10181-3 specification, so portableattribute names and corresponding attribute value types have been defined to allowimplementations 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 entriescarrying the values of these common types of context information.


Constants Parameter Passing Conventions

______________________________________________________________________________________________Name Value Meaning______________________________________________________________________________________________

An integer representingthe initiator’s subjectindex within thecredentials chain.

[AZN_C_INITIATOR_INDEX] 0

______________________________________________________________________________________________An attribute name; thecorresponding stringvalue will contain asubject’s audit identifier.

[AZN_C_AUDIT_ID] "AZN_AUDIT_ID"

______________________________________________________________________________________________An attribute name; thecorresponding buffervalue will contain a time_tstructure representingtime at which the accessrequest occurred.

[AZN_C_REQUEST_TIME] "AZN_REQUEST_TIME"

______________________________________________________________________________________________An attribute name; thecorresponding stringvalue will describe thestrength and mechanismof authentication used toestablish the initiator’sidentity.

[AZN_C_AUTHN_QUALITY] "AZN_AUTHN_QUALITY"

______________________________________________________________________________________________An attribute name; thecorresponding stringvalue will contain thelocation (source address)from which the requestwas initiated. In the caseof IP addresses, this willconsist of a stringcontaining a standard textrepresentation of thenumeric binary IPaddress.

[AZN_C_REQUESTER_LOC] "AZN_REQUESTER_LOC"

______________________________________________________________________________________________An attribute name; thecorresponding stringvalue will describe thesecurity characteristics ofthe connection over whichthe request wastransmitted from theinitiator to the AEF.

[AZN_C_REQUEST_ROUTE_QOP] "AZN_REQUEST_ROUTE_QOP"

______________________________________________________________________________________________LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL



Table 6-4 Attribute Name Constants


Parameter Passing Conventions Constants

The azn_initialize( ) function can return a version number in an attribute list. The value of thename attribute of the entry in which the version number is returned is shown in Table 6-5.______________________________________________________________________________________________

Name Value Meaning______________________________________________________________________________________________An attribute name; thecorresponding stringvalue will contain adotted-integer versionnumber (for example,‘‘3.3’’) passed back frominitialization.

[AZN_C_VERSION] "AZN_VERSION"

______________________________________________________________________________________________LLLLLLLLLLL

LLLLLLLLLLL

LLLLLLLLLLL

LLLLLLLLLLL

Table 6-5 Initialization Constants

6.5 Authority and Mechanism IDs

6.5.1 Authority , Service, and Scheme IDs

aznAPI implementations may support more than one provider of the following services:

• 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 Chapter 5 on page 25 for a list of required and optionalservices.

If an implementation supports multiple providers of a service, it must identify each providerusing a unique OID. The implementation’s documentation must provide a list of supportedproviders and their OIDs.

Additionally, implementations which support multiple providers of a service must implementthe 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 OIDas an argument to the calls listed above.

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


Authority and Mechanism IDs Parameter Passing Conventions

Applications can select the default provider of a service by passing the constant in Table 6-6 asthe value of the appropriate authority, service, or scheme ID argument to each call whichrequires a provider’s OID.______________________________________________________________________________________________

Name Value Meaning______________________________________________________________________________________________The implementationshould use the defaultprovider of the invokedservice.

[AZN_NULL_ID] ""

______________________________________________________________________________________________LLLLLLL

LLLLLLL

LLLLLLL

LLLLLLL

Table 6-6 Default ID

6.5.2 Authentication Mechanism IDs

The aznAPI defines one function, azn_id_get_creds( ), for the acquisition of credentials chains.The implementation of this function may be able to create credentials chains using Initiator ACIfrom several different authentication mechanisms.

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 determinewhich mechanism’s authentication data is being passed through the mechanism_info argument.All implementations must designate a default mechanism for each authority id. aznAPIapplications calling azn_id_get_creds( ) can select the default authentication mechanism for aprovider by passing AZN_NULL_ID as the value of the mechanism_id argument.

6.5.3 Portability — Authentication Mechanism OIDs

To support portability of applications calling aznAPI implementations supporting multipleauthentication mechanisms, mechanism identifiers and the associated mechanism information(including the identity information data type) are standardized in a registration system managedby The Open Group. In this registration system, The Open Group maintains a unique ObjectIdentifier for each mechanism, and administers the registration of new mechanisms, using theX/Open Object Identifier.

Note: Note that aznAPI implementations are free to use mechanisms with ObjectIdentifiers 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 registeredmechanisms, starting with reference number 1.

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


Parameter Passing Conventions Authority and Mechanism IDs

• Each mechanism includes a specification name, and a detailed description of the datatypethat 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 theauthentication mechanism which was used to create the data passed as the value of themechanism_info argument (or AZN_NULL_ID, as noted above) should be passed as the value ofthe mechanism_id argument.


Parameter Passing Conventions


Chapter 7

Function Call Definitions

This chapter defines the aznAPI’s functions, giving C-bindings.

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 classtogether.


azn_attrlist_add_entry( ) Function Call Definitions

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

SYNOPSISazn_status_tazn_attrlist_add_entry(

azn_attrlist_h_t attr_list /* in */,azn_string_t attr_name /* in */,azn_string_t string_value /* in */

);

DESCRIPTIONThis call adds an entry to the attribute list attr_list . The added entry will have name attr_nameand 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 valuesfor the specified name.

The attr_name and string_value input parameters are copied into a new attrlist entry by theaznAPI implementation; changes to the values of the input parameters after the call completeswill have no effect on the newly added attrlist entry, and in fact the attr_name and string_valueparameters’ storage should be released by the calling application when their values are nolonger 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 errorcodes 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 minorerror codes can be derived from the returned status code with azn_error_minor( ).


Function Call Definitions azn_attrlist_add_entry( )

ERRORSNo other errors are defined.


azn_attrlist_add_entry_buffer( ) Function Call Definitions

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

SYNOPSISazn_status_tazn_attrlist_add_entry(

azn_attrlist_h_t attr_list /* in */,azn_string_t attr_name /* in */,azn_buffer_t buffer_value /* in */

);

DESCRIPTIONThis call adds an entry to the attribute list, attr_list . The added entry will have name attr_nameand 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 valuesfor the specified name.

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


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_INVALID_BUFFER]The attribute buffer is invalid.



Function Call Definitions azn_attrlist_add_entry_buffer( )



azn_attrlist_create( ) Function Call Definitions

NAMEazn_attrlist_create — creates a valid, empty attribute list, assigns it a handle, and returns thehandle.

SYNOPSISazn_status_tazn_attrlist_create(

azn_attrlist_h_t *new_attrlist /* out */);

DESCRIPTIONThis call creates a new, empty attribute list, assigns it a handle new_attrlist , and returns thehandle.

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


PARAMETERS

new_attrlist (out)A reference to the new attribute list handle which will be returned.

RETURN VALUE







Function Call Definitions azn_attrlist_delete( )

NAMEazn_attrlist_delete — deletes the attribute list associated with the attribute list handle.

SYNOPSISazn_status_tazn_attrlist_delete(

azn_attrlist_h_t *old_attrlist /* in, out */);

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


PARAMETERS

old_attrlist (in, out)On input an existing attribute list handle.

RETURN VALUE







azn_attrlist_get_entry_buffer_value( ) Function Call Definitions

NAMEazn_attrlist_get_entry_buffer_value — returns a single specified value attribute for a nameattribute with multiple values (within an attribute-list whose entries’ value attributes arebuffers).

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis call returns one buffer-type value attribute in buffer_value . The returned value attribute willbe the one at position value_index within set of value attributes belonging to the name attributespecified by attr_name . The first value attribute for any particular name attribute within anattribute list has index 0.

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


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_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).


Function Call Definitions azn_attrlist_get_entry_buffer_value( )




azn_attrlist_get_entry_string_value( ) Function Call Definitions

NAMEazn_attrlist_get_entry_string_value — returns a single specified value attribute for a nameattribute with multiple values (within an attribute-list whose entries’ value attributes arestrings).

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis call returns one string-type value attribute in string_value . The returned value attribute willbe the one at position value_index within set of value attributes belonging to the name attributespecified by attr_name . The first value attribute for any particular name attribute within anattribute list has index 0.

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


PARAMETERS


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_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).


Function Call Definitions azn_attrlist_get_entry_string_value( )




azn_attrlist_get_names( ) Function Call Definitions

NAMEazn_attrlist_get_names — returns the list of all name attributes appearing in entries of theattribute list.

SYNOPSISazn_status_tazn_attrlist_get_names(

azn_attrlist_h_t attr_list /* in */,azn_string_t *attr_names[] /* out */

);

DESCRIPTIONThis 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 callingazn_release_strings( ).


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_INVALID_STRING_REF]The pointer to the string array is invalid.




Function Call Definitions azn_attrlist_name_get_num( )

NAMEazn_attrlist_name_get_num — returns the number of value attributes for a given name attributein a given attribute list.

SYNOPSISazn_status_tazn_attrlist_name_get_num(

azn_attrlist_h_t attr_list /* in */,azn_string_t attr_name /* in */,unsigned int *num_values /* out */

);

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


PARAMETERS


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_ATTR_INVALID_INTEGER_REF]The integer reference is not valid.




azn_authority_get_authorities( ) Function Call Definitions

NAMEazn_authority_get_authorities — returns a list of the authorization authority IDs supported bythe aznAPI implementation.

SYNOPSISazn_status_tazn_authority_get_authorities(

azn_string_t *azn_authorities[] /* out */);

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

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

Authority IDs can subsequently be used to find supported services and mechanisms usingazn_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 callingazn_release_strings( ).


PARAMETERS

authzn_authorities (out)A NULL-terminated array of azn_string_t values which will contain the returnedauthorization authority IDs.

RETURN VALUE



[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 authorizationauthority ID should use the default value by passing AZN_NULL_ID through the authorityID argument.




Function Call Definitions azn_authority_get_entitlements_svcs( )

NAMEazn_authority_get_entitlements_svcs — returns a list of the entitlements service IDs supportedby the implementation.

SYNOPSISazn_status_tazn_authority_get_entitlements_svcs(

azn_string_t *entitlements_svc_ids[] /* out */);

DESCRIPTIONThis call returns all the entitlements service IDs supported by implementation. These servicescan subsequently be used in azn_entitlement_get_entitlements( ).

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


PARAMETERS

entitlements_svc_ids (out)A NULL-terminated array of azn_string_t values which will contain the returnedentitlements service IDs.

RETURN VALUE




[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 entitlementsservice ID should use the default value by passing AZN_NULL_ID through theentitlements service ID argument.




azn_authority_get_labeling_schemes( ) Function Call Definitions

NAMEazn_authority_get_labeling_schemes — returns a list of the labeling scheme IDs supported bythe implementation.

SYNOPSISazn_status_tazn_authority_get_labeling_schemes(

azn_string_t *labeling_scheme_ids[] /* out */);

DESCRIPTIONThis call returns all the labeling scheme IDs supported by implementation. These labelingscheme IDs can subsequently be used in the data classification functionsazn_entitlement_get_labels( ) and azn_decision_has_clearance( ).

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


PARAMETERS

labeling_scheme_ids (out)A NULL-terminated array of azn_string_t values which will contain the returnedlabeling_scheme IDs.

RETURN VALUE




[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 schemeID should use the default value by passing AZN_NULL_ID through the labeling scheme IDargument.




Function Call Definitions azn_authority_get_mechanisms( )

NAMEazn_authority_get_mechanisms — returns a list of the authentication mechanism IDs supportedby the specified authorization authority.

SYNOPSISazn_status_tazn_authority_get_mechanisms(

azn_string_t authority /* in */,azn_string_t *mechanism_ids[] /* out */

);

DESCRIPTIONThis call returns all the authentication mechanism IDs supported by the named authorizationauthority . 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 callingazn_release_strings( ).


PARAMETERS

authority (in)An azn_string_t value containing the authorization authority ID of the authority whosesupported authentication mechanism IDs are to be returned.

mechanism_ids (out)A NULL-terminated array of azn_string_t values which will contain the returnedauthentication mechanism IDs.

RETURN VALUE




[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 IDshould use the default value by passing AZN_NULL_ID through the mechanism IDargument.




azn_authority_get_mod_svcs( ) Function Call Definitions

NAMEazn_authority_get_mod_svcs — returns a list of the credential modification service IDssupported by the specified authorization authority.

SYNOPSISazn_status_tazn_authority_get_mod_svcs(

azn_string_t authority /* in */,azn_string_t *mod_svc_ids[] /* out */

);

DESCRIPTIONThis call returns all the credential modification service IDs supported by the specifiedauthorization 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 callingazn_release_strings( ).


PARAMETERS

authority (in)An azn_string_t value containing the authorization authority ID of the authority whosesupported 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 credentialmodification service IDs.

RETURN VALUE




[AZN_S_INVALID_STRING_REF]The credential modification service string reference is invalid.


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




Function Call Definitions azn_authority_get_pac_svcs( )

NAMEazn_authority_get_pac_svcs — returns a list of the privilege attribute certificate (PAC) serviceIDs supported by the specified authorization authority.

SYNOPSISazn_status_tazn_authority_get_pac_svcs(

azn_string_t azn_authority /* in */,azn_string_t *pac_svc_ids[] /* out */

);

DESCRIPTIONThis call returns all the privilege attribute certificate service IDs supported by the specifiedauthorization authority. These services can subsequently be used in azn_creds_get_pac( ) andazn_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 attributecertificates versus SESAME PACs). Different PAC services might generate identical PACformats, but use different (or no) signature mechanisms to assert their validity. Different PACservices might encode chained credentials in different orders in the PACs they generate. aznAPIimplementations are not required to support multiple PAC services.

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


PARAMETERS

authority (in)An azn_string_t value containing the authorization authority ID of the authority whosesupported 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 returnedauthorization PAC service IDs.

RETURN VALUE




[AZN_S_INVALID_STRING_REF]The authorization PAC service string reference is invalid.


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


azn_authority_get_pac_svcs( ) Function Call Definitions




Function Call Definitions azn_creds_combine( )

NAMEazn_creds_combine — combines two credentials chains and returns a handle to the resultingcombined credentials chain.

SYNOPSISazn_status_tazn_creds_combine(

azn_creds_h_t creds /* in */,azn_creds_h_t creds_to_add /* in */,azn_creds_h_t *combined_creds /* out */

);

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

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

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


PARAMETERS

creds (in)Handle to credentials chain whose first indexed entry is the credential of the intiator of arequest.

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 chainreferred to by creds followed by the credentials chain referred to by creds_to_add.

RETURN VALUE




[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_creds_combine( ) Function Call Definitions

[AZN_S_UNIMPLEMENTED_FUNCTION]This function is not supported by the implementation.




Function Call Definitions azn_creds_create( )

NAMEazn_creds_create — creates a new, empty credentials chain, assigns it a handle, and returns thehandle.

SYNOPSISazn_status_tazn_creds_create(

azn_creds_h_t *creds /* out */);

DESCRIPTIONThis 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( ).


PARAMETERS

creds (out)Pointer to the new credential handle which will be returned.

RETURN VALUE




[AZN_S_INVALID_CREDS_HDL]The credential handle supplied is invalid.




azn_creds_delete( ) Function Call Definitions

NAMEazn_creds_delete — deletes the credentials chain associated with the credential handle.

SYNOPSISazn_status_tazn_creds_delete(

azn_creds_h_t *creds /* in, out */);

DESCRIPTIONThis 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 usedin future calls.


PARAMETERS

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

RETURN VALUE








Function Call Definitions azn_creds_for_subject( )

NAMEazn_creds_for_subject — returns a handle to a credentials chain; used to extract a individualsubject’s credentials chain from a longer chain containing the combined credentials chains ofseveral subjects.

SYNOPSISazn_status_tazn_creds_for_subject(

azn_creds_h_t creds /* in */,unsigned int subject_index /* in */,azn_creds_h_t *new_creds /* out */

);

DESCRIPTIONThis call returns a handle, new_creds, to a credentials chain for the individual subject at indexsubject_index within a longer credentials chain creds which contains the combined credentialschains of several subjects.

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

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

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


PARAMETERS

creds (in)Handle to a credentials chain representing the combined credentials chains of severalsubjects, which contains a list of 1 or more individual credentials chains. When the callreturns, the structure referred to by this argument is unchanged; subsequent changes to thecredentials chain returned through new_creds do not affect the structure referred to by thisargument.

subject_index (in)The index of the requested individual credentials chain within the combined credentialschain. The index of the first credentials chain in the combined credentials chain, whichshould be that of the initiator, is zero (0). The total number of credentials chains in acombined 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_creds_for_subject( ) Function Call Definitions


[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.





Function Call Definitions azn_creds_get_attrlist_for_subject( )

NAMEazn_creds_get_attrlist_for_subject — returns information from a specific subject’s credentialschain within a specified (possibly combined) credentials chain.

SYNOPSISazn_status_tazn_creds_get_attrlist_for_subject (

azn_creds_h_t creds /* in */,unsigned int subject_index /* in */,azn_attrlist_h_t *creds_attrlist /* out */

);

DESCRIPTIONThis function returns an attribute list containing privilege attribute information from thecredentials 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 firstcredentials chain in a combined credentials chain will be that of the initiator, and its index willbe zero (0); callers can retrieve the attributes for the credentials chain of the initiator by passingthe 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 wayby this call, and later changes to this structure (including releasing its storage) will have no effecton the creds_attrlist returned by this call.

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

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 returnedattribute 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 callingazn_attrlist_delete( ).


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 thefirst 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 credentialschain, 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 attributeinformation on return.

RETURN VALUE



azn_creds_get_attrlist_for_subject( ) Function Call Definitions




[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.





Function Call Definitions azn_creds_get_pac( )

NAMEazn_creds_get_pac — creates and returns a privilege attribute certificate (PAC) by invoking aspecified PAC service on the supplied credentials chain.

SYNOPSISazn_status_tazn_creds_get_pac(

azn_creds_h_t creds /* in */,azn_string_t pac_svc_id /* in */,azn_buffer_t *pac /* out */

);

DESCRIPTIONThis call uses the PAC service whose ID is supplied to build a new PAC. The PAC service usesthe information in the supplied credentials chain to build the PAC. Different PAC services mayproduce PACs with different formats. Some PAC services may cryptographically protect orsign 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 pacreturned by this call.

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


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_INVALID_PAC_SVC]The privilege attribute certificate service identifier is invalid.




azn_creds_get_pac( ) Function Call Definitions




Function Call Definitions azn_creds_modify( )

NAMEazn_creds_modify — modifies an existing credentials chain and returns a handle to an newcredentials chain containing the modifications.

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis function uses the specified modification service and (optionally) an attribute list mod_infocontaining modification information provided by the caller to modify a copy of the suppliedcredentials chain. The function returns a handle to a new credentials chain containing therequested 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 modifiedfirst element followed by unmodified copies of the remaining elements in the input combinedcredentials chains; the elements in the output credentials chain will be in the same order as theircounterparts in the input credentials chain.

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

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


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 describingthe desired credential modifications. This list may be empty (that is, contain no attributes).Implementation documentation must describe the behavior of this function when it ispassed an empty mod_info list.

new_creds (out)Pointer to a new, empty credentials chain; will hold the modified credentials chain uponreturn.

RETURN VALUE




azn_creds_modify( ) Function Call Definitions


[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_NEW_CREDS_HDL]The pointer to the credential handle referring to the output new credentials chain is invalid.






Function Call Definitions azn_creds_num_of_subjects( )

NAMEazn_creds_num_of_subjects — returns the number of individual subjects’ credentials chains in acombined credentials chain.

SYNOPSISazn_status_tazn_creds_num_of_subjects(

azn_creds_h_t creds /* in */,unsigned int *num_of_subjects /* out */

);

DESCRIPTIONThis call returns the number of individual subjects, num_of_subjects, whose credentials appear ina (possibly combined) credentials chain creds. Combined credentials chains are created by theazn_creds_combine( ) function.


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 credentialschain.

RETURN VALUE




[AZN_S_INVALID_CREDS_HDL]The creds( ) handle supplied is invalid.

[AZN_S_ATTR_INVALID_INTEGER_REF]The integer reference is invalid.





azn_decision_access_allowed( ) Function Call Definitions

NAMEazn_decision_access_allowed — makes an access control decision.

SYNOPSISazn_status_tazn_decision_access_allowed(

azn_creds_h_t creds /* in */,azn_string_t protected_resource /* in */,azn_string_t operation /* in */,int *permission /* out */

);

DESCRIPTIONThis function decides whether the initiator specified by creds is authorized to perform theoperation operation on the target protected_resource. The decision is returned throughpermission.

azn_decision_access_allowed is semantically equivalent to azn_decision_access_allowed_ext whenapp_context = NULL and permission_info = NULL.


PARAMETERS

creds (in)Handle to the credentials chain which will be used as initiator ADI to make the accessdecision.

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 somesituations. Applications may be able to get additional information by callingazn_decision_access_allowed_ext( ).

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

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

RETURN VALUE





Function Call Definitions azn_decision_access_allowed( )

[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_decision_access_allowed_ext( ) Function Call Definitions

NAMEazn_decision_access_allowed_ext — makes an access control decision using application-specificcontext information; returns information about why the decision was made.

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis function decides whether the initiator specified by creds is authorized to perform theoperation operation on the target protected_resource. Optionally, callers may supplyapplication-specific context ACI using the app_context argument. The decision is returnedthrough permission.

Optionally, the implementation may return implementation-specific information about thedecision (for example, information indicating which rule or rules was responsible for granting ordenying 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 Table 6-4on page 31, may be used as the name attributes of entries in the app_context attribute list tocommunicate common types of context.


PARAMETERS


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 thereis 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 permissionwill be [AZN_C_PERMITTED] or [AZN_C_NOT_PERMITTED].

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

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


Function Call Definitions azn_decision_access_allowed_ext( )

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 toAZN_C_NOT_PERMITTED to assist the calling application and/or the initiator informulating a request which will be authorized. Examples of such qualifiers might includenot permitted yet, requires additional privilege attributes , or permissible with restrictions .

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

RETURN VALUE






[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_decision_has_clearance( ) Function Call Definitions

NAMEazn_decision_has_clearance — decides whether an initiator has the clearance necessary tooperate on protected resources with a specified label.

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONUsing a classification defined by labeling_scheme_id , the call checks whether the initiatorspecified 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 toretrieve 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 shoulduse azn_decision_access_allowed( ) or azn_decision_access_allowed_ext( ) instead ofazn_decision_has_clearance( ).

Note that AEFs invoking this function must pass label data as a string. If the label as retrievedby the application is not already in a suitable format (for example, XML or encoded ASN.1), theAEF 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.


PARAMETERS


labeling_scheme_id (in)ID of the labeling to which label belongs.


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 permissionwill 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].


Function Call Definitions azn_decision_has_clearance( )

Calling applications are bound by the decision returned using the permission argumentonly 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_INVALID_LABELING_SCHEME]The labeling scheme ID is unknown or 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_entitlement_get_entitlements( ) Function Call Definitions

NAMEazn_entitlement_get_entitlements — returns entitlements of an initiator.

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis uses an entitlements service identified by entitlements_svc_id to return the entitlements of aninitiator specified by creds. The calling application may pass application-specific orentitlements-service-specific context data using an attribute listapp_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 Table 6-4on page 31, may be used as name attribute of entries in the app_context attribute list tocommunicate common types of context information.


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-specificcontext 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_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.


Function Call Definitions azn_entitlement_get_entitlements( )

[AZN_S_INVALID_ENTITLEMENTS_HDL]The attribute list handle for the entitlements is invalid.






azn_entitlement_get_labels( ) Function Call Definitions

NAMEazn_entitlement_get_labels — returns the set of labels which the initiator specified by thesupplied credentials chain is authorized to access.

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis 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 datalabeled using only labels included in the returned set of labels.


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 bythe supplied credentials chain to invoke. If the value of this argument is NULL, the set oflabels 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 argumentwill contain all the labels within the specified labeling scheme to which the initiatorspecified by creds has clearance. Memory for this argument must be released by the callerusing azn_release_strings( ).

RETURN VALUE





[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.


Function Call Definitions azn_entitlement_get_labels( )

[AZN_S_INVALID_OPERATION]The name of the requested operation is invalid or not recognized by the specified labelingscheme.

[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 tosee).





azn_entitlement_get_operations( ) Function Call Definitions

NAMEazn_entitlement_get_operations — returns the list of operations permitted or forbidden to aspecified initiator on a specified resource.

SYNOPSISazn_status_tazn_entitlement_get_operations(

azn_creds_h_t creds /* in */,azn_string_t protected_resource /* in */,int permission /* in */,azn_string_t *operations[] /* out */

);

DESCRIPTIONThis function returns a list of operation names operations .

If the value of permission is [AZN_C_PERMITTED], operations will contain the names of all theoperations 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 allthe operations the initiator specified by creds is forbidden to perform on the targetprotected_resource.


PARAMETERS

creds (in)Handle to the credentials chain whose entitled operations are to be returned.


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_PERMITTEDoperations; an implementation which does not support retrieval of NOT_PERMITTEDoperations must return the AZN_S_UNIMPLEMENTED_FUNCTION status code if thecaller passes AZN_C_NOT_PERMITTED as the value of this argument.

Implementations may return the AZN_S_AUTHORIZATION_FAILURE status code if thecaller 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





Function Call Definitions azn_entitlement_get_operations( )


[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 namesof the operations are themselves sensitive information which the caller is not authorized tosee.





azn_entitlement_get_operations_ext( ) Function Call Definitions

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

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis function returns a list of operation names operations .

If the value of permission is [AZN_C_PERMITTED], operations will contain the names of all theoperations 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 allthe operations the initiator specified by creds is forbidden to perform on the targetprotected_resource.

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

Optionally, the implementation may return implementation-specific information about thedecision 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 Table 6-4on page 31, may be used as the name attributes of entries in the app_context attribute list tocommunicate common types of context.


PARAMETERS

creds (in)Handle to the credentials chain whose entitled operations are to be returned.


app_context (in)An attribute list containing application-specific context ACI. A NULL value indicates thereis 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 .


Function Call Definitions azn_entitlement_get_operations_ext( )

permission_info (in, out)A pointer to an attribute list through which the implementation may returnimplementation-specific information about the permitted or forbidden operations. If aNULL value is passed as input, then no information will be returned.

RETURN VALUE





[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 examplebecause the names of the operations are themselves sensitive information which the caller isnot authorized to see.





azn_error_major( ) Function Call Definitions

NAMEazn_error_major — returns major error code associated with a returned status code.

SYNOPSISunsigned intazn_error_major(

azn_status_t status_code /* in */);

DESCRIPTIONThe 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 VALUEAny of the defined major error codes, AZN_S_*, will be returned.



Function Call Definitions azn_error_minor( )

NAMEazn_error_minor — returns implementation-specific minor error code associated with areturned status code.

SYNOPSISunsigned intazn_error_minor(

azn_status_t status_code /* in */);

DESCRIPTIONThe 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 toretrieve them.

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

PARAMETERS

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

RETURN VALUEAn implementation-specific minor error code will be returned.



azn_error_minor_get_string( ) Function Call Definitions

NAMEazn_error_minor_get_string — returns a string describing the implementation-specific minorerror.

SYNOPSISazn_status_tazn_error_minor(

unsigned int minor_error /* in */,azn_string_t *minor_error_string /* out */

);

DESCRIPTIONA string describing the error corresponding to a previously returned minor error status code isreturned.

When minor_error_string is no longer needed, its storage should be released by callingazn_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_errorcode.

RETURN VALUE



[AZN_S_FAILURE]The specified minor_error code is invalid, or no string describing the specified minor_errorcan be returned.



Function Call Definitions azn_id_get_creds( )

NAMEazn_id_get_creds — returns a handle to the credentials chain associated by a specifiedauthorization authority with a specified identity.

SYNOPSISazn_status_tazn_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 */

);

DESCRIPTIONThis function returns a handle new_creds to a newly constructed credentials chain for the identitycorresponding to the initiator ACI mechanism_info produced by an authentication mechanismmechanism_id . If the implementation supports more than one authorization authority, the callercan specify which authority should be used by passing the ID of the desired authority inauthority .

The Open Group maintains a list of registered mechanism IDs together with a description oftheir mechanism_info formats (see Section 6.5.3 on page 34).

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 authenticationmechanism and the default identity to be used.

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


PARAMETERS

authority (in)The ID of the authorization authority which should be used to build the credentials chain. ANULL input value selects a default authority.

mechanism_id (in)The authentication mechanism which was used to generate the identity passed throughmechanism_info .ANULL input value selects a default authentication mechanism.

mechanism_info (in)A buffer containing initiator ACI consisting of identity information obtained from anauthentication service. The authentication service used to produce this information shouldbe identified using the mechanism_id argument.

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

new_creds (out)Pointer to a new, empty credentials chain; will hold the returned credentials chain.


azn_id_get_creds( ) Function Call Definitions

RETURN VALUE





[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.




Function Call Definitions azn_initialize( )

NAMEazn_initialize — initializes the authorization service.

SYNOPSISazn_status_tazn_initialize(

azn_attrlist_h_t init_data /* in */,azn_attrlist_h_t *init_info /* in, out */

);

DESCRIPTIONazn_initialize( ) must be called before any aznAPI functions other than azn_attrlist_*( ) andazn_error_*( ) are called.

The implementation may permit or require implementation-specific data to be passed in atinitialization 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 entrywhose name attribute is [AZN_C_VERSION] (unless the caller passes a null pointer as the inputvalue of init_info ).

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


PARAMETERS

init_data (in)A handle to an attribute list containing implementation-specific initialization data. If thereis no initialization data, an attribute list with no entries should be passed as the value of thisargument.

init_info (in, out)Pointer to an attribute list containing through which implementation-specific informationwill be returned from initialization. If a NULL pointer is passed as input, then noinformation will be returned.

RETURN VALUE



[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.


azn_initialize( ) Function Call Definitions



Function Call Definitions azn_pac_get_creds( )

NAMEazn_pac_get_creds — returns a handle to new credentials chain derived from a privilegeattribute certificate (PAC) by a specified PAC service.

SYNOPSISazn_status_tazn_pac_get_creds(

azn_buffer_t pac /* in */,azn_string_t pac_svc_id /* in */,azn_creds_h_t *new_creds /* out */

);

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


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 credentialschain.

RETURN VALUE




[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 examplebecause the caller is not authorized to create credentials chains for initiators it has notauthenticated.



azn_pac_get_creds( ) Function Call Definitions




Function Call Definitions azn_release_buffer( )

NAMEazn_release_buffer — frees storage associated with a buffer.

SYNOPSISazn_status_tazn_release_buffer(

azn_buffer_t *buffer /* in, out */);

DESCRIPTIONThis 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 infuture calls.


PARAMETERS

buffer (in, out)A pointer to the buffer whose memory is to be released.

RETURN VALUE




[AZN_S_INVALID_BUFFER]The buffer is invalid.




azn_release_string( ) Function Call Definitions

NAMEazn_release_string — frees storage associated with a string.

SYNOPSISazn_status_tazn_release_string(

azn_string_t *string /* in, out */);

DESCRIPTIONThis 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 infuture calls.


PARAMETERS

string (in, out)Pointer to the string to be released.

RETURN VALUE




[AZN_S_INVALID_STRING_REF]The string reference is invalid.




Function Call Definitions azn_release_strings( )

NAMEazn_release_strings — frees storage associated with an array of strings.

SYNOPSISazn_status_tazn_release_strings(

azn_string_t *strings[] /* in, out */);

DESCRIPTIONThis 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 infuture calls.


PARAMETERS

strings (in)Pointer to the array azn_string_t structures to be released.

RETURN VALUE




[AZN_S_INVALID_STRING_REF]The reference to the array of strings is invalid.




azn_shutdown( ) Function Call Definitions

NAMEazn_shutdown — cleans up internal authorization service state in preparation for shutdown.

SYNOPSISazn_status_tazn_shutdown(

void);

DESCRIPTIONAn application which has initialized the aznAPI using the azn_initialize( ) function should callazn_shutdown ( ) to clean up the aznAPI’s memory and other internal implementation state beforethe 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_*( ) callsbefore azn_shutdown ( ) is called.


PARAMETERSThere are no arguments for azn_shutdown ( ).

RETURN VALUE







Appendix A

Header File

/** FILENAME* ogauthzn.h** DESCRIPTION** COPYRIGHT NOTICE* Copyright (c) 1999 DASCOM Inc. All Rights Reserved.*/

/** HISTORY* $Log: ogauthzn.h,v $* $EndLog$*/

#ifndef OGAUTHZN_H#define OGAUTHZN_H

#ifdef __cplusplusextern "C" {#endif

/* defined constants */

#define AZN_C_PERMITTED 0#define AZN_C_NOT_PERMITTED 1

#define AZN_C_EMPTY_BUFFER NULL#define AZN_C_NO_BUFFER NULL

#define AZN_C_INITIATOR_INDEX 0#define AZN_C_AUDIT_ID "AZN_AUDIT_ID"#define AZN_C_REQUEST_TIME "AZN_REQUEST_TIME"#define AZN_C_AUTHN_QUALITY "AZN_AUTHN_QUALITY"#define AZN_C_REQUESTER_LOC "AZN_REQUESTER_LOC"#define AZN_C_REQUEST_ROUTE_QOP "AZN_REQUEST_ROUTE_QOP"#define AZN_C_VERSION "AZN_VERSION"

/* status codes */

#define AZN_S_COMPLETE 0#define AZN_S_FAILURE 1#define AZN_S_AUTHORIZATION_FAILURE 2#define AZN_S_INVALID_CREDS_HDL 3#define AZN_S_INVALID_NEW_CREDS_HDL 4#define AZN_S_INVALID_ENTITLEMENTS_SVC 5#define AZN_S_INVALID_COMB_CREDS_HDL 6#define AZN_S_INVALID_MECHANISM_INFO 7#define AZN_S_INVALID_MECHANISM 8#define AZN_S_INVALID_STRING_VALUE 9#define AZN_S_UNKNOWN_LABEL 10#define AZN_S_INVALID_ADDED_CREDS_HDL 11


Header File

#define AZN_S_INVALID_PROTECTED_RESOURCE 12#define AZN_S_INVALID_OPERATION 13#define AZN_S_INVALID_PAC 14#define AZN_S_INVALID_PAC_SVC 15#define AZN_S_INVALID_APP_CONTEXT_HDL 16#define AZN_S_INVALID_MOD_FUNCTION 17#define AZN_S_INVALID_SUBJECT_INDEX 18#define AZN_S_UNIMPLEMENTED_FUNCTION 19#define AZN_S_INVALID_ATTRLIST_HDL 20#define AZN_S_INVALID_ATTR_NAME 21#define AZN_S_INVALID_BUFFER 22#define AZN_S_INVALID_BUFFER_REF 23#define AZN_S_INVALID_STRING_REF 24#define AZN_S_ATTR_VALUE_NOT_STRING_TYPE 25#define AZN_S_ATTR_INVALID_INDEX 26#define AZN_S_INVALID_INTEGER_REF 27#define AZN_S_INVALID_PERMISSION_REF 28#define AZN_S_INVALID_AUTHORITY 29#define AZN_S_INVALID_APP_CONTEXT_HDL 30#define AZN_S_INVALID_ENTITLEMENTS_HDL 31#define AZN_S_INVALID_LABELING_SCHEME 32#define AZN_S_INVALID_INIT_DATA_HDL 33#define AZN_S_INVALID_INIT_INFO_HDL 34#define AZN_S_ATTR_VALUE_NOT_STRING_TYPE 35

/* Null ID; used to specify defaults for authority and mechanism IDs */

#define AZN_NULL_ID ""

/* type definitions */

/* implementation specific status and handle definitions */

typedef unsigned long azn_status_t;typedef long azn_creds_h_t;typedef long azn_attrlist_h_t;

/* standard data types */

typedef struct azn_buffer_desc_struct {size_t length;void *value;

} azn_buffer_desc, *azn_buffer_t;

typedef char *azn_string_t;

/* function prototypes */

azn_status_tazn_attrlist_add_entry(

azn_attrlist_h_t attr_list /* in */,azn_string_t attr_name /* in */,azn_string_t string_value /* in */

);

azn_status_tazn_attrlist_add_entry_buffer(

azn_attrlist_h_t attr_list /* in */,azn_string_t attr_name /* in */,


Header File

azn_buffer_t buffer_value /* in */);

azn_status_tazn_attrlist_create(

azn_attrlist_h_t *attrlist_list /* out */);

azn_status_tazn_attrlist_delete(

azn_attrlist_h_t *attrlist_list /* in, out */);

azn_status_tazn_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 */

);

azn_status_tazn_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 */

);

azn_status_tazn_attrlist_get_names(

azn_attrlist_h_t attr_list /* in */,azn_string_t *attr_names[] /* out */

);

azn_status_tazn_attrlist_name_get_num(

azn_attrlist_h_t attr_list /* in */,azn_string_t attr_name /* in */,unsigned int *num_values /* out */

);

azn_status_tazn_authority_get_authorities(

azn_string_t *azn_authorities[] /* out */);

azn_status_tazn_authority_get_entitlements_svcs(

azn_string_t *entitlements_svc_ids[] /* out */);

azn_status_tazn_authority_get_labeling_schemes(

azn_string_t *labeling_scheme_ids[] /* out */);

azn_status_tazn_authority_get_mechanisms(


Header File

azn_string_t azn_authority /* in */,azn_string_t *mechanism_ids[] /* out */

);

azn_status_tazn_authority_get_mod_svcs(

azn_string_t azn_authority /* in */,azn_string_t *mod_svc_ids[] /* out */

);

azn_status_tazn_authority_get_pac_svcs(

azn_string_t azn_authority /* in */,azn_string_t *pac_svc_ids[] /* out */

);

azn_status_tazn_creds_combine(

azn_creds_h_t creds /* in */,azn_creds_h_t creds_to_add /* in */,azn_creds_h_t *combined_creds /* out */

);

azn_status_tazn_creds_create(

azn_creds_h_t *creds /* out */);

azn_status_tazn_creds_delete(

azn_creds_h_t *creds /* in, out */);

azn_status_tazn_creds_for_subject(

azn_creds_h_t creds /* in */,unsigned int subject_index /* in */,azn_creds_h_t *subject_creds /* out */

);

azn_status_tazn_creds_get_attrlist_for_subject(

azn_creds_h_t creds /* in */,unsigned int subject_index /* in */,azn_attrlist_h_t *creds_attrlist /* out */

);

azn_status_tazn_creds_get_pac(

azn_creds_h_t creds /* in */,azn_string_t pac_svc_id /* in */,azn_buffer_t *pac /* out */

);

azn_status_tazn_creds_modify(

azn_creds_h_t creds /* in */,azn_string_t mod_svc_id /* in */,azn_attrlist_h_t mod_info /* in */,


Header File

azn_creds_h_t *new_creds /* out */);

azn_status_tazn_creds_num_subjects(

azn_creds_h_t creds /* in */,unsigned int *num_of_subjects /* out */

);

azn_status_tazn_decision_access_allowed(

azn_creds_h_t creds /* in */,azn_string_t protected_resource /* in */,azn_string_t operation /* in */,int *permission /* out */

);

azn_status_tazn_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 */

);

azn_status_tazn_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 */

);

azn_status_tazn_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 */

);

azn_status_tazn_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 */

);

azn_status_tazn_entitlement_get_operations(

azn_creds_h_t creds /* in */,azn_string_t protected_resource /* in */,


Header File

int permission /* in */,azn_string_t *operations[] /* out */

);

azn_status_tazn_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 */

);

unsigned intazn_error_major(

azn_status_t azn_status /* in */);

unsigned intazn_error_minor(

azn_status_t azn_status /* in */);

azn_status_tazn_error_minor(

unsigned int minor_error /* in */,azn_string_t *minor_error_string /* out */

);

azn_status_tazn_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 */

);

azn_status_tazn_initialize(

azn_attrlist_h_t init_data /* in */,azn_attrlist_h_t *init_info /* in, out */

);

azn_status_tazn_pac_get_creds(

azn_buffer_t pac /* in */,azn_string_t pac_svc_id /* in */,azn_creds_h_t *new_creds /* out */

);

azn_status_tazn_release_buffer(

azn_buffer_t *buffer /* in, out */);

azn_status_t


Header File

azn_release_string(azn_string_t *string /* in, out */

);

azn_status_tazn_release_strings(

azn_string_t *strings[] /* in, out */);

azn_status_tazn_shutdown(

void);

#ifdef __cplusplus}#endif

#endif /* OGAUTHZN_H */


Header File


Glossary

Access controlThe prevention of unauthorized use of a resource, including the prevention of use of a resourcein an unauthorized manner (ISO 7498-2).

Access requestthe operations and operands that form part of an attempted access (ISO 10181-3).

ACIAny information used for access control purposes, including contextual information (ISO10181-3).

ADFA specialized function that makes access control decisions by applying access control policyrules to an access request, ADI (of initiators, targets, access requests, or that retained from priordecisions), and the context in which the access request is made (ISO 10181-3).

ADIThe portion (possibly all) of the ACI made available to the ADF in making a particular accesscontrol decision (ISO 10181-3).

AEFA specialized function that is part of the access path between an initiator and a target on eachaccess control request and enforces the decision made by the ADF (ISO 10181-3).

Attribute listA data structure through which applications and aznAPI implementations can exchange lists ofname-value pairs.

Audit idAn identity attribute containing an identity used only for accountability purposes (ECMA 219).

AuthenticationThe process of verifying an identity claimed by or for a system entity.

AuthorityAn identified computer-based entity which implements a security service (e.g. creation of PACs).

AuthorizationThe granting of access rights to a subject (for example, a user, or program).

BufferA data structure through which applications and aznAPI implementations can exchange opaquedata.

CapabilityA token that gives its holder the right to access a system resource. Possession of the token isaccepted by the access control mechanism as proof that the holder has been authorized to accessthe resource named or indicated by the token.

ClearanceInitiator-bound ACI that can be compared with security labels of targets (ISO 10181-3).

ContextInformation about or derived from the context in which an access request is made (e.g. time ofday). This is identical to the ISO 10181-3 definition of "contextual information", with which term


Glossary

this specification uses "context" interchangeably).

Credential handleA handle to a credentials chain.

Credentials chainA structure maintained by an aznAPI implementation which contains its internal representationof an initiator’s privilege attributes.

Combined creds chainA credentials chain consisting of an ordered list of elements. Each element in the ordered listrepresents the privilege attributes of a subject which initiated or passed on an access request.The first element in the ordered list is the credentials chain of the initiator of the access request.The remaining elements in the ordered list are a sequence of (zero or more) credentials chainsbelonging to intermediaries through which the initiator’s access request has passed.

DecisionThe response of an ADF to a decision request.

Decision requestThe message an AEF sends to an ADF to ask it whether a particular access request should begranted or denied.

EntitlementA data structure containing ADI and/or access control policy rule information in a form whichcan be used by applications to customize their behavior based on access control policy or tomake access control decisions in their own code.

IdentityInitiator ACI passed to the aznAPI. This specification uses the term to describe anything used asinitiator ACI, including names, identity certificates, and capabilities. Note that this usage isunique to this specification and should not be confused with other uses of the term "identity" inother systems.

InitiatorAn entity (e.g. human user or computer-based entity) that attempts to access other entities (ISO10181-3).

IntermediaryAn entity which, after receiving an access request from an initiator, issues another access requeston that initiator’s behalf.

LabelA marking that is bound to a protected resource and that names or designates the security-relevant attributes of that resource (derived from the ISO 7498-2 definition).

OperationThe action that an initiator’s access request asks to have performed on a protected resource.

PACA data structure containing privilege attributes. May be signed by the authority whichgenerated it.

Privilege attributeAn attribute associated with an initiator that, when matched against control attributes of aprotected resource is used to grant or deny access to that protected resource (derived fromECMA TR/46 definition).


Glossary

Protected resourceA target, access to which is restricted by an access control policy.

TargetAn entity to which access may be attempted (ISO 10181-3).


Glossary


Index

Access control .........................................................105access control framework .........................................6Access request .........................................................105ACI.............................................................................105ADF ...........................................................................105ADI ............................................................................105administration.............................................................3AEF ............................................................................105architecture ..................................................................5attribute list................................................................28Attribute list.............................................................105audit events..................................................................3Audit id.....................................................................105audit service.................................................................3Authentication ........................................................105authentication and authorization..........................21authentication mechanism ID................................34authentication mechanism OIDs...........................34Authority..................................................................105Authorization..........................................................105aznAPI...........................................................................1azn_attrlist_add_entry( ) .........................................38azn_attrlist_add_entry_buffer( )............................40azn_attrlist_create( ).................................................42azn_attrlist_delete( ).................................................43azn_attrlist_get_entry_buffer_value( ) .................44azn_attrlist_get_entry_string_value( ) .................46azn_attrlist_get_names( ) ........................................48azn_attrlist_name_get_num( ) ...............................49azn_authority_get_authorities( ) ...........................50azn_authority_get_entitlements_svcs( ) ..............51azn_authority_get_labeling_schemes( )...............52azn_authority_get_mechanisms( ) ........................53azn_authority_get_mod_svcs( ) ............................54azn_authority_get_pac_svcs( ) ..............................55azn_creds_combine( ) ..............................................57azn_creds_create( ) ...................................................59azn_creds_delete( ) ...................................................60azn_creds_for_subject( )..........................................61azn_creds_get_attrlist_for_subject( )....................63azn_creds_get_pac( )................................................65azn_creds_modify( ).................................................67azn_creds_num_of_subjects( ) ...............................69azn_decision_access_allowed( ) ............................70azn_decision_access_allowed_ext( ).....................72azn_decision_has_clearance( ) ...............................74

azn_entitlement_get_entitlements( ) ....................76azn_entitlement_get_labels( ) ................................78azn_entitlement_get_operations( ) .......................80azn_entitlement_get_operations_ext( )................82azn_error_major( ) ....................................................84azn_error_minor( )....................................................85azn_error_minor_get_string( ) ...............................86azn_id_get_creds( )...................................................87azn_initialize( ) ..........................................................89azn_pac_get_creds( )................................................91azn_release_buffer( ) ................................................93azn_release_string( ).................................................94azn_release_strings( )...............................................95azn_shutdown( ) .......................................................96Buffer.........................................................................105Capability.................................................................105character strings........................................................27Clearance..................................................................105Combined creds chain...........................................106constants...............................................................27, 30Context .....................................................................105Credential handle ...................................................106credential handles.....................................................28Credentials chain....................................................106data types ...................................................................27Decision ....................................................................106Decision request......................................................106definition of authorization........................................1delegation of credentials ...........................................3design goals .................................................................3Entitlement...............................................................106error codes..................................................................29exchange of information ...........................................3families of functions.................................................18function call definitions...........................................37Identity......................................................................106Initiator .....................................................................106Intermediary............................................................106interoperability............................................................3ISO 10181-3 ..................................................................6Label ..........................................................................106major error codes......................................................29mandatory function calls ........................................25object identifier..........................................................34Operation .................................................................106PAC............................................................................106


Index

policy.............................................................................4portability.............................................................26, 34Privilege attribute...................................................106Protected resource..................................................107state machine.............................................................19status values ..............................................................28string data ..................................................................27structured data types...............................................27supported functions.................................................18system structure........................................................17Target ........................................................................107trusted computing base...........................................23trust model.................................................................21trust relationships.....................................................23X/Open object identifier .........................................34
