{"action":"created","issue":{"url":"https://api.github.com/repos/barrysteyn/node-scrypt/issues/72","labels_url":"https://api.github.com/repos/barrysteyn/node-scrypt/issues/72/labels{/name}","comments_url":"https://api.github.com/repos/barrysteyn/node-scrypt/issues/72/comments","events_url":"https://api.github.com/repos/barrysteyn/node-scrypt/issues/72/events","html_url":"https://github.com/barrysteyn/node-scrypt/issues/72","id":68118409,"number":72,"title":"Scrypt Version 5","user":{"login":"barrysteyn","id":1537348,"avatar_url":"https://avatars.githubusercontent.com/u/1537348?v=3","gravatar_id":"","url":"https://api.github.com/users/barrysteyn","html_url":"https://github.com/barrysteyn","followers_url":"https://api.github.com/users/barrysteyn/followers","following_url":"https://api.github.com/users/barrysteyn/following{/other_user}","gists_url":"https://api.github.com/users/barrysteyn/gists{/gist_id}","starred_url":"https://api.github.com/users/barrysteyn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/barrysteyn/subscriptions","organizations_url":"https://api.github.com/users/barrysteyn/orgs","repos_url":"https://api.github.com/users/barrysteyn/repos","events_url":"https://api.github.com/users/barrysteyn/events{/privacy}","received_events_url":"https://api.github.com/users/barrysteyn/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":32,"created_at":"2015-04-13T14:54:45Z","updated_at":"2015-06-12T02:54:51Z","closed_at":null,"body":"Scrypt Version 5.0\r\n\r\n@fresheneesz @ironwallaby @BrandonZacharie \r\n\r\nThis issue is to address #67, #68, #69, #70 and #71. Its outcome is to produce a consistent API that is \"JavaScripty\". It will not be backward compatible (hence the major version increment). This ticket is here for us as a community to discuss and have a say regarding the future of this module. As such, I will not start developing until I feel that there has been an adaquate debate. At the very least, I will leave this up for at least a week. The outcome of this issue will be many \"children\" issues that I will use to alter the module.\r\n\r\nWhat does everyone think of putting the new design in a wiki so we can all have input?\r\n\r\nIt will consist of the following:\r\n\r\n# Drop legacy support\r\nThe first version of the library is so old it really does not need to be supported anymore. Seeing as version 5.0 will not be backward compatible with previous versions, this is a good time to drop support for the previous version:\r\n\r\n  * Remove legacy support from code base\r\n  * Remove legacy api from documentation\r\n\r\n# Redesign API\r\n\r\n## No Global Config\r\nA global configuration object will be dropped. This will produce a more consistent and expected result when modules are cached by reducing side effects. \r\n\r\n## Callback functions consistent\r\nAll callback functions will have the following consistent signatures:\r\n\r\n```\r\nfunction(errObject, result)\r\n```\r\n\r\n  * errObject will be null if there is no error (not undefined)\r\n  * result will be a json object\r\n\r\n## Error handling\r\n\r\n### Everything of Type Error\r\nAll errors objects will be of type [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error).\r\n\r\n### Throwing Exceptions\r\nWhen dealing with asynchronous callbacks, this can get a bit hairy. Looking at [this](https://www.joyent.com/developers/node/design/errors#) document, it proposes that programmer errors are thrown as exceptions in asynch (or normal sync) functions. Async is normally where the debate comes in.\r\n\r\nAny programmer error will be thrown as an exception (even in the async case). For async, we don't want to start the infrastructure of an async call when we already know that there is an error. Rather, throw an exception immediately.\r\n\r\n### Error descriptions\r\nCurrently, it has been pointed out that the error descriptions returned are obtuse. This is because the errors are trying to mimic the original Scrypt C library. I am up for suggestions from the community for making them easier to understand.\r\n\r\n## Buffers\r\nOne crucial step towards the above goal will be for all inputs (keys, hashes, salts, outputs) to be of type [Buffer](https://nodejs.org/api/buffer.html). This will remove the need to configure an output's transcoding. Speaking of transcoding, lets just leave that to the Buffer in the end (but document for people to understand quickly). If a string is presented instead of a buffer as an input, it will automatically be cast as a buffer.\r\n\r\n## Params Object\r\nThe params object is an attempt for Scrypt's internal config to be altered in a human \"understandable\" manner. As it stands now, I think it is okay. So I am going to leave it be\r\n\r\n## Hash\r\nThe hash function will keep the same API, but as mentioned above, there will be no config for setting key and output encoding. Instead, both key and output will be of type buffer:\r\n\r\n```\r\nhash(key, scrypt_parameters, callback_function)\r\n```\r\n\r\n## Verify\r\nThe verify function will be as it is now, except no config (all inputs assumed to be buffer)\r\n\r\n## KDF\r\nThe key derivation function is where most of the changes will occur. Without a global object, everything can be assumed to be of type Buffer. The KDF api is:\r\n\r\n```\r\nkdf(key, scrypt_parameters, outputLength, salt, callback_function)\r\n```\r\n\r\nCurrently, if no salt is provided, then a 32 bit salt will be randomly generated. The size of this salt can be set in the global config (it defaults to 32 bits). Since we are removing this global object, I am up for suggestions regarding how this default salt size should be set. One option is to have a default size as an input parameter. This will be ignored if a valid salt object is presented. Again, suggestions are welcome.\r\n\r\n# Improve Verify function\r\nIt has been pointed out that the verify function is not consistent. #71 states that the verify object throws an exception instead of returning false. I am sure that this was due to a programmer error (as mentioned above, these exceptions are meant to be thrown). Still, it is confusing. The verify function will therefore aim not to throw any exceptions and instead, just return a boolean.\r\n\r\n# Alter Hash length\r\nShould we give the ability to alter the length of the hash? Currently, the has is constrained to a 32 bit HMAC. Perhaps we should allow an increase in size? I don't know if this feature is a needed or wanted, so lets discuss here.\r\n\r\n# Change object \"functors\" to real functions\r\nAs pointed out in #68, the functions are not real functions, instead you can think about them as objects with the () operators overloaded. I will change these to proper functions so that there are not surprises\r\n\r\n# What else?\r\n\r\nPlease provide any other feedback and discussion here. If I have left anything out, then please shout out."},"comment":{"url":"https://api.github.com/repos/barrysteyn/node-scrypt/issues/comments/111337278","html_url":"https://github.com/barrysteyn/node-scrypt/issues/72#issuecomment-111337278","issue_url":"https://api.github.com/repos/barrysteyn/node-scrypt/issues/72","id":111337278,"user":{"login":"barrysteyn","id":1537348,"avatar_url":"https://avatars.githubusercontent.com/u/1537348?v=3","gravatar_id":"","url":"https://api.github.com/users/barrysteyn","html_url":"https://github.com/barrysteyn","followers_url":"https://api.github.com/users/barrysteyn/followers","following_url":"https://api.github.com/users/barrysteyn/following{/other_user}","gists_url":"https://api.github.com/users/barrysteyn/gists{/gist_id}","starred_url":"https://api.github.com/users/barrysteyn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/barrysteyn/subscriptions","organizations_url":"https://api.github.com/users/barrysteyn/orgs","repos_url":"https://api.github.com/users/barrysteyn/repos","events_url":"https://api.github.com/users/barrysteyn/events{/privacy}","received_events_url":"https://api.github.com/users/barrysteyn/received_events","type":"User","site_admin":false},"created_at":"2015-06-12T02:54:51Z","updated_at":"2015-06-12T02:54:51Z","body":"Why can't we just detect if the feature is available. That was my plan all\nalong, I did not intend forcing a cutting edge version of scrypt on anyone\nOn Jun 11, 2015 7:52 PM, \"Michael Phan-Ba\" <notifications@github.com> wrote:\n\n> As a compromise, I would say write the default export require(\"scrypt\")\n> to use callbacks and require(\"scrypt/promise\") to return promises.\n>\n> —\n> Reply to this email directly or view it on GitHub\n> <https://github.com/barrysteyn/node-scrypt/issues/72#issuecomment-111337048>\n> .\n>\n"}}