satellite-cssm synchronization file exchange overview · cssm sends the synchronization...

Ó 2017 Cisco – All Rights Reserved 1

Satellite-CSSM Synchronization File Exchange Overview When Smart Software Manager satellite is deployed (either as a standalone or in a High Availability (HA) configuration), it needs to register with Cisco Smart Software Manager (CSSM) in order to be fully functional. Afterwards, during steady state, we recommend that satellite synchronizes with CSSM every 30 days to ensure that the license entitlement and usage are not stale. Any instance of Smart Software Manager satellite that has not synchronized with CSSM for more than 31 days receives an overdue alert (on day 32 or after). After 90 days of non-synchronization, the satellite is removed from Cisco Smart Software Manager (software.cisco.com). Existing product instances associated with it continue to be registered and function for up to 365 days from the last registration renew. Authorization renews will get Out-Of-Compliance (OOC) responses, and no new product can be registered. The satellite is still reachable but the UI is not functional and the user is directed to a reset page below:

The only way to recover is to re-deploy a new satellite, re-register it to CSSM, and re-register previous product instances.

Satellite Operations

The following diagram shows the steps to get Smart Software Manager satellite setup and operational:

A. Satellite Installation

B. Configure IP @, DNS, NTP

C. On browser with satellite IP@

or FQDN

D. Register satellite with

Cisco

E. Satellite now operational

G. Periodic synchronization

with Cisco

F. Products register to satellite

1. Customer needs the following info for Smart Licensing:• Customer Smart

Account (off cisco.com)• Virtual Account• CCO ID/password2. Customer needs to login and click on option to register.

1. Customer logins with standard satellite credentials (needs to change pw)

2. Customer adjusts NTP/DNS as needed

1. Customer configures VM with IP address, DNS, NTP

1. Customer downloads VM off cisco.com and installs


At registration, there are two files that are exchanged between satellite and CSSM

• Registration file (SSM satellite -> Cisco) • Authorization file (Cisco -> SSM satellite)

During normal operation, there are two different files that are exchanged between satellite and CSSM

• Synchronization Request file (satellite -> Cisco) • Synchronization Response file (Cisco -> SSM satellite)

This file is a text YML format that can be inspected by the user. However, if it’s modified by the user, CSSM will reject it. 1. Satellite registration to CSSM

During satellite registration to CSSM, satellite sends difference CSRs (Certificate Signing Requests) to CSSM: lcs_csr, tg_csr, ssms_csr. CSRs can be veified as discussed in Section 6.

instance_id: A Universally Unique IDentifier (UUID). A UUID is simply a 128-bit value and is standardized by the Open Software Foundation and is unique per SSM satellite (see also RFC 4122). exported_timestamp: this is the timestamp when this image was created by Cisco. lcs_csr: from offline/local LCS (License Crypto Service) resident along with satellite (vs lcs online which is deployed inside Cisco internal network used by CSSM).


tg_csr: from Transport Gateway. Dual NIC need two different certificates (tg and ssms), one per interface. ssms_csr: from satellite (Ruby/Rails applications), used for satellite UI. During satellite registration, a full synchronization is also performed. (see full synchronization description on page 5). CSSSM sends registration authorization file with eight different certificates in the registration response file. During registration, the local LCS generates the CSR and puts it in the request file. In the authorization response, the satellite gets back the local sub CA which will be used by the local LCS to sign the ID certificate for product instance (PI) registration.

id_cert: the id cert is used by the satellite to identify all product instances. It is also used by Cisco to identify satellites. This certificate is renewed on every sync between satellite and CSSM. sub_ca_cert: use by the licensing agent on the Cisco product to verify certificate's chain id_cert -> sub_ca -> licensing_root_ca (embedded in the satellite application’s source). signing_cert: signer of the id_cert. Used by Satellite to verify whether the id_cert was signed by licensing_root_ca tg_ssl_cert: use by Transport Gateway (TG) in order to accepts secure connections, also to allow product instances (PI) and satellite to communicate over a secured connection (HTTPs). tg_issuer_cert: use by TG to establish certificate's chain, tg_ssl_cert -> tg_issuer_cert -> licensing root certificate (embedded in TG code). satellite_cert: used by the online LCS to sign the local_sub_ca_cert_1_1 for the local offline LCS local_sub_ca_cert_1_1: use by local satellite LCS and satellite to handle 4-tier product instances registration (see 3-tier vs 4-tier certificate on page 7). LCS uses this certificate to sign the id_cert while sending to the PI. In the PI's registration response, it appears as sub_ca. ssms_ssl_cert: use by satellite to accepts secure connections, also allow web browser and satellite to communicate over a secured connection (HTTPS). CSSM also sends back the Smart Account assigned information and satellite information such as uuid and satellite name as shown below.


