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/

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.

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