Cisco APIC Signature Based Transactions - REST API using POSTMAN

Ramakrishnan R · ‎12-01-2017

Cisco Documents are usually accurate, but when it came to the document on Cisco APIC Signature-Based Transactions it was slightly off the mark. This document is for those novices to API like me who cant seem to figure out how to go about performing signature based transactions on APIC.

Prerequisites

1. Generate a RSA Private Key and create a X.509 Certificate

openssl req -new -newkey rsa:1024 -days 36500 -nodes -x509 -keyout userabc.key -out userabc.crt -subj '/CN=User ABC/O=Cisco Systems/C=US'

The above command should create two files, a Private Key - userabc.key & X.509 certificate - userabc.crt

2. Display the created certificate in PEM format

openssl x509 -text -in userabc.crt

3. Copy the certificate (Copy contents starting from ---BEGIN CERTIFICATE till ---END CERTIFICATE--)

4. Configure a Local User with admin access to all domain using APIC GUI under Admin-> Security Management -> Local Users

5. Add User Certificate under the created local user - in our case "userabc". Certificate Name: userabc.txt and paste the content copied in step 4

6. Once you have configured, double click the user->double click on the imported user certificate. You can download the configuration as a XML file.

Inside the XML File you can find the DN of the User Certificate.

To download the Certificate

Your XML File should look like this, from there you can extract the DN.

<?xml version="1.0" encoding="UTF-8"?><imdata totalCount="1"><aaaUserCert certificateDecodeInformation="Verified x509 Certificate, format: PEM, size 813 bytes, fingerprint 4a:68:56:53:18:64:f2:03:f1:ae:6a:32:df:71:b6:68:43:ab:b3:6d, notBefore=Nov 30 10:46:31 2017 GMT
, notAfter=Nov 30 10:46:31 2018 GMT
" childAction="" data="-----BEGIN CERTIFICATE-----
MIICLTCCAZagAwIBAgIJAMXzvPCXSVyLMA0GCSqGSIb3DQEBCwUAMC4xDzANBgNV
BAMMBmNuc2VnIDEOMAwGA1UECgwFU2lmeSAxCzAJBgNVBAYTAklOMB4XDTE3MTEz
MDEwNDYzMVoXDTE4MTEzMDEwNDYzMVowLjEPMA0GA1UEAwwGY25zZWcgMQ4wDAYD
VQQKDAVTaWZ5IDELMAkGA1UEBhMCSU4wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJ
AoGBAMrv6F2VrNOG0E6s+LdwOGJpPRLcZi9Vq2EdtBeosKP9xBnXrFkqs8TyvEc3
fZXfnIRMXhMhgoSKbf9uW8t9dAhciDyrFi4BDSq6UvPk8o5ovJKeNFA/uaTioVQ5
D9IznfSdzcV8kvazIDWZb3sCi0a1md8JtHt/uMvcqAtdxLkXAgMBAAGjUzBRMB0G
A1UdDgQWBBSbTzA1WO2ZRAVa63v8lCiy/QAXrzAfBgNVHSMEGDAWgBSbTzA1WO2Z
RAVa63v8lCiy/QAXrzAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4GB
AIxBPi8qPjXx9u+sdkGUe6ftndfdd0D2fOn/t0miAaSHa1iCz9i+q8rlqZqE+US3
MsLPk68UjmwW9rNCDOLAhEHbex/jirp2UeteIZjMNmQbkdWB7fRwope3YiN4Srvv
PC02XFXW2RrzOVIoqBLJ1mDAKk20uFHLxKoW0cN3iM66
-----END CERTIFICATE-----" descr="" dn="uni/userext/user-userabc/usercert-userabc.crt" fingerprint="4a:68:56:53:18:64:f2:03:f1:ae:6a:32:df:71:b6:68:43:ab:b3:6d" lcOwn="local" modTs="2017-11-30T09:18:00.281+05:30" name="cnseg.crt" nameAlias="" ownerKey="" ownerTag="" publicKey="-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK7+hdlazThtBOrPi3cDhiaT0S
3GYvVathHbQXqLCj/cQZ16xZKrPE8rxHN32V35yETF4TIYKEim3/blvLfXQIXIg8
qxYuAQ0qulLz5PKOaLySnjRQP7mk4qFUOQ/SM530nc3FfJL2syA1mW97AotGtZnf
CbR7f7jL3KgLXcS5FwIDAQAB
-----END PUBLIC KEY-----
" status="" uid="15374"/></imdata>

