xxtea 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8eca82a1c887086264d8807bf55a1980dc28f35f956c02a5bf66ebef33ab8f6
-  data.tar.gz: d6707b17d68788035c7d8f2d90210f15408ba3a1d7a0e3c4dc0636d2b519dd10
+  metadata.gz: 89a73616644886a2d6c15b0567b6a123ba8029a410affd9aa7c76213358ba5b9
+  data.tar.gz: 181fff72b4214e44978ccd5ad26209d1362b0dcccaa949944bcf8e29c14b3577
 SHA512:
-  metadata.gz: e829728fcc9f4296e74f9bee45568aab867679971c866ca992146a715a62444fea17602bf21322041c82bed745d7ba7a7f10905e7df4ecf194547b41164ac686
-  data.tar.gz: 3a4224238e8e3d062dfc83671981834e1ab571c2e293bb90095db8ad46de86921c94d87972dcd0f3180ab6c562d9913e1dd1f2f4692dd07815752ffb12b8349e
+  metadata.gz: 5dc86b066d959b3d9bbb013fa9f3ba7cd772608cc5dcb434889185c8a0fccb4ab0b01f210fa3c628745d6efd9e760a29e175d469febb2d4618d61e62e13b0ad8
+  data.tar.gz: 804d0e50a19dcfcfbfb087376612e4d7f92309b9192463e324b92e133cf291466f0812127b6dabe22927bb48bb160032290beea8e596f3be4b66f25374c2c42e

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.2.0
+
+- Add the `:length_word_suffix` and `:length_word_prefix` padding schemes, matching all five padding modes of [Python xxtea](https://github.com/ifduyue/xxtea) 6.2.0.
+  - `:length_word_suffix`: zero-pads to a 4-byte boundary, then appends one little-endian `uint32` with the original length (Cocos Creator JSC files).
+  - `:length_word_prefix`: prepends one little-endian `uint32` with the original length, then zero-pads the data to a 4-byte boundary.
+  - Both support empty input (padded to XXTEA's 2-word minimum) and raise `ArgumentError` on decrypt when the zero padding or length word is inconsistent.
+- Add `XXTEA::LENGTH_WORD_SUFFIX` and `XXTEA::LENGTH_WORD_PREFIX` constant aliases.
+
+## 1.1.0
+
+- Add named padding schemes: `:pkcs7_4_min8` (default, also `true`), `:pkcs7_8`, and `:none` (also `false`).
+- `:pkcs7_4_min8` is 4-byte PKCS#7-like with an 8-byte minimum (pad values 5–8 for short inputs), compatible with Python xxtea.
+- `:pkcs7_8` is standard 8-byte PKCS#7, compatible with Python [xxteang](https://github.com/ifduyue/xxteang).
+
 ## 1.0.0
 
 - Rewrite as a Ruby C extension compatible with Python [xxtea](https://github.com/ifduyue/xxtea) 5.3.3.

data/README.md

@@ -5,7 +5,8 @@
 
 [XXTEA](https://en.wikipedia.org/wiki/XXTEA) implemented as a Ruby C extension, licensed under 2-clause BSD.
 
-Ciphertext is compatible with the [Python xxtea](https://github.com/ifduyue/xxtea) package.
+Default ciphertext is compatible with the [Python xxtea](https://github.com/ifduyue/xxtea) package.
+`padding: :pkcs7_8` is compatible with [Python xxteang](https://github.com/ifduyue/xxteang).
 
 The XXTEA algorithm takes a 128-bit key and operates on an array of 32-bit
 integers (at least 2 integers), but it doesn't define the conversions between
@@ -21,12 +22,11 @@ integers, which is required by the XXTEA algorithm). As a result of these
 measures, you can encrypt not only texts, but also any binary bytes of any
 length.
 
-> **Note:** This implementation uses a **non-standard** 4-byte block PKCS#7
-> padding instead of the conventional 8-byte or 16-byte block. For inputs
-> shorter than 4 bytes, a non-standard hack pads an extra 4 bytes (producing
-> pad values 5–8) to satisfy XXTEA's 2-word minimum. This means the output is
-> **NOT** compatible with other XXTEA implementations. Pass `padding: false`
-> for raw XXTEA (requires data length ≥ 8 and multiple of 4).
+> **Note:** The default (`:pkcs7_4_min8`) is **not** standard 4-byte PKCS#7.
+> For inputs shorter than 4 bytes it pads an extra 4 bytes (pad values 5–8)
+> to satisfy XXTEA's 2-word minimum. Pass `padding: :pkcs7_8` for standard
+> 8-byte PKCS#7 (compatible with Python xxteang), or `padding: false` for
+> raw XXTEA (requires data length ≥ 8 and multiple of 4).
 
 ## Installation
 
@@ -87,9 +87,11 @@ They are stored on the object and used by every `encrypt`, `decrypt`,
 `encrypt_hex`, and `decrypt_hex` call:
 
 ```ruby
-c = XXTEA.new(key)                       # rounds=0, padding=true
-c = XXTEA.new(key, rounds: 64)           # override rounds
-c = XXTEA.new(key, padding: false)       # disable padding
+c = XXTEA.new(key)                         # rounds=0, padding=:pkcs7_4_min8
+c = XXTEA.new(key, rounds: 64)             # override rounds
+c = XXTEA.new(key, padding: false)         # disable padding
+c = XXTEA.new(key, padding: :pkcs7_8)      # 8-byte PKCS#7
+c = XXTEA.new(key, padding: :length_word_suffix)  # length word + zero padding
 c = XXTEA.new(key, padding: false, rounds: 42)
 ```
 
@@ -103,19 +105,43 @@ s == XXTEA.decrypt([hexenc].pack("H*"), key)  # => true
 
 ## Padding
 
-Padding is enabled by default, using a **non-standard 4-byte block PKCS#7**
-scheme. The pad byte value is `4 - (data.bytesize & 3)` (range 1–4), plus an
-extra 4 bytes when the input is shorter than 4 bytes to meet XXTEA's 2-word
-minimum (producing pad values 5–8).
+`padding` accepts a scheme name, so more paddings can be added later:
 
-Because padding always adds at least one byte, encrypting an 8-byte input
-produces a 12-byte ciphertext. This is incompatible with other XXTEA
-implementations that use a standard block size or skip padding altogether.
-Use `padding: false` for raw, unpadded XXTEA.
+| Value | Meaning |
+| --- | --- |
+| `true` or `:pkcs7_4_min8` (default) | 4-byte PKCS#7-like, padded to at least 8 bytes. Compatible with Python xxtea. Not standard 4-byte PKCS#7 |
+| `:pkcs7_8` | Standard **8-byte** PKCS#7, compatible with Python xxteang |
+| `:length_word_suffix` | Zero-pad to a 4-byte boundary, then append one little-endian `uint32` with the original length. Cocos Creator JSC files using this layout can be decrypted. Compatible with Python xxtea 6.2.0 |
+| `:length_word_prefix` | Prepend one little-endian `uint32` with the original length, then zero-pad the data to a 4-byte boundary. Compatible with Python xxtea 6.2.0 |
+| `false` or `:none` | No padding (raw XXTEA) |
+
+`XXTEA::PKCS7_4_MIN8`, `XXTEA::PKCS7_8`, `XXTEA::LENGTH_WORD_PREFIX`, and
+`XXTEA::LENGTH_WORD_SUFFIX` are aliases for the symbols.
+
+The default `:pkcs7_4_min8` scheme uses pad byte value `4 - (data.bytesize & 3)`
+(range 1–4), plus an extra 4 bytes when the input is shorter than 4 bytes
+to meet XXTEA's 2-word minimum (producing pad values 5–8). Standard 4-byte
+PKCS#7 never uses pad values 5–8. Because padding always adds at least one
+byte, encrypting an 8-byte input produces a 12-byte ciphertext.
+
+8-byte PKCS#7 uses pad byte value `8 - (data.bytesize & 7)` (range 1–8).
+Encrypting an 8-byte input produces a 16-byte ciphertext.
+
+The length-word schemes store the original byte length in a little-endian
+`uint32` word, so the plaintext length must fit in 32 bits (`RangeError`
+otherwise). The data is zero-padded to a 4-byte boundary around that word:
+the length word is the last word for `:length_word_suffix` and the first
+word for `:length_word_prefix`. Because of XXTEA's 2-word minimum, empty
+input produces an 8-byte ciphertext in either scheme.
 
 ```ruby
 XXTEA.decrypt_hex(XXTEA.encrypt_hex("", key), key)   # => ""
 XXTEA.decrypt_hex(XXTEA.encrypt_hex(" ", key), key)  # => " "
+
+XXTEA.encrypt("12345678", key).bytesize                                 # => 12  (:pkcs7_4_min8)
+XXTEA.encrypt("12345678", key, padding: :pkcs7_8).bytesize              # => 16  (:pkcs7_8)
+XXTEA.encrypt("12345678", key, padding: :length_word_suffix).bytesize   # => 12
+XXTEA.encrypt("12345678", key, padding: :length_word_prefix).bytesize   # => 12
 ```
 
 You can disable padding by setting `padding: false`.
@@ -196,7 +222,8 @@ XXTEA.new("k" * 16, rounds: 2**32)
 
 ## Compatibility
 
-- Compatible with [Python xxtea](https://github.com/ifduyue/xxtea) (same padding, endianness, and rounds).
+- Compatible with [Python xxtea](https://github.com/ifduyue/xxtea) 6.2.0: all five padding schemes (`:pkcs7_4_min8`, `:pkcs7_8`, `:length_word_prefix`, `:length_word_suffix`, `:none`), endianness, and rounds.
+- `padding: :pkcs7_8` is compatible with [Python xxteang](https://github.com/ifduyue/xxteang).
 - The `XXTEA.encrypt(data, key)` / `XXTEA.decrypt(data, key)` class methods remain compatible with gem 0.0.1 for valid ciphertext. `XXTEA` is now a class rather than a module, and invalid padding raises `ArgumentError` instead of returning stripped bytes.
 
 ## Releasing

data/ext/xxtea/xxtea.c

@@ -22,9 +22,13 @@
  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
- * Ciphertext is compatible with the Python xxtea package
+ * Default ciphertext is compatible with the Python xxtea package
  * (https://github.com/ifduyue/xxtea): little-endian 32-bit words and
- * non-standard 4-byte PKCS#7 padding (pad+4 for inputs shorter than 4 bytes).
+ * :pkcs7_4_min8 padding (4-byte PKCS#7-like, pad+4 for inputs shorter than 4 bytes).
+ * padding: :pkcs7_8 uses 8-byte PKCS#7, compatible with Python xxteang
+ * (https://github.com/ifduyue/xxteang); :length_word_prefix and
+ * :length_word_suffix prepend/append a little-endian uint32 length word
+ * with zero padding, matching Python xxtea 6.2.0.
  */
 
 #include "ruby.h"
@@ -45,6 +49,11 @@
 
 static ID id_padding;
 static ID id_rounds;
+static ID id_none;
+static ID id_pkcs7_4_min8;
+static ID id_pkcs7_8;
+static ID id_length_word_prefix;
+static ID id_length_word_suffix;
 static VALUE cXXTEA;
 
 typedef struct {
@@ -122,36 +131,84 @@ bytes2longs(const char *in, long inlen, uint32_t *out, int padding)
     long i, nwords;
     int pad;
     const unsigned char *s = (const unsigned char *)in;
+    uint32_t *dst = out;
+
+    if (padding == 2) {
+        /* uint32 store, not memcpy(&inlen): 64-bit would copy the high half. */
+        out[0] = (uint32_t)inlen;
+        dst = out + 1;
+    }
 
     nwords = inlen >> 2;
     for (i = 0; i < nwords; i++) {
 #if XXTEA_LITTLE_ENDIAN
-        memcpy(&out[i], s + 4 * i, 4);
+        memcpy(&dst[i], s + 4 * i, 4);
 #else
         const unsigned char *p = s + 4 * i;
-        out[i] = (uint32_t)p[0] | ((uint32_t)p[1] << 8) |
+        dst[i] = (uint32_t)p[0] | ((uint32_t)p[1] << 8) |
                  ((uint32_t)p[2] << 16) | ((uint32_t)p[3] << 24);
 #endif
     }
 
+    i = nwords << 2;
+
+    if (padding == 1 || padding == 2) {
+        /* XXTEA needs two words, so empty input gets an extra zero word. */
+        uint32_t w = 0;
+        int shift = 0;
+        for (; i < inlen; i++, shift += 8) {
+            w |= (uint32_t)s[i] << shift;
+        }
+        if ((inlen & 3) != 0) {
+            dst[nwords] = w;
+            nwords++;
+        }
+        if (nwords < 1) {
+            dst[nwords++] = 0;
+        }
+        if (padding == 1) {
+            dst[nwords] = (uint32_t)inlen;
+        }
+        return;
+    }
+
+    if (padding == 8) {
+        /*
+         * 8-byte PKCS#7 (xxteang): pad = 8 - (len & 7), range 1-8.
+         * Completes the partial word, then adds a whole extra pad word
+         * unless the length is 4 mod 8.
+         */
+        uint32_t w = 0;
+        int r = (int)(inlen & 3);
+        int shift = 0;
+        uint32_t pw;
+        for (; i < inlen; i++, shift += 8) {
+            w |= (uint32_t)s[i] << shift;
+        }
+        pad = 8 - (int)(inlen & 7);
+        pw = (uint32_t)pad * 0x01010101u;
+        w |= pw & (~0u << (8 * r));
+        out[nwords] = w;
+        if ((inlen & 4) == 0) {
+            out[nwords + 1] = pw;
+        }
+        return;
+    }
+
     /*
-     * Assemble the final partial word (0-3 leftover data bytes plus
-     * padding) in a local and store it with a single write, so every
-     * output byte is written exactly once and the caller does not need
-     * to zero the buffer first.  Inputs shorter than 4 bytes are padded
-     * to two words, which also guarantees the minimum XXTEA block size.
+     * :pkcs7_4_min8 (default): 4-byte PKCS#7-like, but inputs shorter
+     * than 4 bytes are padded to two words (pad values 5-8) for XXTEA's
+     * 2-word minimum.  Not standard PKCS#7.
      */
-    i = nwords << 2;
-    if (padding || (inlen & 3) != 0) {
+    if (padding == 4 || (inlen & 3) != 0) {
         uint32_t w = 0;
         int r = (int)(inlen & 3);
         int shift = 0;
         for (; i < inlen; i++, shift += 8) {
             w |= (uint32_t)s[i] << shift;
         }
-        if (padding) {
+        if (padding == 4) {
             pad = 4 - r;
-            /* Ensure XXTEA always has at least two 32-bit words. */
             if (inlen < 4) {
                 pad += 4;
             }
@@ -190,8 +247,41 @@ longs2bytes(const uint32_t *in, long inlen, char *out, int padding)
 
     outlen = inlen * 4;
 
-    /* 4-byte PKCS#7-style unpadding. */
-    if (padding) {
+    if (padding == 1 || padding == 2) {
+        int prefix = padding == 2;
+        long n = outlen - 4;
+        long leftover, pad_from, pad_to;
+        uint32_t m32;
+        if (prefix) {
+            m32 = (uint32_t)s[0] | ((uint32_t)s[1] << 8) |
+                  ((uint32_t)s[2] << 16) | ((uint32_t)s[3] << 24);
+        }
+        else {
+            m32 = (uint32_t)s[n] | ((uint32_t)s[n + 1] << 8) |
+                  ((uint32_t)s[n + 2] << 16) | ((uint32_t)s[n + 3] << 24);
+        }
+        if ((size_t)m32 > (size_t)n) {
+            return -1;
+        }
+        leftover = n - (long)m32;
+        pad_from = prefix ? 4 + (long)m32 : (long)m32;
+        pad_to = prefix ? outlen : n;
+        /* leftover 4 is the empty 2-word case; otherwise 0-3 zero-pad bytes. */
+        if (leftover > 3 && !(m32 == 0 && leftover == 4)) {
+            return -1;
+        }
+        for (i = pad_from; i < pad_to; i++) {
+            if (s[i] != 0) {
+                return -1;
+            }
+        }
+        if (prefix && m32 != 0) {
+            memmove(s, s + 4, (size_t)m32);
+        }
+        outlen = (long)m32;
+    }
+    /* PKCS#7-style unpadding (4-byte or 8-byte; pad values 1-8). */
+    else if (padding) {
         pad = s[outlen - 1];
         outlen -= pad;
 
@@ -266,13 +356,56 @@ parse_rounds(VALUE obj)
     return NUM2UINT(obj);
 }
 
+/* 0 = none, 1 = :length_word_suffix, 2 = :length_word_prefix,
+ * 4 = :pkcs7_4_min8 (default), 8 = :pkcs7_8. */
+static int
+parse_padding(VALUE obj)
+{
+    ID id;
+
+    if (obj == Qfalse) {
+        return 0;
+    }
+    if (obj == Qtrue) {
+        return 4;
+    }
+    if (RB_TYPE_P(obj, T_STRING)) {
+        obj = rb_str_intern(obj);
+    }
+    if (!SYMBOL_P(obj)) {
+        rb_raise(rb_eTypeError,
+                 "padding must be true, false, :none, :pkcs7_4_min8, "
+                 ":pkcs7_8, :length_word_prefix, or :length_word_suffix");
+    }
+    id = SYM2ID(obj);
+    if (id == id_none) {
+        return 0;
+    }
+    if (id == id_length_word_suffix) {
+        return 1;
+    }
+    if (id == id_length_word_prefix) {
+        return 2;
+    }
+    if (id == id_pkcs7_4_min8) {
+        return 4;
+    }
+    if (id == id_pkcs7_8) {
+        return 8;
+    }
+    rb_raise(rb_eArgError,
+             "unknown padding %+"PRIsVALUE" (expected :none, :pkcs7_4_min8, "
+             ":pkcs7_8, :length_word_prefix, or :length_word_suffix)",
+             obj);
+}
+
 static void
 parse_opts(VALUE opts, int *padding, unsigned int *rounds)
 {
     ID kwids[2];
     VALUE kwvals[2];
 
-    *padding = 1;
+    *padding = 4;
     *rounds = 0;
     if (NIL_P(opts)) {
         return;
@@ -283,7 +416,7 @@ parse_opts(VALUE opts, int *padding, unsigned int *rounds)
     rb_get_kwargs(opts, kwids, 0, 2, kwvals);
 
     if (kwvals[0] != Qundef) {
-        *padding = RTEST(kwvals[0]);
+        *padding = parse_padding(kwvals[0]);
     }
     if (kwvals[1] != Qundef) {
         *rounds = parse_rounds(kwvals[1]);
@@ -315,7 +448,33 @@ encrypt_impl(VALUE data, const char key[16], int padding, unsigned int rounds)
                  "Data length must be a multiple of 4 bytes and must not be less than 8 bytes");
     }
 
-    alen = data_len < 4 ? 2 : (data_len >> 2) + padding;
+    if (padding == 8) {
+        if (data_len > LONG_MAX - 8) {
+            rb_raise(rb_eRangeError, "data too large");
+        }
+        alen = ((data_len & ~7L) + 8) >> 2;
+    }
+    else if (padding == 4) {
+        alen = data_len < 4 ? 2 : (data_len >> 2) + 1;
+    }
+    else if (padding == 1 || padding == 2) {
+        /* The length word is a uint32, so the plaintext length must fit. */
+#if LONG_MAX > 2147483647L
+        if (data_len > 0xFFFFFFFFL) {
+            rb_raise(rb_eRangeError, "data too large");
+        }
+#endif
+        if (data_len > LONG_MAX - 4) {
+            rb_raise(rb_eRangeError, "data too large");
+        }
+        alen = (data_len >> 2) + ((data_len & 3) != 0 ? 1 : 0) + 1;
+        if (alen < 2) {
+            alen = 2;
+        }
+    }
+    else {
+        alen = data_len >> 2;
+    }
     if (alen > INT_MAX || alen > LONG_MAX / 4) {
         rb_raise(rb_eRangeError, "data too large");
     }
@@ -501,7 +660,7 @@ xxtea_alloc(VALUE klass)
     xxtea_cipher_t *cipher;
     VALUE obj = TypedData_Make_Struct(klass, xxtea_cipher_t, &xxtea_cipher_type, cipher);
     memset(cipher, 0, sizeof(*cipher));
-    cipher->padding = 1;
+    cipher->padding = 4;
     cipher->rounds = 0;
     return obj;
 }
@@ -556,7 +715,11 @@ xxtea_inspect(VALUE self)
     xxtea_cipher_t *cipher = xxtea_get(self);
     return rb_sprintf("#<%s:%p padding=%s rounds=%u>",
                       rb_obj_classname(self), (void *)self,
-                      cipher->padding ? "true" : "false", cipher->rounds);
+                      cipher->padding == 0 ? "false" :
+                      cipher->padding == 1 ? "length_word_suffix" :
+                      cipher->padding == 2 ? "length_word_prefix" :
+                      cipher->padding == 4 ? "pkcs7_4_min8" : "pkcs7_8",
+                      cipher->rounds);
 }
 
 void
@@ -566,6 +729,11 @@ Init_xxtea(void)
 
     id_padding = rb_intern("padding");
     id_rounds = rb_intern("rounds");
+    id_none = rb_intern("none");
+    id_pkcs7_4_min8 = rb_intern("pkcs7_4_min8");
+    id_pkcs7_8 = rb_intern("pkcs7_8");
+    id_length_word_prefix = rb_intern("length_word_prefix");
+    id_length_word_suffix = rb_intern("length_word_suffix");
 
     cXXTEA = rb_define_class("XXTEA", rb_cObject);
     rb_define_alloc_func(cXXTEA, xxtea_alloc);
@@ -581,4 +749,9 @@ Init_xxtea(void)
     rb_define_method(cXXTEA, "encrypt_hex", xxtea_encrypt_hex, 1);
     rb_define_method(cXXTEA, "decrypt_hex", xxtea_decrypt_hex, 1);
     rb_define_method(cXXTEA, "inspect", xxtea_inspect, 0);
+
+    rb_define_const(cXXTEA, "PKCS7_4_MIN8", ID2SYM(id_pkcs7_4_min8));
+    rb_define_const(cXXTEA, "PKCS7_8", ID2SYM(id_pkcs7_8));
+    rb_define_const(cXXTEA, "LENGTH_WORD_PREFIX", ID2SYM(id_length_word_prefix));
+    rb_define_const(cXXTEA, "LENGTH_WORD_SUFFIX", ID2SYM(id_length_word_suffix));
 }

data/lib/xxtea/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class XXTEA
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xxtea
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Yue Du
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies: []
 description: |
   XXTEA implemented as a Ruby C extension. Ciphertext is compatible with the