org.bouncycastle.crypto.params

Class SM9EncPrivateKeyParameters

java.lang.Object

org.bouncycastle.crypto.params.AsymmetricKeyParameter

org.bouncycastle.crypto.params.SM9EncPrivateKeyParameters

All Implemented Interfaces:

javax.security.auth.Destroyable, CipherParameters

public class SM9EncPrivateKeyParameters
extends AsymmetricKeyParameter
implements javax.security.auth.Destroyable

A user's SM9 encryption private key de = [t2]P2, a point of G2 (GM/T 0044.4-2016). Carries the master public key and the user's identity, both needed to decapsulate/decrypt (the identity is part of the KDF input), and the hid the KGC derived the key under, which the key exchange relies on to form the peer's Q point.

A key additionally records which usage it was derived for - KEM/decryption (SM9EncMasterPrivateKeyParameters.generateUserKey(byte[], byte)) or key exchange (SM9EncMasterPrivateKeyParameters.generateExchangeKey(byte[])) - and the consumers enforce it: the key exchange evaluates the pairing e(R, de) on a peer-supplied point R, so a key that also decapsulates would hand any exchange peer the very pairing oracle on de that the KEM's security argument assumes is unavailable. Keeping the two usages on separate keys (distinct hid, or distinct master keys as the GM/T 0044.5 examples do) is what makes sharing the master key sound.

A key rebuilt from its encoding (fromEncoded(byte[], org.bouncycastle.crypto.params.SM9EncMasterPublicKeyParameters, byte[], byte) / fromEncodedExchangeKey(byte[], org.bouncycastle.crypto.params.SM9EncMasterPublicKeyParameters, byte[])) carries the usage the importer names - the point encoding itself does not record which usage the KGC derived it for - so an importer must claim the usage the key was actually derived under.

Method Summary

Modifier and Type	Method and Description
void	destroy() Destroy this object, dropping its reference to the private point de and zeroizing the identity.
static SM9EncPrivateKeyParameters	fromEncoded(byte[] enc, SM9EncMasterPublicKeyParameters masterPublicKey, byte[] identity, byte hid) Rebuild a KEM / decryption user key from its bare point encoding.
static SM9EncPrivateKeyParameters	fromEncodedExchangeKey(byte[] enc, SM9EncMasterPublicKeyParameters masterPublicKey, byte[] identity) Rebuild a key-exchange user key from its bare point encoding, under SM9EncMasterPrivateKeyParameters.HID_EXCHANGE - the import path for an exchange party that received its key from the KGC rather than deriving it in-process via SM9EncMasterPrivateKeyParameters.generateExchangeKey(byte[]).
static SM9EncPrivateKeyParameters	fromEncodedExchangeKey(byte[] enc, SM9EncMasterPublicKeyParameters masterPublicKey, byte[] identity, byte hid) Rebuild a key-exchange user key from its bare point encoding under an explicit hid, for a KGC whose published exchange hid is not SM9EncMasterPrivateKeyParameters.HID_EXCHANGE (the official English edition's GM/T 0044.5 Annex B example runs the exchange under 0x03).
byte[]	getEncoded() The user's encryption private key point de of G2 in uncompressed form (0x04 || x || y, 129 bytes).
byte	getHid() The private-key generation function identifier hid this key was derived under - the KGC's published choice, not sensitive.
byte[]	getIdentity()
SM9EncMasterPublicKeyParameters	getMasterPublicKey()
SM9G2Point	getPrivatePoint()
boolean	isDestroyed()
boolean	isExchangeKey() Whether this key was derived for the key exchange (SM9EncMasterPrivateKeyParameters.generateExchangeKey(byte[])) rather than for KEM / decryption.

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

Method Detail

getPrivatePoint

public SM9G2Point getPrivatePoint()

getMasterPublicKey

public SM9EncMasterPublicKeyParameters getMasterPublicKey()

getHid

public byte getHid()

The private-key generation function identifier hid this key was derived under - the KGC's published choice, not sensitive.

isExchangeKey

public boolean isExchangeKey()

Whether this key was derived for the key exchange (SM9EncMasterPrivateKeyParameters.generateExchangeKey(byte[])) rather than for KEM / decryption. SM9KeyExchange accepts only exchange keys; SM9KEMExtractor and SM9 decryption accept only non-exchange keys.

getIdentity

public byte[] getIdentity()

getEncoded

public byte[] getEncoded()

The user's encryption private key point de of G2 in uncompressed form (0x04 || x || y, 129 bytes). The master public key, identity and hid are not part of this encoding; supply them via fromEncoded(byte[], org.bouncycastle.crypto.params.SM9EncMasterPublicKeyParameters, byte[], byte) to rebuild a usable key (the identity is part of the decryption KDF input, the hid drives the key exchange's Q-point computation).

fromEncoded

public static SM9EncPrivateKeyParameters fromEncoded(byte[] enc,
                                                     SM9EncMasterPublicKeyParameters masterPublicKey,
                                                     byte[] identity,
                                                     byte hid)

Rebuild a KEM / decryption user key from its bare point encoding. For a key the KGC derived for the key exchange use fromEncodedExchangeKey(byte[], org.bouncycastle.crypto.params.SM9EncMasterPublicKeyParameters, byte[]) instead - the usage is the importer's claim (see the class note), and the consumers enforce whichever is claimed.

fromEncodedExchangeKey

public static SM9EncPrivateKeyParameters fromEncodedExchangeKey(byte[] enc,
                                                                SM9EncMasterPublicKeyParameters masterPublicKey,
                                                                byte[] identity)

Rebuild a key-exchange user key from its bare point encoding, under SM9EncMasterPrivateKeyParameters.HID_EXCHANGE - the import path for an exchange party that received its key from the KGC rather than deriving it in-process via SM9EncMasterPrivateKeyParameters.generateExchangeKey(byte[]).

fromEncodedExchangeKey

public static SM9EncPrivateKeyParameters fromEncodedExchangeKey(byte[] enc,
                                                                SM9EncMasterPublicKeyParameters masterPublicKey,
                                                                byte[] identity,
                                                                byte hid)

Rebuild a key-exchange user key from its bare point encoding under an explicit hid, for a KGC whose published exchange hid is not SM9EncMasterPrivateKeyParameters.HID_EXCHANGE (the official English edition's GM/T 0044.5 Annex B example runs the exchange under 0x03).

destroy

public void destroy()

Destroy this object, dropping its reference to the private point de and zeroizing the identity.

As the point's coordinates are immutable they cannot be zeroized in place; destruction drops the reference and marks the key destroyed, after which getPrivatePoint(), getEncoded() and getIdentity() throw IllegalStateException. The master public key remains available.

Specified by:

destroy in interface javax.security.auth.Destroyable

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface javax.security.auth.Destroyable