Add AES Key Wrap (RFC 3394) Cipher support

.github/workflows/windows-vs.yml

@@ -299,7 +299,7 @@ jobs:
           $content = Get-Content $userSettingsPath -Raw
           Write-Output "Original file size: $($content.Length) characters"
 
-          $newDefines = "#define WOLFSSL_KEY_GEN`n#define HAVE_CRL`n#define OPENSSL_ALL`n#define ERROR_QUEUE_PER_THREAD`n#define HAVE_THREAD_LS`n#define WOLFSSL_SHA224`n#define HAVE_FFDHE_2048`n#define HAVE_FFDHE_3072`n#define HAVE_FFDHE_4096`n#define HAVE_FFDHE_Q`n#define WOLFSSL_VALIDATE_FFC_IMPORT`n#define WOLFSSL_PUBLIC_MP`n`n"
+          $newDefines = "#define WOLFSSL_KEY_GEN`n#define HAVE_CRL`n#define OPENSSL_ALL`n#define ERROR_QUEUE_PER_THREAD`n#define HAVE_THREAD_LS`n#define WOLFSSL_SHA224`n#define HAVE_FFDHE_2048`n#define HAVE_FFDHE_3072`n#define HAVE_FFDHE_4096`n#define HAVE_FFDHE_Q`n#define WOLFSSL_VALIDATE_FFC_IMPORT`n#define WOLFSSL_PUBLIC_MP`n#define WOLFSSL_AES_DIRECT`n#define HAVE_AES_KEYWRAP`n`n"
 
           # Try multiple possible insertion points
           $insertPoints = @(

IDE/Android/app/src/main/cpp/CMakeLists.txt

@@ -67,6 +67,7 @@ if ("${WOLFSSL_PKG_TYPE}" MATCHES "normal")
                 -DECC_TIMING_RESISTANT -DTFM_TIMING_RESISTANT
                 -DWC_RSA_BLINDING -DWC_RSA_NO_PADDING -DWC_RSA_PSS -DWOLFSSL_PSS_LONG_SALT
                 -DHAVE_AESGCM -DGCM_TABLE_4BIT -DHAVE_CTS -DWOLFSSL_AES_DIRECT
+                -DHAVE_AES_KEYWRAP
                 -DHAVE_CHACHA -DHAVE_POLY1305
                 -DHAVE_DH_DEFAULT_PARAMS -DHAVE_FFDHE_2048
                 -DHAVE_HASHDRBG -DHAVE_HKDF
@@ -182,7 +183,7 @@ elseif("${WOLFSSL_PKG_TYPE}" MATCHES "fipsready")
                 -DHAVE_AESGCM -DGCM_TABLE_4BIT -DWOLFSSL_AESGCM_STREAM -DHAVE_AESCCM
                 -DWOLFSSL_AES_COUNTER -DWOLFSSL_CMAC -DWOLFSSL_AES_OFB -DWOLFSSL_AES_CFB
                 -DWOLFSSL_AES_XTS -DWOLFSSL_AESXTS_STREAM -DWOLFSSL_AES_DIRECT
-                -DHAVE_AES_ECB -DHAVE_AES_KEYWRAP -DWOLFSSL_AES_XTS -DHAVE_AES_KEYWRAP
+                -DHAVE_AES_ECB -DHAVE_AES_KEYWRAP
 
                 -DHAVE_ED25519 -DHAVE_ED25519_KEY_IMPORT -DHAVE_ED448 -DHAVE_ED448_KEY_IMPORT
                 -DWOLFSSL_ED448_STREAMING_VERIFY
@@ -365,6 +366,7 @@ add_library(wolfcryptjni SHARED
         ${wolfcryptjni_DIR}/jni/jni_aesecb.c
         ${wolfcryptjni_DIR}/jni/jni_aesgcm.c
         ${wolfcryptjni_DIR}/jni/jni_aesgmac.c
+        ${wolfcryptjni_DIR}/jni/jni_aeskeywrap.c
         ${wolfcryptjni_DIR}/jni/jni_aesofb.c
         ${wolfcryptjni_DIR}/jni/jni_asn.c
         ${wolfcryptjni_DIR}/jni/jni_chacha.c

IDE/WIN/README.md

@@ -147,8 +147,15 @@ section titled `/* Configuration */`:
 #define HAVE_FFDHE_Q
 #define WOLFSSL_VALIDATE_FFC_IMPORT
 #define WOLFSSL_PUBLIC_MP
+#define WOLFSSL_AES_DIRECT
+#define HAVE_AES_KEYWRAP
 ```
 
+`WOLFSSL_AES_DIRECT` and `HAVE_AES_KEYWRAP` enable AES Key Wrap (RFC 3394),
+used by the wolfJCE `AESWrap` / `AES/KW/NoPadding` Cipher services. They can
+be left out if AES Key Wrap is not needed, in which case those services are
+not registered.
+
 If also building wolfSSL JNI/JSSE, additional defines may be needed. Please
 reference the Windows build documentation for wolfSSL JNI/JSSE if so.
 

IDE/WIN/wolfcryptjni.vcxproj

@@ -43,6 +43,7 @@
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesEcb.h" />
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesGcm.h" />
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesGmac.h" />
+    <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesKeyWrap.h" />
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesOfb.h" />
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_Asn.h" />
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_Chacha.h" />
@@ -83,6 +84,7 @@
     <ClCompile Include="..\..\jni\jni_aesecb.c" />
     <ClCompile Include="..\..\jni\jni_aesgcm.c" />
     <ClCompile Include="..\..\jni\jni_aesgmac.c" />
+    <ClCompile Include="..\..\jni\jni_aeskeywrap.c" />
     <ClCompile Include="..\..\jni\jni_aesofb.c" />
     <ClCompile Include="..\..\jni\jni_asn.c" />
     <ClCompile Include="..\..\jni\jni_chacha.c" />

IDE/WIN/wolfcryptjni.vcxproj.filters

@@ -27,6 +27,9 @@
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesCtr.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesCts.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesEcb.h">
       <Filter>Header Files</Filter>
     </ClInclude>
@@ -36,6 +39,9 @@
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesGmac.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesKeyWrap.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
     <ClInclude Include="..\..\jni\include\com_wolfssl_wolfcrypt_AesOfb.h">
       <Filter>Header Files</Filter>
     </ClInclude>
@@ -149,6 +155,9 @@
     <ClCompile Include="..\..\jni\jni_aesgmac.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\..\jni\jni_aeskeywrap.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="..\..\jni\jni_aesofb.c">
       <Filter>Source Files</Filter>
     </ClCompile>

README.md

@@ -73,6 +73,16 @@ recommended configuration for SHA2 parameter-set support (the
 `SLH-DSA-SHA2-128f` default lives in the SHA2 family). Without SLH-DSA, wolfJCE
 compiles and runs normally but the SLH-DSA services are not registered.
 
+**Note on AES Key Wrap (RFC 3394 / NIST SP 800-38F KW):** AES Key Wrap support
+is **not** enabled by `--enable-jni` alone. To use the `AESWrap`
+(`AES/KW/NoPadding`, `AESWrap_128/192/256`, `AES/KW/PKCS5Padding`) `Cipher`
+services, add `--enable-aeskeywrap` to the native wolfSSL `./configure` line,
+or use `--enable-all` (or `--enable-pkcs7`) which include it. wolfSSL FIPS
+v6/v7 and FIPS Ready builds enable it by default. Without it, wolfJCE compiles
+and runs normally but the AES Key Wrap services are not registered. Only
+RFC 3394 KW is provided. AES Key Wrap with Padding (RFC 5649 KWP, `AESWrapPad`)
+is not available in native wolfSSL. See README\_JCE.md for usage notes.
+
 **wolfSSL Standard Build**:
 ```
 $ cd wolfssl-x.x.x

README_JCE.md

@@ -165,6 +165,21 @@ The JCE provider currently supports the following algorithms:
         AES/OFB/NoPadding
             Aliases: AES_128/OFB/NoPadding, AES_192/OFB/NoPadding, AES_256/OFB/NoPadding
             OIDs: 2.16.840.1.101.3.4.1.3, 2.16.840.1.101.3.4.1.23, 2.16.840.1.101.3.4.1.43
+        AESWrap
+            Aliases: AES/KW/NoPadding, AESKW
+        AESWrap_128
+            Alias: AES_128/KW/NoPadding
+            OID: 2.16.840.1.101.3.4.1.5
+        AESWrap_192
+            Alias: AES_192/KW/NoPadding
+            OID: 2.16.840.1.101.3.4.1.25
+        AESWrap_256
+            Alias: AES_256/KW/NoPadding
+            OID: 2.16.840.1.101.3.4.1.45
+        AES/KW/PKCS5Padding
+        AES_128/KW/PKCS5Padding
+        AES_192/KW/PKCS5Padding
+        AES_256/KW/PKCS5Padding
         DESede/CBC/NoPadding
         RSA
         RSA/ECB/PKCS1Padding
@@ -447,6 +462,59 @@ Interoperability with the JDK reference implementation:
 See `examples/provider/MlKemExample.java` for a complete encapsulate /
 decapsulate and key encoding example.
 
+### AES Key Wrap (RFC 3394) Notes
+
+wolfJCE provides AES Key Wrap (RFC 3394 / NIST SP 800-38F "KW") as a `Cipher`
+service when native wolfSSL is built with `--enable-aeskeywrap` (also pulled
+in by `--enable-all` and `--enable-pkcs7`, and on by default for FIPS v6/v7
+builds). `--enable-jni` alone does not enable it. When it is not compiled in,
+the services below are not registered.
+
+- `AESWrap`, registered aliases `AES/KW/NoPadding` and `AESKW`. The JDK 8
+  transformation forms `AESWrap/ECB/NoPadding` and `AESWrap/ECB/PKCS5Padding`
+  also resolve, through the JCE mode/padding fallback rather than as aliases.
+- `AESWrap_128`, `AESWrap_192`, `AESWrap_256` (aliases
+  `AES_128/KW/NoPadding`, ...) lock the KEK size and carry the NIST OIDs
+  `2.16.840.1.101.3.4.1.5`, `.25`, `.45`. A KEK of any other size is rejected
+  with `InvalidKeyException`.
+- `AES/KW/PKCS5Padding` (and `AES_128/192/256/KW/PKCS5Padding`), which
+  PKCS#5 pads the input to the 8-byte semi-block size before wrapping. Use
+  this to wrap keys whose encodings are not a multiple of 8 bytes, such as
+  X.509 public keys and PKCS#8 private keys via `Cipher.PUBLIC_KEY` /
+  `Cipher.PRIVATE_KEY`. This matches SunJCE on JDK 21 and later. JDK 17 SunJCE
+  pads `AES/KW/PKCS5Padding` to 16-byte blocks instead, so PKCS#5-padded
+  wrapped keys do not interoperate with JDK 17.
+
+Usage details:
+
+- All four opmodes are supported: `WRAP_MODE`/`UNWRAP_MODE` for `wrap()`/
+  `unwrap()`, and `ENCRYPT_MODE`/`DECRYPT_MODE` for `doFinal()` over raw
+  data (`update()` buffers, all output comes from `doFinal()`).
+- Input to wrap must be at least 16 bytes and a multiple of 8 bytes, and
+  wrapped input to unwrap at least 24 bytes and a multiple of 8
+  (`IllegalBlockSizeException` otherwise). Wrapped output is 8 bytes longer
+  than the input. `getBlockSize()` returns 8 (the semi-block size).
+- The 8-byte "IV" is the RFC 3394 integrity check value, not a nonce. With
+  no parameters the default `A6A6A6A6A6A6A6A6` is used and wolfJCE never
+  generates a random IV. An alternative value may be given as an 8-byte
+  `IvParameterSpec` (or an `AlgorithmParameters("AES")` holding one) and
+  must then be supplied to the unwrapping side as well. `getIV()` and
+  `getParameters()` return `null` unless an IV was set explicitly, in which
+  case `getParameters()` is an `AlgorithmParameters("AES")` holding the
+  8-byte IV, as with SunJCE 17+. That object can be passed to another
+  provider's `Cipher.init()` (which uses `getParameterSpec()`). Its DER
+  encoding, `04 08 <iv>`, is the same one SunJCE produces, but SunJCE's own
+  DER decoder only accepts 16-byte AES IVs, where wolfJCE decodes both.
+- `unwrap()` failures (bad length, wrong KEK, wrong IV, corrupted data, bad
+  padding) throw `InvalidKeyException`. In `DECRYPT_MODE`, an integrity check
+  failure throws `BadPaddingException` and a bad length throws
+  `IllegalBlockSizeException`.
+- Only RFC 3394 KW is available. AES Key Wrap with Padding (RFC 5649 KWP,
+  `AESWrapPad` / `AES/KWP/NoPadding`) is not implemented in native wolfSSL.
+
+See `examples/provider/AesKeyWrapExample.java` for a complete wrap / unwrap
+example.
+
 ### SecureRandom.getInstanceStrong()
 
 When registered as the highest priority security provider, wolfJCE will provide
@@ -866,6 +934,24 @@ This descrepancy should not be an issue, since `doFinal()` returns the
 actual number of bytes written to the output buffer, so applications can use
 that to know the true output size in the output buffer returned.
 
+#### AES Key Wrap `DECRYPT_MODE` Integrity Failure Exception
+
+When an `AESWrap` / `AES/KW/NoPadding` Cipher in `DECRYPT_MODE` detects an
+integrity check failure, wolfJCE throws `BadPaddingException("Integrity check
+failed")`, consistent with its other authenticated modes and with Bouncy
+Castle. SunJCE (JDK 17+) throws `IllegalBlockSizeException` with the same
+message in this case. `UNWRAP_MODE` is unaffected: both providers throw
+`InvalidKeyException` for every `unwrap()` failure.
+
+`getParameters()` on an AES Key Wrap Cipher returns `null` unless an IV was
+set explicitly (JDK 8 and Bouncy Castle behavior), whereas SunJCE 17+ returns
+`AlgorithmParameters` holding the default IV. This keeps
+`otherCipher.init(mode, key, wolfCipher.getParameters())` working against
+providers that accept no AES Key Wrap parameters at all. With an explicit IV
+both providers return `AlgorithmParameters("AES")` with the same `04 08 <iv>`
+DER encoding; `AlgorithmParameters.getInstance("AES", "SunJCE")` rejects that
+encoding (even its own), while wolfJCE accepts both 8 and 16 byte IVs.
+
 #### PKIXRevocationChecker `PREFER_CRLS` Check Order
 
 When using `PKIXRevocationChecker` with the `PREFER_CRLS` option and fallback