org.bouncycastle.crypto.params

Class SM9EncMasterPrivateKeyParameters

java.lang.Object

org.bouncycastle.crypto.params.AsymmetricKeyParameter

org.bouncycastle.crypto.params.SM9EncMasterPrivateKeyParameters

All Implemented Interfaces:

javax.security.auth.Destroyable, CipherParameters, SM9EncUserKeyParametersGenerator

public class SM9EncMasterPrivateKeyParameters
extends AsymmetricKeyParameter
implements javax.security.auth.Destroyable, SM9EncUserKeyParametersGenerator

SM9 encryption master private key ke (GM/T 0044.4-2016). Held by the KGC; derives the master public key P_pub-e = [ke]P1 and users' encryption private keys de = [t2]P2 from their identities.

Field Summary

Fields

Modifier and Type	Field and Description
static byte	HID The encryption private-key generation function identifier hid, 0x03 - the value used by the GM/T 0044.5-2016 Annex C/D worked examples (and, note, by the official English edition's Annex B key exchange example).
static byte	HID_EXCHANGE The key-exchange private-key generation function identifier hid, 0x02, as used by the Chinese edition of the GM/T 0044.5-2016 Annex B worked example (the official English edition of the same annex chose 0x03 - see the hid note on HID; the KGC's published choice governs).

Constructor Summary

Constructors

Constructor and Description
SM9EncMasterPrivateKeyParameters(java.math.BigInteger ke)

Method Summary

Modifier and Type	Method and Description
void	destroy() Destroy this object, dropping its reference to the master secret ke.
static SM9EncMasterPrivateKeyParameters	fromEncoded(byte[] enc)
SM9EncPrivateKeyParameters	generateExchangeKey(byte[] identity) Derive the key-exchange private key of the user identified by identity (GM/T 0044.3-2016), under HID_EXCHANGE - the hid the standard's Chinese-edition worked example publishes for the exchange.
SM9EncPrivateKeyParameters	generateExchangeKey(byte[] identity, byte hid) Derive the key-exchange private key of the user identified by identity under an explicit hid, for a KGC whose published exchange hid is not HID_EXCHANGE (the official English edition's Annex B example runs the exchange under 0x03, on its own master key).
SM9EncPrivateKeyParameters	generateUserKey(byte[] identity, byte hid) Derive the KEM / decryption private key de = [t2]P2 (a G2 point) for the user identified by identity under the given hid (GM/T 0044.4-2016): t1 = H1(identity||hid, N) + ke; if t1 = 0 the master key must be regenerated; otherwise t2 = ke*t1^-1.
byte[]	getEncoded() The master private key ke as a 32-byte big-endian scalar.
SM9EncMasterPublicKeyParameters	getPublicKeyParameters()
boolean	isDestroyed()

Methods inherited from class org.bouncycastle.crypto.params.AsymmetricKeyParameter

isPrivate

Methods inherited from class java.lang.Object

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

Field Detail

HID

public static final byte HID

The encryption private-key generation function identifier hid, 0x03 - the value used by the GM/T 0044.5-2016 Annex C/D worked examples (and, note, by the official English edition's Annex B key exchange example).

hid is not fixed by the standard: GM/T 0044.3-2016 defines it as the "identifier of the encryption private key generating function, denoted by one byte", which the KGC chooses and publishes. These constants are the two identifier values the published GM/T 0044 examples use, and the only values generateUserKey(byte[], byte) accepts.

See Also:

Constant Field Values

HID_EXCHANGE

public static final byte HID_EXCHANGE

The key-exchange private-key generation function identifier hid, 0x02, as used by the Chinese edition of the GM/T 0044.5-2016 Annex B worked example (the official English edition of the same annex chose 0x03 - see the hid note on HID; the KGC's published choice governs).

Key exchange runs on the encryption master key: a single master key may serve both key exchange and KEM / public-key encryption. That sharing is the design of GM/T 0044, not a caller-side shortcut - GM/T 0044.3-2016 6.1 names the protocol's own inputs as the encryption public key P_pub-e and the encryption private key de. The hid is folded into the derivation (t1 = H1(identity || hid, N) + ke, see generateUserKey(byte[], byte)), so when the KGC publishes distinct hids for the two functions the user keys obtained under them are as independent as keys for two different identities. If the two collide on one master key, a user's exchange key and decryption key are the identical G2 point - and since the exchange pairs that point with a peer-supplied value, any peer would gain the pairing oracle on de that the KEM's security argument assumes away. The API therefore derives the two usages as distinct key objects (generateUserKey(byte[], byte) vs generateExchangeKey(byte[])) which the consumers mutually reject; a KGC whose lifecycles differ should prefer separate master keys outright, as the GM/T 0044.5 worked examples themselves do.

See Also:

Constant Field Values

Constructor Detail

SM9EncMasterPrivateKeyParameters

public SM9EncMasterPrivateKeyParameters(java.math.BigInteger ke)

Method Detail

getPublicKeyParameters

public SM9EncMasterPublicKeyParameters getPublicKeyParameters()

getEncoded

public byte[] getEncoded()

The master private key ke as a 32-byte big-endian scalar.

fromEncoded

public static SM9EncMasterPrivateKeyParameters fromEncoded(byte[] enc)

generateUserKey

public SM9EncPrivateKeyParameters generateUserKey(byte[] identity,
                                                  byte hid)

Derive the KEM / decryption private key de = [t2]P2 (a G2 point) for the user identified by identity under the given hid (GM/T 0044.4-2016): t1 = H1(identity||hid, N) + ke; if t1 = 0 the master key must be regenerated; otherwise t2 = ke*t1^-1. The derived key records the hid it was formed under. For a key-exchange user key use generateExchangeKey(byte[]) - the two usages are kept on separate keys and the consumers enforce it.

Specified by:

generateUserKey in interface SM9EncUserKeyParametersGenerator

Parameters:

identity - the user's identity.

hid - the private-key generation function identifier the KGC chose, HID or HID_EXCHANGE.

Returns:

the user's private key.

generateExchangeKey

public SM9EncPrivateKeyParameters generateExchangeKey(byte[] identity)

Derive the key-exchange private key of the user identified by identity (GM/T 0044.3-2016), under HID_EXCHANGE - the hid the standard's Chinese-edition worked example publishes for the exchange.

generateExchangeKey

public SM9EncPrivateKeyParameters generateExchangeKey(byte[] identity,
                                                      byte hid)

Derive the key-exchange private key of the user identified by identity under an explicit hid, for a KGC whose published exchange hid is not HID_EXCHANGE (the official English edition's Annex B example runs the exchange under 0x03, on its own master key).

destroy

public void destroy()

Destroy this object, dropping its reference to the master secret ke.

As BigInteger is immutable the secret value cannot be zeroized in place; destruction drops the reference and marks the key destroyed, after which getEncoded() and generateUserKey(byte[], byte) throw IllegalStateException. The public key parameters remain available.

Specified by:

destroy in interface javax.security.auth.Destroyable

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface javax.security.auth.Destroyable