I was looking into WebCT's automatic sign-on feature. To use this, I needed to build a URL like http://server/webct/public/autosignon?IMS%20id=LONGID&Time%20Stamp=1108683051&URL=/somewhere&MAC=LONGSTR
and use a HTTP redirect to send the browser in.
WebCT does provide fairly detailed technical documentation of their API, explaining how to calculate the right values for IMS id and MAC. Unfortunately, it left some details out, such as exactly which values are used in calculating the MAC and in what order.
A search turned up Java example code. Never mind that this is from the attic of its CVS repository (meaning that it was deleted from CVS). At one time, it probably worked. Java source code is unambiguous — there is no doubt about how values are calculated. I didn't need to compile this code. I didn't even want to implement my solution in Java. (It's ColdFusion, if you must know.)
By using this code as a crib, I was able to get the right value for IMS id. So far, so good. Unfortunately, I wasn't getting the right value for the MAC.
autosignon is a CGI program. No source code, but it can be run
in isolation. I just needed to set up its inputs and watch what it was trying to do.
Hmmm, where to look up how to set up the inputs? I decided to look through
CGI.pm. Easy to look for references to $ENV and see what it wants. Sure enough, by setting the same environment variables I could run autosignon from
the shell. Looking at the strace output I noticed it was reading from a file
I hadn't expected... It was reading its shared secret from
autosignon_secret, not api_secret. That made
sense, it just wasn't clear from the technical documentation.
In the end, I needed to get some information in the absence of source code.
I was lucky that I was able to run autosignon standalone:
had it been embedded in something bigger I would have faced much greater
difficulty.
In most cases, a specification need not be acccurate to the nth degree. An API with security implications is a different matter. It's true that the technical documentation could have included more detail. However, source code showing how to calculate the MAC (for example) is not only less ambiguous than English (or tables and diagrams), it's also more compact. It's also relatively easy to verify.
One factor I'm leaving out is that vendors have a conflict of interest. They want to encourage people to use their professional services to do integration and customization work. That would be a reason to publish enough documentation to show that something is possible without giving away every detail. I think that this has the side effect, however, of lowering the customer's FYO point for that software.