API 参考

常用接口已经自动导入 gmalg 命名空间, 可以直接使用, 点击下方链接快速跳转至说明.

继续向下阅读 gmalg 中涉及的所有主要接口及其参数说明.

gmalg.sm2

SM2 Algorithm Implementation Module.

gmalg.sm2.SM2Core(ecdlp, hash_cls, rnd_fn=None)

Bases: SMCoreBase

SM2 Core Algorithms.

Attributes:
  • ecdlp (ECDLP) –

    ECDLP used in SM2.
Parameters:
  • ecdlp (ECDLP) –

    ECDLP used in SM2.

  • hash_cls (Type[Hash]) –

    Hash class used in SM2.

  • rnd_fn (Callable[[int], int], default: None ) –

    Random function used to generate k-bit random number, default to secrets.randbits.

gmalg.sm2.SM2Core.generate_pk(sk)

Generate public key by secret key.

Parameters:
  • sk (int) –

    Secret key.
Returns:
  • EcPoint( EcPoint ) –

    Point of public key.

gmalg.sm2.SM2Core.generate_keypair()

Generate key pair.

Returns:
  • int( int ) –

    Secret key.

  • EcPoint( EcPoint ) –

    Public key.

gmalg.sm2.SM2Core.verify_pk(pk)

Verify if a public key is valid.

Parameters:
  • pk (EcPoint) –

    Public key point.
Returns:
  • bool( bool ) –

    Whether valid.

gmalg.sm2.SM2Core.entity_info(uid, pk)

Generate other entity information bytes.

Parameters:
  • uid (bytes) –

    User ID.

  • pk (EcPoint) –

    Public key point.
Returns:
  • bytes( bytes ) –

    User entity information.
Raises:

gmalg.sm2.SM2Core.sign(message, sk, uid, pk=None)

Generate signature on the message.

Parameters:
  • message (bytes) –

    Message to be signed.

  • sk (int) –

    Secret key.

  • uid (bytes) –

    User ID.

  • pk (EcPoint, default: None ) –

    Public key
Returns:
  • int( int ) –

    r.

  • int( int ) –

    s.

gmalg.sm2.SM2Core.verify(message, r, s, uid, pk)

Verify the signature on the message.

Parameters:
  • message (bytes) –

    Message to be verified.

  • r (int) –

    r

  • s (int) –

    s

  • uid (bytes) –

    User ID.

  • pk (EcPoint) –

    Public key.
Returns:
  • bool( bool ) –

    Whether OK.

gmalg.sm2.SM2Core.encrypt(plain, pk)

Encrypt.

Parameters:
  • plain (bytes) –

    Plain text to be encrypted.

  • pk (EcPoint) –

    Public key.
Returns:
  • EcPoint( EcPoint ) –

    C1, kG point.

  • bytes( bytes ) –

    C2, cipher.

  • bytes( bytes ) –

    C3, hash value of cipher.
Raises:
Note

The return order is C1, C2, C3, NOT C1, C3, C2.

gmalg.sm2.SM2Core.decrypt(C1, C2, C3, sk)

Decrypt.

Parameters:
  • C1 (EcPoint) –

    kG point.

  • C2 (bytes) –

    Cipher.

  • C3 (bytes) –

    Hash value.

  • sk (int) –

    Secret key.
Returns:
  • bytes( bytes ) –

    Plain text.
Raises:

gmalg.sm2.SM2Core.begin_key_exchange(sk)

Generate data to begin key exchange.

Parameters:
  • sk (int) –

    Secret key.
Returns:
  • EcPoint( EcPoint ) –

    Random point.

  • int( int ) –

    t

gmalg.sm2.SM2Core.get_secret_point(t, R, pk)

Generate same secret point as another user.

Parameters:
  • t (int) –

    Generated from begin_key_exchange

  • R (EcPoint) –

    Random point from another user.

  • pk (EcPoint) –

    Public key of another user.
Returns:
  • EcPoint( EcPoint ) –

    The same secret point as another user.
Raises:

gmalg.sm2.SM2Core.generate_skey(klen, S, uid_init, pk_init, uid_resp, pk_resp)

Generate secret key of klen bytes as same as another user.

Parameters:
  • klen (int) –

    key length in bytes to generate.

  • S (EcPoint) –

    Secret point.

  • uid_init (bytes) –

    User ID bytes of initiator.

  • pk_init (EcPoint) –

    Public key of initiator.

  • uid_resp (bytes) –

    User ID bytes of responder.

  • pk_resp (EcPoint) –

    Public key of responder.
Returns:
  • bytes( bytes ) –

    Secret key of klen bytes.

