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.
  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;
}

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

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:

rpc Rotate(stream RotateCertificateRequest)
returns (stream RotateCertificateResponse);

// Request messages to rotate existing certificates on the target.
message RotateCertificateRequest {
  // Request Messages.
  oneof rotate_request {
    GenerateCSRRequest generate_csr = 1;
    LoadCertificateRequest load_certificate = 2;
    FinalizeRequest finalize_rotation = 3;
  }
}

// A Finalize message is sent to the target to confirm the Rotation of
// the certificate and that the certificate should not be rolled back when
// the RPC concludes. The certificate must be rolled back if the target returns
// an error after receiving a Finalize message.
message FinalizeRequest {
}

message RotateCertificateResponse {
  // Response messages.
  oneof rotate_response {
    GenerateCSRResponse generated_csr = 1;
    LoadCertificateResponse load_certificate = 2;
  }
}

The Rotate RPC differs from the Install RPC in the following ways:

• PKI has to save or cache the old certificate and the CA certificate when installing a new certificate (for the purpose of rollback).

• The controller creates a new connection to test whether the renewed certificate works, and in case of success, finalizes the certificate rotation.

This RPC is used to revoke one or more certificates, each uniquely identified by a certificate ID. Revocation of a certificate results in the corresponding trustpoint to be removed from the Cisco IOS XE configuration. If the corresponding trustpoints are currently in use, or if the trustpoints do not exist, revocation of the certificates may fail.

A RevokeCertificate RPC may have certificates revoked successfully or unsuccessfully. On the target device, revocation is a simple delete operation; the actual revocation with the CA is done by the client. If the client revokes a certificate that is in use, new connections fail, but the existing connections are unaffected.

The following is a sample RevokeCertificate RPC:

// An RPC to revoke specific certificates.
// If a certificate is not present on the target, the request should silently
// succeed. Revoking a certificate should render the existing certificate
// unusable by any endpoints.
rpc RevokeCertificates(RevokeCertificatesRequest)
returns (RevokeCertificatesResponse);

message RevokeCertificatesRequest {
  // Certificates to revoke.
  repeated string certificate_id = 1;
}

message RevokeCertificatesResponse {
  // List of certificates successfully revoked.
  repeated string revoked_certificate_id = 1;

  // List of errors why certain certificates could not be revoked.
  repeated CertificateRevocationError certificate_revocation_error = 2;
}

// An error message indicating why a certificate id could not be revoked.
message CertificateRevocationError {
  string certificate_id = 1;
  string error_message = 2;
}

This RPC queries all certificate IDs.

The response to the query contains the following information:

• Certificate information for all the certificates that are identified by a certificate ID.

• The list of endpoints, for example, tunnels, daemons, and so on, that use this certificate.

  Note	Endpoints are not supported.

Note	Responses do not contain the ca_certificate bundle.

The following is a sample GetCertificate RPC:

// An RPC to get the certificates on the target.
rpc GetCertificates(GetCertificatesRequest) returns (GetCertificatesResponse);

// The request to query all the certificates on the target.
message GetCertificatesRequest {
}

// Response from the target about the certificates that exist on the target what
// what is using them.
message GetCertificatesResponse {
  repeated CertificateInfo certificate_info = 1;
}

message CertificateInfo {
  string certificate_id = 1;
  Certificate certificate = 2;

  // List of endpoints using this certificate.
  repeated Endpoint endpoints = 3;

  // System modification time when the certificate was installed/rotated in
  // nanoseconds since epoch.
  int64 modification_time = 4;
}

// An endpoint represents an entity on the target which can use a certificate.
message Endpoint {
  // Type of endpoint that can use a cert. This list is to be extended based on
  // conversation with vendors.
  enum Type {
    EP_UNSPECIFIED = 0;
    EP_IPSEC_TUNNEL = 1;
    EP_DAEMON = 2;
  }
  Type type = 1;

  // Human readable identifier for an endpoint.
  string endpoint = 2;
}

This RPC queries whether a device can generate a CSR for a specific key type, certificate type, and key size. The supported key type is Rivest, Shamir, and Adelman (RSA), and the supported certificate type is X.509.

