Cisco IOS XR XML API Guide, Release 3.2
Chapter 8 - Cisco XML Security
Downloads: This chapterpdf (PDF - 163.0KB) The complete bookPDF (PDF - 2.09MB) | Feedback

Cisco XML Security

Table Of Contents

Cisco XML Security

Authentication

Authorization

Retrieving Task Permissions

Task Privileges

Task Names

Authorization Failure


Cisco XML Security


Specific security privileges are required for a client application requesting information from the router.

This chapter contains the following sections:

Authentication

Authorization

Retrieving Task Permissions

Task Privileges

Task Names

Authorization Failure

Authentication

User authentication through authentication, authorization, and accounting (AAA) is handled on the router by the transport-specific XML agent and is not exposed through the XML interface.

Authorization

Every operation request by a client application is authorized. If the client is not authorized to perform an operation, the operation is not performed by the router and an error is returned.

Authorization of client requests is handled through the standard AAA "task permissions" mechanism. The XML agent caches the AAA user credentials obtained from the user authentication process, and then each client provides these to the XML infrastructure on the router. As a result, no AAA information needs to be passed in the XML request from the client application.

Each object class in the schema has a task ID associated with it. A client application's capabilities and privileges in terms of task IDs are exposed by AAA through a show command. A client application can use the XML interface to retrieve the capabilities prior to sending configuration requests to the router.

A client application requesting an operation through the XML interface must have the appropriate task privileges enabled/assigned for any objects accessed in the operation:

<Get> operations require AAA "read" privileges.

<Set> and <Delete> operations require AAA "write" privileges.

The "configuration services" operations through configuration manager can also require the appropriate predefined task privileges.

If an operation requested by a client application fails authorization, an appropriate <Error> element is returned in the response sent to the client. For "native data" operations, the <Error> element is associated with the specific element or object classes where the authorization error occurred.

Retrieving Task Permissions

A client application's capabilities and privileges in terms of task permissions are exposed by AAA through command-line interface (CLI) show commands. A client application can also use the XML interface to programatically retrieve the current AAA capabilities from the router. This retrieval can be done by issuing the appropriate <Get> request to the <AAA> component.

The following example shows a request to retrieve all of the AAA configuration from the router:

Sample XLM Request to Retrieve AAA Configuration Information

<?xml version="1.0" encoding="UTF-8"?>  
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <AAA MajorVersion="1" MinorVersion="0"/>
    </Configuration>
  </Get>
</Request>

Sample XML Response from the Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <AAA MajorVersion="1" MinorVersion="0">
        .
        .
        .
         AAA configuration returned here
        .
        .
        .
      </AAA>
    </Configuration>
  </Get>
</Response>

Task Privileges

A client application requesting a native data operation through the XML interface must have the appropriate task privileges enabled/assigned for any items accessed in the operation, as follows:

<Get>, <GetNext>, and <GetVersionInfo> operations require AAA "read" privileges.

<Set> and <Delete> operations require AAA "write" privileges.

The "configuration services" operations through configuration manager can also require the appropriate predefined task privileges.

Task Names

Each object (that is, data item or table) exposed through the XML interface and accessible to the client application has one or more task names associated with it. The task names are published in the XML schema documents as <appinfo> annotations.

For example, the complex type definition for the top-level element in the Border Gateway Protocol (BGP) configuration schema contains the following annotation:

<xsd:appinfo>
  <MajorVersion>1</MajorVersion>
  <MinorVersion>0</MinorVersion>
  <TaskIdInfo TaskGrouping="Single">
    <TaskName>bgp</TaskName>
  </TaskIdInfo>
</xsd:appinfo>
 
   

Here is another example from a different component schema. This annotation includes a list of task names.

<xsd:appinfo>
  <MajorVersion>1</MajorVersion>
  <MinorVersion>0</MinorVersion>
  <TaskIdInfo TaskGrouping="And">
    <TaskName>ouni</TaskName>
    <TaskName>mpls-te</TaskName>
  </TaskIdInfo>
</xsd:appinfo>
 
   

Task names indicate what permissions are required to access the data below the object. In the example, the task names ouni and mpls-te are specified for the object. The task names apply to the object and are inherited by all of the descendants of the object in the schema. In other words, the task names that apply to a particular object are the task names specified for the object and the task names of all ancestors for which there is a task name specified in the schema.

The TaskGrouping attribute specifies the logical relationship among the task names when multiple task names are specified for a particular object. For example, for a client application to issue a <Get> request for the object containing the preceding annotation, the corresponding AAA user credentials must have read permissions set for both the ouni and mpls-te tasks (and any tasks inherited by the object). The possible values for the TaskGrouping attribute are And, Or, and Single. The value Single is used when there is only a single task name specified for the object.

Authorization Failure

If an operation requested by a client application fails authorization, an appropriate <Error> element is returned in the response sent to the client. For "native data" operations, the <Error> element is associated with the specific element or object where the authorization error occurred.

If a client application issues a <Get> request to retrieve all data below a container object, and if any subsections of that data require permissions that the user does not have, then an error is not returned. Instead, the subsection of data is not included in the <Get> response.