Certificate based Authentication

/misc/config/grpc/ems.pem
/misc/config/grpc/ems.key
/misc/config/grpc/ca.cert

Note	For clients to use the certificates, ensure to copy the certificates from /misc/config/grpc/ The gRPC server advertises TLS 1.2 as the maximum TLS version when using a SUDI-based SSL profile.

Generation of Certificates

These certificates are typically generated using a Certificate Authority (CA) by the device. The EMS certificates, including the server certificate (ems.pem ), public key (ems.key ), and CA certificate (ca.cert ), are generated with specific parameters like the common name ems.cisco.com to uniquely identify the EMS server and placed in the /misc/config/grpc/ location.

The default certificates that are generated by the server are Server-only TLS certificates and by using these certificates you can authenticate the identity of the server.

Usage of Certificates

These certificates are used for enabling secure communication through Transport Layer Security (TLS) between gRPC clients and the EMS server. The client should use ems.pem and ca.cert to initiate the TLS authentication.

To update the certificates, ensure to copy the new certificates that has been generated earlier to the location and restart the server.

Custom Certificates

If you want to use your own certificates for EMS gRPC communication, then you can follow a workflow to generate a custom certificates with the required parameters and then configure the EMS server to use these custom certificates. This process involves replacing the default EMS certificates with the custom ones and ensuring that the gRPC clients also trust the custom CA certificate. For more information on how to customize the common-name , see Certificate Common-Name For Dial-in Using gRPC Protocol.

The gRPC Remote Procedure Calls (gRPC) server Transport Layer Security (TLS) version 1.3 support is a security feature that

• provides end-to-end communications security over networks,

• prevents unauthorized access and eavesdropping, and

• protects against tampering and message forgery.

The TLS private key is encrypted before being stored on the disk. For more details on SSL or TLS version certificates, keys, and communication parameters, see certz profile ID.

Workflow for SPIFFE ID-Based Authentication and Authorization for gRPC Services

The high-level workflow of SPIFFE ID-based authentication and authorization for gRPC services involves the following steps:

1. The EMS starts searching for the spiffe-user-map.json file at the location /misc/config/grpc/gnsi/credentialz/spiffe-user-map.json.

2. If the file exists, it is parsed, and the mapping is stored globally in the aaa/auth package.

3. If the file does not exist or parsing is unsuccessful, the mapping will be empty.

4. The EMS registers with the configuration manager to receive updates for the aaa configuration.

5. When processing requests in the Authentication interceptor, the spiffe-user mapping API checks for the SPIFFE ID mapping in the map created in step 2.

6. If the mapping exists, the API responds with the corresponding username.

7. If the mapping does not exist but the aaa configuration exists, the API responds with the configured username.

8. If neither the mapping nor the aaa configuration is present, the API responds with an empty string.

9. Upon a client connecting to the server, the server interceptor extracts the SPIFFE ID from the client's certificate and uses the mapping stored in the aaa/auth package to find the corresponding username.

10. The username identifies it and then includes the metadata into the context.

11. gRPC services that require XR Authorization will later verify the access rights for the username identified in the previous step when handling the request.

12. If the mapping is unsuccessful, the request is passed to the relevant service, such as gNMI, which then decides whether to grant or deny access based on its authorization requirements.

gNMI Replace Example

This example shows the gNMI replace request and response messages.

Request Message:
replace: <
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "config"
    >
    elem: <
      name: "hostname"
    >
  >
  val: <
    json_ietf_val: "\"testing123\""
  >
>

Response Message:
  path: <
    elem: <
      name: "system"
    >
    elem: <
      name: "config"
    >
    elem: <
      name: "hostname"
    >
  >
  op: REPLACE
>
message: <
>
timestamp: 1662873319202107537

How gNSI pathz Policy Works

Upon receiving a gNMI SetRequest message for a configuration change, the router applies an XPath-based pathz policy to determine the request's authorization. The pathz policy originates from a gNSI RPC within the router. The policy configurations can be established during the router's boot process or dynamically adjusted while the router is operational.

The router securely receives the initial pathz policy either through Secure Zero Touch Provisioning (sZTP) or a secure bootstrapping protocol like bootz when booting up. The policy includes the user or group name and a list of rules defining XPaths and their associated access permissions. The policy is enforced before processing any gNMI requests.

Authorization by the gNSI pathz policy is granted or denied based on user or group credentials, permitting or declining the gNMI SetRequest accordingly.

gNMI Authorization Using gNSI pathz Policy

Starting from Release 24.2.11, you can perform gNMI XPath-based authorization using gNSI pathz policies.