gmalg.sm2.SM2(sk=None, uid=None, pk=None, *, rnd_fn=None, pc_mode=PC_MODE.RAW)

SM2 Algorithm.

Parameters:
  • sk (bytes, default: None ) –

    Secret key.

  • pk (bytes, default: None ) –

    Public key.

  • uid (bytes, default: None ) –

    User ID.

  • rnd_fn (Callable[[int], int], default: None ) –

    Random function used to generate k-bit random number, default to secrets.randbits.

  • pc_mode (PC_MODE, default: RAW ) –

    Point compress mode used for generated data, no effects on the data to be parsed.

gmalg.sm2.SM2.can_sign: bool property

Whether can do sign.

gmalg.sm2.SM2.can_verify: bool property

Whether can do verify.

gmalg.sm2.SM2.can_encrypt: bool property

Whether can do encrypt.

gmalg.sm2.SM2.can_decrypt: bool property

Whether can do decrypt.

gmalg.sm2.SM2.can_exchange_key: bool property

Whether can do key exchange.

gmalg.sm2.SM2.generate_pk(sk)

Generate public key from secret key.

Parameters:
  • sk (bytes) –

    Secret key.
Returns:
  • bytes( bytes ) –

    Public key.

gmalg.sm2.SM2.generate_keypair()

Generate key pair.

Returns:
  • bytes( bytes ) –

    Secret key

  • bytes( bytes ) –

    Public key.

gmalg.sm2.SM2.verify_pk(pk)

Verify if a public key is valid.

Parameters:
  • pk (bytes) –

    public key.
Returns:
  • bool( bool ) –

    Whether valid.

gmalg.sm2.SM2.sign(message)

Generate signature on message.

Returns:
Raises:

gmalg.sm2.SM2.verify(message, r, s)

Verify a message and it's signature.

Parameters:
  • message (bytes) –

    Message to be signed.

  • r (bytes) –

    r of signature.

  • s (bytes) –

    s of signature.
Returns:
  • bool( bool ) –

    Whether OK.
Raises:

gmalg.sm2.SM2.encrypt(plain)

Encrypt.

Parameters:
  • plain (bytes) –

    plain text to be encrypted.
Returns:
  • bytes( bytes ) –

    Cipher data.
Raises:

gmalg.sm2.SM2.decrypt(cipher)

Decrypt.

Parameters:
  • cipher (bytes) –

    Cipher data.
Returns:
  • bytes( bytes ) –

    Plain data.
Raises:

gmalg.sm2.SM2.begin_key_exchange()

Begin key exchange.

Returns:
  • bytes( bytes ) –

    Random point, will be sent to another user.

  • int( int ) –

    t, will be used in next step.
Raises:

gmalg.sm2.SM2.end_key_exchange(klen, t, R, uid, pk, mode)

End key exchange and get the secret key bytes.

Parameters:
  • klen (int) –

    Length of secret key in bytes to generate.

  • t (int) –

    t value of self.

  • R (bytes) –

    Random point from another user.

  • uid (bytes) –

    ID of another user.

  • pk (bytes) –

    Public key of another user.

  • mode (KEYXCHG_MODE) –

    Key exchange mode, initiator or responder.
Returns:
  • bytes( bytes ) –

    Secret key of klen bytes.
Raises:

gmalg.sm2.point_to_bytes(P, mode)

Convert point to bytes.

Parameters:
  • P (EcPoint) –

    Point to be converted.

  • mode (PC_MODE) –

    : Compress mode.
Returns:
  • bytes( bytes ) –

    Converted point bytes.
Raises:

gmalg.sm2.bytes_to_point(b)

Convert bytes to point.

Parameters:
  • b (bytes) –

    Point bytes.
Returns:
  • EcPoint( EcPoint ) –

    Point converted.
Raises:

gmalg.sm3

SM3 Algorithm Implementation Module.

gmalg.sm3.SM3()

Bases: Hash

SM3 Algorithm.

gmalg.sm3.SM3.max_msg_length() classmethod

Get maximum message length in bytes.

gmalg.sm3.SM3.hash_length() classmethod

Get output hash value length in bytes.

gmalg.sm3.SM3.update(data)

Update internal state.

Parameters:
  • data (bytes) –

    Data stream to be updated.
Raises:

gmalg.sm3.SM3.value()

Get current hash value.

Returns:
  • bytes( bytes ) –

    Current hash value.
Note

Each invocation of the method will dynamically compute the hash value that should be output, so it is advisable to retain the resulting hash value after the method call.

gmalg.sm4

SM4 Algorithm Implementation Module.

gmalg.sm4.SM4(key)

Bases: BlockCipher

