1. REST API for the Session Border ControllerREST API for Session Border Controller, Enterprise Session Border Controller, and Subscriber-Aware Load Balancer, Release 10.0.0
  2. Examples
  3. Replace the TLS Certificate

Replace the TLS Certificate

On virtual platforms, the SBC can be deployed with a temporary self-signed certificate that allows a client to access the REST API. This certificate should be replaced with a certificate signed by a valid Certificate Authority (CA). The API endpoints under the certificate category, which are supported only on virtual platforms, allow a client to create a new certificate-record, generate a Certificate Signing Request (CSR) for that certificate-record, and then import a CA-signed certificate.

Table - Prerequisites

Prerequisite More Information
Authenticate Authenticate

This example assumes you have exported the access token to the variable $TOKEN.

Task 1: Create the Certificate Signing Request

  1. Retrieve the certificate-record template.

    The template of a configuration element is a data structure containing all required sub-elements and supported attributes with their default values, along with any specified optional sub-elements.

    curl -X GET -o response.xml \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/elementTypes/template?elementType=certificate-record"

    The response is saved to the file response.xml.

  2. Copy the content between the opening and closing <configElement> tags to a new file called certificate-record.xml.

    If you are on a Linux system with xmllint installed, you may optionally format the XML before writing it to the file system. 

    sed -n '/<configElement>/,/<\/configElement>/p' response.xml | xmllint --format - > certificate-record.xml

  3. Open the certificate-record.xml file and set values for each attribute.

    Note:

    See the ACLI Reference Guide for a description of each attribute.

    The name attribute must have a value. 

    <?xml version="1.0"?>
<configElement>
  <elementType>certificate-record</elementType>
  <attribute>
    <name>name</name>
    <value>restless</value>
  </attribute>
  <attribute>
    <name>country</name>
    <value>US</value>
  </attribute>
  ...
<configElement>

  4. Acquire the configuration lock.

    curl -X POST \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/lock"

  5. Add the certificate-record configuration element to the SBC.

    curl -X POST \
    -d@certificate-record.xml \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/configElements"

  6. Save, verify, and activate the configuration.

  7. Generate a CSR for your new certificate-record.

    Use the name attribute to identify the new certificate-record. 

    curl -X PUT \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/certificates/generateRequest?recordName=restless"

    The server returns the CSR.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <data>
    <CertificateRequest>
      <recordName>restless</recordName>
      <certificateSignedRequest>-----BEGIN CERTIFICATE REQUEST-----
MIICzDCCAbQCAQAwVDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMRMwEQYDVQQH
ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALOFsEcqNpSNG+LZsuaH
EwpCdXJsaW5ndG9uMRQwEgYDVQQKEwtFbmdpbmVlcmluZzENMAsGA1UEAxMEQWNt
9xC6KbZySRpbFz3XDLV+HCECZe2W9pEv6yiGMWFRg+zj4snFIdMM8+fOLiW2FMlB
rEe3wysGgZ9a388v2o+5lf1MdXVUmiZyuaq5yb2k3qM/KCMdsY9Y5JnTP7jaRuTM
X4XcuSY8GrYEO/WZUFSQHQxkTmr8YBucvbZIHMo+VNdzGLKtT+Whb9eFdMXoVLyw
MAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4IBAQAT4v2F/AbwMnzcnEsGMZ5h
J2d273Jv5BUARK35IFZUWcTk56/h7jYvh5wmukUlYtGg/0oAfzBHk6JFOb4sh9f/
W/pWRfgJ2iJk4eyxR4wYB3zPKmXaiDfJ/UrmmJk0kg4o4fnSld+sdFXOkHK1/JGL
entSxbePd2kJr+kh91JVndQ1wKI3oMnW3afa1vLG8M/UDZh6riCEFaoFNmfLdD0S
J5ySjy3pkedgQtkBVgYdgi0fwUtyUvfclLOE4rNkoLegxMaxX52kkvmhvKsJ5C4V
oH0CAwEAAaAzMDEGCSqGSIb3DQEJDjEkMCIwCwYDVR0PBAQDAgWgMBMGA1UdJQQM
4hDaJMPin4i0wRh4sGPplBL3sGsHptO2HkmKWZqMzXVHlD2xSK12f0vRGkCbGaji
ugKQjnkB7tjZeE4L7bm7Q/49r8bKLZIJAaJ/3laTVH5w3VtI2jWQV04MRHrVdmDy
-----END CERTIFICATE REQUEST-----
</certificateSignedRequest>
    </CertificateRequest>
  </data>
  <messages/>
  <links/>
