Cisco IOS XE: gRPC Network Operations Interface (gNOI) User Guide (EN)

Certificate Management Service

gRPC Network Operations Interface The Google Remote Procedure Call (gRPC) Network Operations Interface (gNOI) is a suite of microservices, each corresponding to a set of operations. This module describes the supported gNOI services. Information About the gRPC Network Operations Interface, on page 1 Additional References for the gRPC Network Operations Interface, on page 16 Feature Information for the gRPC Network Operations Interface, on page 17 Information About the gRPC Network Operations Interface gNOI Protocol gNOI defines a set of gRPC-based microservices for executing operational commands on network devices.

The gNMI service defines operations for configuration management, operational state retrieval, and bulk data collection through streaming telemetry. gNOI only allows the adoption of services that a device supports. gNOI supports the OS installation service. gNOI can be used with or without user authentication. User authentication is disabled by default. Use the gnxi secure-password-auth command to enable user authentication. For information about enabling user authentication through the OpenConfig model, see https://github.com/YangModels/yang/blob/master/vendor/ cisco/xe/1751/openconfig-system-management.yang . The gNOI protocol supports the following operations:

• Certificate Management • Bootstrapping • OS Installation Service • Factory Reset Service Certificate Management Service The Certificate Management Service primarily exports two main RPCs, Install and Rotate, that are used for the installation of new certificates, and the rotation of existing certificates on a device, respectively. The following RPCs are supported by the Certificate Management Service: gRPC Network Operations Interface 1

Стр. 1

Install RPC

• Install: Installs a certificate. All certificates are uniquely identified by a certificate ID. The certificate ID is a string. • Rotate: Rotates an existing certificate. • RevokeCertificates: Revokes one or more certificates. • GetCertificates: Queries all certificates. • CanGenerateCSR: Queries whether the device can generate a Certificate Signing Request (CSR). Trustpoints and certificates created through the RPCs mentioned above persist across switchovers and device reboots. The following is a sample Certificate Management Service definition:

service CertificateManagement { rpc Install(stream InstallCertificateRequest) returns (stream InstallCertificateResponse); rpc Rotate(stream RotateCertificateRequest) returns (stream RotateCertificateResponse); rpc RevokeCertificates(RevokeCertificateRequest) returns (RevokeCertificateResponse); rpc GetCertificates(GetCertificateRequest) returns (GetCertificateResponse); returns (CanGenerateCSRResponse); } rpc CanGenerateCSR(CanGenerateCSRRequest) Install RPC The Install RPC adds a new certificate to a device by creating a new CSR request. The new certificate is associated with a new certificate ID on the device.

If the device has a pre-existing certificate with the given certificate ID, the operation fails. The Install RPC is a bidirectional streaming RPC. It has an input (InstallCertificateRequest) and an output (IntsallCertificateResponse) both of which are streaming. If the stream is broken, or any steps in the process fail, the device rolls back the changes. The following is an example of the Install RPC definition and messages: rpc Install(stream InstallCertificateRequest) returns (stream InstallCertificateResponse); // Request messages to install new certificates on the target. message InstallCertificateRequest { // Request Messages.

oneof install_request { GenerateCSRRequest generate_csr = 1; LoadCertificateRequest load_certificate = 2; } } // Request to generate the CSR. message GenerateCSRRequest { // Parameters for creating a CSR. gRPC Network Operations Interface Install RPC gRPC Network Operations Interface 2

Стр. 2

Install RPC

CSRParams csr_params = 1; // The certificate id with which this CSR will be associated. The target // configuration should bind an entity which wants to use a certificate to // the certificate_id it should use. string certificate_id = 2; } // Parameters to be used when generating a Certificate Signing Request. message CSRParams { // The type of certificate which will be associated for this CSR. CertificateType type = 1; // Minimum size of the key to be used by the target when generating a // public/private key pair. uint32 min_key_size = 2; // If provided, the target must use the provided key type.

If the target // cannot use the algorithm specified in the key_type, it should cancel the // stream with an Unimplemented error. KeyType key_type = 3; // --- common set of parameters applicable for any type of certificate --- // string common_name = 4; // e.g "device.corp.google.com" string country = 5; // e.g "US" string state = 6; // e.g "CA" string city = 7; // e.g "Mountain View" string organization = 8; // e.g "Google" string organizational_unit = 9; // e.g "Security" string ip_address = 10; string email_id = 11; } // A certificate. message Certificate { // Type of certificate. CertificateType type = 1; // Actual certificate. // The exact encoding depends upon the type of certificate.

// for X509, this should be a PEM encoded Certificate. bytes certificate = 2; } message LoadCertificateRequest { // The certificate to be Loaded on the target. Certificate certificate = 1; // The key pair to be used with the certificate. This is provided in the event // that the target cannot generate a CSR (and the corresponding public/private // keys). KeyPair key_pair = 2; // Certificate Id of the above certificate. This is to be provided only when // there is an externally generated key pair. string certificate_id = 3; // Optional pool of CA certificates to be used for authenticating the client.

repeated Certificate ca_certificate = 4; } // A message representing a pair of public/private keys. message KeyPair { bytes private_key = 1; bytes public_key = 2; } gRPC Network Operations Interface Install RPC gRPC Network Operations Interface 3

Стр. 3

Rotate RPC

// Response Messages from the target for the InstallCertificateRequest. message InstallCertificateResponse { // Response messages. oneof install_response { GenerateCSRResponse generated_csr = 1; LoadCertificateResponse load_certificate = 2; } } // GenerateCSRResponse contains the CSR associated with the Certificate ID // supplied in the GenerateCSRRequest. When a Certificate is subsequently // installed on the target in the same streaming RPC session, it must be // associated to that Certificate ID. // // An Unimplemented error will be returned if the target cannot generate a CSR // as per the request. In this case, the caller must generate its own key pair.

message GenerateCSRResponse { CSR csr = 1; } // A Certificate Signing Request. message CSR { // Type of certificate. CertificateType type = 1; // Bytes representing the CSR. // The exact encoding depends upon the type of certificate requested. // for X509: This should be the PEM encoded CSR. bytes csr = 2; } After the target device is up and gNOI is in default state, the controller (a third-party implementation) uses the Install RPC to install a certificate that is signed by a Certificate Authority (CA). The certificate is uniquely identified by a certificate ID. This ID is used as the trustpoint name in the Public Key Infrastructure (PKI) configuration.

The installation will fail, if you try to install a certificate that has an existing certificate ID. The following section describes how a CSR is generated by a device: 1. The device generates a self-signed certificate through the Install RPC. The controller does not require a copy of this certificate because in encrypted mode (or gNMI default state) the controller does not validate the certificate presented by the target device. This is the default state. 2. The controller requests the device to generate a CSR, sends the CSR to the CA, and gets the signed certificate back from the CA. 3.

The signed certificate is installed into the device along with the CA certificates used to sign the certificate. The CA certificate is present in the ca_certificates bundle, and is required by the PKI to install the device certificate. 4. The gNMI or the gNOI service restarts using the newly installed certificate that is now in the provisioned state. Rotate RPC The Rotate RPC renews an existing certificate; a certificate that is already installed. If a certificate is not already installed, the Rotate RPC fails. A certificate that is not in use can be rotated, but the client cannot test it. The following is a sample Rotate RPC definition:

gRPC Network Operations Interface Rotate RPC gRPC Network Operations Interface 4

Стр. 4