Separate functions to generate Signature and Authorization headers #36

liamdennehy · 2018-08-17T22:06:59Z

Different use cases for each (authorisation vs digital signatures)
Different meanings deserve distinct flows
A Signature may need to be be added to a message with an existing Authorization header so can't presume we can simply generate both on every invocation

mtibben · 2018-08-20T22:22:10Z

src/Signer.php

+     */
+    public function authorize($message)
+    {
+        $signatureParameters = $this->signatureParameters($message);
        $message = $message->withAddedHeader("Authorization", "Signature " . $signatureParameters->string());
        return $message;
    }


hmm this is a BC break.

What actually is the difference between Signature and Authorization anyway? Seems like the same data is on each header.

They have the same cryptographic signatures if signing the same data (headers) but serve two different intents, and the distinction is crucial:

Authorization is a claim that I am authorised to make a statement. For a token request, it's "I am a particular identity, I can prove it with this signature derived from a secret only I know, and would like to perform an action.". It could be a signature, a username/password, APIKey etc, but is generally proof of identity through proof of knowledge/possession. The signature is incidental to the purpose.

Signature is an assertion that information is correct - including the request I am making (request-target), headers, signed body etc) has not changed during transmission - something not explicitly asserted in an authorisation claim. The requester typically accompanies this with a separate Authorization artefact (e.g. a Bearer token, or indeed maybe a HTTP signature but it is distinct and may be signed differently to convey the different intent).

The Signature is especially important for some requests e.g. My Signature asserts I have correctly formatted the body of my POST action to initiate a payment to someone - you can trust I have actually sent this and crucially I cannot deny I sent it at a later time (non-repudiation).

Crucially a specific request may require an Authorization header with e.g. a Bearer token, which we would either overwrite or add a second instance of using this library. See for example page 36 of this standard - the Authorization header carries an unrelated token (to authorise the request) alongside a Signature header (which validates the content of the request and that it was explicitly and intentionally made by the requester with the force of a contract).

Even outside implementation constraints lumping them together doesn't force the requester to think about exactly which claim they are making. "It just works" serves nobody in Information Security, and it's unlikely an endpoint would require both headers under the HTTP Signatures scheme. If so, explicitly request both with ->sign() and ->authorize(), for each intent (specifically, Contexts).

Apologies for the long explanation, I'm actually an InfoSec professional not a developer, and getting this right matters to me.

What actually is the difference between Signature and Authorization anyway? Seems like the same data is on each header.

@mtibben Please check w3c-ccg/http-signatures#48 and see if it is clear, these are quite distinct so important to make sure it's right and communicated properly for non-specialists.

I'm consulting on an implementation now where the Authorization header uses a (bearer) token retrieved from an OAuth2 service, and Signature header from this protocol. Using this library as-is (generating both) would either overwrite the Authorization header (losing the token) or add a second Authorization header, which most implementations would probably not understand or some may outright reject if they're not expecting it.

This is a required change IMHO, though I realise the potential for BC impact.

This distinction is now part of the RFC version 11, clearly spelled out in section 1. Since they serve distinct purposes, and can collide with existing headers, I don't see how we can carry on generating both in all cases.

mtibben · 2018-10-02T05:03:14Z

src/Verification.php

@@ -28,11 +31,19 @@ public function __construct($message, KeyStoreInterface $keyStore)
    /**
     * @return bool
     */
-    public function isValid()
+    public function isSigned()


This is a BC break. Could we keep (and deprecate) the isValid method instead?

Unsure what the strategy would be, advise?
Similarly the existing sign() generates Signature and Authorization, so generating only Signature would be a BC

keep isValid function around, mark it as deprecated and return isSigned && isAuthorized

I can re-introduce isValid(), but don't know the approach to deprecate. Is this a hint, a warning emitted in runtime (print()?), documentation only?

@mtibben Any advice?

@mtibben, I need to know how deprecation is achieved to get this finished, any suggestions?

src/Verification.php

mtibben · 2018-10-02T05:04:46Z

Could you rebase out the merge commit?

* Include tests to confirm

* Only available in >=PHP-5.6, which was just bumped to new minimum version * http://php.net/manual/en/function.hash-equals.php * From above: Apparently important user-supplied string is second parameter.

mtibben · 2018-10-09T09:01:42Z

src/Verification.php

+    /**
+     * @return string
+     *
+     * @throws Exception


says throws Exception but the method doesn't

mtibben · 2018-10-09T09:02:01Z

src/Verification.php

-     * @return HmacAlgorithm
+     * @return Key
+     *
+     * @throws Exception


says throws Exception but the method doesn't

But the invoked method does (following the chain). Is this hint only for direct throws in this function, or unhandled exceptions in all further called functions within?

Compare src/Context.php with @throws hints for both the directly thrown and invoked functions' thrown exceptions.:

/** * @return Key * * @throws Exception * @throws KeyStoreException */ private function signingKey() { if (isset($this->signingKeyId)) { return $this->keyStore()->fetch($this->signingKeyId); } else { throw new Exception('no implicit or specified signing key'); } }

@mtibben Happy to remove these hints, but I want to be consistent so your advice is appreciated.

mtibben · 2018-10-09T09:02:17Z

src/Verification.php

