Merge branch 'master' into 1.0

.backportrc.json

@@ -0,0 +1,9 @@
+{
+    "repoOwner": "kelvinmo",
+    "repoName": "simplejwt",
+    "targetBranchChoices": [ "1.0" ],
+    "targetPRLabels": [ "backport" ],
+    "branchLabelMapping": {
+        "^backport-to-(.+)$": "$1"
+    }
+}

.github/workflows/backport.yml

@@ -15,10 +15,9 @@ jobs:
       - name: Backporting
         uses: sorenlouv/backport-github-action@v9.5.1
         with:
-          # github_token requires the following permissions
-          # repo or public_repo
-          # workflow
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # github_token requires a token that has write permissions to the following:
+          # Contents, Pull Requests, Workflows
+          github_token: ${{ secrets.BACKPORT_TOKEN }}
           auto_backport_label_prefix: backport-to-
 
       - name: Log output on success

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+- Fixed: Uncaught `SodiumException` if an error occurs in functions
+  that use libsodium (#218)
+
 ## [1.0.0]
 
 - Removed: Support for PHP 7.3 and 7.4
@@ -226,6 +231,7 @@ All notable changes to this project will be documented in this file.
 
 - Initial release
 
+[Unreleased]: https://github.com/kelvinmo/simplejwt/compare/v0.1.0...HEAD
 [1.0.0]: https://github.com/kelvinmo/simplejwt/compare/v0.9.3...v1.0.0
 [0.9.3]: https://github.com/kelvinmo/simplejwt/compare/v0.9.2...v0.9.3
 [0.9.2]: https://github.com/kelvinmo/simplejwt/compare/v0.9.1...v0.9.2

src/SimpleJWT/Crypt/AlgorithmFactory.php

@@ -111,7 +111,7 @@ static public function create(string $alg, ?string $use = null): AlgorithmInterf
     /**
      * Returns a list of supported algorithms for a particular use.
      *
-     * The uses can be one of the constants in the {@link Algorithm} class.
+     * The uses can be one of the constants in the {@link AlgorithmInterface} class.
      *
      * @param string $use the use
      * @return array<string> an array of algorithms

src/SimpleJWT/Crypt/AlgorithmInterface.php

@@ -42,8 +42,9 @@
  * Interface for a cryptographic algorithm.
  *
  * Algorithms will ordinarily implement one or more of the subinterfaces
- * of this interface: {@link SignatureAlgorithm},
- * {@link EncryptionAlgorithm} or {@link KeyManagementAlgorithm}.
+ * of this interface: {@link Signature\SignatureAlgorithm SignatureAlgorithm},
+ * {@link Encryption\EncryptionAlgorithm EncryptionAlgorithm} or
+ * {@link KeyManagement\KeyManagementAlgorithm KeyManagementAlgorithm}.
  */
 interface AlgorithmInterface {
 
@@ -63,7 +64,7 @@ public function getAlg(): ?string;
      *
      * Implementations should test the host system's configuration to determine
      * an algorithm is supported.  For example, if an algorithm requires a
-     * particular PHP extension is installed, then this method should test
+     * particular PHP extension to be installed, then this method should test
      * the presence of this extension before including the algorithm in the
      * return value.
      *

src/SimpleJWT/Crypt/BaseAlgorithm.php

@@ -47,8 +47,10 @@
  * The actual `alg` or `enc` to be used is specified by the `$alg` parameter
  * in the constructor.
  *
- * Algorithms will ordinarily implement one or more of {@link SignatureAlgorithm},
- * {@link EncryptionAlgorithm} or {@link KeyManagementAlgorithm} interfaces.
+ * Algorithms will ordinarily implement one or more of
+ * {@link Signature\SignatureAlgorithm SignatureAlgorithm},
+ * {@link Encryption\EncryptionAlgorithm EncryptionAlgorithm} or
+ * {@link KeyManagement\KeyManagementAlgorithm KeyManagementAlgorithm} interfaces.
  */
 abstract class BaseAlgorithm implements AlgorithmInterface {
 
@@ -85,14 +87,14 @@ public function getAlg(): ?string {
      *
      * The criteria specified in this function is combined with the default
      * criteria for the algorithm (through the {@link getKeyCriteria()} function)
-     * before it is bassed to the {@link SimpleJWT\Keys\KeySet::get()} function
+     * before it is bassed to the {@link KeySet::get()} function
      * to retrieve the key.
      *
      * `$criteria` can be one of the following:
      *
      * 1. `null`, in which case only the default criteria are used
      * 2. a string containing the key ID; or
-     * 3. an array compatible with the {@link SimpleJWT\Keys\KeySet::get()} function
+     * 3. an array compatible with the {@link KeySet::get()} function
      *
      * @param KeySet $keys the key set from which the key will
      * be selected

src/SimpleJWT/Crypt/KeyManagement/AESGCMKeyWrap.php

@@ -107,7 +107,7 @@ public function decryptKey(string $encrypted_key, KeySet $keys, array $headers,
 
     /**
      * Generates the initialisation vector.  This uses
-     * {@link SimpleJWT\Util\Util::random_bytes()} to generate random bytes.
+     * {@link \SimpleJWT\Util\Util::random_bytes()} to generate random bytes.
      *
      * @return string the initialisation vector as a binary string
      */

src/SimpleJWT/Crypt/KeyManagement/PBES2.php

@@ -148,7 +148,7 @@ public function decryptKey(string $encrypted_key, KeySet $keys, array $headers,
     }
 
     /**
-     * Generates salt input.  This uses {@link SimpleJWT\Util\Util::random_bytes()}
+     * Generates salt input.  This uses {@link \SimpleJWT\Util\Util::random_bytes()}
      * to generate random bytes.
      *
      * @return string the salt input

src/SimpleJWT/Crypt/KeyManagement/RSAES.php

@@ -82,7 +82,7 @@ public function getKeyCriteria(): array {
     }
 
     /**
-     * Generates a seed for OAEP encoding.  This uses {@link SimpleJWT\Util\Util::random_bytes()}
+     * Generates a seed for OAEP encoding.  This uses {@link \SimpleJWT\Util\Util::random_bytes()}
      * to generate random bytes.
      *
      * @param int<1, max> $len the length of the seed required, in octets

src/SimpleJWT/Crypt/Signature/EdDSA.php

@@ -45,7 +45,10 @@
 use SodiumException;
 
 /**
- * Abstract class for SHA2-based signature algorithms.
+ * Edwards-curve Digital Signature Algorithm (EdDSA).  This class implements
+ * the `EdDSA` algorithm.
+ * 
+ * @link https://datatracker.ietf.org/doc/html/rfc8032 RFC 8032
  */
 class EdDSA extends BaseAlgorithm implements SignatureAlgorithm {
     public function __construct(?string $alg) {

src/SimpleJWT/Crypt/Signature/None.php

@@ -47,8 +47,9 @@
  * 
  * By default, the `none` algorithm is disabled in SimpleJWT.  Attempts
  * to decode a JWT with a `none` algorithm will return a
- * {@link SimpleJWT\InvalidTokenException}.  In order to enable this
- * algorithm, call {@link AlgorithmFactory::addNoneAlg()} static
+ * {@link \SimpleJWT\InvalidTokenException InvalidTokenException}.
+ * In order to enable this algorithm, call the 
+ * {@link \SimpleJWT\Crypt\AlgorithmFactory::addNoneAlg()} static
  * method.
  * 
  * @link https://datatracker.ietf.org/doc/html/rfc8725.html#section-3.2

src/SimpleJWT/InvalidTokenException.php

@@ -49,12 +49,20 @@ class InvalidTokenException extends \RuntimeException {
 
     /** An error code indicating that the JWT's signature cannot be verified.
      * This may be due to the lack of a key, cryptographic errors, or the
-     * signature is incorrect. */
+     * signature is incorrect.
+     * 
+     * Further information on the error may be available with the
+     * {@link getPrevious()} method.
+     */
     const SIGNATURE_VERIFICATION_ERROR = 16;
 
     /** An error code indicating that the JWE cannot be decrypted.
      * This may be due to the lack of a key, cryptographic errors, or the
-     * authentication information is incorrect. */
+     * authentication information is incorrect.
+     * 
+     * Further information on the error may be available with the
+     * {@link getPrevious()} method.
+     */
     const DECRYPTION_ERROR = 17;
 
     /** An error code indicating that the JWT or JWE is invalid as a result
@@ -87,6 +95,10 @@ public function __construct(string $message = "", int $code = 0, \Exception $pre
     /**
      * Returns the required time specified in the token.
      * 
+     * This is used if the exception code is one of
+     * {@link self::TOO_EARLY_ERROR TOO_EARLY_ERROR} or
+     * {@link self::TOO_LATE_ERROR TOO_LATE_ERROR}.
+     * 
      * @return int the required time time
      */
     public function getTime(): int {

src/SimpleJWT/JWE.php

@@ -47,6 +47,17 @@
 use SimpleJWT\Util\Helper;
 use SimpleJWT\Util\Util;
 
+/**
+ * A JSON web encryption (JWE) object.
+ * 
+ * A JWE consists of a header and ciphertext.  To create a JWE, use the
+ * constructor with the header and plaintext as the parameter.  The JWE can then
+ * be encrypted using the {@link encrypt()} function.
+ *
+ * To decrypt a JWE, use the {@link decrypt()} static function.  If
+ * successful, the static function will return a JWE object.  The plaintext
+ * can then be retrieved using the {@link getPlaintext()} function.
+ */
 class JWE extends Token {
     /** @var array<string, mixed> $headers */
     protected $headers = ['typ' => 'JWE'];
@@ -234,7 +245,8 @@ public function getPlaintext(): string {
      * content encryption key
      * @param string $kid the ID of the key to use to encrypt. If null, this
      * is automatically retrieved
-     * @param string $format the JWE serialisation format
+     * @param string $format the JWE serialisation format, should be one of
+     * {@link Token::COMPACT_FORMAT} or {@link Token::JSON_FORMAT}
      * @return string the encrypted JWE
      * @throws \SimpleJWT\Keys\KeyException if there is an error obtaining the key
      * to sign the JWT

src/SimpleJWT/JWT.php

@@ -197,7 +197,8 @@ public function getClaim(string $claim) {
      * should be automatically completed, or false if no auto-completion is
      * to be performed
      * @param string $alg if not null, override the `alg` header
-     * @param string $format the JWT serialisation format
+     * @param string $format the JWT serialisation format, should be one of
+     * {@link Token::COMPACT_FORMAT} or {@link Token::JSON_FORMAT}
      * @return string the signed and serialised JWT
      * @throws \SimpleJWT\Keys\KeyException if there is an error obtaining the key
      * to sign the JWT

src/SimpleJWT/Keys/KeySet.php

@@ -259,8 +259,8 @@ function get(array $criteria): ?KeyInterface {
      * There are also a number of special properties that can be used to match
      * keys:
      * 
-     * - {@link Key::SIZE_PROPERTY}, which specifies the length of the key in bits
-     * - {@link Key::PUBLIC_PROPERTY}, which is true if the key is an asymmetric public
+     * - {@link KeyInterface::SIZE_PROPERTY}, which specifies the length of the key in bits
+     * - {@link KeyInterface::PUBLIC_PROPERTY}, which is true if the key is an asymmetric public
      *   key
      *
      * A criterion can be mandatory, mandatory-if-present (indicated using a `@`
@@ -437,7 +437,7 @@ function isPublic(): bool {
      * key.
      *
      * @param string $secret the secret
-     * @param string $format the format of the secret - see {@link SymmetricKey::__create()}
+     * @param string $format the format of the secret - see {@link SymmetricKey::__construct()}
      * for further details
      * @return KeySet the created key set
      */