In this section:


The Public Key Infrastructure (PKI) provides a common set of infrastructure features supporting public key and certificate-based authentication based on the RSA public/private key pairs and X.509 digital certificates.

Certificate Types

Local-Internal Certificates

In previous SBC versions, the RSA key pairs and Certificate Signing Request (CSR) for SBC platforms were generated on an external workstation. The CSR was then submitted to a Certificate Authority, and the resulting certificate was received back from the CA, copied onto the workstation, and combined with the private key in a PKCS#12 file, which was used to install the key pair and certificate onto the SBC.

The SBC application can now generate and install RSA key pairs and generate Certificate Signing Request (CSR) on the SBC system itself. The certificate request is sent to a CA, and the issued certificate is then installed on the SBC. The local-internal certificate option simplifies the certificates and keys managing process and also provides more security since the private key never leaves the SBC. For steps to configure local-internal certificates, see Generating PKI Certificates.

Certificate file format: PEM

Local Certificates

Local certificates are credentials belonging to the local system, which it presents to peers to prove their identity. You must upload local certificate files to the system before installing the certificates. For Cloud SBC platforms, you must upload the local certificate files to active and standby nodes.

Certificate file format: PKCS#12 containing both the local SBC certificate and corresponding private key, or the local certificate and corresponding private key in PEM or DER format.

Remote Certificates

Remote certificates are credentials belonging to Certificate Authorities (CA). The copies of these certificates are installed in the SBC because they are either part of a chain of certificates the local system will present to peers, or because the corresponding CAs are trust anchors for the local system. You should also install certificates belonging to non-CA remote systems as trust anchors in this manner. You must upload remote certificate files in DER format to the system before installing the remote certificates. For Cloud SBC platforms, you must upload the remote certificate files to active and standby nodes.

The Certificate Authority (CA) certificates and trusted remote certificates contain public key certificates; they do not contain the private keys. The CA certificates and remote certificates are Distinguished Encoding Rules (DER) format files, a method for encoding a data object (such as an X.509 certificate) that uses a digital signature to bind together a public key with an identity.

Certificate file format: DER



Note

The SBC supports a maximum of 4,096 TLS certificates/CAs (both local and remote).

The SBC allows importing of a single certificate in a single file only. If a CA provides a .p12 or a .pfx certificate bundle with multiple CA certificates in it, extract the certificates from the bundle, store them in separate files, and import them separately.

Note

The DER content of the certificate being installed must be under 6400 Bytes.


Command Syntax

Set Command Syntax

% set system security pki certificate <certificate name>
	fileName <1-255 characters>
	passPhrase <pass phrase>
	state <disabled | enabled>
	type <local | local-internal | remote>
	keyFileName <1-255 characters>

% show system security pki
 
% delete system security pki

Request Command Syntax