The gnsi-pathz YANG model defines the following counters and timestamps for each configured rule READ, WRITE, PERMIT, and DENY.

• access-rejects: 64-bit

• last-access-reject: timestamp

• access-accepts: 64-bit

• last-access-accept: timestamp

The counters get incremented per accepted or rejected XPath (Example, per gNMI request).

Define Authorization Policy for a gNSI Pathz

The authorization policy for gNSI Pathz consists of three components.

How Authorization Policy Matching Rules Work

Policy evaluation results with a single best match rule for the provided {user, path, or mode}. If multiple best matches emerge, an error is logged, and the evaluation fails.

If no matching rule is found, an implicit DENY is applied and detailed in a log entry.

The authorization evaluation process results in a PERMIT or DENY decision, along with the version of the policy and the identifier of the rule applied.

Scenario for Authorization Policy Rules

For user Bob, the following authorization rules apply:

• READ or WRITE (gNMI request) access to the XPath /interfaces/interface[FourHundredGigE0/0/0/0] is granted under rules 1 and 2.

• READ access to the XPath /interfaces/interface[FourHundredGigE1/1/1/1] is granted under rule 5 due to the longest match criterion, which specifies READ mode. WRITE access to this path is denied by rule 3.

• WRITE access to the XPath /interfaces/interface[FourHundredGigE2/2/2/2] is granted being a member of the Admins group as specified by rule 4. Without the Admin membership, access is denied by the default deny all rule.

• READ access to the XPath /interfaces/interface[FourHundredGigE2/2/2/2] is granted under rule 5, independent of group affiliation.

For user Jim, the following authorization rule applies:

• Access to the XPath /interfaces/interface[FourHundredGigE0/0/0/0] is controlled by a policy that favors personal user permissions over group permissions. As a result, although the admins group is allowed access, Jim is individually denied access because the policy emphasizes user-specific rules.

The gRPC Network Operations Interface (gNOI) Packet Link Qualification service provides a way to certify link quality between a generator and a reflector device. The generator device generates test traffic and sends it out of the requested interface, maintaining counters of the sent, received, errored, and dropped packets. The reflector device loops back the traffic on the requested interface. The Packet-Based Link Qualification service verifies that the packets are sent and received on the requested interface. You can obtain the transmission rate and the link's capacity range for that interface from the gNSI Packet Link Qualification RPC messages: Capabilities and Get.

To view the packet link qualification specification, see the Github repository.

Link Qualifications Based on Timing

When you run the Create RPC (see table Packet Link Qualification (PLQ) RPCs), it creates a set of link qualifications based on either it’s NTP-based or RPC-based timing.

For both NTP-based and RPC-based timings, the qualification start time must be set no earlier than the minimum setup duration from the current time, as specified in the Capabilities RPC (see table Packet Link Qualification (PLQ) RPCs) response message.

NTP-based timing specifies:

• Specific start time

• Specific end time

• Teardown time

RPC-based timing specifies:

• Presync duration (duration from the current time to when the setup should start)

• Setup duration

• Qualification duration

• Postsync duration (duration from the end of the qualification to when the teardown should start)

• Teardown duration

The gRPC Network Operations Interface (gNOI) Healthz is gRPC service that focuses on the health check, and monitoring of the network devices. It determines whether all the nodes of a network are fully functional, degraded, or must be replaced. The gNOI Healthz process involves

• waiting for the health status data from various subsystem components

• inspecting and analyzing health status data to identify any unhealthy entities, and

• collecting logs.

gNOI Healthz, in conjunction with gNMI telemetry, monitors the health of network components.

When a component becomes HEALTHY or UNHEALTHY, a telemetry update is sent for that health event. For more details about the health event, see gNOI Healthz RPCs . When a system component changes its state to UNHEALTHY, the intended artifacts (debug logs, core file, and so on) are generated automatically at the time of the health event.

Router health status updates workflow

1. The client subscribes to the component's OpenConfig path with an ON_CHANGE request and waits for a health event to occur. When a health event is detected in the router for that component, the client receives a notification. The client monitors these parameters:

   • status: Health, Unhealthy, or Unknown

   • last-unhealthy time: Timetsamp of last known healthy state

   • unhealthy-count: Number of times the particular component is reported unhealthy

2. When the router receives gNOI Healthz RPCs from gNOI client, it performs these actions and responds to the gNOI client.

   Table 15. gNOI healthz RPCs

   When the gNOI client sends...	The Router...
   Get RPC	retrieves the latest set of health statuses that are associated with a specific component and its subcomponents.
   List RPC	returns all events that are associated with a device.
   Artifact RPC	retrieves specific artifacts that are listed by the target system in the List() or Get() RPC.
   Acknowledge RPC	acknowledges a series of artifacts that are listed by the Acknowledge() RPC.
   Check RPC	performs intensive health checks that may impact the service, ensuring they are done intentionally to avoid disruptions.

