{"id":13545662,"url":"https://github.com/namshi/jose","last_synced_at":"2025-05-14T02:03:53.739Z","repository":{"id":8770619,"uuid":"10456191","full_name":"namshi/jose","owner":"namshi","description":"JSON Object Signing and Encryption library for PHP.","archived":false,"fork":false,"pushed_at":"2021-06-18T12:34:30.000Z","size":214,"stargazers_count":1804,"open_issues_count":13,"forks_count":133,"subscribers_count":62,"default_branch":"master","last_synced_at":"2025-05-13T22:21:59.950Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/namshi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-03T14:21:08.000Z","updated_at":"2025-05-10T13:37:27.000Z","dependencies_parsed_at":"2022-08-07T04:16:45.408Z","dependency_job_id":null,"html_url":"https://github.com/namshi/jose","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fjose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fjose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fjose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fjose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namshi","download_url":"https://codeload.github.com/namshi/jose/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052670,"owners_count":22006716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T11:01:08.633Z","updated_at":"2025-05-14T02:03:53.688Z","avatar_url":"https://github.com/namshi.png","language":"PHP","funding_links":[],"categories":["PHP","安全 Security","身份验证( Authentication and Authorization )"],"sub_categories":[],"readme":"# NAMSHI | JOSE\n\n## Deprecation notice\n\n\u003e Hi there,\n\u003e\n\u003e as much as we'd like to be able to work on all of the OSS in the world,\n\u003e we don't actively use this library anymore\n\u003e This means that new features / bugfixes / etc will\n\u003e only be merged based on pull requests from external contributors, and\n\u003e we strongly recommend you look for a long-term alternative.\n\u003e \n\u003e If you're looking for an actively maintained library check\n\u003e [firebase/php-jwt](https://github.com/firebase/php-jwt) out!\n\n[![Build Status](https://travis-ci.org/namshi/jose.svg)](https://travis-ci.org/namshi/jose)\n[![Latest Stable Version](https://poser.pugx.org/namshi/jose/v/stable)](https://packagist.org/packages/namshi/jose)\n[![Total Downloads](https://poser.pugx.org/namshi/jose/downloads)](https://packagist.org/packages/namshi/jose)\n[![License](https://poser.pugx.org/namshi/jose/license)](https://packagist.org/packages/namshi/jose)\n\nThis library provides a lightweight\nimplementation of the JWS\n([JSON Web Signature](http://tools.ietf.org/html/draft-jones-json-web-signature-04)) specification.\n\n## Prerequisites\n\nThis library needs PHP 5.5+ and the library OpenSSL.\n\nIt has been tested using `PHP5.5` to `PHP7.0` and `HHVM`.\n\n\n## Installation\n\nYou can install the library directly from\ncomposer / [packagist](https://packagist.org/packages/namshi/jose):\n\n```\n\"namshi/jose\": \"7.0.*\"\n```\n\n## Usage\n\nUsing it is pretty straightforward:\nimagine that you want to offer a service\nthe ability to authenticate a user via\na cookie, and the service is built with\njavascript; what you would need to do is\nto generate a JWS (after verifying the\ncredentials once), store it as a cookie\nand then pass it from your JavaScript app\neverytime you want to authenticate that\nuser.\n\nFirst, generate the JWS:\n\n``` php\n\u003c?php\n\nuse Namshi\\JOSE\\SimpleJWS;\n\nif ($username == 'correctUsername' \u0026\u0026 $pass == 'ok') {\n\t$user = Db::loadUserByUsername($username);\n\n\t$jws  = new SimpleJWS(array(\n\t\t'alg' =\u003e 'RS256'\n\t));\n\t$jws-\u003esetPayload(array(\n\t\t'uid' =\u003e $user-\u003egetid(),\n\t));\n\n    $privateKey = openssl_pkey_get_private(\"file://path/to/private.key\", self::SSL_KEY_PASSPHRASE);\n    $jws-\u003esign($privateKey);\n    setcookie('identity', $jws-\u003egetTokenString());\n}\n```\n\nThen your JS app can use the available cookie to execute\nauthenticated calls, without sending passwords or credentials.\n\nOnce a request is submitted, you only have to verify that it\nis a valid call:\n\n``` php\n\u003c?php\n\nuse Namshi\\JOSE\\SimpleJWS;\n\n$jws        = SimpleJWS::load($_COOKIE['identity']);\n$public_key = openssl_pkey_get_public(\"/path/to/public.key\");\n\n// verify that the token is valid and had the same values\n// you emitted before while setting it as a cookie\nif ($jws-\u003eisValid($public_key, 'RS256')) {\n\t$payload = $jws-\u003egetPayload();\n\n\techo sprintf(\"Hey, my JS app just did an action authenticated as user #%s\", $payload['uid']);\n}\n```\n\n\u003e PROTIP: you can omit the second argument of the isValid() method, so jose will try to validate the token with the algorithm specified in the token's header, though this might expose you to some security issues.\n\u003e\n\u003e For now we recommend to always explicitely set the algorithm you want to use to validate tokens.\n\n### PHPSECLIB For RSA Verification\n\nYou may find that you need to use this library in an environment where\n[PHP's wrappers for OpenSSL](http://php.net/manual/en/ref.openssl.php)\ndo not work, or OpenSSL simply is not installed.  This library uses\nOpenSSL to encrypt by default, but you can specify that you want to use [PHPSecLib](http://phpseclib.sourceforge.net/) for a pure PHP\nimplementation of RSA encryption.\n\nIn these cases, simply add the optional `'SecLib'` parameter when\nconstructing a JWS:\n\n```php\n$jws = new JWS(array('alg' =\u003e 'RS256'), 'SecLib');\n```\n\nYou can now use the PHPSecLib implementation of RSA signing.  If you use\na password protected private key, you can still submit the private key\nto use for signing as a string, as long as you pass the password as the\nsecond parameter into the `sign` method:\n\n```php\n$jws-\u003esign(file_get_contents(SSL_KEYS_PATH . \"private.key\"), 'tests');\n```\n\nYou may also load a JWS using the PHPSecLib implementation of RSA verification:\n\n```php\n$jws = JWS::load($tokenString, false, $encoder, 'SecLib');\n```\n\n## Under the hood\n\nIn order to [validate the JWS](https://github.com/namshi/jose/blob/master/src/Namshi/JOSE/SimpleJWS.php#L43),\nthe signature is first [verified](https://github.com/namshi/jose/blob/master/src/Namshi/JOSE/JWS.php#L113)\nwith a public key and then we will check whether the [token is expired](https://github.com/namshi/jose/blob/master/src/Namshi/JOSE/SimpleJWS.php#L55).\n\nTo give a JWS a TTL, just use the standard `exp` value in the payload:\n\n``` php\n$date    \t= new DateTime('tomorrow');\n$this-\u003ejws  = new SimpleJWS(array('alg' =\u003e 'RS256'));\n$this-\u003ejws-\u003esetPayload(array(\n\t'exp' =\u003e $date-\u003eformat('U'),\n));\n```\n\n### Unsecure JWSes\n\nYou can allow [unsecure JWSes](https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#page-12)\nby setting the `$allowUnsecure` flag while loading JWSes:\n\n``` php\nJWS::load($this-\u003ejws-\u003egetTokenString(), true);\n```\n\nThis allows tokens signed with the 'none' algorithms to go through, which is something\nyou probably don't want to do. Proceed with caution :)\n\n**Unsecure JWSes are disabled by default since version 2.2.2. You should **not**\nuse previous versions other than 2.2.2 as they have a security\nvulnerability. More info [here](http://tech.namshi.com/blog/2015/02/19/update-your-namshi-slash-jose-installations-as-a-security-vulnerability-was-found/).**\n\n## Using a custom encoder\n\nIf, for some reason, you need to encode the token in a different way, you can\ninject any implementation of `Namshi\\JOSE\\Base64\\Encoder` in a `JWS` instance.\nLikewise, `JWS::load()` accepts such an implementation as a second argument.\n\n## Implementation Specifics\n\nThe library provides a base JWT Class that implements what is needed just for JSON Web Tokens. The JWS Class then extends\nthe JWT class and adds the implementation for signing and verifying using JSON Web Signatures. The SimpleJWS class extends\nthe base JWS class and adds validation of a TTL and inclusion of automatic claims.\n\n## Major Versions\n\n### 2.x.x to 3.x.x\n\nIntroduced the ability to specify an encryption engine. Added support of PHPSecLib to the existing OpenSSL implementation.\n\n### 3.x.x to 4.x.x - Not Backwards Compatible\n\nAdded the ability to set custom properties in the header. Moved automatic inclusion of certain claims into an SimpleJWS class from the base JWS class.\n\n### 6.x.x - Not Backwards Compatible\n\n#### 6.1.x\n- Dropped support for PHP 5.4\n- phpseclib 2.0\n\n#### 6.0.x\n- Dropped support for PHP 5.3\n- Don't escape slashes when generating signin input.\n  This may render tokens generated with earlier versions of Jose incompatible.\n\n### 7.x.x\n\n#### 7.0.x\n\nMoved phpseclib and the openssl extension as suggested dependencies.\n\n## Tests\n\nTests are written using PHPUnit for this library. After doing composer install you can execute the following command to run tests:\n\n```\n./vendor/bin/phpunit\n```\n\n## Credits\n\nThis library has been inspired by the\n[initial work done by @ritou](https://github.com/ritou/php-Akita_JOSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamshi%2Fjose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamshi%2Fjose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamshi%2Fjose/lists"}