% request system security 
	eventLogValidation 
        deleteUserPrivateKey
        generateDefaultKeys
        setUserPrivateKey <uniqueUserPrivateKeyName> <userPrivateKey>
        showPublicKey <default/user>
    generateSipHeaderEncryptionKeys
	pki 
		certificate <certificate name>
			generateCSR
				csrSub (max 255 chars)
				keySize (keySize1K | keySize2K | keySize4K | keySizeEcDsaSecp521rl 
				subjectAlternativeDnsName (0-4096 chars)
			importCert certContent (max 4096 chars)
			retrieveCertContent

Command Parameters

Note

The subjectAlternativeDnsNames field limit is 4096 characters.


Set system security parameters

Parameter

Length/Range

Description

certificate

Up to 23 characters

<certificate name> – The name of the certificate object on the SBC.

fileName

Up to 255 characters

<filename> – Enter the name of the file that contains the certificate.

Supported file formats:

  • Local-Internal: PEM
  • Local: PKCS#12, PEM, DER
  • Remote: DER, PEM

keyFileName

Up to 255 characters

The name of the file containing the private key in DER/PEM format.

Leave this parameter empty if importing a PKCS#12 file.

passPhrase

Up to 23 characters

Specifies either the pass-phrase to decrypt the RSA private key in the PKCS#12 file or the pass-phrase to decrypt the encrypted private key in the "Key File Name," depending upon the file (PKCS#12, PEM) you import.

state

N/A

Enable this flag to use the certificate once it has been installed. 

  • disabled (default) – Prohibits the PKI certificate from being used by the SBC for authenticating remote peers (when this is a remote certificate) OR presenting its own identity (in case of a local or local-internal certificate).
  • enabled – Certificate is usable by the SBC for authentication purposes.

type

N/A

Specifies the certificate type.

  • local – Certificate belongs to (has as its subject) the local system itself; the key pair and CSR were generated elsewhere.
  • local-internal – Certificate belongs to (has as its subject) the local system itself; the key pair and CSR were generated on this machine.
  • remote – Certificate belongs to (has as its subject) a remote entity such as a  CA or peer device.

Request Parameters

Parameter

Description

eventLogValidation

deleteUserPrivateKey – Delete an existing user-submitted private key. When the key is removed the SBC will revert back to using its default private key.

generateDefaultKeys – Requests the generation of a new default SBC-generated private key pair.

setUserPrivateKey <uniqueUserPrivateKeyName> <userPrivateKey> – Configures the user-submitted private key. The private key is encrypted in CDB using existing CDB encryption methods. The user-submitted private key is only available internally. The key is encrypted and hidden, thus not displayable, once configured in CDB.

showPublicKey <user/default> – Access the public key associated with the chosen private key. 

generateSipHeaderEncryptionKeys

Use this command to generate header encryption keys. A "Success" or "Failure" indication is returned. The SBC then adds the key-Id to each encrypted header based on which key is selected as the correct key for decryption.

The SBC stores up to two sets of keys at any given time. There is no limit to the number of times this command may be executed. Additionally, there is no specific time delay required before reissuing the command.

NOTE: Generating new keys too frequently may lead to a situation where the SBC receives a request with an expired key-id (i.e. the current header encryption key is over-written due to the new key generation) causing unsuccessful decryption of headers. This may lead to call failures any calls caught in the transition to the new key-id.

pki

PKI certification configuration details.

  • certificate <certificateName> –The name of the certificate object on the SBC.
    • generateCSR – Use this parameter to generate CSR (Certificate Signing Request).

      • csrSub – CSR subject name (max 255 chars). Place the parameter value within quotation marks if a string contains a space.

      • keySize – The size of the key pair, in bits, to generate the private key via openssl command.

        • keySize1K (1024 bits)

        • keySize2K (2048 bits)

        • keySize4K (4096 bits)
        • keySizeEcDsaSecp521rl     

      • subjectAlternativeDnsName – Alternative DNS subject name(s). Multiple alternative names can be specified using "," (comma) separator. (0-4096 chars). Example:  "nj.example.com, in.example.com, uk.example.com, ca.example.com, tx.example.com"

    • importCert certContent – Import PEM format certificate (max 4096 characters).
      Note: When issuing this command, the SBC enables multi-line mode automatically. To exit multi-line mode you must press Ctrl+D manually.
    • retrieveCertContent – Retrieve content of an existing PKI certificate (local, local-internal and remote).

Command Examples

Configuration example for local and remote certificate types:

set system security pki certificate SBC_LOCAL fileName sbc_server.p12 passphrase CertPassSecret type local state enabled
set system security pki certificate COMPANY_CA filename company_ca.der type remote state enabled
commit

set system security pki certificate COMPANY_CA filename company_ca.pem type remote state enabled
commit

show system security pki certificate SBC_LOCAL
state      enabled;
fileName   sbc_server.p12;
passPhrase $7$pedr0+bl4Mq95P0ITV/idUlmqRL4xUWR;
type       local;

show system security pki certificate COMPANY_CA
state    enabled;
filename company_ca.der;
type     remote;


Configuration example for local-internal certificate type:

set system security pki certificate test3 type local-internal
commit

request system security pki certificate test3 generateCSR csrSub /C=US/ST=MA/L=Westford/O=Ribbon/CN=swe03.ribbon.com keySize keySize2K


After receiving the signed certificate from CA, you can configure the local-internal certificate from a PEM file, or copy-paste the PEM file content (importCert certContent).

set system security pki certificate test3 fileName test3.pem state enabled
commit
 
request system security pki certificate test3 importCert certContent

Value for 'certContent' (<string, min: 0 chars, max: 4096 chars>):

[Multiline mode, exit with ctrl-D.]

> -----BEGIN CERTIFICATE-----

MIIDrzCCAxGgAwIBAgIJAOW6z3FjlVbjMAoGCCqGSM49BAMDMEsxCzAJBgNVBAYT

...

Import certificate success.

set system security pki certificate test3 state enabled
commit


Configuration example - Importing PEM/DER certificates and keys:

set system security pki certificate newcert type local fileName mycert.pem keyFileName mycert.key passPhrase sonus
Commit complete.

Configuration example - The PEM/DER keys are supported:

set system security pki certificate newcert4 type local fileName mycert.pem keyFileName mycert.key.der
Commit complete.

Configuration example - The PKCS12 certificates are not supported in FIPS mode:

set system security pki certificate myp12 state enabled type local fileName mycert.p12 passPhrase sonus
Aborted: 'system security pki certificate': PKCS12 certs are not supported in FIPS mode; please provide both cert and key as PEM/DER.

Configuration example - Importing encrypted keys without passphrase fails:

set system security pki certificate newcert3 type local fileName mycert.pem keyFileName mycert.key.enc
Aborted: 'system security pki certificate': Failed to read private key, please verify key/passphrase