2. Satellite synchronization with CSSM During periodic synchronizations, satellite sends CSSM information about its registered product instances and license usage. It also sends CSRs and two certificates (id_cert, signing_cert) to CSSM.

sync_version: the version of the synchronization code with CSSM. ssms_version: satellite software version. id_cert, signing_cert: used by CSSM to verify whether the satellite is a valid satellite or not. csr (lcs csr): no longer used. tg_csr: satellite only send this CSR to CSSM if administrator ip address changes or satellite is restored to different host (different ip address). PI to TG ssms_csr: satellite only send this CSR to CSSM if administrator ip address changes or satellite is restored to different host (different ip address). Browser to satellite. In addition to the certificates, the synchronization request shows the following information: last_generated/last_sync: timestamps used to get the (delta) synchronization data. virtual_accounts: the virtual accounts, registered product instances and licenses in the satellite.

:status:success:uuid: 491a5670-9295-0135-cf27-0050568f1fb9 :smartaccount:BUProductionTest:accountdomain:buproductiontest.cisco.com:satellitename:sat-rest-003:lastgenerated:2017-Oct-1322:42:03UTC


Note that hostname is sent by default. To disable sending the hostname, configure:

cfg-call-home# data-privacy hostname With the synchronization optimization released satellite 2.5.0, the sync_type = PARTIAL or sync_type = FULL is also included in the synchronization request file.

A partial (standard) synchronization means satellite and CSSM send only delta product instances and licenses (entitlement and usage) from the last synchronization. A full synchronization means that satellite and CSSM send all of their respective product instance and licensing information to each other. Note that CSSM is the source of truth for license entitlements and satellite is the source of truth for product instances and license usage.

3. CSSM synchronization response

CSSM sends the synchronization authorization response upon receiving and processing a synchronization request from satellite. An underlying full synchronization occurs when satellite initially registers with CSSM. Then upon periodic synchronization requests from satellite, CSSM also processes them. A synchronization response provides certificate information to secure communication between satellite and CSSM, and information about the virtual accounts and licenses from CSSM to satellite.

:sync: 2.0.0,:version: 2.0.0

:collector_id: 4cdd0470-e5e4-0132-a310-005056841670

:last_sync: 2017-Jun-22 08:50:35 UTC:last_generated: 2017-Jul-20 11:22:16 UTC:virtual_accounts:- :id: 101342:name: Ross-1:product_instances:- :id: 2373d312-2cd8-4029-9517-8c60037cca8c

:registration_date: 2017-Jun-12 07:25:40 UTC:last_contact_date: 2017-Jul-02 06:13:47 UTC:is_active: true:software_tag_identifier: regid.2013-08.com.cisco.CSR1000V,1.0_1562da96-9176-4f99-a6cb-14b4dd0fa135:udi_pid: CSR1000V:hostname: CSR-1000v:ip_address::mac_address::udi_serial_number: 97YZFA9VYJK:host_identifier::licenses:- :tag_id: 1146:tag: regid.2014-05.com.cisco.ax_2500M,1.0_3e0288f3-4838-47c2-93a8-3d8743850f0c:consumed_quantity: 1

:root_cert_hash:C3CyNDezXF9nJrp6zLpAnUQOMbxQyeDRn/O0x347an0= :sync_type:PARTIAL:device_conversion_data:[]:signature:|-


local_sub_ca_cert: use by satellite and LCS to handle 3-tier product instances registration. This is only included in sync response if the satellite is registered to CSSM for more than 48 hours. collector_instance_id: ID assigned to this satellite. satellite_name: name of satellite. last_generated/last_sync: timestamps used to get the (delta) synchronization data. synchronization: includes info about virtual accounts and licenses from CSSM to satellite.

