Tag Archives: openssl

Posted on
by

Every page on a Known site can potentially be an API endpoint, which means that pretty much everything you can do with the interface, you can write a script or client to connect to.

As things are still being built out there are no libraries, or indeed detailed instructions, out there yet (although you might want to look at some of my sample code) so I’ve been fielding a bunch of questions from folk.

Overview

At its simplest level, all pages on a Known site are API endpoints.

When you post a status update, the form you fill in POSTs the form fields to the API endpoint /status/edit. So, if you were to write a client to do this, you’d send the same variables to the same endpoint, but you’ll also have to do a couple of extra things as well.

Authentication

In order to access restricted content, or to post to your stream, you will need to authenticate yourself. There is currently only one built in way to do this, however Known supports extensible authentication methods, so it is of course possible to hook in other methods.

For example, if you don’t want to use the built signed HTTP request method, you could use an OAuth2 server.

  • Get your API Key: from your Tools and Apps page.
  • Generate a signature: You need to generate a base64 encoded HMAC, which is a SHA256 digest of the path of the api (i.e. if you’re using “`https://yoursite.com/status/edit“`, your path should be “`/status/edit“`) using your API key as the key.

    From the shell:

    HMAC=$(echo -n "/status/edit" | openssl dgst -binary -sha256 -hmac '***APIKEY***' |  base64 -w0)

    In PHP:

    base64_encode(hash_hmac('sha256', "/status/edit", $api_key', true));
  • Sign your HTTP requests by sending the following HTTP headers: 
    X-KNOWN-USERNAME: 
X-KNOWN-SIGNATURE:
  • Tell Known you want the API to return a machine understandable response by sending the following header: 
    Accept: application/json

Some points to remember…

  • Remember to follow forwards: Known makes use of forwards, for example when creating a post, you’ll be forwarded to the completed object. So, you need to tell cURL (if that’s what you’re using) to follow forwards CURLOPT_FOLLOWLOCATION
  • Create a cookie jar: In order to preserve your session, and to avoid getting 403 errors after a successful post, you’ll need to store your cookies. Again, if you’re using cURL you can do this by passing the CURLOPT_COOKIEJAR option.

Hope this helps!

Posted on
by

I needed some tools for talking to the Known API from the command line in order to play around with a few ideas I’ve been having.

So, I put together a few BASH shell scripts.

Installation

  • Install the prerequisites: curl php_cli python openssl base64
  • Check out the repository and add it to your system path.

Note, due to this bug, you’ll need to be running the latest version of Known if you want to use the syndication functionality.

Talking to Known

The first thing you’ll need (other than a Known account of course) is to get your API key, you can find this in your settings page under “Tools and Apps”.

You can then use those as parameters to known.sh. For example, to make a status update you’d type:

echo "body=my+data" | known.sh https://mysite.com/status/edit *username* *apikey*

Of course, you might want to use one of the wrapper scripts like status.sh, which also supports syndication e.g:

echo "my tweet" | status.sh https://mysite.com *username* *apikey* twitter::username

If successful, the scripts will output a JSON representation of what the API says.

Have fun!

» Visit the project on Github...

Posted on
by

Just a quick note to say that the my Known Chrome plugin will now return an installable .crx file.

You’ll need the OpenSSL PHP extension installed, but if you do an installable .CRX file will be returned instead of a .zip. If you don’t have OpenSSL installed, the oldstyle .zip will be installed, however some people had problems with this.

» Visit the project on Github...