SM4 Algorithm.

Parameters:
  • key (bytes) –

    16 bytes key.
Raises:

gmalg.sm4.SM4.key_length() classmethod

Get key length in bytes.

gmalg.sm4.SM4.block_length() classmethod

Get block length in bytes.

gmalg.sm4.SM4.encrypt(block)

Encrypt.

Parameters:
  • block (bytes) –

    Plain block to encrypt, must be 16 bytes.
Returns:
  • bytes( bytes ) –

    16 bytes cipher block.
Raises:

gmalg.sm4.SM4.decrypt(block)

Decrypt.

Parameters:
  • block (bytes) –

    cipher block to decrypt, must be 16 bytes.
Returns:
  • bytes( bytes ) –

    16 bytes plain block.
Raises:

gmalg.sm9

SM9 Algorithm Implementation Module.

gmalg.sm9.SM9Core(bnbp, hash_cls, rnd_fn=None)

Bases: SMCoreBase

SM9 Core Algorithms.

Attributes:
  • bnbp (SM9BNBP) –

    BNBP used in SM9.
Parameters:

gmalg.sm9.SM9Core.generate_mpk_sign(msk_s)

Generate master key for sign.

Parameters:
  • msk_s (int) –

    Master secret key for sign.
Returns:
  • EcPoint2( EcPoint2 ) –

    Master public key for sign.

gmalg.sm9.SM9Core.generate_keypair_sign()

Generate masterkey pair for sign.

Returns:
  • int( int ) –

    Master secret key for sign.

  • EcPoint2( EcPoint2 ) –

    Master public key for sign.

gmalg.sm9.SM9Core.generate_mpk_encrypt(msk_e)

Generate master key for encrypt.

Parameters:
  • msk_e (int) –

    Master secret key for encrypt.
Returns:
  • EcPoint( EcPoint ) –

    Master public key for encrypt.

gmalg.sm9.SM9Core.generate_keypair_encrypt()

Generate master key pair for encrypt.

Returns:
  • int( int ) –

    Master secret key for encrypt.

  • EcPoint( EcPoint ) –

    Master public key for encrypt.

gmalg.sm9.SM9Core.generate_sk_sign(hid_s, msk_s, uid)

Generate user secret key for sign.

Parameters:
  • hid_s (bytes) –

    Sign function identity byte.

  • msk_s (int) –

    Master secret key for sign.

  • uid (bytes) –

    User ID.
Returns:
  • EcPoint( EcPoint ) –

    User secret key for sign.
Raises:
  • InvalidUserKeyError –

    Encounter zero when generating, need regenerate master key pair and user keys.

gmalg.sm9.SM9Core.generate_sk_encrypt(hid_e, msk_e, uid)

Generate user secret key for encrypt.

Parameters:
  • hid_e (bytes) –

    Encrypt function identity byte.

  • msk_e (int) –

    Master secret key for encrypt.

  • uid (bytes) –

    User ID.
Returns:
  • EcPoint2( EcPoint2 ) –

    User secret key for encrypt.
Raises:
  • InvalidUserKeyError –

    Encounter zero when generating, need regenerate master key pair and user keys.

gmalg.sm9.SM9Core.sign(message, mpk_s, sk_s)

Sign.

Parameters:
  • message (bytes) –

    Message to be signed.

  • mpk_s (EcPoint2) –

    Master public key for sign.

  • sk_s (EcPoint) –

    User secret key for sign.
Returns:

gmalg.sm9.SM9Core.verify(message, h, S, hid_s, mpk_s, uid)

Verify.

Parameters:
  • message (bytes) –

    Message to be verified.

  • h (int) –

    Generated by sign.

  • S (EcPoint) –

    Generated by sign.

  • hid_s (bytes) –

    Sign function identity byte.

  • mpk_s (EcPoint2) –

    Master public key for sign.

  • uid (bytes) –

    User ID.
Returns:
  • bool( bool ) –

    Whether OK.

gmalg.sm9.SM9Core.begin_key_exchange(hid_e, mpk_e, uid)

Generate data to begin key exchange.

Parameters:
  • hid_e (bytes) –

    Encryption identity byte.

  • mpk_e (EcPoint) –

    Master public key for encryption.

  • uid (bytes) –

    ID of another user.
Returns:
  • int( int ) –

    r.

  • EcPoint( EcPoint ) –

    Random point, [r]Q.

gmalg.sm9.SM9Core.get_secret_data(mpk_e, r, R, sk_e)

Generate same secret point as another user.

Parameters:
  • mpk_e (EcPoint) –

    Master public key for encryption.

  • r (int) –

    Random number generated by begin_key_exchange.

  • R (EcPoint) –

    Random point from another user.

  • sk_e (EcPoint2) –

    Secret key for encryption.
