Package: ecuth
ECUTHA library for authentication and authorization with public key signature, using random challenge/response.The main motivation for writing this package was to be able to use an established HTTP authentication scheme with Metamask to sign a challenge to prove identity. However, the package is (hopefully) designed to work in any generic case.The server application in/exampledemonstrates the Metamask use-case, at the same time demonstrating all parts of the package.UsageIn theexamplesfolder auwsgiHTTP server is provided. This illustrates how to use theeip712andhobafilters to perform a pure HTTP authentication using Metamask as a signer, using theEthereumRetrieverimplementation.To run the server, you need the "uwsgi python plugin" installed. Once you have, you can run it like this:uwsgi --wsgi-file examples/server.py --http :5555(note that the provided config uses port 5555 in the origin. It has no special meaning, just made up on the spot. If you change it, you will have to change the config, too).The recipe is as follows:Server generates and stores the challenge, and sends it to the client in aWWW-Authenticationheader along withrealmandmax-age.Client uses the challenge to generate the HOBA signature material.Client hashes the HOBA signature material with sha256.Client uses thehashedHOBA signature material as the challenge in the EIP712 schema.Client serializes the challenge according to the EIP712 schema.Client prompts the puny human to sign the serialized data in step 5 above with Metamask.Client generates the HOBA authorization header value and sends it to the server. Note that:the challenge part of the header is the original server challenge.the signature part is a signature on the HOBA-challenge-wrapped-in-EIP712 described in steps 2-6 above.Server parses the header, verifies that the challenge hasn't expired.Server retrieves the filter pipeline from the stored challenge and executes it on the original challenge. The filters are, in sequence:HOBA filterSHA256 filter (this filter is defined in the server example source file directly)EIP712 filterThe resulting value of step 9 is the data signed by the client. The ethereum address of the client is recovered using the signature and this data.Server requests a file at the base-url with filename matching the 0x-hex of the recovered ethereum address.If the file can be retrieved and is readable, it means that the authentication was a success. There should be much rejoicing.OverviewACLThe ACL items used in this example constitute a simple key/value store, implemented with theYAMLAclclass. The document must:be a valid YML document.must have two top-level elements;levelanditems.itemsmust be a collection of key/value entries on a single-level.the value of eachitemmust be0(no access),2(write) or4(read). (any key with value 0 can optionally be omitted).level: <level>
items:
  foo: 0
  foo.bar: 2
  xyzzy.baz: 4
  ...InterpretationThelevelfield defines an hierarchical criteria for changing data:Iflevelof userXislowerorequal tolevelof userY, then userXcannotchangeordeletedata for that user.The values for theitemskeys are a simplificaiton of thechmodbitflag used in unix systems;If0x04is set, read access is granted.If0x02is set, write access is granted.GNUPG ACL encryptionThe example uses gnupg for encryption of the ACL list.Provided in this repository is a.gnupgresource directory with the keys used in the test and server, along with thetest/datadirectory containing:exported keysthe ACL source filethe encrypted and signed ACL source fileThe private key (and keystore file) of the ethereum key used in the exampleThe latter was generated with this command:gpg -aer 245508630E91CA06EFA1FBB20B297F3839D18362 --sign -u 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -o test/data/0xe1AB8145F7E55DC933d51a18c793F901A3A0b276 test/data/data.ymlThe test/server gnupg setup will expect the key thatsignedthe ACL document to befully trusted. The trustdb in.gnupgalready includes this trust. Of course I'm not gonna give you my secret key, so you may want to try yourself with your own. When you do, just remember you have to update the trust settings.... or just write your own decrypter method, dang nabbit :)FiltersA deterministic transformation pipeline of the challenge can be added by using filter methods. This is useful in cases where the client needs to wrap the data before signing it.Two filters are provided in theecuth.filterspackage:EIP712: Metadata wrapper for Ethereum, increasingly standard in the ecosystem, and soon-to-be enforced by the Metamask message signer.HOBA: The HTTP Origin-Bound Authentication scheme, which allows authentication with client signing a challenge using public key crypto, exactly what we're exploring here.These filters each have additional dependencies, defined asextra_requiresin thesetup.cfgfile (i.e. to install them both, usepip install ecuth[eip712,hoba])EIP712Described inhttps://eips.ethereum.org/EIPS/eip-712The provided filter will expect the challenge to be provided wrapped in the following (pseudo) schema:const challenge_type = [
	{
	type: 'bytes',
	name: 'challenge',
	}
];

const domain_type = [
	{ 
		name: "name",
		type: "string"
	},
	{
		name: "version",
		ype: "string"
	},
	{
		name: "chainId",
		type: "uint256",
	},
//{ name: "verifyingContract", type: "address" },
//{ name: "salt", type: "bytes32" },
];

const data_to_serialize_and_sign = {
	types: {
		EIP712Domain: domain_type,
		Challenge: challenge_type,
	},
	primaryType: "Challenge",
	domain: <domain_data>,
	message: {
		challenge: <challenge_value>,
	},
}(verifyingContractandsaltare commented out as the contract part not yet implemented)To be clear; this schema is custom designed for the EIP712 filter and example server (see below).HOBAA superficial study of the existing authentication schemes for HTTP has suggested that HOBA is the least "hacky" for the purposes of a simple challenge/response mechanism where the public key is known to the server. The only caveat is that thesecp256k1signature algorithm used with Ethereum (and other cryptocurrencies) is not standardized as an IANA public key signature algo scheme. In fact, at the time of writing, onlyRSA-SHA256andRSA-SHA1are. Since all numbres between 2 and 99 are up for grabs, the arbitrary but not quite unpretentious number42has been chosen in the dependency packagehttp-hoba-authwritten specifically to support this package. So, collisions may happen. Beware.That being said; it's anyway advisable to readRFC 7486before you use this filter.