+    /**
+     * @return Algorithm
+     *
+     * @throws Exception


says throws Exception but the method doesn't

mtibben · 2018-10-09T09:02:56Z

src/Verification.php

+    }
+
+    /**
+     * @return Algorithm
     *
     * @throws Exception


liamdennehy · 2018-11-21T16:49:28Z

This PR is now mirrored in a PR for the specification itself (w3c-ccg/http-signatures#48) to make it more clear that these headers serve different purposes - while both Signature and Authorization can be used for authorisation, Signature is distinct in that it can create a digitally signed document out of a HTTP Message. I can even imagine a use case where Signature can sign the Authorization header, so we need to make these distinct.

liamdennehy · 2019-08-02T14:08:35Z

I have integrated this feature in my own project along with a number of others, and published this in packagist. Documentation for the entire library is published at Read the Docs: http-signatures-php - incomplete but being expanded regularly.

- Remove unsupported Symfony/PHP version combinations - Add PHP 7.3 support

liamdennehy · 2019-08-15T13:25:39Z

Closing PR due to inactivity.

liamdennehy mentioned this pull request Aug 17, 2018

Separate Authorization and Signature headers #37

Closed

mtibben reviewed Aug 20, 2018

View reviewed changes

liamdennehy force-pushed the separate-sign-and-authrorize branch from cfd8543 to a875c1a Compare August 22, 2018 13:28

mtibben reviewed Oct 2, 2018

View reviewed changes

src/Verification.php Outdated Show resolved Hide resolved

liamdennehy added 7 commits October 6, 2018 13:14

Unit test Signer/Authorizer separation

ed1821f

Verification & Unit Tests for separate Signed and Authorized messages

938600f

Ensure sign() does not interfere with existing Authorize header

8d29c13

Rebase includes Auto-Digest

830292c

Separate Authorize function

3ef8144

Code Style

6127a8c

sign() doesn't add Authorization header

f90d8b7

* Include tests to confirm

liamdennehy changed the title ~~Separate functions to generate Signature and Authorize headers~~ Separate functions to generate Signature and Authorization headers Oct 7, 2018

liamdennehy force-pushed the separate-sign-and-authrorize branch 2 times, most recently from 5243a87 to c63bbee Compare October 8, 2018 18:07

liamdennehy added 3 commits October 8, 2018 21:05

Remove comments, better test name

07595f0

Simpler tests, common flows and better function names

5d87ec3

Move to hash_equals(): Timing-attack resistant string comparison

f2ea38d

* Only available in >=PHP-5.6, which was just bumped to new minimum version * http://php.net/manual/en/function.hash-equals.php * From above: Apparently important user-supplied string is second parameter.

liamdennehy force-pushed the separate-sign-and-authrorize branch from c63bbee to f2ea38d Compare October 8, 2018 19:05

mtibben reviewed Oct 9, 2018

View reviewed changes

src/Verification.php

/**

* @return string

*

* @throws Exception

Copy link

Member

mtibben Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

says throws Exception but the method doesn't

mtibben reviewed Oct 9, 2018

View reviewed changes

src/Verification.php

/**

* @return Algorithm

*

* @throws Exception

Copy link

Member

mtibben Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

says throws Exception but the method doesn't

mtibben reviewed Oct 9, 2018

View reviewed changes

src/Verification.php

}

/**

* @return Algorithm

*

* @throws Exception

Copy link

Member

mtibben Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and here

liamdennehy added 3 commits March 8, 2019 01:14

Re-add isValid() and emit deprecation warning

31aaa7f

Test for isValid() compatibility and deprecation warning

31e0b04

Code Style & typo

21e178f

liamdennehy force-pushed the separate-sign-and-authrorize branch from 2fabd9e to 21e178f Compare March 8, 2019 00:25

Travis build fixes and include phpunit script

f34e4dd

- Remove unsupported Symfony/PHP version combinations - Add PHP 7.3 support

liamdennehy force-pushed the separate-sign-and-authrorize branch from 5fa5092 to f34e4dd Compare August 2, 2019 14:17

liamdennehy closed this Aug 15, 2019

liamdennehy deleted the separate-sign-and-authrorize branch August 15, 2019 13:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Separate functions to generate Signature and Authorization headers #36

Separate functions to generate Signature and Authorization headers #36

liamdennehy commented Aug 17, 2018 •

edited

Loading

mtibben Aug 20, 2018

liamdennehy Aug 21, 2018

liamdennehy Nov 21, 2018

liamdennehy Mar 6, 2019

liamdennehy Jul 23, 2019

mtibben Oct 2, 2018

liamdennehy Oct 7, 2018

mtibben Oct 9, 2018

liamdennehy Oct 9, 2018 •

edited

Loading

liamdennehy Nov 21, 2018

liamdennehy Mar 6, 2019

mtibben commented Oct 2, 2018

mtibben Oct 9, 2018

mtibben Oct 9, 2018

liamdennehy Oct 9, 2018 •

edited

Loading

liamdennehy Nov 21, 2018

liamdennehy Mar 6, 2019

mtibben Oct 9, 2018

mtibben Oct 9, 2018

liamdennehy commented Nov 21, 2018

liamdennehy commented Aug 2, 2019

liamdennehy commented Aug 15, 2019

Separate functions to generate Signature and Authorization headers #36

Separate functions to generate Signature and Authorization headers #36

Conversation

liamdennehy commented Aug 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liamdennehy Oct 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtibben commented Oct 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liamdennehy Oct 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liamdennehy commented Nov 21, 2018

liamdennehy commented Aug 2, 2019

liamdennehy commented Aug 15, 2019

liamdennehy commented Aug 17, 2018 •

edited

Loading

liamdennehy Oct 9, 2018 •

edited

Loading

liamdennehy Oct 9, 2018 •

edited

Loading