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)
static SM9EncMasterPrivateKeyParameters	fromEncoded(byte[] enc, SM9EncMasterPublicKeyParameters publicKey) Rebuild a master private key and check it against the master public key its KGC published.
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.
SM9EncPrivateKeyParameters	generateUserKey(byte[] identity, byte hid, int usage) Derive the KEM / decryption private key of the user identified by identity under the given hid, as generateUserKey(byte[], byte) does, declared for one of the two.
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 defaults here; the explicit-hid entry points take whatever value a KGC publishes, the one exception being that a KEM or decryption key may not be derived under HID_EXCHANGE, which names the other function.

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)

fromEncoded

public static SM9EncMasterPrivateKeyParameters fromEncoded(byte[] enc,
                                                           SM9EncMasterPublicKeyParameters publicKey)

Rebuild a master private key and check it against the master public key its KGC published. A key decoded from its scalar alone always agrees with the public key it derives from that scalar, so a stale or substituted scalar - still 32 bytes, still in [1, N-1] - imports as a well-formed key pair that is simply not the KGC's, and every user key it then issues is consistent with that wrong public key, and imports under it; comparing against the published one is the check the import of a user key cannot make.

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.

The hid is the KGC's published choice and may be any one byte, with one exception: HID_EXCHANGE names the key exchange's generation function, and a KEM / decryption key derived under it would be the identical G2 point as the exchange key of the same identity - the collision the separate usages exist to prevent (see HID_EXCHANGE), reached without the consumers' usage check ever being consulted. A KGC publishing neither of these two values separates its own functions by publishing two values of its own.

Usage warning: the key this returns should be used for the KEM or for public-key encryption, but not for both. A KGC offering both functions publishes a separate hid for each and calls this once per function, as it already does for the key exchange, so that the two keys are distinct.

Specified by:

generateUserKey in interface SM9EncUserKeyParametersGenerator

Parameters:

identity - the user's identity.

hid - the private-key generation function identifier the KGC chose for the encryption function, HID. HID_EXCHANGE names the key exchange's own function and is refused here - a key derived under it is that identity's exchange key, which the two usages are kept apart to stop a KEM or decryption key from also being. A KGC offering both the KEM and public-key encryption publishes a further value of its own for one of them, so that no identity's key serves both.

Returns:

the user's private key.

generateUserKey

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

Derive the KEM / decryption private key of the user identified by identity under the given hid, as generateUserKey(byte[], byte) does, declared for one of the two. A key declared for SM9EncPrivateKeyParameters.USAGE_KEM or SM9EncPrivateKeyParameters.USAGE_DECRYPTION is refused for the other on every use, its first included; SM9EncPrivateKeyParameters.USAGE_UNSPECIFIED declares neither - see SM9EncPrivateKeyParameters.recordUsage(int).

Parameters:

identity - the user's identity.

hid - the hid the KGC publishes for the function the key serves.

usage - SM9EncPrivateKeyParameters.USAGE_KEM, SM9EncPrivateKeyParameters.USAGE_DECRYPTION or SM9EncPrivateKeyParameters.USAGE_UNSPECIFIED.

Returns:

the user's 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).

A master key that issues exchange keys under HID issues them as the identical points as its KEM / decryption keys, so it must serve the exchange alone - which is how the example that needs this overload is written. Where one master key serves both functions the KGC publishes two hids, and the no-argument generateExchangeKey(byte[]) is the call to make.

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