Updating the gRPC-Level Authorization Policy in the Router Using gNSI Client

Before you start

When a router boots for the first time, it should have the following prerequisites:

• The gNSI.authz service is up and running.

• The default gRPC-level authorization policy is added for all gRPC services.

• The default gRPC-level authorization policy allows access to all RPCs.

The following steps are used to update the gRPC-level authorization policy:

1. Initiate the gNSI.authz.Rotate() streaming RPC. This step creates a streaming connection between the router and management application (client).

   Note	Only one gNSI.authz.Rotate() must be in progress at a time. Any other RPC request is rejected by the server.

2. The client uploads new gRPC-level authorization policy using the UploadRequest message.

   Note

   There must be only one gRPC-level authorization policy in the router. All the policies must be defined in the same gRPC-level authorization policy which is being updated. As gNSI.authz.Rotate() method replaces all previously defined or used policies once the finalize message is sent. The upgrade information is passed to the version and the created_on fields. These information are not used by the gNSI.authz service. It is designed to help you to track the active gRPC-level authorization policy on a particular router.

3. The router activates the gRPC-level authorization policy.

4. The router sends the UploadResponse message back to the client after activating the new policy.

5. The client verifies the new gRPC-level authorization policy using separate gNSI.authz.Probe() RPCs.

6. The client sends the FinalizeRequest message, indicating the previous gRPC-level authorization policy is replaced.

   Note	It is not recommended to close the stream without sending the finalize message. It results in the abandoning of the uploaded policy and rollback to the one that was active before the gNSI.authz.Rotate() RPC started.

{
  "version": "version-1",
  "created_on": "1632779276520673693",
  "policy": {
    "name": "gNSI.ssh policy",
    "allow_rules": [{
      "name": "admin-access",
      "source": {
        "principals": [
          "spiffe://company.com/sa/V1",
          "spiffe://company.com/sa/V2"
        ]
      },
      "request": {
        "paths": [
          "/gnsi.ssh.Ssh/*"
        ]
      }
    }],
    "deny_rules": [{
      "name": "sales-access",
      "source": {
        "principals": [
          "spiffe://company.com/sa/V3",
          "spiffe://company.com/sa/V4"
        ]
      },
      "request": {
        "paths": [
          "/gnsi.ssh.Ssh/MutateAccountCredentials",
          "/gnsi.ssh.Ssh/MutateHostCredentials"
        ]
      }
    }]
  }
}

Updating the gRPC-Level Authorization Policy file Using Exec Command

Use the following steps to update the authorization policy in the router.

1. Create the users profiles for the users who need to be added in the authorization policy. You can skip this step if you have already defined the user profiles.

   The following example creates three users who are added in the authorization policy.

   
   Router(config)#username V1
   Router(config-un)#group root-lr
   Router(config-un)#group cisco-support
   Router(config-un)#secret x
   Router(config-un)#exit
   Router(config)#username V2
   Router(config-un)#group root-lr
   Router(config-un)#password x
   Router(config-un)#exit
   Router(config)#username V3
   Router(config-un)#group root-lr
   Router(config-un)#password x
   Router(config-un)#commit

2. Enable tls-mutual to establish the secure mutual between the client and the router.

   
   Router(config)#grpc
   Router(config-grpc)#port 0
   Router(config-grpc)#tls-mutual
   Router(config-grpc)#certificate-authentication
   Router(config-grpc)#commit

3. Define the gRPC-level authorization policy.

   The following sample gRPC-level authorization policy defines authorization policy for the users V1, V2 and V3.

   
   {
       "name": "authz",
       "allow_rules": [
           {
               "name": "allow all gNMI for all users",
               "source": {
                   "principals": [
                       "*"
                   ]
               },
               "request": {
                   "paths": [
                       "*"
                   ]
               }
           }
       ],
       "deny_rules": [
            {
               "name": "deny gNMI set for oper users",
               "source": {
                   "principals": [
                       "V1"
                   ]
               },
               "request": {
                   "paths": [
                       "/gnmi.gNMI/Get".
                   ]
               }
           },
   
           {
               "name": "deny gNMI set for oper users",
               "source": {
                   "principals": [
                       "V2"
                   ]
               },
               "request": {
                   "paths": [
                       "/gnmi.gNMI/Get"
                   ]
               }
           },
           {
               "name": "deny gNMI set for oper users",
               "source": {
                   "principals": [
                       "V3"
                   ]
               },
               "request": {
                   "paths": [
                       "/gnmi.gNMI/Set"
                   ]
               }
           }
       ]
   }
    
   

