docs: add SSH CA revocation behavior, rotation guidance, and OpenSSH usage context (#60977)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: stacycarter <16823802+stacycarter@users.noreply.github.com>
Co-authored-by: Stacy Carter <stacycarter@users.noreply.github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>

Author: 3 people

content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise.md

@@ -76,6 +76,8 @@ Before you require secure methods of two-factor authentication, we recommend not
 
 You can use a SSH certificate authority (CA) to allow members of any organization owned by your enterprise to access that organization's repositories using SSH certificates you provide. {% ifversion ssh-user-ca %}{% ifversion ghec %}If your enterprise uses {% data variables.product.prodname_emus %}, enterprise{% elsif ghes %}Enterprise{% endif %} members can also be allowed to use the certificate to access personally-owned repositories.{% endif %} {% data reusables.organizations.can-require-ssh-cert %} For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities).
 
+{% data variables.product.github %} uses OpenSSH-format SSH user certificates to authenticate Git operations over SSH by validating the certificate's signature and fields (including its validity period) against a trusted SSH certificate authority (CA) configured at the organization and/or enterprise level.
+
 {% data reusables.organizations.add-extension-to-cert %}
 
 ### Adding an SSH certificate authority
@@ -104,7 +106,9 @@ You can enable or disable access to user-owned repositories with an SSH certific
 
 ### Deleting an SSH certificate authority
 
-Deleting a CA cannot be undone. If you want to use the same CA in the future, you'll need to upload the CA again.
+Deleting an SSH certificate authority (CA) from your enterprise settings on {% data variables.product.github %} can't be undone. If you want to trust the same CA again in the future, you'll need to add the CA back to {% data variables.product.github %} by uploading the CA's public key again in your enterprise's SSH certificate authority settings.
+
+Deleting a CA immediately prevents {% data variables.product.github %} from accepting SSH certificates signed by that CA, including certificates that have not yet expired. For CA rotation guidance, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#certificate-revocation-and-ca-rotation).
 
 {% data reusables.enterprise-accounts.access-enterprise %}
 {% data reusables.enterprise-accounts.settings-tab %}

content/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities.md

@@ -16,6 +16,8 @@ category:
 
 An SSH certificate is a mechanism for one SSH key to sign another SSH key. If you use an SSH certificate authority (CA) to provide your organization members and outside collaborators with signed SSH certificates, you can add the CA to your enterprise account or organization to allow these organization contributors to use their certificates to access organization resources.
 
+{% data variables.product.github %} uses OpenSSH-format SSH user certificates to authenticate Git operations over SSH by validating the certificate's signature and fields (including its validity period) against a trusted SSH certificate authority (CA) configured at the organization and/or enterprise level.
+
 {% data reusables.organizations.ssh-ca-ghec-only %}
 
 After you add an SSH CA to your organization or enterprise account, you can use the CA to sign client SSH certificates for organization members and outside collaborators. These organization contributors can use the signed certificates to access that organization's repositories.
@@ -27,7 +29,6 @@ Certificates added to your enterprise grant access to all organizations owned by
 Optionally, you can require that members and outside collaborators use SSH certificates to access organization resources. For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities) and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-ssh-certificate-authorities-for-your-enterprise).
 
 For example, you can build an internal system that issues a new certificate to your developers every morning. Each developer can use their daily certificate to work on your organization's repositories on {% data variables.product.github %}. At the end of the day, the certificate can automatically expire, protecting your repositories if the certificate is later compromised.
-
 {% ifversion ghec %}
 Organization contributors can use their signed certificates for authentication even if you've enforced SAML single sign-on (SSO), without the need to authorize the signed certificates.
 
@@ -88,3 +89,20 @@ You can restrict the IP addresses from which an organization member can access y
 ```shell
 ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:login@{% data variables.product.product_url %}=USERNAME -O source-address=COMMA-SEPARATED-LIST-OF-IP-ADDRESSES-OR-RANGES ./user-key.pub
 ```
+
+## Certificate revocation and CA rotation
+
+{% data variables.product.github %} validates SSH certificates based on their signature, fields (including their validity period), and whether the signing CA is trusted at the organization or enterprise level. OpenSSH certificates don't use certificate revocation lists (CRLs) or the Online Certificate Status Protocol (OCSP), so there is no way to revoke an individual already-issued certificate while continuing to trust the same CA.
+
+To invalidate certificates before they naturally expire, remove the issuing CA from your organization or enterprise settings. Removing a CA immediately prevents {% data variables.product.github %} from accepting any SSH certificates signed by that CA.
+
+> [!WARNING]
+> Removing a CA from your organization or enterprise settings invalidates all certificates it has signed, including certificates that have not yet expired.
+
+To rotate a CA with minimal disruption:
+
+1. Add the new CA to your enterprise or organization settings.
+1. Update your certificate issuance system to sign new certificates with the new CA.
+1. After all users have received new certificates from the new CA, remove the old CA.
+
+Issuing short-lived certificates reduces the window of risk if a certificate is compromised. For more information about managing CAs, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities) and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-ssh-certificate-authorities-for-your-enterprise).

content/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities.md

@@ -33,6 +33,8 @@ If you require SSH certificates for your enterprise, enterprise members should u
 
 ## Deleting an SSH certificate authority
 
+Deleting an SSH CA from your organization immediately prevents {% data variables.product.github %} from accepting SSH certificates signed by that CA, including certificates that have not yet expired. For CA rotation guidance, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#certificate-revocation-and-ca-rotation).
+
 {% data reusables.profile.access_org %}
 {% data reusables.profile.org_settings %}
 {% data reusables.organizations.security %}