SM2 cryptographic algorithms

[athoelke]

The Crypto API already has definitions for the SM3 hash algorithm and a SM4 block cipher key type.

CSTC also defines the SM2 public-key algorithms for digital signature, key exchange, and asymmetric encryption.

The digital signature (DSA) and key exchange (KE) algorithms for SM2 require additional context information. Currently the Crypto API does not have a mechanism to provide this context data. This underlying issue is shared with some form of the EdDSA signature algorithm (see #18).

SM2 requires an identity-based value in the signature generation/verification and key exchange, referred to as Z_A in the specifications. Z_A is an SM3 hash of the identity of A (bit length ENTL_A and identity string ID_A), the curve domain parameters (a, b, x_G and y_G, for which there is a single set of recommended values), and A's public key (x_A and y_A).

In both DSA and KE, the domain parameters are fixed by the key/family, and the public key values are available to the Crypto API implementation for both parties. However, the identity string is not - RFC 8998 describes two values that must be used as the identity string for its uses of SM2. As a result, the Crypto API needs to enable an identity string to be provided as part of the signature, verification and key exchange operations.

API options

• We could encapsulate the ID with the key-pair and public-key objects, although we would need a mechanism to specify this when creating a key. This is logically reasonable, as this is the 'identity' associated with the key.
• We could extend the signature and key agreement APIs (e.g. provide additional variants) to take this additional context data. (This might also be useful for supporting EdDSA with non-trivial context).
• We could implement a multi-part signature API and provide the signing keys identity information using a dedicated function for this operation.

References:

Public key cryptographic algorithm SM2 based on elliptic curves
Part 2: Digital signature algorithm
Part 3: Key exchange protocol
Part 4: Public key encryption algorithm
Part 5: Parameter definition

These are now paid-for documents from CSTC. The algorithms are also documented in an IETF draft: https://datatracker.ietf.org/doc/draft-shen-sm2-ecdsa/02/

[athoelke]

SM2-DSA is required as part of the ShangMi (SM) ciphersuite for TLS 1.3, according to RFC 8998.

In the RFC it describes the 'identity strings' (e.g. ID_A) to be used for signatures used within the protocol, and those expected to be used in the Certificate messages. These are not actual identity values, but application-specific values. This suggests that adding a 'context' parameter to the signature API would be the most appropriate design choice - and this would also enables the addition of context parameters for EdDSA (if and when required).