org.cloudburstmc.protocol.bedrock.util

Class EncryptionUtils

java.lang.Object

org.cloudburstmc.protocol.bedrock.util.EncryptionUtils

public final class EncryptionUtils
extends java.lang.Object

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ALGORITHM_TYPE

Method Summary

Modifier and Type	Method and Description
static javax.crypto.Cipher	createCipher(boolean gcm, boolean encrypt, javax.crypto.SecretKey key)
static java.lang.String	createHandshakeJwt(java.security.KeyPair serverKeyPair, byte[] token) Create handshake JWS used in the ServerToClientHandshakePacket which completes the encryption handshake.
static java.lang.String	createHandshakeJwt(java.security.KeyPair serverKeyPair, byte[] token, java.lang.String signedToken) Create handshake JWS used in the ServerToClientHandshakePacket which completes the encryption handshake.
static java.security.KeyPair	createKeyPair() Create EC key pair to be used for handshake and encryption
static java.lang.String	extractServerTokenFromEduTokenChain(java.lang.String eduTokenChain) Extract the inner server token from an Education Edition login JWT (EduTokenChain).
static byte[]	generateRandomToken() Generate 16 bytes of random data for the handshake token using a SecureRandom
static java.security.PublicKey	getEducationPublicKey() Microsoft's public key used to verify Education Edition server tokens.
static java.security.interfaces.ECPublicKey	getMojangPublicKey() Mojang's public key used to verify the JWT during login.
static javax.crypto.SecretKey	getSecretKey(java.security.PrivateKey localPrivateKey, java.security.PublicKey remotePublicKey, byte[] token) Generate the secret key used to encrypt the connection
static java.security.interfaces.ECPublicKey	parseKey(java.lang.String b64) Generate EC public key from base 64 encoded string
static ChainValidationResult	validateChain(java.util.List<java.lang.String> chain)
static EducationTokenValidationResult	validateEducationPayload(java.lang.String eduTokenChain) Validate the Education Edition login JWT end-to-end.
static EducationTokenValidationResult	validateEducationToken(java.lang.String serverToken) Validate an education server token signed by Microsoft's MESS service.
static ChainValidationResult	validatePayload(org.cloudburstmc.protocol.bedrock.data.auth.AuthPayload payload)
static ChainValidationResult	validateToken(org.cloudburstmc.protocol.bedrock.data.auth.AuthType type, java.lang.String token)
static byte[]	verifyClientData(java.lang.String clientDataJwt, java.security.PublicKey identityPublicKey)
static byte[]	verifyClientData(java.lang.String clientDataJwt, java.lang.String identityPublicKey)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALGORITHM_TYPE

public static final java.lang.String ALGORITHM_TYPE

See Also:

Constant Field Values

Method Detail

parseKey

public static java.security.interfaces.ECPublicKey parseKey(java.lang.String b64)
                                                     throws java.security.NoSuchAlgorithmException,
                                                            java.security.spec.InvalidKeySpecException

Generate EC public key from base 64 encoded string

Parameters:

b64 - base 64 encoded key

Returns:

key generated

Throws:

java.security.NoSuchAlgorithmException - runtime does not support the EC key spec

java.security.spec.InvalidKeySpecException - input does not conform with EC key spec

createKeyPair

public static java.security.KeyPair createKeyPair()

Create EC key pair to be used for handshake and encryption

Returns:

EC KeyPair

verifyClientData

public static byte[] verifyClientData(java.lang.String clientDataJwt,
                                      java.lang.String identityPublicKey)
                               throws java.security.NoSuchAlgorithmException,
                                      java.security.spec.InvalidKeySpecException,
                                      org.jose4j.lang.JoseException

Throws:

java.security.NoSuchAlgorithmException

java.security.spec.InvalidKeySpecException

org.jose4j.lang.JoseException

verifyClientData

public static byte[] verifyClientData(java.lang.String clientDataJwt,
                                      java.security.PublicKey identityPublicKey)
                               throws org.jose4j.lang.JoseException

Throws:

org.jose4j.lang.JoseException

validatePayload