</response>

  8. Release the configuration lock.

    curl -X POST \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/unlock"

Task 2: Acquire the Certificate

Send the CSR to a Certificate Authority. The CA will reply with a certificate for you to install on the SBC.

WARNING:

Do not delete your CSR. You will need the CSR when renewing your certificate.

Task 3: Import the Certificate

  1. Create an empty file called cert.xml using the XML structure shown below. 

    <?xml version="1.0" encoding="UTF-8"?>
<ImportCertificate>
    <recordName></recordName>
    <format>x509</format>
    <certificateRequest>
</certificateRequest>
</ImportCertificate>

  2. Set the recordName element to the name of the certificate-record previously added to the SBC.

  3. After the certificate authority responds with a certificate, paste the certificate into the <certificateRequest> element as shown below.

    <?xml version="1.0" encoding="UTF-8"?>
<ImportCertificate>
    <recordName>restless</recordName>
    <format>x509</format>
    <certificateRequest>-----BEGIN CERTIFICATE-----
MIIFMDCCAxigAwIBAgIBFjANBgkqhkiG9w0BAQUFADCBgTELMAkGA1UEBhMCVVMx
AoIBAQCzhbBHKjaUjRvi2bLmh6xHt8MrBoGfWt/PL9qPuZX9THV1VJomcrmqucm9
ZXJpbmcxDTALBgNVBAMTBEFjbWUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
UYPs4+LJxSHTDPPnzi4lthTJQSecko8t6ZHnYELZAVYGHYItH8FLclL33JSzhOKz
CzAJBgNVBAgMAk1BMRMwEQYDVQQHDApCdXJsaW5ndG9uMRQwEgYDVQQKDAtFbmdp
MDRaMD8xCzAJBgNMBIGA1UEChMLRW5naW5lVBAYTAlVTMQswCQYDVQQIEwJNQTEU
EmxhcnJ5LmVAb3JhY2xlLmNvbTAeFw0yMDA5MTUxMjM0MDRaFw0yNTA5MTUxMjM0
ZKC3oMTGsV+dpJL5obyrCeQuFQcas1nZPm8h+kcskfPCCfn2pu4N/Zj2d+vcYDzG
HQ4EFgQUZVBRSc1beAG+fzLfqXtqEVbi2WAwgbYGA1UdIwSBrjCBq4AU1laBwHsH
pN6jPygjHbGPWOSZ0z+42kbkzPcQuim2ckkaWxc91wy1fhwhAmXtlvaRL+sohjFh
9T+iGKb1cI00khtz7EyhgYekgYQwgYExCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJN
YWNsZS5jb22CCQDadtCGJeWr5DALBgNVHQ8EBAMCBaAwDQYJKoZIhvcNAQEFBQAD
BgNVBAMMDkFjbWUgUGFja2V0IE1BMSEwHwYJKoZIhvcNAQkBFhJsYXJyeS5lQG9y
FCowbP+DMkJeP0pSjw5KmXzGpuIQ2iTD4p+ItMEYeLBj6ZQS97BrB6bTth5Jilma
bmVlcmluZzEXMBUGA1UEAwwOQWNtZSBQYWNrZXQgTUExITAfBgkqhkiG9w0BCQEW
jM11R5Q9sUitdn9L0RpAmxmo4qB9AgMBAAGjgfMwgfAwCQYDVR0TBAIwADAdBgNV
DdfgEutmptjNP2dmfesPmVTfVNg9v/RgrHjFxbi/z6gyy1eTumIHzbpydvjm94WC
fvI12+MqToIG+xlbhCwZGvGeaBl8NbGWpStLtmisUY2/NUOyvBRPDBy8lCCdLX/w
iq5GMBdW6tAA8rzxJmjRgOJtmB5tQ89actULn9vuUl/uZgVuJDZC19Sbb6yAX3Nh
c0oAsC2kkp5E+Osjp2I8o7OnQ9rpu7wuIbKewFxsMNBLmaMaNDgT8t/JXzXE40Fy
QTETMBEGA1UEBwwKQnVybGluZ3RvbjEUMBIGA1UECgwLRW5naW5lZXJpbmcxFzAV
ggIBAA5xf2krzCC5a+FYr1/z4AIv9IMdKHM0oR2srejYqCEb7b9bGvN5Oc5PpGFa
e4uDzlyTrDrCYVBNBdrusD45bssGoFyancnycfcVmImaudEn1gwvo2Kv19nXmdjg
hK2hAZzq3o7PK2oy4dqjPOZ2C2UvaGvF8InxJ3C+C03RIBhP4Fjahgt7JvzyWoiU
SR3KDZjKcZerFaLaFqR7CIqaC4i5DB4b3uSwsB37DhvOQxwPpnIqjVPHg6zDYcx6
Is81AhPoYg4xKZAHIoPMyiPq/zFx9nW4u2kQtyeZIoGMA7wnUuY4FOiRgXlikS49
mas/VJIi3tBpVtv2LKaOkM1UK9nH5hQNhBkCu0iWhJEwp/7q
-----END CERTIFICATE-----</certificateRequest>
</ImportCertificate>

    Replace the contents of the <certificateRequest> element with the certificate you received from your Certificate Authority.

  4. Acquire the configuration lock.

    curl -X POST \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/lock"

  5. Import the certificate.

    curl -X PUT \
    -d@cert.xml \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/certificates/import"