Returns:
Raises:

gmalg.sm9.SM9Core.generate_skey(klen, g1, g2, g3, uid_init, R_init, uid_resp, R_resp)

Generate secret key of klen bytes as same as another user.

Parameters:
  • klen (int) –

    Key length in bytes to generate.

  • g1 (Fp12Ele) –

    g1 from get_secret_data.

  • g2 (Fp12Ele) –

    g2 from get_secret_data.

  • g3 (Fp12Ele) –

    g3 from get_secret_data.

  • uid_init (bytes) –

    User ID bytes of initiator.

  • R_init (EcPoint) –

    Random point of initiator.

  • uid_resp (bytes) –

    User ID bytes of responder.

  • R_resp (EcPoint) –

    Random point of responder.
Returns:
  • bytes( bytes ) –

    Secret key of klen bytes.

gmalg.sm9.SM9Core.encapsulate(hid_e, mpk_e, klen, uid)

Encapsulate secret key.

Parameters:
  • hid_e (bytes) –

    Encryption identity byte.

  • mpk_e (EcPoint) –

    Master public key for encryption.

  • klen (int) –

    Key length in bytes to encapsulate.

  • uid (bytes) –

    ID of another user.
Returns:
  • bytes( bytes ) –

    Encapsulated secret key of klen bytes.

  • EcPoint( EcPoint ) –

    Encapsulated cipher.

gmalg.sm9.SM9Core.decapsulate(C, klen, sk_e, uid)

Decapsulate secret key.

Parameters:
  • C (EcPoint) –

    Encapsulated cipher.

  • klen (int) –

    Key length in bytes to encapsulate.

  • sk_e (EcPoint2) –

    Secret key for encrypt.

  • uid (bytes) –

    User ID.
Returns:
  • bytes( bytes ) –

    Encapsulated secret key of klen bytes.
Raises:

gmalg.sm9.SM9Core.encrypt(hid_e, mpk_e, plain, uid, mac_klen)

Encrypt.

Parameters:
  • hid_e (bytes) –

    Encryption identity byte.

  • mpk_e (EcPoint) –

    Master public key for encryption.

  • plain (bytes) –

    Plain data.

  • uid (bytes) –

    ID of another user.

  • mac_klen (int) –

    MAC key length in bytes.
Returns:
  • EcPoint( EcPoint ) –

    C1, encapsulated cipher key.

  • bytes( bytes ) –

    C2, cipher data.

  • bytes( bytes ) –

    C3, MAC of plain data.

gmalg.sm9.SM9Core.decrypt(C1, C2, C3, sk_e, uid, mac_klen)

Decrypt.

Parameters:
  • C1 (EcPoint) –

    Encapsulated cipher key.

  • C2 (bytes) –

    Cipher data.

  • C3 (bytes) –

    MAC of plain data.

  • sk_e (EcPoint2) –

    Secret key for encrypt.

  • uid (bytes) –

    User ID.

  • mac_klen (int) –

    MAC key length in bytes.
Returns:
  • bytes( bytes ) –

    Plain data.
Raises:

gmalg.sm9.SM9KGC(hid_s=None, msk_s=None, mpk_s=None, hid_e=None, msk_e=None, mpk_e=None, *, rnd_fn=None, pc_mode=PC_MODE.RAW)

SM9 Key Generation Center.

Parameters:
  • hid_s (bytes, default: None ) –

    Single byte for sign key generation.

  • msk_s (bytes, default: None ) –

    Master secret key for sign.

  • mpk_s (bytes, default: None ) –

    Master public key for sign.

  • hid_e (bytes, default: None ) –

    Single byte for encrypt key generation.

  • msk_e (bytes, default: None ) –

    Master secret key for encrypt.

  • mpk_e (bytes, default: None ) –

    Master public key for encrypt.

  • rnd_fn (Callable[[int], int], default: None ) –

    random function used to generate k-bit random number, default to secrets.randbits.

  • pc_mode (PC_MODE, default: RAW ) –

    Point compress mode used for generated data, no effects on the data to be parsed.

gmalg.sm9.SM9KGC.can_generate_sk_sign: bool property

Whether can generate user secret key for sign.

gmalg.sm9.SM9KGC.can_generate_sk_encrypt: bool property

Whether can generate user secret key for encrypt.

gmalg.sm9.SM9KGC.generate_mpk_sign(msk_s)

Generate master key for sign.

Parameters:
  • msk_s (bytes) –

    Master secret key for sign.
Returns:
  • bytes( bytes ) –

    Master public key for sign.

