<commit_before># gNSI cert Service Protobuf Definition
**Contributors**: <EMAIL>, <EMAIL>, <EMAIL>
**Last Updated**: 2022-07-12

## Background

The cert service definition provides the API to be used for installing,
rotating, and testing PKI primatives used on network systems. The Rotate
and Install are bidirectional streaming rpcs which permit mutating
Certificates, Root Certificate Bundles, Certificate Revocation Lists.
For either an Install or Rotate stream it is possible to mutate one or
more of the elements, and to send a Finalize message once the in-flight
change has been verified to be operational. Failure to send the Finalize
message will result in the candidate element being discarded and the
original element being used instead.

## Motivation

Management of the PKI elements for a network system should have
a clear and direct method for installation and update.

### CertificateManagement.Install

CertificateManagemetn.Install will permit installation, and
verification of function, of any of the PKI elements. The normal
use-case would be to:

* send an Certificate and Key to a network system as an
InstallCertificateRequest.
* verify that the services which will use the certificate continues
to operate normally.
* send a FinalizeRequest to finish the installation process.

### CertificateManagement.Rotate

CertificateManagement.Rotate will permit rotation, and
verification of function, of any of the PKI elements.
The normal use-case would be to:

* send an CertificateBundle to a network system as a
RotateCertificateRequest.
* verify that the services which will use the new certificate bundle
continue to operate normally.
* send a FinalizeRequest to finish the rotateion process.

## User Experiences

### A Certificate is to be installed

Create a new Certificate and Key.

Send that certificate to the target network system with a
cert.InstallCertificateRequest to the cert.Install rpc. The
InstallCertificateRequest's install_request will be a
cert.Certificate.

Verify that the certificate newly deployed is usable by the relevant
services, that the services properly present the certificate upon
new service connections.

Send a cert.Finalize message to the cert.Install rpc to close
out the action.

If the stream is disconnected prior to the Finalize message being
sent, the proposed configuration is rolled back automatically.

### A CertificateRevocationList is to be installed

Create a new CertificateRevocationList (CRL).

Send that certificate to the target network system with a
cert.InstallCertificateRequest to the cert.Install rpc. The
InstallCertificateRequest's install_request will be a
cert.CertificateRevocationListBundle.

Verify that the CRL newly deployed is usable by the relevant
services.

Send a cert.Finalize message to the cert.Install rpc to close
out the action.

If the stream is disconnected prior to the Finalize message being
sent, the proposed configuration is rolled back automatically.

### A CertificateBundle is to be rotated or updated

Create, and test, a new CertificateBundle.

Send that policy to the target network system with a
cert.RotateCertificateRequest to cert.Rotate rpc. The
RotateCertificateRequest's rotate_request will be a cert.CertificateBundle.

Verify that the CertificateBundle newly rotated is used by services
which require it.

Send a Finalize message to the cert.Rotate rpc to close out the action.

If the stream is disconnected prior to the Finalize message being
sent, the proposed configuration is rolled back automatically.

## Open Questions/Considerations

None to date. <commit_msg>Address comment from review.<commit_after># gNSI cert Service Protobuf Definition
**Contributors**: <EMAIL>, <EMAIL>, <EMAIL>
**Last Updated**: 2022-07-12

## Background

The cert service definition provides the API to be used for installing,
rotating, and testing PKI primatives used on network systems. The Rotate
and Install are bidirectional streaming rpcs which permit mutating
Certificates, Root Certificate Bundles, Certificate Revocation Lists.
For either an Install or Rotate stream it is possible to mutate one or
more of the elements, and to send a Finalize message once the in-flight
change has been verified to be operational. Failure to send the Finalize
message will result in the candidate element being discarded and the
original element being used instead.

## Motivation

Management of the PKI elements for a network system should have
a clear and direct method for installation and update.

### CertificateManagement.Install

CertificateManagemetn.Install will permit installation, and
verification of function, of any of the PKI elements. The normal
use-case would be to:

* send an Certificate and Key to a network system as an
InstallCertificateRequest.
* verify that the services which will use the certificate continues
to operate normally.
* send a FinalizeRequest to finish the installation process.

### CertificateManagement.Rotate

CertificateManagement.Rotate will permit rotation, and
verification of function, of any of the PKI elements.
The normal use-case would be to:

* send an CertificateBundle to a network system as a
RotateCertificateRequest.
* verify that the services which will use the new certificate bundle
continue to operate normally.
* send a FinalizeRequest to finish the rotateion process.

## User Experiences

### A Certificate is to be installed

Create a new Certificate and Key.

Send that certificate to the target network system with a
cert.InstallCertificateRequest to the cert.Install rpc. The
InstallCertificateRequest's install_request will be a
cert.Certificate.

Verify that the certificate newly deployed is usable by the relevant
services, that the services properly present the certificate upon
new service connections.

Send a cert.Finalize message to the cert.Install rpc to close
out the action.

If the stream is disconnected prior to the Finalize message being
sent, the proposed configuration is rolled back automatically.

### A CertificateRevocationList is to be installed

Create a new CertificateRevocationList (CRL).

Send that certificate to the target network system with a
cert.InstallCertificateRequest to the cert.Install rpc. The
InstallCertificateRequest's install_request will be a
cert.CertificateRevocationListBundle.

Optional, verify that the CRL newly deployed is usable by the relevant
services.

Send a cert.Finalize message to the cert.Install rpc to close
out the action.

If the stream is disconnected prior to the Finalize message being
sent, the proposed configuration is rolled back automatically.

### A CertificateBundle is to be rotated or updated

Create, and test, a new CertificateBundle.

Send that policy to the target network system with a
cert.RotateCertificateRequest to cert.Rotate rpc. The
RotateCertificateRequest's rotate_request will be a cert.CertificateBundle.

Verify that the CertificateBundle newly rotated is used by services
which require it.

Send a Finalize message to the cert.Rotate rpc to close out the action.

If the stream is disconnected prior to the Finalize message being
sent, the proposed configuration is rolled back automatically.

## Open Questions/Considerations

None to date. 
{'fraction_non_alphanumeric': 0.03606602857539187, 'fraction_numerical': 0.0022194479123318076, 'mean_word_length': 5.0588235294117645, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5122892', 'n_tokens_mistral': 1741, 'n_tokens_neox': 1667, 'n_words': 984}