Task 4: Update the Default TLS Profile

The default tls-profile element is used by the http-server element. Once the tls-profile element is updated and the SBC rebooted, the http-server element will use the new certificate.

  1. Save the default tls-profile to a file called response.xml. 

    curl -X GET -o response.xml \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/configElements?elementType=tls-profile&name=defaultTlsProfile"

  2. Copy the content between the opening and closing <configElement> tags to a new file called tls-profile.xml.

    If you are on a Linux system with xmllint installed, you may optionally format the XML before writing it to the file system. 

    sed -n '/<configElement>/,/<\/configElement>/p' response.xml | xmllint --format - > tls-profile.xml

  3. Open the tls-profile.xml file and update the value of the end-entity-certificate attribute to match the name of your new certificate-record. 

    <?xml version="1.0"?>
<configElement>
  <elementType>tls-profile</elementType>
  <attribute>
    <name>name</name>
    <value>defaultTlsProfile</value>
  </attribute>
  <attribute>
    <name>end-entity-certificate</name>
    <value>restless</value>
  </attribute>
  . . .
</configElement>

  4. Update the SBC with the new tls-profile.

    curl -X PUT \
    -d@tls-profile.xml \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/configElements"

  5. Delete the default self-signed certificate.

    curl -X DELETE \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/configElements?elementType=certificate-record&name=defaultSelfSignedRestCert"

  6. Then save, verify, and activate the configuration.

  7. Release the configuration lock.

    curl -X POST \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/configuration/unlock"

  8. Reboot the SBC.

    curl -X POST \
    --header "Authorization: Bearer $TOKEN" \
    "https://${SBCIP}/rest/v1.2/admin/reboot"