When this RPC request is made for installing a completely new certificate as part of the Install RPC, the device must ensure that the certificate ID is new and no entities on the device are bound to this certificate ID. If any existing certificate matches the certificate ID, this request fails.

When this RPC request is made for rotating an existing certificate as part of the Rotate RPC, the device must ensure that the certificate ID is already available. If certificate rotation proceeds to load the certificate, it must associate the new certificate with the previously created certificate ID.

The following is a sample CanGenerateCSR RPC:

// An RPC to ask a target if it can generate a Certificate.
rpc CanGenerateCSR(CanGenerateCSRRequest) returns (CanGenerateCSRResponse);

// A request to ask the target if it can generate key pairs.
message CanGenerateCSRRequest {
  KeyType key_type = 1;
  CertificateType certificate_type = 2;
  uint32 key_size = 3;
}

// Algorithm to be used for generation the key pair.
enum KeyType {
  // 1 - 500, for known types.
  // 501 and onwards for private use.
  KT_UNKNOWN = 0;
  KT_RSA = 1;
}

// Types of certificates.
enum CertificateType {
  // 1 - 500 for public use.
  // 501 onwards for private use.
  CT_UNKNOWN = 0;
  CT_X509 = 1;
}

// Response from the target about whether it can generate a CSR with the given
// parameters.
message CanGenerateCSRResponse {
  bool can_generate = 4;
}

The Install RPC transfers an image to a device. The RPC consists of the input InstallRequest RPC, and the output InstallResponse RPC, both of which are bidirectional streaming RPCs.

This RPC does not support Software Maintenance Update (SMU).

The following is a high-level message sequence for an Install RPC on a device with a single RP that is running the operating system Version 1:

1. A client initiates an Install RPC to the device.

2. The client sends a TransferRequest message to the device, with version set to Version 2.

3. The device responds with a TransferReady message to the client. This is required for the client to start transferring the image.

4. The client transfers the image by sending multiple transfer_content messages to the device.

5. Optionally, the device sends TransferProgress messages to the client.

6. The client sends a TransferEnd message to the device, indicating that the image transfer is complete.

7. In install mode, the device does an operation equivalent of the install add command programmatically. The contents of the package are extracted.

8. The device sends a Validated message, which contains the version extracted from the image, to the client, indicating that the image transfer is valid.

Note	If the Install RPC is stopped prematurely by the client, or if any part of the operation fails, the local image file is removed, and the install remove inactive command is invoked automatically. An appropriate status code is returned to the client.

The Activate RPC sets the requested operating system version as the version to be used at the next reboot, and reboots the target device. The RPC activates an installed operating system version. If the version is not already installed, the Activate RPC fails.

The client must provide a version that has been received in the Validated message of the Install RPC.

The following is the message sequence for an Activate RPC on a device with a single RP running operating system Version 1:

1. The client initiates an Activate RPC to a device.

2. The client sends an ActivateRequest message to the device with Version 2.

   For the purpose of this message sequence, assume that Version 2 is already installed through the Install RPC.

3. The device does a programmatic operation equivalent to the install activate commit command, if it is in install mode, or the install add file activate commit command if it is in bundle mode.

4. Because no errors are detected in the activate process, the device responds with an ActivateResponse(OK) message to the client.

5. The device reloads with Version 2.

6. When the device comes up after the reload, it does a programmatic operation equivalent to the install commit command.

Note	Only one inactive image version is supported. Because of this, if a client installs Version 2 and then Version 3, the Version 2 files get deleted. The following images display the image activation workflow.

The Verify RPC verifies the running OS version. The response to the RPC contains information about the support and presence of a standby RP.

If there was an error in the last activate RPC, that error is returned in the response as a string. The gNOI OS installation service uses the install operational model and platform model to populate this information. Currently, the install operational model does not support different versions running on two RPs.

gNOI factory-reset services return an empty ResetSuccess message upon successfully triggering the factory reset on a device.

Some of the error messages that are returned in the context of gRPC and factory reset services are described in this section:

Without using a cert.proto provisioning operation, or configuring gNOI with a signed certificate (not self-signed), the gNOI factory-reset service will always return the FAILED_PRECONDITION error code.