4. Copy the gRPC-level authorization policy to the router.

   The following example copies the gNSI Authz policy to the router:

   -bash-4.2$ scp test.json V1@192.0.2.255:/disk0:/
   Password: 
   test.json                                                                                                                 100%  993   161.4KB/s   00:00    
   -bash-4.2$
   

5. Activate the gRPC-level authorization policy to the router.

   The following example loads the policy to the router.

   
   Router(config)#gnsi load service authorization policy /disk0:/test.json
   Successfully loaded policy
   

Verification

Router#show gnsi service authorization policy
Wed Jul 19 10:56:14.509 UTC{
    "version": "1.0",
    "created_on": 1700816204,
    "policy": {
        "name": "authz",
        "allow_rules": [
            {
                "name": "allow all gNMI for all users",
                "request": {
                    "paths": [
                        "*"
                    ]
                },
                "source": {
                    "principals": [
                        "*"
                    ]
                }
            }
        ],
        "deny_rules": [
            {
                "name": "deny gNMI set for oper users",
                "request": {
                    "paths": [
                        "/gnmi.gNMI/*"
                    ]
                },
                "source": {
                    "principals": [
                        "User1"
                    ]
                }
            }
        ]
    }
}

In the following example, User1 user tries to access the get RPC request for which the permission is denied in the above authorization policy.

bash-4.2$ ./gnmi_cli -address 198.51.100.255 -ca_crt 
certs/certs/ca.cert -client_crt certs/certs/User1.pem -client_key 
certs/certs/User1.key -server_name ems.cisco.com -get -proto get-oper.proto

Output

E0720 14:49:42.277504   26473 gnmi_cli.go:195] 
target returned RPC error for Get("path:{origin:"openconfig-interfaces" elem:{name:"interfaces"}
 elem:{name:"interface" key:{key:"name" value:"HundredGigE0/0/0/0"}}}
 type:OPERATIONAL encoding:JSON_IETF"): 
rpc error: code = PermissionDenied desc = unauthorized RPC request rejected 

gNSI Acctz Data Logging

The gNSI accounting (Acctz) is a gNSI accounting protocol that collects and transfers accounting records from a router to a remote collection service over a gRPC transport connection.

Starting from Release 24.3.1, you can log gRPC AAA accounting data through gNSI accounting (Acctz). The gNSI Acctz data is logged, stored in accounting records, and sent to gNSI client for monitoring purposes. These gNSI Acctz accounting records contain

• users' login or logout times,

• network access resources such as interface IP and port, and

• duration of each session.

The gNSI Acctz logging can be done using the RecordSubscribe() gRPC request to a router. For more information on the RecordSubscribe() RPC, see the GitHub repository.

gNSI Acctz Logging Stream Capacity

The gNSI Acctz logs are recorded in a queue, maintaining a history of the 10 most recent records. When the accounting queue is full and no gNSI Acctz collectors are connected, the stream drops the records. Besides the 10 records stored for streaming, up to 512 additional records are stored during processing. As new records arrive, the data stream continues until the gNSI session ends or an error occurs, such as a client disconnection due to network issues or the server going down. If the server's output buffer remains full for an extended period, new records are dropped until the collector starts receiving them.

When the queue reaches its full capacity, the system automatically replaces the oldest records with the newest ones. The router then transmits this logged information through gNSI to gNSI client for real-time monitoring purposes. You can configure the queue size using the grpc aaa accounting queue-size command.

Supported Records for gNSI Acctz Logging

gNSI Acctz logging system supports Command and gRPC service records.

Default Behavior and Verification of gNSI Acctz Logging

By default, gNSI Acctz records are logged when the configuration is enabled. You can verify the gNSI Acctz using show gnsi state , show gnsi acctz statistics , and show aaa accounting statistics commands.

Starting from Cisco IOS XR Release 24.4.1, the gNSI AcctzStream server-streaming service is used to collect and transfer accounting records from a router to a remote collection service over a gRPC transport connection, similar to the depricated gNSI Acctz protocol.

The collectors request for logs using the RecordSubscribe() gRPC from the gNSI AcctzSteam service running on the router. The logs are sent to the collectors through the RecordResponse() gRPC.

This feature has introduced the new grpc aaa accounting history-memomy command used to configure the maximum memory allocated for cached accounting history records. Use this command with the grpc aaa accounting queue-size configuration to effectively limit the EMSD memory used by cached accounting history records.