Cisco: Not Serious About Network Programmability

"You can't fool me, there ain't no sanity clause!"

Cisco isn't known for providing easy programmatic access to their device configurations, but has recently made some significant strides in this regard.

The REST API plugin for newer ASA hardware is an example of that. It works fairly well, supports a broad swath of device features, is beautifully documented and has an awesome interactive test/dev dashboard. The dashboard even has the ability to spit out example code (java, javascript, python) based on your point/click interaction with it.

It's really slick.

But I Can't Trust It

Here's the problem: It's an un-versioned REST API, and the maintainers don't hesitate to change its behavior between minor releases. Here's what's different between 1.3(2) and 1.3(2)-100:

New Features in ASA REST API 1.3(2)-100

Released: February 16, 2017

As a result of the fix for CSCvb21388, the response type of /api/certificate/details was changed from the CertificateDetails object to a list of CertificateDetails. Scripts utilizing this API will need to be modified accordingly.

So, any code based on earlier documentation is now broken when it calls /api/certificate/details.

This Shouldn't Happen

Don't take my word for it:

---

Remember than an API is a published contract between a Server and a Consumer. If you make changes to the Servers API and these changes break backwards compatibility, you will break things for your Consumer and they will resent you for it. 

---

Versioning your API is terrifying. If you push out a “breaking change” – basically any change that runs counter to what client developers have planned for, such as renaming or deleting a parameter or changing the format of the response – you run the risk of bringing down many, if not all, of your customers’ systems, leading to angry support calls or – worse – massive churn. For this reason, versioning is the number one concern among the development teams I work with when helping them design their APIs.

---

Breaking changes include:

1. Renaming fields and/or resource paths – often for clarity after your API is released
2. Changing payload structures to accommodate the following: renaming or removing fields (even if they are considered optional – contracts!); changing fields from a single value to a one-to-many relationship (e.g. moving from one email address per account to a list of email addresses for an account)
3. Fixing poor choices of HTTP verbs, response codes, or inconsistent design across your API endpoints

In short, once you release your API into the wild, you have to live with it. If you encounter one or more of the items above, it may be time to version your API to prevent breaking your existing API consumers.

---

It Gets Worse

Not only does the API fail to provide consistently formatted responses, it doesn't even provide a way to discover its version. Cisco advised me to scrape the 'show version' CLI output in order to divine the correct way to parse the API's responses. Whenever they decide to change things.

The irony of having to abandon the API for screen scraping in order to improve API compatibility is almost too much to bear. Lets assume for the moment that I'm willing to do it. Will the regex that finds the API version today still work on tomorrow's release? Do I even know how to parse the version numbers?

What's the version number of the current release anyway?

• 1.3(2)-100 (according to the release notes above)
• 1.3.2.100 (according to show version CLI output)
• 1.3.2 (according to the 'release:' field on the download page)

This does not look like a road I'm going to enjoy traveling.

Would You Use This API?

When I inquired about version-to-version incompatibilities, Cisco's initial response was:

"This definitely shouldn't be happening."

Followed by:

"We are aware of the limitations resulting for not having versioned ASA REST API releases. And as of now there are no plans for us to fix this."

 Further followed by:

"we will update the documentation to reflect the correct behavior, once we post this fix to CCO."

So hey, no problem right? We might sneak breaking changes into the smallest of maintenance releases, but at least we'll document it! Have fun selling and supporting your application!

Clearly I am one of the angry and resentful customers predicted by the articles quoted above :)

Epoch Rollover: Coming Two Years Early To A Router Near You!

The 2038 Problem

Broken Time? -  Roeland van der Hoorn

Many computer systems and applications keep track of time by counting the seconds from "the epoch", an arbitrary date. Epoch for UNIX-based systems is the stroke of midnight in Greenwich on 1 January 1970.

Lots of application functions and system libraries keep track of the time using a 32-bit signed integer, which has a maximum value of around 2.1 billion. It's good for a bit more than 68 years worth of seconds.

Things are likely to get weird 2.1 billion seconds after the epoch on January 19th, 2038.

As the binary counter rolls over from 01111111111111111111111111111111 to 10000000000000000000000000000000, the sign bit gets flipped. The counter will have changed from its farthest reach after the epoch to its farthest reach before the epoch. time will appear to have jumped from early 2038 to late 1901.