public static ChainValidationResult validatePayload(org.cloudburstmc.protocol.bedrock.data.auth.AuthPayload payload)
                                             throws org.jose4j.lang.JoseException,
                                                    java.security.NoSuchAlgorithmException,
                                                    java.security.spec.InvalidKeySpecException,
                                                    org.jose4j.jwt.consumer.InvalidJwtException

Throws:

org.jose4j.lang.JoseException

java.security.NoSuchAlgorithmException

java.security.spec.InvalidKeySpecException

org.jose4j.jwt.consumer.InvalidJwtException

validateChain

public static ChainValidationResult validateChain(java.util.List<java.lang.String> chain)
                                           throws org.jose4j.lang.JoseException,
                                                  java.security.NoSuchAlgorithmException,
                                                  java.security.spec.InvalidKeySpecException

Throws:

org.jose4j.lang.JoseException

java.security.NoSuchAlgorithmException

java.security.spec.InvalidKeySpecException

validateToken

public static ChainValidationResult validateToken(org.cloudburstmc.protocol.bedrock.data.auth.AuthType type,
                                                  java.lang.String token)
                                           throws org.jose4j.jwt.consumer.InvalidJwtException,
                                                  org.jose4j.lang.JoseException

Throws:

org.jose4j.jwt.consumer.InvalidJwtException

org.jose4j.lang.JoseException

getSecretKey

public static javax.crypto.SecretKey getSecretKey(java.security.PrivateKey localPrivateKey,
                                                  java.security.PublicKey remotePublicKey,
                                                  byte[] token)
                                           throws java.security.InvalidKeyException

Generate the secret key used to encrypt the connection

Parameters:

localPrivateKey - local private key

remotePublicKey - remote public key

token - token generated or received from the server

Returns:

secret key used to encrypt connection

Throws:

java.security.InvalidKeyException - keys provided are not EC spec

createHandshakeJwt

public static java.lang.String createHandshakeJwt(java.security.KeyPair serverKeyPair,
                                                  byte[] token)
                                           throws org.jose4j.lang.JoseException

Create handshake JWS used in the ServerToClientHandshakePacket which completes the encryption handshake.

Parameters:

serverKeyPair - used to sign the JWT

token - salt for the encryption handshake

Returns:

signed JWS object

Throws:

org.jose4j.lang.JoseException - invalid key pair provided

createHandshakeJwt

public static java.lang.String createHandshakeJwt(java.security.KeyPair serverKeyPair,
                                                  byte[] token,
                                                  java.lang.String signedToken)
                                           throws org.jose4j.lang.JoseException

Create handshake JWS used in the ServerToClientHandshakePacket which completes the encryption handshake.

For Education Edition clients, the signedToken parameter must contain the education server token. Education clients verify this token during the handshake and reject the connection if it is missing or invalid.

Parameters:

serverKeyPair - used to sign the JWT

token - salt for the encryption handshake

signedToken - education server token, or null for standard Bedrock

Returns:

signed JWS object

Throws:

org.jose4j.lang.JoseException - invalid key pair provided

generateRandomToken

public static byte[] generateRandomToken()

Generate 16 bytes of random data for the handshake token using a SecureRandom

Returns:

16 byte token

getMojangPublicKey

public static java.security.interfaces.ECPublicKey getMojangPublicKey()

Mojang's public key used to verify the JWT during login.

Returns:

Mojang's public EC key

getEducationPublicKey

public static java.security.PublicKey getEducationPublicKey()

Microsoft's public key used to verify Education Edition server tokens.

Returns:

Education RSA public key

validateEducationPayload

public static EducationTokenValidationResult validateEducationPayload(java.lang.String eduTokenChain)
                                                               throws org.jose4j.lang.JoseException,
                                                                      java.security.NoSuchAlgorithmException,
                                                                      java.security.InvalidKeyException

Validate the Education Edition login JWT end-to-end.

Education Edition clients send an outer self-signed JWT (the EduTokenChain) in place of the standard Bedrock identity chain. Its payload carries a single chain field containing the MESS-signed server token that actually proves player identity.