With the support of 3rd party integration, CSSM also sends the provider information in its FULL synchronization response file, which can indicate 3rd party support for SpeechView, Apple Push Notifications, and PnP respectively. With Device-Led Conversion (DLC) support, CSSM provides device conversion information (status, sudi, software id tag, message, etc.) in the :device_conversion_response: field of the sync file for the satellite registered product instances that initiated DLC.

:data::authentication::id_cert: |-

:local_sub_ca_cert:

:collector_instance_id: 4cdd0470-e5e4-0132-a310-005056841670:satellite_name: Ross-SSMS-SCH4.1.2-Prod-OVF10:last_generated: 2017-Jul-20 11:25:48 UTC:last_sync: 2017-Jul-20 11:22:16 UTC

:synchronization::products:- :id: 3662

:display_name: Cisco IOS XRV 9000 Router- :id: 3642

:product_type: IOSXRV:software_tag_id: regid.2017-07.com.cisco.IOS-XRv9000,1.0_5a181e3a-27db-4cbc-8996-fb083ddbd594

- :id: 3682:virtual_accounts:

- :id: 101342:name: Ross-1:smart_account_id: 10560


4. 3-tier vs 4-tier certificates: Before the satellite can accept registrations from product instances, it has to register with CSSM. Previously, satellite to CSSM registration requires a 48-hour wait because a person has to manually sign the Certificate Signing Request (CSR) from satellite to CSSM. This means that if products want to connect to satellite, it has to wait 48 hours for satellite to be fully registered and functional. With satellite 2.1.0 release, this manual signing of the CSR was automated so that the CSR from satellite to CSSM is now signed immediately. However, there are changes that must be made to the product smart agents, satellite and CSSM for this trust chain to work in an automated way. The previous trust chain consisted of 3 levels of certificates (i.e., 3-tier) from the device to satellite to CSSM. In the new implementation to automate the trust chain validation, an additional certificate was added and we had 4-levels of certificates (i.e., 4-tier). These changes also must be backward compatible so that older devices that do not have this updated level of smart agent, satellite, and CSSM code would continue to function. In the new implementation, smart agents, satellite and CSSM must exchange a new message type to know if it supports a 3-tier or 4-tier certificate. Products that have not implemented the latest smart agent code (1.4+) needing to register with satellite will need to wait 48-hour as satellite needs to get the 3-tier certificate from CSSM before it can register the product instance. As a result, 48 hours after synchronization with CSSM, the 3-tier certificate is embedded in the response labeled by the :local_sub_ca_cert: field. At this point, the 3-tier devices can then be registered to satellite. Products varies in their smart agent implementation, so we don’t always know what version of Smart Agent they embed this functionality. At the time of this writing, the 3-tier products are ASAv, FMC, vCUSP, CBR8, and 5921. To know what version of the Smart Agent, simply issue the command “license smart status” or “show license all”.

5. Verifying data integrity of sync file contents

:device_conversion_response:

- :sudi:

:udi_pid:CSR1000V

:udi_serial_number: 90MDZP3IDHJ

:conversion_status:FAILED

:status_message_localized:

:status_message:DlcConversionnotallowed.

:software_tag_identifier: regid.2013-08.com.cisco.CSR1000V,1.0_1562da96-9176-4f99-a6cb-

14b4dd0fa135

:conversion_response_line: []


The data in every synchronization file exchanged between the satellite and Cisco is signed with the signing certificates described above. To verify the content against the signature, one can use a cryptography library to extract the public key from the signing certificate and use that to verify the content against the signature. An example using Ruby is below: OpenSSL::X509::Certificate.new(Base64.decode64(signing_cert)).public_key.verify OpenSSL::Digest::SHA256.new, Base64.decode64(signature), content.to_s Where signing_cert is the signing certificate and content is the content in the yml file (everything under the :data field which is everything about the signature). The content is converted into a sha256 digest before it is signed and hence it must be specified as a parameter while attempting to verify. Note also that the signing certificate and signature in the sync file are Base64 encoded and therefore must be decoded while verifying.

6. Verifying Certificates

All certificates exchanged between the satellite and Cisco are issued by the Cisco Smart Licensing CA. Below is an example of the certificate information for the id_cert from an SSL decoder at https://www.sslshopper.com/certificate-decoder.html

where common name is the unique identifier for the satellite represented by collector_instance_id in the synchronization file.

satellite-cssm synchronization file exchange overview · cssm sends the synchronization...

Documents