gmalg.sm9.SM9KGC.generate_keypair_sign()

Generate master key pair for sign.

Returns:
  • bytes( bytes ) –

    Master secret key for sign.

  • bytes( bytes ) –

    Master public key for sign.

gmalg.sm9.SM9KGC.generate_mpk_encrypt(msk_e)

Generate master key for encrypt.

Parameters:
  • msk_e (bytes) –

    Master secret key for encrypt.
Returns:
  • bytes( bytes ) –

    Master public key for encrypt.

gmalg.sm9.SM9KGC.generate_keypair_encrypt()

Generate master key pair for encrypt.

Returns:
  • bytes( bytes ) –

    Master secret key for encrypt.

  • bytes( bytes ) –

    Master public key for encrypt.

gmalg.sm9.SM9KGC.generate_sk_sign(uid)

Generate user secret key for sign.

Parameters:
  • uid (bytes) –

    User ID.
Returns:
  • bytes( bytes ) –

    User secret key for sign.

gmalg.sm9.SM9KGC.generate_sk_encrypt(uid)

Generate user secret key for encrypt.

Parameters:
  • uid (bytes) –

    User ID.
Returns:
  • bytes( bytes ) –

    User secret key for encrypt.

gmalg.sm9.SM9(hid_s=None, mpk_s=None, sk_s=None, hid_e=None, mpk_e=None, sk_e=None, uid=None, *, rnd_fn=None, pc_mode=PC_MODE.RAW, mac_klen=32)

SM9 Algorithm.

Parameters:
  • hid_s (bytes, default: None ) –

    Single byte for sign key generation.

  • mpk_s (bytes, default: None ) –

    Master public key for sign.

  • sk_s (bytes, default: None ) –

    User secret key for sign.

  • hid_e (bytes, default: None ) –

    Single byte for encrypt key generation.

  • mpk_e (bytes, default: None ) –

    Master public key for encrypt.

  • sk_e (bytes, default: None ) –

    User secret key for encrypt.

  • uid (bytes, default: None ) –

    User ID.

  • rnd_fn (Callable[[int], int], default: None ) –

    Random function used to generate k-bit random number, default to secrets.randbits.

  • pc_mode (PC_MODE, default: RAW ) –

    Point compress mode used for generated data, no effects on the data to be parsed.

  • mac_klen (int, default: 32 ) –

    MAC value key length in bytes, default to 32.

gmalg.sm9.SM9.can_sign: bool property

Whether can do sign.

gmalg.sm9.SM9.can_verify: bool property

Whether can do verify.

gmalg.sm9.SM9.can_exchange_key: bool property

Whether can do key exchange.

gmalg.sm9.SM9.can_encapsulate: bool property

Whether can do key encapsulate.

gmalg.sm9.SM9.can_decapsulate: bool property

Whether can do key decapsulate.

gmalg.sm9.SM9.can_encrypt: bool property

Whether can do encrypt.

gmalg.sm9.SM9.can_decrypt: bool property

Whether can do decrypt.

gmalg.sm9.SM9.sign(message)

Sign.

Parameters:
  • message (bytes) –

    Message to be signed.
Returns:
  • bytes( bytes ) –

    h of signature.

  • bytes( bytes ) –

    S of signature.
Raises:

gmalg.sm9.SM9.verify(message, h, S)

Verify.

Parameters:
  • message (bytes) –

    Message to be verified.

  • h (bytes) –

    h of signature.

  • S (bytes) –

    S of signature.
Returns:
  • bool( bool ) –

    Whether OK.
Raises:

gmalg.sm9.SM9.begin_key_exchange(uid)

Begin key exchange.

Parameters:
  • uid (bytes) –

    ID of another user.
Returns:
  • int( int ) –

    r, random number.

  • bytes( bytes ) –

    Random point, will be sent to another user.
Raises:

gmalg.sm9.SM9.end_key_exchange(klen, r, R, uid, R2, mode)

End key exchange and get the secret key bytes.

Parameters:
  • klen (int) –

    Length of secret key in bytes to generate.

  • r (int) –

    Random number of self.

  • R (bytes) –

    Random point of self.

  • uid (bytes) –

    ID of another user.

  • R2 (bytes) –

    Random point of another user.

  • mode (KEYXCHG_MODE) –

    Key exchange mode, initiator or responder.
Returns:
  • bytes( bytes ) –

    Secret key of klen bytes.
Raises:

gmalg.sm9.SM9.encapsulate(klen, uid)

Encapsulate secret key.

Parameters:
  • klen (int) –

    Key length in bytes to encapsulate.

  • uid (bytes) –

    ID of another user.
