Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/logibit/logibit.hawk

A F# Hawk implementation with a strongly typed API that guides your usage and minimises security programming errors.
https://github.com/logibit/logibit.hawk

Last synced: 19 days ago
JSON representation

A F# Hawk implementation with a strongly typed API that guides your usage and minimises security programming errors.

Awesome Lists containing this project

README 

        
# Logibit Hawk



A F# implementation of the Hawk authentication protocol. Few dependencies. No

cruft. No thrown exceptions.



If this library throws an exception, report an issue - instead it uses return

values that are structured instead.



``` bash

paket add nuget Hawk

paket add nuget Hawk.Suave

```



Dependencies: { Aether, FSharp.Core, NodaTime }, nugets [Hawk][ng-h] and

[Hawk.Suave][ng-hs].



For all API methods implemented, the full test suite for those methods has also

been translated.



Sponsored by [qvitoo – A.I. bookkeeping](https://qvitoo.com?utm_source=github).



## Usage (Suave Example)



``` fsharp

open Logibit.Hawk

open Logibit.Hawk.Types

open Logibit.Hawk.Server



open Suave

open Suave.Http // houses submodule 'Hawk'

open Suave.Http.Successful

open Suave.Http.RequestErrors

open Suave.Types



// your own user type

type User =

  { homepage  : Uri

    realName : string }



// this is the structure that is the 'context' for Logibit.Hawk

let settings =

  // this is what the lib is looking for to verify the request

  let sampleCreds =

    { id        = "haf"

      key       = "werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn"

      algorithm = SHA256 }



  // the generic type param allows you to implement a generic user repository

  // for your own user type (above)

  { Settings.empty() with

     // sign: UserId -> Choice

     credsRepo = fun id ->

       (sampleCreds,

        { homepage = Uri("https://qvitoo.com"); realName = "Henrik" }

       )

       // no error:

       |> Choice1Of2 }



// You can compose this into the rest of the app, as it's a web part. In this

// case you're doing a Authorization header authentication

let sampleApp settings : WebPart =

  Hawk.authenticate

    settings

    Hawk.bindHeaderReq

    // in here you can put your authenticated web parts

    (fun (attr, creds, user) -> OK (sprintf "authenticated user '%s'" user.realName))

    // on failure to authenticate the request

    (fun err -> UNAUTHORIZED (err.ToString()))



// Similarly for bewits, where you want to authenticate a portion of the query

// string:

let sampleApp2 settings : WebPart =

  Hawk.authenticateBewit

    settings Hawk.bindQueryRequest

    // in here you can put your authenticated web parts

    (fun (attr, creds, user) -> OK (sprintf "authenticated user '%s'" user.realName))

    // on failure to authenticate the request

    (fun err -> UNAUTHORIZED (err.ToString()))

```



Currently the code is only fully documented - but not outside the code, so have

a browse to

[the source code](https://github.com/logibit/Logibit.Hawk/blob/master/src/Logibit.Hawk/Server.fs#L1)

that you are interested in to see how the API composes.



## Usage from client:



Use the .js file from `src/vendor/hawk.js/lib`, then you can wrap your ajax

calls like this:



**request.js:** (using CommonJS module layout, which you can use to require it and

get a function in return).



``` javascript

var Auth   = require('./auth.js'),

    Hawk   = require('./lib/hawk.js'),

    Logger = require('./logger.js'),

    jQuery = require('jquery');



var qt = function(str) {

  return "'" + str + "'";

}



var jqSetHawkHeader = function(opts, creds, jqXHR, settings) {

  if (typeof opts.contentType == 'undefined') {

    throw new Error('missing contentType from options');

  }



  var opts = jQuery.extend({ credentials: creds, payload: settings.data }, opts),

      // header(uri, method, options): should have options values for

      // - contentType

      // - credentials

      // - payload

      header = Hawk.client.header(settings.url, settings.type, opts); // type = HTTP-method



  if (typeof header.err !== 'undefined') {

    Logger.error('(1/2) Hawk error:', qt(header.err), 'for', method, qt(settings.url));

    Logger.error('(2/2) Using credentials', opts.credentials);

    return;

  }



  Logger.debug('(1/3)', settings.type, settings.url);

  Logger.debug('(2/3) opts:', opts);

  Logger.debug('(3/3) header:', header.field);



  jqXHR.setRequestHeader('Authorization', header.field);

};



module.exports = function (method, resource, data, opts) {

  var origin    = window.location.origin,

      creds     = Auth.getCredentials(),

      url       = origin + resource,

      opts      = jQuery.extend({

        contentType: 'application/x-www-form-urlencoded; charset=UTF-8',

        dataType: 'html'

      }, (typeof opts !== 'undefined' ? opts : {})),

      jqOpts    = jQuery.extend({

        type:       method,

        data:       data,

        url:        url,

        beforeSend: function(xhr, s) { jqSetHawkHeader(opts, creds, xhr, s) }

      }, opts);



  return jQuery.ajax(jqOpts);

};

```



## Changelog



Please have a look at [Releases](https://github.com/logibit/Logibit.Hawk/releases).



## API



This is the public API of the library. It mimics the API of Hawk.js - the

[reference implementation](https://github.com/hueniverse/hawk/blob/master/lib/client.js).



### `Logibit.Hawk.Bewit`



These functions are available to creating and verifying Bewits.



 - [x] generate - generate a new bewit from credentials, a uri and an optional

       ext field.

 - [x] generate' - generate a new bewit from credentials, a string uri and an

       optional ext field.

 - [x] authenticate - verify a given bewit



#### `authenticate` details



TBD - docs, in the meanwhilse, see Server authenticate (superset is validated).



### `Logibit.Hawk.Client`



These functions are available, checked functions are implemented



 - [x] header - generate a request header for server to authenticate

 - [x] bewit - delegates to Bewit.generate

 - [x] authenticate - test that server response is authentic, see

   [Response Payload Validation](https://github.com/hueniverse/hawk#response-payload-validation).

 - [ ] message - generate an authorisation string for a message



### `Logibit.Hawk.Server`



 - [x] authenticate - authenticate a request

 - [x] authenticatePayload - authenticate the payload of a request - assumes

   you first have called `authenticate` to get credentials.

   [Payload Validation](https://github.com/hueniverse/hawk#payload-validation)

 - [ ] authenticatePayloadHash

 - [ ] header - generate a server-header for the client to authenticate

 - [x] authenticateBewit - authenticate a client-supplied bewit, see [Bewit

   Usage Example](https://github.com/hueniverse/hawk#bewit-usage-example).

 - [ ] authenticateMessage - authenticate a client-supplied message



#### `authenticate` details



How strictly does the server validate its input? Compared to reference

implementation. This part is important since it will make or break the usability

of your api/app. Just throwing SecurityException for any of these is not

granular enough.



 - [x] server cannot parse header -> `FaultyAuthorizationHeader`

 - [x] server cannot find Hawk scheme in header -> `FaultyAuthorizationHeader`

 - [x] id, ts, nonce and mac (required attrs) are supplied -> `MissingAttribute`

 - [x] credential function errors -> `CredsError`

 - [x] mac doesn't match payload -> `BadMac`

 - [x] missing payload hash if payload -> `MissingAttribute`

 - [x] payload hash not matching -> `BadPayloadHash of hash_given * hash_calculated`

 - [x] nonce reused -> `NonceError AlreadySeen`, with in-memory cache

 - [x] stale timestamp -> `StaleTimestamp`



##### Hints when not under attack (in dev)



If you see `CredsError`, it's most likely a problem that you can't find the user

with your repository function.



If you see `BadMac`, it means probably means you haven't fed the right parameters

to `authenticate`. Log the input parameters, verify that host and port match

(are you [behind a][revproxy-read] [reverse proxy][revproxy]?) and check that the

length of the content is the same on the client as on the server.



The `BadMac` error comes from hashing a normalised string of these parameters:



 - hawk header version

 - type of normalisation ('header' in this case)

 - timestamp

 - nonce

 - method

 - resource (aka PathAndQuery for the constructed Uri)

 - host

 - port

 - hash value

 - ext if there is one

 - app if there is one

 - dlg if there is app and if there is one



If you see PadPayloadHash, it means that the MAC check passed, so you're

probably looking at an empty byte array, or your Content-Type isn't being passed

to the server properly, or the server implementation doesn't feed the correct

Content-Type header (e.g. it doesn't trim the stuff after the first MimeType

declaration, before the semi-colon `;`).



### `Logibit.Hawk.Crypto`



The crypto module contains functions for validating the pieces of the request.



 - [x] genNormStr - generate a normalised string for a request/auth data

 - [x] calcPayloadHash - calculates the payload hash from a given byte[]

 - [x] calcPayloadHash - calculates the payload hash from a given string

 - [x] calcHmac - calculates the HMAC for a given string



### `Logibit.Hawk.Types`



This module contains the shared types that you should use for interacting with

the above modules.



 - HttpMethod - discriminated union type of HTTP methods

 - Algo - The supported hash algorithms

 - Credentials - The credentials object used in both client and server

 - HawkAttributes - Recognised attributes in the Hawk header

 - FullAuth - A structure that represents the fully calculated hawk request data

   structure



This module also contains a module-per-type with lenses for that type. The

lenses follow the same format as [Aether](https://github.com/xyncro/aether)

recommends.



### `Logibit.Hawk.Logging`



Types:



 - `LogLevel` - the level of the LogLine.

 - `LogLine` - this is the data structure of the logging module, this is where

   you feed your data.

 - `Logger interface` - the main interface that we can log to/into.

 - `Logger module` - a module that contains functions equiv. to the instance

   methods of the logger interface.

 - `NoopLogger : Logger`  - the default logger, you have to replace it yourself



It's good to know that you have to construct your LogLine yourself. That

LogLines with Verbose or Debug levels should be sent to the `debug` or `verbose`

functions/methods of the module/interface Logger, which in turn takes functions,

which are evaluated if it's the case that the logging infrastructure is indeed

logging at that level.



This means that logging at that level, and computing the log lines, needs only

be done if we can really do something with them.



### Other APIs



There are some modules that are currently internal as to avoid conflicting with

existing code. If these are made 'more coherent' or else moved to external

libraries, they can be placed on their own and be made public. The modules like this are `Random`, `Prelude`, `Parse`.



[ng-h]: https://www.nuget.org/packages/Hawk/

[ng-hs]: https://www.nuget.org/packages/Hawk.Suave/

[revproxy]: https://github.com/logibit/Logibit.Hawk/blob/master/src/Logibit.Hawk/Types.fs#L323-L333

[revproxy-read]: https://github.com/logibit/Logibit.Hawk/blob/master/src/Logibit.Hawk.Suave/Hawk.fs#L86-L95