Class SM9EncMasterPrivateKeyParameters
- All Implemented Interfaces:
Destroyable, CipherParameters, SM9EncUserKeyParametersGenerator
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final byteThe 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 final byteThe 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 onHID; the KGC's published choice governs). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoiddestroy()Destroy this object, dropping its reference to the master secret ke.fromEncoded(byte[] enc) fromEncoded(byte[] enc, SM9EncMasterPublicKeyParameters publicKey) Rebuild a master private key and check it against the master public key its KGC published.generateExchangeKey(byte[] identity) Derive the key-exchange private key of the user identified byidentity(GM/T 0044.3-2016), underHID_EXCHANGE- the hid the standard's Chinese-edition worked example publishes for the exchange.generateExchangeKey(byte[] identity, byte hid) Derive the key-exchange private key of the user identified byidentityunder an explicit hid, for a KGC whose published exchange hid is notHID_EXCHANGE(the official English edition's Annex B example runs the exchange under 0x03, on its own master key).generateUserKey(byte[] identity, byte hid) Derive the KEM / decryption private key de = [t2]P2 (a G2 point) for the user identified byidentityunder 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.generateUserKey(byte[] identity, byte hid, int usage) Derive the KEM / decryption private key of the user identified byidentityunder the given hid, asgenerateUserKey(byte[], byte)does, declared for one of the two.byte[]The master private key ke as a 32-byte big-endian scalar.booleanMethods inherited from class AsymmetricKeyParameter
isPrivate
-
Field Details
-
HID
public static final byte HIDThe 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:
-
HID_EXCHANGE
public static final byte HID_EXCHANGEThe 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 onHID; 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)vsgenerateExchangeKey(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:
-
-
Constructor Details
-
SM9EncMasterPrivateKeyParameters
-
-
Method Details
-
getPublicKeyParameters
-
getEncoded
public byte[] getEncoded()The master private key ke as a 32-byte big-endian scalar. -
fromEncoded
-
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
Derive the KEM / decryption private key de = [t2]P2 (a G2 point) for the user identified byidentityunder 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 usegenerateExchangeKey(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_EXCHANGEnames 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 (seeHID_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:
generateUserKeyin interfaceSM9EncUserKeyParametersGenerator- Parameters:
identity- the user's identity.hid- the private-key generation function identifier the KGC chose for the encryption function,HID.HID_EXCHANGEnames 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
Derive the KEM / decryption private key of the user identified byidentityunder the given hid, asgenerateUserKey(byte[], byte)does, declared for one of the two. A key declared forSM9EncPrivateKeyParameters.USAGE_KEMorSM9EncPrivateKeyParameters.USAGE_DECRYPTIONis refused for the other on every use, its first included;SM9EncPrivateKeyParameters.USAGE_UNSPECIFIEDdeclares neither - seeSM9EncPrivateKeyParameters.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_DECRYPTIONorSM9EncPrivateKeyParameters.USAGE_UNSPECIFIED.- Returns:
- the user's key.
-
generateExchangeKey
Derive the key-exchange private key of the user identified byidentity(GM/T 0044.3-2016), underHID_EXCHANGE- the hid the standard's Chinese-edition worked example publishes for the exchange. -
generateExchangeKey
Derive the key-exchange private key of the user identified byidentityunder an explicit hid, for a KGC whose published exchange hid is notHID_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
HIDissues 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-argumentgenerateExchangeKey(byte[])is the call to make. -
destroy
public void destroy()Destroy this object, dropping its reference to the master secret ke.As
BigIntegeris immutable the secret value cannot be zeroized in place; destruction drops the reference and marks the key destroyed, after whichgetEncoded()andgenerateUserKey(byte[], byte)throwIllegalStateException. The public key parameters remain available.- Specified by:
destroyin interfaceDestroyable
-
isDestroyed
public boolean isDestroyed()- Specified by:
isDestroyedin interfaceDestroyable
-