Returns:
  • bytes( bytes ) –

    Encapsulated secret key of klen bytes.

  • bytes( bytes ) –

    Encapsulated cipher.
Raises:

gmalg.sm9.SM9.decapsulate(C, klen)

Decapsulate secret key.

Parameters:
  • C (bytes) –

    Encapsulated cipher.

  • klen (int) –

    Key length in bytes to encapsulate.
Returns:
  • bytes( bytes ) –

    Encapsulated secret key of klen bytes.
Raises:

gmalg.sm9.SM9.encrypt(plain, uid)

Encrypt.

Parameters:
  • plain (bytes) –

    Plain data.

  • uid (bytes) –

    ID of another user.
Returns:
  • bytes( bytes ) –

    Cipher data.
Raises:

gmalg.sm9.SM9.decrypt(cipher)

Decrypt.

Parameters:
  • cipher (bytes) –

    Cipher data.
Returns:
  • bytes( bytes ) –

    Plain data.
Raises:

gmalg.sm9.point_to_bytes_1(P, mode)

Convert point to bytes (Fp).

Parameters:
  • P (EcPoint) –

    Point to be converted.

  • mode (PC_MODE) –

    Compress mode.
Returns:
  • bytes( bytes ) –

    Converted point.
Raises:

gmalg.sm9.bytes_to_point_1(p)

Convert bytes to point (Fp).

Parameters:
  • p (bytes) –

    Bytes to be converted point.
Returns:
  • EcPoint( EcPoint ) –

    Point to be converted.
Raises:

gmalg.sm9.point_to_bytes_2(P, mode)

Convert point to bytes (Fp2).

Parameters:
  • P (EcPoint2) –

    Point to be converted.

  • mode (PC_MODE) –

    Compress mode.
Returns:
  • bytes( bytes ) –

    Converted point.
Raises:

gmalg.sm9.bytes_to_point_2(p)

Convert bytes to point (Fp2).

Parameters:
  • p (bytes) –

    Bytes to be converted point.
Returns:
  • EcPoint2( EcPoint2 ) –

    Point to be converted.
Raises:

gmalg.zuc

ZUC Algorithm Implementation Module.

gmalg.zuc.ZUC(key, iv)

ZUC Algorithm.

Parameters:
  • key (bytes) –

    16 bytes key.

  • iv (bytes) –

    16 bytes iv.
Raises:

gmalg.zuc.ZUC.key_length() classmethod

Get key length in bytes.

gmalg.zuc.ZUC.iv_length() classmethod

Get IV length in bytes.

gmalg.zuc.ZUC.generate()

Generate pseudo-random words.

Returns:
  • bytes( bytes ) –

    32-bit pseudo-random word.

gmalg.errors

GM Exceptions.

gmalg.errors.GMError

Bases: Exception

Base class of all errors in GM algorithms.

gmalg.errors.CheckFailedError

Bases: GMError

Check failed.

gmalg.errors.DataOverflowError

Bases: GMError

Data over maximum length limit.

gmalg.errors.IncorrectLengthError

Bases: GMError

Incorrect data length given.

gmalg.errors.InfinitePointError

Bases: GMError

Encountered a point at infinity.

gmalg.errors.InvalidArgumentError

Bases: GMError

Invalid arguments.

gmalg.errors.InvalidPCError

Bases: GMError

Invalid PC byte.

gmalg.errors.InvalidUserKeyError

Bases: GMError

Invalid user secret key in SM9 key generation.

gmalg.errors.PointNotOnCurveError

Bases: GMError

Point not on elliptic curve.

gmalg.errors.RequireArgumentError

Bases: GMError

Missing some required arguments.

gmalg.errors.UnknownError

Bases: GMError

Unknown errors.

gmalg.primefield

Prime field operations module.

This module provides basic operations on extension fields. The extension field is constructed through a tower extension in the "1-2-4-12" manner, as detailed in the SM9 standard documentation.

gmalg.primefield.PrimeFieldBase(p)

Base class of Fp operations.

All subclasses derived from this class have the same methods as the base class, with the only difference being the replacement of the type FpExEle with the corresponding field element type.

Any variations will be explicitly documented within the respective subclass.

Parameters:
  • p (int) –

    A prime number.

gmalg.primefield.PrimeFieldBase.zero() classmethod

Get Zero.

gmalg.primefield.PrimeFieldBase.one() classmethod

Get One.

gmalg.primefield.PrimeFieldBase.extend(x) classmethod

Extend domain element.

gmalg.primefield.PrimeFieldBase.isoppo(x, y)

Whether is opposite.

gmalg.primefield.PrimeFieldBase.neg(x)

