{"action":"created","issue":{"url":"https://api.github.com/repos/tekul/jose-jwt/issues/10","repository_url":"https://api.github.com/repos/tekul/jose-jwt","labels_url":"https://api.github.com/repos/tekul/jose-jwt/issues/10/labels{/name}","comments_url":"https://api.github.com/repos/tekul/jose-jwt/issues/10/comments","events_url":"https://api.github.com/repos/tekul/jose-jwt/issues/10/events","html_url":"https://github.com/tekul/jose-jwt/issues/10","id":131408289,"number":10,"title":"Jose.Jwk Haddocks and Questions","user":{"login":"jasonzoladz","id":8467728,"avatar_url":"https://avatars.githubusercontent.com/u/8467728?v=3","gravatar_id":"","url":"https://api.github.com/users/jasonzoladz","html_url":"https://github.com/jasonzoladz","followers_url":"https://api.github.com/users/jasonzoladz/followers","following_url":"https://api.github.com/users/jasonzoladz/following{/other_user}","gists_url":"https://api.github.com/users/jasonzoladz/gists{/gist_id}","starred_url":"https://api.github.com/users/jasonzoladz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jasonzoladz/subscriptions","organizations_url":"https://api.github.com/users/jasonzoladz/orgs","repos_url":"https://api.github.com/users/jasonzoladz/repos","events_url":"https://api.github.com/users/jasonzoladz/events{/privacy}","received_events_url":"https://api.github.com/users/jasonzoladz/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2016-02-04T16:52:51Z","updated_at":"2016-02-05T12:20:34Z","closed_at":null,"body":"First, thanks very much for building this library.  I'm not in a position to roll-my-own-crypto, so it's practical libraries like this one that keep me free of Scala's rough, wtf-is-this embrace.\r\n\r\nSecond, please create haddocks for Jose.Jwk.  Lack of docs for Jose.Jwk definitely impeded my progress with the library.\r\n\r\nThird, as a sanity check, is this proper usage of the lib?  Further, do you have concerns with your library being used in production?\r\n\r\n```haskell\r\nimport qualified Data.Aeson.Encode     as A\r\nimport           Data.ByteString.Lazy  (toStrict)\r\nimport           Data.Either\r\nimport           Data.Time.Clock\r\nimport           Data.Time.Clock.POSIX\r\nimport           Jose.Jwa\r\nimport           Jose.Jwk\r\nimport           Jose.Jws\r\nimport           Jose.Jwt\r\n\r\n-- Get a Jwk\r\nprivateJwk :: IO Jwk\r\nprivateJwk = do\r\n  (_, privKey) <- generateRsaKeyPair 256 (KeyId \"mykey\") Sig (Just (Signed RS256))\r\n  return privKey\r\n\r\n-- Make some claims\r\nmakeJwtClaims :: IO JwtClaims\r\nmakeJwtClaims = do\r\n  currentUTC <- getCurrentTime\r\n  let laterDate =  IntDate $ utcTimeToPOSIXSeconds $ addUTCTime (60 * 60 * 24 * 14) currentUTC\r\n  return $\r\n    JwtClaims (Just \"issuer\")\r\n              (Just \"sub\")\r\n              (Just [\"aud1\", \"aud2\"])\r\n              (Just laterDate)\r\n              Nothing\r\n              Nothing\r\n              (Just \"jti\")\r\n\r\n-- Create a Payload\r\nmakePayload :: JwtClaims -> Payload\r\nmakePayload claims = Claims $ toStrict $ A.encode claims\r\n\r\n-- Test Encode and Decode a Jwt\r\nencodeDecodePrint :: IO ()\r\nencodeDecodePrint = do\r\n  jwk    <- privateJwk\r\n  claims <- makeJwtClaims\r\n  let encAlg  = JwsEncoding RS256\r\n      payload = makePayload claims\r\n  eitherJwt <- encode [jwk] encAlg payload\r\n  case eitherJwt of\r\n    Right jwt -> do\r\n      eitherContent <- decode [jwk] (Just encAlg) (unJwt jwt)\r\n      either (\\_ -> print \"Decode Failure\")\r\n             (\\(Jws (_, bs)) -> print bs)\r\n             eitherContent\r\n    _ -> print \"Encode failure\"\r\n```\r\n\r\nFinally, if possible, please post details on how to send donations to support your work on this.  I'd gladly contribute.\r\n\r\nCheers,\r\nJason"},"comment":{"url":"https://api.github.com/repos/tekul/jose-jwt/issues/comments/180326927","html_url":"https://github.com/tekul/jose-jwt/issues/10#issuecomment-180326927","issue_url":"https://api.github.com/repos/tekul/jose-jwt/issues/10","id":180326927,"user":{"login":"tekul","id":191720,"avatar_url":"https://avatars.githubusercontent.com/u/191720?v=3","gravatar_id":"","url":"https://api.github.com/users/tekul","html_url":"https://github.com/tekul","followers_url":"https://api.github.com/users/tekul/followers","following_url":"https://api.github.com/users/tekul/following{/other_user}","gists_url":"https://api.github.com/users/tekul/gists{/gist_id}","starred_url":"https://api.github.com/users/tekul/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tekul/subscriptions","organizations_url":"https://api.github.com/users/tekul/orgs","repos_url":"https://api.github.com/users/tekul/repos","events_url":"https://api.github.com/users/tekul/events{/privacy}","received_events_url":"https://api.github.com/users/tekul/received_events","type":"User","site_admin":false},"created_at":"2016-02-05T12:20:34Z","updated_at":"2016-02-05T12:20:34Z","body":"Hi. Thanks for your feedback! I will try to add some more documentation in general to clarify some of the things that your questions raise. Most of the library evolved to support my own use cases on another project, so it's definitely not comprehensive and some things are only implemented as far as I needed them to be. The APIs could also probably be improved.\r\n\r\nIt's true that there isn't any Haddock for the JWK module. This is mostly because the code (like the spec) is rather clunky to work with directly and I don't really like it as a public API. It is mainly there because you often have to work with JWKs when using the various specs, so it is useful to be able to deal with existing JSON encoded keys. In this case you are only really using the FromJSON instances. It is also useful to be able to export JSON JWKs, but the current module is quite limited in terms of how much of the spec if covers. \r\n\r\nIn any case, you don't need to use JWKs to create tokens and you don't need to use `Jwt.encode` and `Jwt.decode`. You get more type safety from working directly with the lower level APIs. For example, you could use the `Jws` module directly in your example above, which makes the code simpler. You don't have to use the `JwtClaims` type to create the content. That is really intended as a convenience for checking certain \r\n\r\n```\r\nimport Jose.Jws\r\nimport Jose.Jwa\r\nimport Crypto.PubKey.RSA\r\n\r\n...\r\n\r\nencodeDecodePrint :: IO ()\r\nencodeDecodePrint = do\r\n    (kPub, kPr) <- generate 512 65537\r\n    eitherJwt <- rsaEncode RSA256 kPr \"your content as a bytestring\"\r\n    case eitherJwt of\r\n        Right jwt -> do\r\n            eitherContent <- rsaDecode kPub (unJwt jwt)\r\n            either (\\_ -> print \"Decode Failure\")\r\n                (\\(Jws (_, bs)) -> print bs)\r\n                eitherContent\r\n    _ -> print \"Encode failure\"   \r\n```\r\n\r\nIn some use cases (like mine) you may need to support multiple key and algorithm options, and have different keys for different purposes. I configure a server with a set of JWKs and also with the algorithms used, but obviously if the keys don't match the algorithms, you will get a runtime error.\r\n\r\nJWTs are pretty general purpose, so \"proper usage\" of the library is hard to define. The functionality is really all in `encode/decode` pairs, so it's quite simple to use and I can't really think of a *wrong* way to use it. However, I'm talking purely about the library functionality here, not about how you choose to use JWTs, where there is obviously more scope for error, depending on what they're being used for.\r\n\r\nRegarding use in production, I don't have any specific concerns. I'm reasonably confident that the code works the way it's intended to, in terms of producing and decoding valid JWTs. Decoding invalid content is something I would like to investigate more. There are no guarantees, and you should do plenty of tests and make your own decision, based on what you are building. Anything that applies to the underlying libraries (such as cryptonite) and Haskell crypto in general applies here.\r\n\r\nI'm not looking for donations at the moment, but thanks for your generous offer. I'll let you know if times get tough ;-)."}}