dn="uni/userext/user-userabc/usercert-userabc.crt"

With this now you are ready to start generating signatures for API Calls

1. First step is to determine the content format of your payload.txt. Your payload must not contain Protocol or IP or Hostname. For Example: If you want to do the below REST API Call.

GET http://10.65.201.217/api/class/fvTenant.json?rsp-subtree=children

Then, your payload.txt should contain only the below line

GET/api/class/fvTenant.json?rsp-subtree=children

2. Now that you have created the payload.txt, next step is to generate a signature. Use the below openssl commands to create the signature in base64 format

openssl dgst -sha256 -sign userabc.key payload.txt > payload_sig.bin
openssl base64 -A -in payload_sig.bin -out payload_sig.base64

3. Now go to POSTMAN

Choose Method GET and type the full URL of the REST API Call and then click on Cookies

4. Now you have to Add 4 cookies

Cookie 1

APIC-Request-Signature=P+OTqK0CeAZjl7+Gute2R1Ww8OGgtzE0wsLlx8f
IXXl4V79Zl7Ou8IdJH9CB4W6CEvdICXqkv3KaQszCIC0+Bn07o3qF//BsIplZmYChD6gCX3f
7qIcjGX+R6HAqGeK7k97cNhXlWEoobFPe/oajtPjOu3tdOjhf/9ujG6Jv6Ro=;

Cookie 2

APIC-Certificate-DN=uni/userext/user-userabc/usercert-userabc.crt

Cookie 3

APIC-Certificate-Algorithm=v1.0;

Cookie 4

APIC-Certificate-Fingerprint=fingerprint;

5. Now click Send!! You should get a 200 OK and list of all tenants.

Note: The Cisco document skips the base64 conversion part and also forgets to mention the exact format of how the payload should be.

Hope this document has helped you.

--

Ramakrishnan R

CCIE #35718

mtimm · ‎12-04-2017

Hi Ramakrishnan,

I'm the original author/source of Cisco APIC Signature-Based Transactions document. It was written a couple of years ago and at the time it was written it was accurate - I was never a fan of the formatting but it went through our doc team and that's what they produced. If something is off the mark even slightly now I would encourage you to submit feedback on the document so it can be updated/corrected. I'm no longer involved with the APIC so I'm not sure what might be off the mark now.

Doing signature based transactions via postman is not the ideal situation. It is fine for testing of course but the real strong use case for this functionality is to programmatically interface with the APIC. That allows you to more easily calculate the required signature for each request being made.

Thanks!

Mike

Ramakrishnan R · ‎12-05-2017

Hi Mike,

I generally dont write documents, but in this case, all of a sudden I thought the world would be better off with more accurate instructions. Since I wanted to add more screenshots, I thought of writing a document instead of feedback. But as you suggested will definitely feedback too.

You were almost accurate, but you seem to have missed out on how to format the payload.txt. It took me several hours of tshooting to understand that the Protocol and IP is not needed in the payload.txt. While in your document the example explicitly indicated that APIC IP and Protocol is needed.

I also understand that it is only practically possible to do this programmatically. In fact I had shared your document to my dev team and they came back saying they are facing error. Then to tshoot I started doing a dry run.

I am glad you took time to respond, its not always the author of a cisco document responds!!

Cheers !!

---

Ramakrishnan R

stsouvle · ‎05-24-2018

Just wanted to say, awesome document! Thank you for sharing this!! I also wanted to mention for those who get stuck, when creating the payload text file, make sure there isn't a new line created after the text, this will result in a 'bad signature' error when sending the api rest call to apic. The below command shows a new line was created for this file, ($).

[root@localhost ~]# cat -e payload.txt

GET/api/class/fvTenant.json?rsp-subtree=children$

To ensure no new line is created you can run the below echo -n command and redirect to a file.

[root@localhost ~]# echo -n "GET/api/class/fvTenant.json?rsp-subtree=children" >payload.txt

[root@localhost ~]# cat -e payload.txt

GET/api/class/fvTenant.json?rsp-subtree=children

[root@localhost ~]#