Negative.

gmalg.primefield.PrimeFieldBase.sadd(n, x)

Scalar add.

gmalg.primefield.PrimeFieldBase.smul(k, x)

Scalar mul.

gmalg.primefield.PrimeFieldBase.pmul(x, y)

Multiply by position.

gmalg.primefield.PrimeFieldBase.add(x, y)

Add two elements.

gmalg.primefield.PrimeFieldBase.sub(x, y)

Substract two elements.

gmalg.primefield.PrimeFieldBase.mul(x, y)

Multiply two elements.

gmalg.primefield.PrimeFieldBase.inv(x)

Inverse of element.

gmalg.primefield.PrimeFieldBase.pow(x, e)

Get the exponentiation of x raised to the power of e.

gmalg.primefield.PrimeFieldBase.sqrt(x)

Square root of x.

gmalg.primefield.PrimeFieldBase.etob(e)

Convert domain element to bytes.

gmalg.primefield.PrimeFieldBase.btoe(b)

Convert bytes to domain element.

gmalg.primefield.PrimeField(p)

Bases: PrimeFieldBase

Fp operations.

Attributes:
  • p (int) –

    Prime number used in operations.

  • p_bitlength (int) –

    Bit length of p.

  • p_length (int) –

    Byte length of p.

  • e_length (int) –

    Byte length of domain element.

gmalg.primefield.PrimeField2(p)

Bases: PrimeFieldBase

Fp2 operations.

Attributes:
  • fp (PrimeField) –

    PrimeField used in operations.

  • e_length (int) –

    Byte length of domain element.

gmalg.primefield.PrimeField4(p)

Bases: PrimeFieldBase

Fp4 operations.

Attributes:
  • fp2 (PrimeField2) –

    PrimeField2 used in operations.

  • e_length (int) –

    Byte length of domain element.

gmalg.primefield.PrimeField12(p)

Bases: PrimeFieldBase

Fp12 operations.

Attributes:
  • fp4 (PrimeField4) –

    PrimeField4 used in operations.

  • e_length (int) –

    Byte length of domain element.

Fp2Ele = Tuple[int, int] module-attribute

Fp4Ele = Tuple[Fp2Ele, Fp2Ele] module-attribute

Fp12Ele = Tuple[Fp4Ele, Fp4Ele, Fp4Ele] module-attribute

FpExEle = Union[int, Fp2Ele, Fp4Ele, Fp12Ele] module-attribute

gmalg.ellipticcurve

Elliptic curve operations.

This module provides fundamental operations related to elliptic curves, including but not limited to those specified in the national cryptographic standard documents.

gmalg.ellipticcurve.EllipticCurve(fp, a, b)

Elliptic Curve.

Attributes:
  • INF –

    Infinite point.

  • a (FpExEle) –

    Parameter a of curve.

  • b (FpExEle) –

    Parameter b of curve.
Parameters:
  • fp (PrimeFieldBase) –

    Prime field operations used in ellitic curve, must be derived from class PrimeFieldBase.

  • a (FpExEle) –

    Parameter a of curve.

  • b (FpExEle) –

    Parameter b of curve.
Note

When instantiating the class, the FpExEle or EcPointEx type in the methods will correspond to the type of fp. Here, a generic placeholder are used to denote the data type.

gmalg.ellipticcurve.EllipticCurve.get_y_sqr(x)

Get the square of y for the specified x.

gmalg.ellipticcurve.EllipticCurve.get_y(x)

Get one of valid y for given x, None means no solution.

gmalg.ellipticcurve.EllipticCurve.isvalid(P)

Whether the point is on curve.

gmalg.ellipticcurve.EllipticCurve.neg(P)

Get negative point.

gmalg.ellipticcurve.EllipticCurve.add(P1, P2)

Add two points.

gmalg.ellipticcurve.EllipticCurve.sub(P1, P2)

Substract two points.

gmalg.ellipticcurve.EllipticCurve.mul(k, P)

Scalar multiplication of point by k.

gmalg.ellipticcurve.ECDLP(p, a, b, G, n, h=1)

Elliptic Curve Discrete Logarithm Problem.

Attributes:
  • fp (PrimeField) –

    PrimeField used in ECDLP.

  • ec (EllipticCurve) –

    EllipticCurve used in ECDLP.

  • G (EcPoint) –

    Base point.

  • fpn (PrimeField) –

    PrimeField operations for the order of base point.

  • h (int) –

    Cofactor of base point.
Parameters:
  • p (int) –

    Parameter p of curve.

  • a (int) –

    Parameter a of curve.

  • b (int) –

    Parameter b of curve.

  • G (EcPoint) –

    Base point.

  • n (int) –

    Order of base point.

  • h (int, default: 1 ) –

    Cofactor of G, default to 1.