Things might even get weird within the next year (January 2018!) as systems begin encounter freshly minted CA certificates with expirations after the epoch rollover (it's common for CA certificates to last for 20 years.) These certificates may appear to have expired in late 1901, over a century prior to their creation.

NTP's 2036 Problem

NTP has a similar, but not-quite-the-same epoch problem. It keeps track of seconds in an unsigned 32-bit value, so it can count twice as high as the problematic UNIX counter (yay!) but NTP's epoch is set 70 years earlier: 1 January 1900 (boo!) The result is that NTP's counter will roll over about 2 years before the UNIX counter.

Practically speaking, NTP's going to be fine for reasons having to do with it being primarily concerned about small offsets in relative time, and it only having to be within 68 years of correct on startup in order to sync up with an authoritative time source.

So What's Up With This Router?

Here's a weird thing I stumbled across recently. Time calculations with dates in 2036 are going wrong but they're unrelated to NTP:

 router#show crypto pki certificates test-1 
 CA Certificate  
  Status: Available  
  Certificate Serial Number (hex): 14  
  Certificate Usage: Signature  
  Issuer:   
   cn=test-2  
  Subject:   
   cn=test-2  
  Validity Date:   
   start date: 02:38:26 UTC Mar 17 2017  
   end  date: 00:00:00 UTC Jan 1 1900  
  Associated Trustpoints: test-1   

But this one looks okay:

 router#show crypto pki certificates test-2
 CA Certificate  
  Status: Available  
  Certificate Serial Number (hex): 12  
  Certificate Usage: Signature  
  Issuer:   
   cn=test-1  
  Subject:   
   cn=test-1  
  Validity Date:   
   start date: 02:37:31 UTC Mar 17 2017  
   end  date: 06:28:15 UTC Feb 7 2036  
  Associated Trustpoints: test-2   

The real expiration dates of these certificates is just one second apart:

$ openssl x509 -in test-1.crt -noout -enddate

notAfter=Feb 7 06:28:16 2036 GMT

$ openssl x509 -in test-2.crt -noout -enddate

notAfter=Feb 7 06:28:15 2036 GMT

So... That's unfortunate.

Here's the actual certificate data and import procedure used for this experiment in case you feel inclined to test:

 crypto pki trustpoint test-1  
  enrollment terminal  
 crypto pki authenticate test-1  
 -----BEGIN CERTIFICATE-----  
 MIIBeDCCASKgAwIBAgIBFDANBgkqhkiG9w0BAQUFADARMQ8wDQYDVQQDDAZ0ZXN0  
 LTIwIBcNMTcwMzE3MDIzODI2WhgPMjAzNjAyMDcwNjI4MTZaMBExDzANBgNVBAMM  
 BnRlc3QtMjBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQDUjEccGNjjtv8lKNnvGpta  
 Z4x8LB82D2JJwTcvA5blUI2nr4vF41RqG0ifZ+Qtyqo+ntSD2QzDu3LKdSUw46if  
 AgMBAAGjYzBhMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1Ud  
 DgQWBBQ2NpEF0FG/g3ryNgU7Skjbm4IGHTAfBgNVHSMEGDAWgBQ2NpEF0FG/g3ry  
 NgU7Skjbm4IGHTANBgkqhkiG9w0BAQUFAANBAIVyT+iBimH7c/jtBrFGmKq+7YdM  
 eMwf9I/En/TAUqtte7QGLNRyTgBJvGgN/uc0KUjlZ5D6G/kxTwDtzse2Uow=  
 -----END CERTIFICATE-----  
 quit  
   
 crypto pki trustpoint test-2  
  enrollment terminal  
 crypto pki authenticate test-2  
 -----BEGIN CERTIFICATE-----  
 MIIBeDCCASKgAwIBAgIBEjANBgkqhkiG9w0BAQUFADARMQ8wDQYDVQQDDAZ0ZXN0  
 LTEwIBcNMTcwMzE3MDIzNzMxWhgPMjAzNjAyMDcwNjI4MTVaMBExDzANBgNVBAMM  
 BnRlc3QtMTBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQDUjEccGNjjtv8lKNnvGpta  
 Z4x8LB82D2JJwTcvA5blUI2nr4vF41RqG0ifZ+Qtyqo+ntSD2QzDu3LKdSUw46if  
 AgMBAAGjYzBhMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1Ud  
 DgQWBBQ2NpEF0FG/g3ryNgU7Skjbm4IGHTAfBgNVHSMEGDAWgBQ2NpEF0FG/g3ry  
 NgU7Skjbm4IGHTANBgkqhkiG9w0BAQUFAANBAIjboo8wtehMpOReLw01tW8MLYzl  
 rtpwYVGoHCVVpXU+s7YQtfR1pt5ZVHZ8OVeP8SoTtoS+5k97aWgBZ+hu8/M=  
 -----END CERTIFICATE-----  
 quit