JJcode

From ProgClub
Revision as of 02:43, 12 May 2016 by John (talk | contribs) (So it begins...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

JJcode is the ProgClub key management software. That's the software that helps you manage identity keys in your applications from the database into the UI. For other projects see projects.

Status

Under way. Not released yet, there's stuff TODO.

Motivation

Why this software? So the idea is make it easy to manage keys in your application. Application keys/hashes are strong, short, human-readable, and profanity free.

Administration

Contributors

Members who have contributed to this project. Newest on top.

All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.

Upstream contributors:

Copyright

Copyright 2016, Contributors.

License

Licensed under the MIT license.

Components

Libraries, tools, services or media from third parties used under license:

  • Our Base56 encoding adapted from base58php provided under the MIT license

Resources

Downloads

There are presently do downloads for this library. See below about how to get the source code.

Source code

The repository can be browsed online:

https://www.progclub.org/pcrepo/jjcode/branches/0.1

The latest stable released version of the code is available from:

https://www.progclub.org/svn/pcrepo/jjcode/tags/latest/0.1

Or if you want the latest version for development purposes:

https://www.progclub.org/svn/pcrepo/jjcode/branches/0.1

Links

Specifications

Functional specification

The functional specification describes what the project does.

The jjcode library provides:

  1. unique keys (similar to GUIDs but more compact)
  2. safe hashes (better than MD5 and SHA1, shorter than SHA256/SHA512)
  3. short/human-readable hashes/keys suitable for URLs (28-29 char strings)
  4. database integration (keys are binary(21) SQL in hex format 0x1234...)
  5. profanity filtering (for English profanity and 1337 5p34k)

A jjcode can be in one of four formats:

  1. bid: binary format, 21 bytes
  2. cid: short character format (human readable), 28-29 character string
  3. hid: hexadecimal format, 42 character string
  4. sql: hexadecimal format for SQL, 44 character string

There are a bunch of functions for converting between formats, e.g. bid2sql. If you have a key but you're not sure of the format you can call e.g. key2bid, key2cid, etc. to get it into a known format.

So a 'bid' is 21 bytes and suitable for use in database tables; a 'cid' is 28-29 human readable characters and suitable for use in URLs or APIs; a 'hid' is a 42 character string suitable for debugging; and 'sql' format is suitable for use in SQL queries. By default data is validated before it is converted between formats (you can override this behaviour).

To generate the 'cid' format codes we use the jjencode function, which is basically a Base56 encoder. Similarly to convert 'cid' codes back into other formats we begin with jjdecode, the Base56 decoder.

Inputs to jjcode hashing functions are converted to strings if necessary. If you want to hash data/objects that aren't strings you can serialize your input before passing it in (which will obviously couple you to PHP). We didn't want to tie our data formats to PHP so we require string inputs (i.e. we don't do input serialization for you, but it's easy to do yourself if that's what you want).

So here is an example key in various formats:

bid: string(21) ";!F7?z???f?NU?n?q???"
cid: string(29) "7vHkwFsRXVUje7HsuZzQYCMtwmvVw"
hid: string(42) "3b214637be7ac03faf6615b44e55a06ee771adaa89"
sql: string(44) "0x3b214637be7ac03faf6615b44e55a06ee771adaa89"

Remember:

  1. bid for databases
  2. cid for URLs and APIs
  3. hid for debugging
  4. sql for queries

It's worth noting that jjcodes aren't the final word in key management for your application. For example, if you were to tell your new customer that their customer ID was 3tt5dfie39y6hJJPQg6PsM8P46N48, they might tell you to get stuffed! If you need keys for use in HTML forms or other business logic see our kkcode functions for shorter and more user-friendly identifiers with built-in classification and redundancy checks.

Regarding profanity filtering: there is a list of blacklisted strings which are English words, or parts thereof, which could possibly be considered offensive. The list of English words is processed to generate 1337 5p34k variations, so e.g. 455 53x would be filtered. Note particularly that only English terms have been catalogued, there is no support for other languages at this time.

The catalogue of profanity is "append only". The developers can append blacklisted terms to the list, but removing terms or reordering terms will be problematic. If the list of profanity is changed by new additions then all previously generated keys/hashes will need to be upgraded. There is a jjcode_upgrade function for this purpose. Remember: you can never ever remove things from the profanity list or change their order.

Technical specification

The technical specification describes how the project works.

Notes

Notes for implementers

If you are interested in incorporating this software into your project, here's what you need to know:

Check-out the code from svn and include it in your application:

require_once '/path/to/jjcode/src/jjcode.php';

Notes for developers

If you're looking to set up a development environment for this project here's what you need to know:

See source code above RE: how to get the code for development purposes.

Tasks

TODO

Things to do, in rough order of priority:

  • Provide initial jjcode/kkcode implementation
  • Document kkcode functionality

Done

Stuff that's done. Latest stuff on top.

  • JE 2016-05-12: created project in svn
  • JE 2016-05-12: created project page