gmalg.ellipticcurve.ECDLP.kG(k)

Scalar multiplication of G by k.

gmalg.ellipticcurve.SM9BNBP(G1, G2)

SM9 Bilinear Pairing on Barreto-Naehrig (BN) Elliptic Curve.

For performance reasons, this implementation focuses solely on operations on the BN curve in the context of SM9. Consequently, certain intermediate values can be precomputed to enhance computational efficiency.

The fundamental parameters used in SM9 are as follows:

t = 0x600000000058F98A
p = 0xB640000002A3A6F1D603AB4FF58EC74521F2934B1A7AEEDBE56F9B27E351457D
n = 0xB640000002A3A6F1D603AB4FF58EC74449F2934B18EA8BEEE56EE19CD69ECF25
b = 0x05
beta_b = (5, 0)

There are some more precomputed intermediate values. Refer to the source code for detailed information.

Attributes:
  • t (int) –

    Parameter t of SM9.

  • fp12 (PrimeField12) –

    PrimeField12 operations used in SM9.

  • fp2 (PrimeField2) –

    PrimeField2 operations used in SM9.

  • fp1 (PrimeField) –

    PrimeField operations used in SM9.

  • fpn (PrimeField) –

    PrimeField operations for the order of base point.

  • ec1 (EllipticCurve) –

    EllipticCurve on Fp operations used in SM9.

  • ec2 (EllipticCurve) –

    EllipticCurve on Fp2 operations used in SM9.

  • G1 (EcPoint) –

    Base point of group 1.

  • G2 (EcPoint2) –

    Base point of group 2.
Parameters:
  • G1 (EcPoint) –

    Base point of group 1.

  • G2 (EcPoint2) –

    Base point of group 2.

gmalg.ellipticcurve.SM9BNBP.kG1(k)

Scalar multiplication of G1 by k.

gmalg.ellipticcurve.SM9BNBP.kG2(k)

Scalar multiplication of G2 by k.

gmalg.ellipticcurve.SM9BNBP.e(P, Q)

R-ate bilinear pairing.

Parameters:
Returns:
  • Fp12Ele( Fp12Ele ) –

    Pairing value on Fp12.

gmalg.ellipticcurve.SM9BNBP.eG1(Q)

R-ate of G1 and Q.

gmalg.ellipticcurve.SM9BNBP.eG2(P)

R-ate of P and G2.

EcPoint = Tuple[int, int] module-attribute

EcPoint2 = Tuple[Fp.Fp2Ele, Fp.Fp2Ele] module-attribute

EcPoint4 = Tuple[Fp.Fp4Ele, Fp.Fp4Ele] module-attribute

EcPoint12 = Tuple[Fp.Fp12Ele, Fp.Fp12Ele] module-attribute

EcPointEx = Tuple[Fp.FpExEle, Fp.FpExEle] module-attribute

gmalg.base

This module provides some base classes and common items.

gmalg.base.PC_MODE

Bases: Enum

Point compress mode.

Attributes:
  • RAW –

    Raw mode.

  • COMPRESS –

    Compressed mode.

  • MIXED –

    Mixed mode.

gmalg.base.KEYXCHG_MODE

Bases: Enum

Key exchange mode.

Attributes:
  • INITIATOR –

    Initiator mode.

  • RESPONDER –

    Responder mode.

gmalg.base.Hash()

Base class of hash algorithm.

gmalg.base.Hash.max_msg_length() classmethod

Get maximum message length in bytes.

gmalg.base.Hash.hash_length() classmethod

Get output hash value length in bytes.

gmalg.base.Hash.update(data)

Update internal state.

Parameters:
  • data (bytes) –

    Data stream to be updated.

gmalg.base.Hash.value()

Returns current hash value in bytes.

Returns:
  • bytes( bytes ) –

    Hash value.

gmalg.base.BlockCipher(key)

Base class of block cipher algorithm.

Parameters:
  • key (bytes) –

    Key used in cipher, has a length of BlockCipher.key_length().

gmalg.base.BlockCipher.key_length() classmethod

Get key length in bytes.

gmalg.base.BlockCipher.block_length() classmethod

Get block length in bytes.

gmalg.base.BlockCipher.encrypt(block)

Encrypt.

gmalg.base.BlockCipher.decrypt(block)

Decrypt.

gmalg.base.SMCoreBase(hash_cls, rnd_fn=None)

SM core algorithm base class.

Parameters:

问题没有得到解决? 不如看看源码或者提个 Issue.