Uprading to tc Server 10.1.55 changed prefix from "pbkdf2" to "pbkdf2-v2"

Products

• VMware Tanzu Spring Runtime

Issue/Introduction

You upgraded to tc Server runtime to v10.1.55+ and you noticed when you try to encode passwords. The prefix changed from"pbkdf2" to "pbkdf2-v2", see sample below:

$ ./tcserver  encode  --passphrase ######### --value ####### instance1
Loading tc Server configuration properties from: /home/was/.tc-server/tc-server-10.1.properties
Generating random passphrase and setting it in catalina.properties
pbkdf2-v2://#######

Resolution

This change of prefix is expected when upgrading to tc version 10.1.55A+. If they have any values encoded with pbkdf2 and the passphrase is used they can be decoded by tc Server version 10.1.55.A. 

pbkdf2-v2 was introduced to fix some flaws in the original implementation.  Both work, however, We would recommend updating to v2 once the documentation is updated.  Here is a brief summary of the differences:

pbkdf2-v2 introduces several significant security and structural improvements over the original pbkdf2 (v1).

Here are the primary differences between the two versions:

1. Key Derivation Algorithm

v1: Uses PBKDF2WithHmacSHA1 by default to derive the keys from the passphrase.
v2: Upgrades to PBKDF2WithHmacSHA256 by default, which is a stronger hashing algorithm.

2. Iteration Count

v1: Defaults to 65,535 iterations. The iteration count is not stored in the encrypted string; it relies on the system default or a system property at decryption time.
v2: Defaults to 100,000 iterations. More importantly, v2 embeds the iteration count directly into the payload. This allows the iteration count to be increased in the future without breaking backward compatibility for older v2 passwords.

3. Initialization Vector (IV)

v1: Uses a static, empty legacy IV (an array of zeros) for the AES cipher. This is a cryptographic weakness because reusing the same IV with the same key can leak information about the ciphertext.
v2: Generates a secure, random Initialization Vector (IV) for every single encryption and embeds the IV (and its length) into the payload.

4. HMAC Coverage (Tamper Resistance)

v1: Calculates the HMAC (authentication code) only over the ciphertext. This means an attacker could theoretically tamper with the salts without invalidating the HMAC signature.
v2: Calculates the HMAC over the entire payload (Version + Iterations + Encryption Salt + HMAC Salt + IV Length + IV + Ciphertext). This ensures that absolutely no part of the encoded string can be tampered with.

5. Payload Structure

Because of the additions in v2, the underlying byte arrays look very different before they are Base64 encoded:

v1 Payload: [Encryption Salt] + [HMAC Salt] + [Ciphertext] + [HMAC]
v2 Payload: [Version=2] + [Iterations] + [Encryption Salt] + [HMAC Salt] + [IV Length] + [IV] + [Ciphertext] + [HMAC]

In summary, pbkdf2-v2 is a much more robust implementation that fixes cryptographic flaws in v1 (like the static IV and limited HMAC scope) while future-proofing the encoding by making the iteration count dynamic.