This method plays the same role for Education Edition that validatePayload(org.cloudburstmc.protocol.bedrock.data.auth.AuthPayload) plays for standard Bedrock. It is the top-level entry point: it unwraps the outer education JWT via extractServerTokenFromEduTokenChain(java.lang.String) and then verifies the inner server token via validateEducationToken(java.lang.String).

Parameters:

eduTokenChain - the outer education login JWT as a compact serialization string

Returns:

the validation result; EducationTokenValidationResult.Status.INVALID is returned if the JWT has no extractable server token

Throws:

org.jose4j.lang.JoseException - the outer JWT is malformed or its payload is not valid JSON

java.security.NoSuchAlgorithmException - SHA256withRSA is not available

java.security.InvalidKeyException - the education public key is not a valid RSA key

extractServerTokenFromEduTokenChain

public static java.lang.String extractServerTokenFromEduTokenChain(java.lang.String eduTokenChain)
                                                            throws org.jose4j.lang.JoseException

Extract the inner server token from an Education Edition login JWT (EduTokenChain).

The EduTokenChain payload contains a chain field whose value is the pipe-separated MESS-signed server token (tenantId|oid|expiry|signatureHex). This method peels the JWT structure and returns that value without verifying anything.

Security: the outer JWT's signature is intentionally NOT verified here. Education login JWTs are self-signed with an ephemeral client key, so verifying the outer signature only proves the client signed its own JWT and establishes nothing about player identity. The inner chain field is the load-bearing credential and carries its own MESS RSA signature, which is verified by validateEducationToken(java.lang.String). Any caller that extracts additional fields from the outer JWT must treat those fields as untrusted unless a separate verification path is established for them.

Parameters:

eduTokenChain - the outer education login JWT as a compact serialization string

Returns:

the inner server token, or null if the input is null/empty or the chain field is absent or not a string

Throws:

org.jose4j.lang.JoseException - the input is not a valid JWT or its payload is not valid JSON

validateEducationToken

public static EducationTokenValidationResult validateEducationToken(java.lang.String serverToken)
                                                             throws java.security.NoSuchAlgorithmException,
                                                                    java.security.InvalidKeyException

Validate an education server token signed by Microsoft's MESS service.

Token format: tenantId|oid|expiry|signatureHex where the signature is RSA PKCS#1 v1.5 SHA-256 over tenantId|oid|expiry as UTF-8 bytes.

This method plays the same role for Education Edition that validateChain(List) plays for standard Bedrock. It verifies player identity against EDUCATION_PUBLIC_KEY in the same manner that validateChain verifies identity against MOJANG_PUBLIC_KEY.

This inner MESS signature is the sole cryptographic anchor for education player identity. Other apparent verification points in the education login flow do not provide identity proof:

• The Bedrock login chain for education clients is a single self-signed JWT with an ephemeral per-session EC P-384 key. No Mojang root signs it, so ChainValidationResult.signed() returns false and the chain's claims prove only that the client holds the private half of a public key they themselves generated.
• The chain's extraData.identity is a client-generated per-session UUID, unrelated to the Entra Object ID and unanchored to any external authority.
• The EduTokenChain JWT that wraps this token in the login packet is itself signed with another client-generated key whose public half is embedded inline via the x5u header, not fetched from a remote trust anchor. Verifying the outer signature proves only that the client signed its own wrapper. An attacker who captures a valid inner token can re-wrap it with a fresh ephemeral key and produce a structurally valid outer JWT without Microsoft's involvement.

Only the inner signature over tenantId|oid|expiry binds the token to a fixed Microsoft-controlled trust anchor (EDUCATION_PUBLIC_KEY). Verifying it is the only mechanism that attests to player identity against a party the client cannot impersonate.

Parameters:

serverToken - the pipe-separated education server token

Returns:

validation result with status, tenant ID, OID, and expiry

Throws:

java.security.NoSuchAlgorithmException - SHA256withRSA is not available

java.security.InvalidKeyException - the education public key is not a valid RSA key

createCipher

public static javax.crypto.Cipher createCipher(boolean gcm,
                                               boolean encrypt,
                                               javax.crypto.SecretKey key)