Manage Cryptographic Tokens and Certificates

Manage your Private PKI certificate settings

  • Updated on Jan 26, 2022

Customizing how Banyan issues cryptographic tokens and certificates is an advanced capability. Please contact us for assistance.


Public Key Infrastructure (PKI)

As in the diagram below, the Banyan component called Shield manages a private PKI (Public Key Infrastructure), also known as an Internal CA (Certificate Authority), to distribute cryptographic identities (typically X.509 Certificates) to clients and services in your organization.

Shield CA distributes certificates

Netagents running on Linux Hosts talk directly to Shield to receive certificates on behalf of workloads and services. The Banyan App (or other clients) communicate with Shield via the Command Center’s RESTful APIs.

Certificates Issued

Banyan issues server certificates for hosted services and SSH servers.

Cert Nickname Format Subject CN / KeyID Validity Period Server Name and Purpose
ServiceCert X.509 Banyan Service ... 1 year (auto-rotated every 24 hours) Banyan Service, to secure hosted services
HostCert SSH ssh-rsa-cert ... host 1 year Linux Host, for SSH authentication

Banyan also issues various types of client certificates for use in different client authentication scenarios.

Cert Nickname Format Subject CN / KeyID Validity Period Client Name and Purpose
DeviceCert X.509 ManagedDevice-BNN ... 1 year (revoke via OCSP) Banyan Desktop App, for device registration
TrustCert X.509 Banyan Client ... 24 hours (adjustable) Banyan Desktop App, for access to TCP Services
WorkloadCert X.509 Banyan Netagent ... 1 year (auto-rotated every 24 hours) Linux Workloads, for service-to-service authNZ
SSHCert SSH ssh-rsa-cert ... user 24 hours (adjustable) Banyan Desktop App, for SSH authentication

Banyan “decorates” the certificates issued by Shield with client and server information.

For X.509 certificates, we use X.509 Subject Alternative Name - SAN, an extension to X.509 that allows various values to be associated with a certificate using a subjectAltName field. In server X.509 certs, the SAN field DNS Name contains the Banyan ServiceName. In client X.509 certs, the SAN field DNS Name contains the client’s Roles.

For SSH certificates, Banyan used the Principals field. In client SSH cert, the Principals field contains the client’s Roles.

Customizing your private PKI

Banyan enables easy management of cryptographic tokens and certificates in a unified Advanced Settings page within the Banyan Command Center. To access the Advanced Settings page, navigate to Settings > TrustProvider Settings > Advanced Settings.

If your organization does not yet have a Cluster coordinator (i.e., Shield) configured, the Private Certificate Authority (CA) section displays a prompt to “Install a cluster before configuring the certificate(s)” instead of the Private Certificate Authority (CA) fields.

Issuing X.509 CA Certificate

Your organization’s Issuing CA cert is automatically distributed to all your devices and hosts. The Issuing Certificate field displays the issuing certificate for your organization. This field is not editable, and it displays the same CA certificate displayed on a cluster’s details page (Directory & Infrastructure > Clusters > (cluster name) > Installation & Device Cert Parameters > CA Certificate).

Root X.509 CA Certificate

If your Issuing CA is an Intermediate CA, you can upload your organization’s Root CA certificate so it can be distributed along with the Issuing CA.

Select Add Root Certificate, paste your Root Certificate, and then select Save.

SSH CA Public Key

Banyan’s PKI infrastructure uses the same key-pair as in your Issuing X.509 CA Certificate to provision SSH certificates. You can find your SSH CA’s public key in the SSH CA Public Key field.

Authentication Tokens and Certificates

By default, Banyan issued short-lived tokens (TrustToken) and short-lived certificates (TrustCert, SSHCert) are valid for 24 hours. To configure the expiration period, change the number of Hours, and then select Update.