Reset Search
 

 

Article

KB43658 - How to add a device certificate to PCS appliance through DMI agent

« Go Back

Information

 
Last Modified Date3/1/2018 12:29 PM
Synopsis
This article provides information on how to add a device certificate to the PCS device through DMI agent.
Problem or Goal
The Device Management Interface (DMI) is an XML-RPC-based protocol used to manage networking devices. With the inbound DMI feature, the administrator can connect to the PCS using an SSH secure shell Command Line Interface (CLI) to manage the device which also included adding a device certificate to the PCS appliances.
Cause
Solution
The add-certificate RPC is used to add a certificate to the PCS appliance. The following types of certificates can be added using RPC:
  • Device certificate
  • Sun Java code signing certificate
  • Microsoft Authenticode certificate
The following are the parameters that need to be specified in the RPC:
  • Certificate type, the value of which can be one of DEVICE_CERT, CODESIGN_MSFT or CODESIGN_SUN
  • The certificate to add, encoded in base-64 format. The certificate and the private key should be packed together and specified here.
  • Password for decrypting the certificate
  • The interfaces to which the certificate needs to be applied to. This is applicable only for device certificates. 
Notes:
  • The certificate and key should be packed together. If the key is a separate file, the device certificate cannot be added through DMI and it will give “Could not read private key” error.
  • Generate the Base64 encoded format of the certificate and use it in the RCP command.
  • There should not be any spaces between <cert> and </cert>.
Below is the step by step procedure for adding a device certificate to the PCS appliance and mapping the Interface to it.

Steps Involved are as follows:
  • Use the add-certificate RPC format to first add the new device certificate.
  • Once the certificate is added, use the get-certificate-info RPC format to see the current available device certificates along with their port mapping.
  • To change the interface mapping, use the update-certificate RPC format. (Note: Currently only <type>DEVICE_CERT</type> is supported with update-certificate RPC format)
Step by Step procedure:
 
Step1) Add the new device certificate using the below RPC format:
 
RCP for adding device certificate without mapping it to any Interface:
 
<rpc message-id='1'>
<add-certificate>
<type>DEVICE_CERT</type>
<cert>paste the base64 encoding output of .pfx certificate here</cert>
<password>password that is used to protect the private key</password>
</add-certificate>
</rpc>
 
Step2) Once New device certificate is added, use the below RPC to check the port mapping with existing device certificates:
 
<rpc message-id="123">
<get-certificate-info>  
<type>DEVICE_CERT</type>
</get-certificate-info>
</rpc>

Step3) Use below RPC format to un-map the interface mapping from the certificate:
 
<rpc message-id="123">
<update-certificate>
<type>DEVICE_CERT</type>
<subject-common-name>common name of the device certificate from where you want to un-map the interface</subject-common-name>
<interfaces>
<internal-interfaces>
</internal-interfaces>
<external-interfaces>
</external-interfaces>
<management-interface>false</management-interface>
</interfaces>
</update-certificate>
</rpc>
 
Step4) Use the below RPC to map the new device certificate to the required interfaces:

RPC to map the certificate to only Internal Interface:
 
<rpc message-id="123">
<update-certificate>
<type>DEVICE_CERT</type>
<subject-common-name>Common Name of the certificate to which you want to map the interface</subject-common-name>
<internal-interfaces>
<internal-interface>&#60;Internal Port&#62;</internal-interface>
</internal-interfaces>
<external-interfaces>
</external-interfaces>
<management-interface>false</management-interface>
</interfaces>
</update-certificate>
</rpc>

RPC to map the certificate to both Internal and External Interface (Management port is not enabled)
 
<rpc message-id="123">
<update-certificate>
<type>DEVICE_CERT</type>
<subject-common-name>Common Name of the certificate to which you want to map the interface</subject-common-name>
<internal-interfaces>
<internal-interface>&#60;Internal Port&#62;</internal-interface>
</internal-interfaces>
<external-interfaces>
<external-interface>&#60;External Port&#62;</external-interface>
</external-interfaces>
<management-interface>false</management-interface>
</update-certificate>
</rpc> 

RPC to map the certificate to both Internal and External Interface (Management port is enabled)
 
<rpc message-id="123">
<update-certificate>
<type>DEVICE_CERT</type>
<subject-common-name>Common Name of the certificate to which you want to map the interface</subject-common-name>
<internal-interfaces>
<internal-interface>&#60;Internal Port&#62;</internal-interface>
</internal-interfaces>
<external-interfaces>
<external-interface>&#60;External Port&#62;</external-interface>
</external-interfaces>
<management-interface>true</management-interface>
</update-certificate>
</rpc>

Troubleshooting steps:
  • If the port is already mapped to some device certificate, following error will appear in the RPC session:
<rpc-reply message-id="12"><rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><error-type>rpc</error-type><error-tag>invalid-value</error-tag><error-severity>error</error-severity><error-message>Virtual port &apos;&lt;Internal Port&gt;&apos; is already in use by a Device Certificate</error-message></rpc-error></rpc-reply>]]>]]>
  • If the private key is not present (in case when key is not packaged together with the certificate), we will get the following error:
<rpc-reply message-id="12"><rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><error-type>rpc</error-type><error-tag>invalid-value</error-tag><error-severity>error</error-severity><error-message>Could not read private key, data type: PEM or PKCS12</error-message></rpc-error></rpc-reply>]]>]]>
  •  If the .pfx certificate base64 encoded value is incorrect, we will get the following errorr:
<rpc-reply message-id="" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><error-type>rpc</error-type><error-tag>invalid-value</error-tag><error-severity>error</error-severity></rpc-error></rpc-reply>]]>]]>
 
Related Links
https://www.pulsesecure.net/download/techpubs/current/711/pulse-connect-secure/pcs/8.2rx/ps-pcs-sa-8.2r3-dmi-solution-guide.pdf 
Attachment 1 
Created ByKshitij Gupta

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255