Certificate with Oauth API

Question

I'm not very used to oAuth or using SSL certificates and was just recently forced to look into it for put.io API access. oAuth seems complicated, some methods ever require the end user to fill out their credientials.

So I went to search for a ready made PHP lib that has the full put.io API implemented and noticed he used a method where not even the "application secret" or "client ID" was needed.

All I had to do was feed it my "Oauth Token" value and it connected with ssl vertifypeer and a cafile - StarFieldSecureCertificationAuthority.crt

Now the question I guess is what this certificate really does or proves, and if I can really use his - or if this is something I should generate myself for the target deployment server?

Suprisingly, Google didn't help much at all - and I have still no idea how this oAuth with a certificate works, why it works, and how I can make sure that it does work. Any pointers?

Answer 1

Presumption

I take it this is the "ready made PHP lib" you refer to? If you have a question on what some code does with some file, it's helpful to post a link to the code and even more helpful to post your breakdown of it. If you try to read the code, you'll get better Google terms, and clearer narrower more easily answered SO questions, that have a wider application for other future visitors: A question "What does some code do" is easier to answer and may be found by people in the future that search for the same function.

SSL certificates

It's hard to understand what some API code does with a certificate if we have no understanding of what certificates are for. So lets try to get ssl explained to us. If reading the explaining answer on security.stackexchange.com comes hard to you, youtube is the dyslexics best friend.

So now we know that certificates are used to confirm identity or, in other words, for authentication.

OAuth tokens

OAuth tokens are like car keys; a secret that grants access to a car. In your case the car is put.io (the Resource Server). Some cars have separate keys for starting it, opening the trunk and opening the glove compartment. Some tokens only grant access to some of all the Owners Resources.

Basic idea is here, that we shouldn't leave carkeys left in our care out in the open and we shouldn't stick them in just any car we see. Because it's pretty easy to make a device that looks like a car and reacts like a car, but in fact is a car key copier. Trust me, it's the next big thing after credit card skimming. So we need to confirm the identity of the car, before stick our keys in. We need to authenticate the car.

It's pretty easy to make a device that looks like put.io and reacts like put.io, but in fact is a man-in-the-middle that copies tokens. So we need to authenticate put.io before we send the precious token.

Authenticating put.io

That is where the SSL certificates come in. Without repeating what we learned from the SSL section, we know we should carefully check the authenticity of the server certificate we get from, what we believe is, put.io. We need to check if the signature on that certificate comes from an authority (a CA) we trust. To do that we need the certificate of the CA. Many operating systems and browsers come pre-packed with trusted CA certificates.

Just open https://put.io in your browser and look for the certificate. Often by (right) clicking some padlock icon and some click for more information. You'll see that it is issued by 'Starfield Technologies, Inc.'

Using StarFieldSecureCertificationAuthority.crt

Now in NativeEngine.php we see:

$context = stream_context_create($contextOptions);

The ssl options require either a cafile or a capath. The easiest way for the API maintainer to be cross-platform is supplying a cafile. OS package maintainers will likely patch this and exchange it with the capath to the CA files they supply in their OS.

Can you trust it?

Now if the API maintainer has created that crt himself, he can impersonate any server if you use it. Luckily, you can easily check the fingerprint and see if it corresponds with the one in your browser. You can export the one in your browser if it doesn't.

Answer 2

The OAuth token is what authenticates you against the put.io API. (As you can see in this example, where no additional CA certificate is used.)

The CA certificate and the VerifyPeer setting are there to protect the integrity of the connection between your application and put.io: The library uses it to verify that the server it connected to really is put.io's, before proceeding to submit the OAuth token. Your code should also work if you disable the verification; but then your application would be vulnerable to a MITM attack and an attacker could obtain your OAuth token – and would then have access to your put.io account. (The same technique is used in HTTPS. See this question at ISSE for further details on the verification process.)

Note that your solution works for now, but the put.io API documentation states that they might start to expire OAuth tokens in the future, so in the long term you should switch to a library which is able to obtain new tokens (there's a list in this question):

Although at this time we do not expire OAuth access tokens, you should be prepared for this possibility in the future. Also remember that a user may revoke access via the put.io settings page at any time. Using /authorize will ask the user to re-authenticate their identity and reauthorize your app while giving the user the option to login under a different account.