Package: python-mbedtls
python-mbedtlsis a free cryptographic library for Python that usesmbed TLSfor back end.mbed TLS (formerly known as PolarSSL) makes it trivially easy for
developers to include cryptographic and SSL/TLS capabilities in their
(embedded) products, facilitating this functionality with a minimal
coding footprint.python-mbedtlsAPI follows the recommendations from:PEP 272– API for Block Encryption Algorithms v1.0PEP 452– API for Cryptographic Hash Functions v2.0PEP 506– Adding a Secret Module to the Standard LibraryPEP 543– A Unified TLS API for Python (completed and modernized)and therefore plays well with thecryptographic servicesfrom the
Python standard library and many other cryptography libraries as well.Licensepython-mbedtlsis licensed under the MIT License (see LICENSE.txt).
This enables the use ofpython-mbedtlsin both open source and closed
source projects.  The MIT License is compatible with both GPL and Apache
2.0 license under which mbed TLS is distributed.API documentationhttps://synss.github.io/python-mbedtls/InstallationThe bindings are tested with mbedTLS 2.28.7 for Python 3.8,
3.9, 3.10, 3.11, and 3.12 on Linux, macOS, and Windows.manylinuxwheels are available for 64-bit Linux systems.  Install
withpip installpython-mbedtls.Usage and examplesNow, let us see examples using the various parts of the library.Check which version of mbed TLS is being used by python-mbedtlsThembedtls.versionmodule shows the run-time version
information to mbed TLS.>>> from mbedtls import version
>>> _ = version.version  # "Mbed TLS 2.28.7"
>>> _ = version.version_info  # (2, 28, 7)Message digestThembedtls.hashlibmodule supports MD2, MD4, MD5, SHA-1, SHA-2
(in 224, 256, 384, and 512-bits), and RIPEMD-160 secure hashes
and message digests.  Note that MD2 and MD4 are not included
by default and are only present if they are compiled in mbedtls.Here are the examples from (standard)hashlibported
topython-mbedtls:>>> from mbedtls import hashlib
>>> m = hashlib.md5()
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
>>> m.digest_size
16
>>> m.block_size
64More condensed:>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'Usingnew():>>> h = hashlib.new('ripemd160')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'HMAC algorithmThembedtls.hmacmodule computes HMAC.Example:>>> from mbedtls import hmac
>>> m = hmac.new(b"This is my secret key", digestmod="md5")
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\x9d-/rj\\\x98\x80\xb1rG\x87\x0f\xe9\xe4\xeb'Warning:The message is cleared after calculation of the digest.  Only callmbedtls.hmac.Hmac.digest()ormbedtls.hmac.Hmac.hexdigest()once per message.HMAC-based key derivation function (HKDF)Thembedtls.hkdfmodule exposes extract-and-expand key derivation
functions.  The main function ishkdf()butextract()andexpand()may be used as well.Example:>>> from mbedtls import hkdf
>>> hkdf.hkdf(
...     b"my secret key",
...     length=42,
...     info=b"my cool app",
...     salt=b"and pepper",
...     digestmod=hmac.sha256
... )
b'v,\xef\x90\xccU\x1d\x1b\xd7\\a\xaf\x92\xac\n\x90\xf9q\xf4)\xcd"\xf7\x1a\x94p\x03.\xa8e\x1e\xfb\x92\xe8l\x0cc\xf8e\rvj'whereinfo,salt, anddigestmodare optional, although providing
(at least)infois highly recommended.Symmetric cipherThembedtls.ciphermodule provides symmetric encryption.  The API
follows the recommendations from PEP 272 so that it can be used as a
drop-in replacement to other libraries.python-mbedtlsprovides the following algorithms:AES encryption/decryption (128, 192, and 256 bits) in ECB, CBC, CFB128,
CTR, OFB, or XTS mode;AES AEAD (128, 192, and 256 bits) in GCM or CCM mode;ARC4 encryption/decryption;ARIA encryption/decryption (128, 192, and 256 bits) in ECB, CBC,
CTR, or GCM modes;Blowfish encryption/decryption in ECB, CBC, CFB64, or CTR mode;Camellia encryption/decryption (128, 192, and 256 bits) in ECB, CBC,
CFB128, CTR, or GCM mode;DES, DES3, and double DES3 encryption/decryption in ECB or CBC mode;CHACHA20 and CHACHA20/POLY1305 encryption/decryption.Example:>>> from mbedtls import cipher
>>> c = cipher.AES.new(b"My 16-bytes key.", cipher.MODE_CBC, b"CBC needs an IV.")
>>> enc = c.encrypt(b"This is a super-secret message!!")
>>> enc
b"*`k6\x98\x97=[\xdf\x7f\x88\x96\xf5\t\x19J\xf62h\xf4n\xca\xe8\xfe\xf5\xd7X'\xb1\x8c\xc9\x85"
>>> c.decrypt(enc)
b'This is a super-secret message!!'RSA public keyThembedtls.pkmodule provides the RSA cryptosystem.  This includes:Public-private key generation and key import/export in PEM and DER
formats;asymmetric encryption and decryption;message signature and verification.Key generation, the default size is 2048 bits:>>> from mbedtls import pk
>>> rsa = pk.RSA()
>>> prv = rsa.generate()
>>> rsa.key_size
256Message encryption and decryption:>>> enc = rsa.encrypt(b"secret message")
>>> rsa.decrypt(enc)
b'secret message'Message signature and verification:>>> sig = rsa.sign(b"Please sign here.")
>>> rsa.verify(b"Please sign here.", sig)
True
>>> rsa.verify(b"Sorry, wrong message.", sig)
False
>>> pub = rsa.export_public_key(format="DER")
>>> other = pk.RSA.from_buffer(pub)
>>> other.verify(b"Please sign here.", sig)
TrueStatic and ephemeral elliptic curve Diffie-HellmanThembedtls.pkmodule provides the ECC cryptosystem.  This includes:Public-private key generation and key import/export in the PEM and DER
formats;asymmetric encrypt and decryption;message signature and verification;ephemeral ECDH key exchange.get_supported_curves()returns the list of supported curves.The API of the ECC class is the same as the API of the RSA class
but ciphering (encrypt()anddecrypt()is not supported by
Mbed TLS).Message signature and verification using elliptic a curve digital
signature algorithm (ECDSA):>>> from mbedtls import pk
>>> ecdsa = pk.ECC()
>>> prv = ecdsa.generate()
>>> sig = ecdsa.sign(b"Please sign here.")
>>> ecdsa.verify(b"Please sign here.", sig)
True
>>> ecdsa.verify(b"Sorry, wrong message.", sig)
False
>>> pub = ecdsa.export_public_key(format="DER")
>>> other = pk.ECC.from_buffer(pub)
>>> other.verify(b"Please sign here.", sig)
TrueThe classesECDHServerandECDHClientmay be used for ephemeral
ECDH.  The key exchange is as follows:>>> ecdh_key = pk.ECC()
>>> ecdh_key.generate()
>>> ecdh_srv = pk.ECDHServer(ecdh_key)
>>> ecdh_cli = pk.ECDHClient(ecdh_key)The server generates the ServerKeyExchange encrypted payload and
passes it to the client:>>> ske = ecdh_srv.generate()
>>> ecdh_cli.import_SKE(ske)then the client generates the ClientKeyExchange encrypted payload and
passes it back to the server:>>> cke = ecdh_cli.generate()
>>> ecdh_srv.import_CKE(cke)Now, client and server may generate their shared secret:>>> secret = ecdh_srv.generate_secret()
>>> ecdh_cli.generate_secret() == secret
True
>>> ecdh_srv.shared_secret == ecdh_cli.shared_secret
TrueDiffie-Hellman-Merkle key exchangeThe classesDHServerandDHClientmay be used for DH Key
exchange.  The classes have the same API asECDHServerandECDHClient, respectively.The key exchange is as follow:>>> from mbedtls.mpi import MPI
>>> from mbedtls import pk
>>> dh_srv = pk.DHServer(MPI.prime(128), MPI.prime(96))
>>> dh_cli = pk.DHClient(MPI.prime(128), MPI.prime(96))The 128-bytes prime and the 96-bytes prime are the modulusPand the generatorG.The server generates the ServerKeyExchange payload:>>> ske = dh_srv.generate()
>>> dh_cli.import_SKE(ske)The payload ends withG^X mod PwhereXis the secret value of
the server.>>> cke = dh_cli.generate()
>>> dh_srv.import_CKE(cke)ckeisG^Y mod P(withYthe secret value from the client)
returned as its representation in bytes so that it can be readily
transported over the network.As in ECDH, client and server may now generate their shared secret:>>> secret = dh_srv.generate_secret()
>>> dh_cli.generate_secret() == secret
True
>>> dh_srv.shared_secret == dh_cli.shared_secret
TrueX.509 certificate writing and parsingThembedtls.x509module can be used to parse X.509 certificates
or create and verify a certificate chain.Here, the trusted root is a self-signed CA certificateca0_crtsigned byca0_key.>>> import datetime as dt
>>>
>>> from mbedtls import hashlib
>>> from mbedtls import pk
>>> from mbedtls import x509
>>>
>>> now = dt.datetime.utcnow()
>>> ca0_key = pk.RSA()
>>> _ = ca0_key.generate()
>>> ca0_csr = x509.CSR.new(ca0_key, "CN=Trusted CA", hashlib.sha256())
>>> ca0_crt = x509.CRT.selfsign(
...     ca0_csr, ca0_key,
...     not_before=now, not_after=now + dt.timedelta(days=90),
...     serial_number=0x123456,
...     basic_constraints=x509.BasicConstraints(True, 1))
...An intermediate then issues a Certificate Singing Request (CSR) that the
root CA signs:>>> ca1_key = pk.ECC()
>>> _ = ca1_key.generate()
>>> ca1_csr = x509.CSR.new(ca1_key, "CN=Intermediate CA", hashlib.sha256())
>>>
>>> ca1_crt = ca0_crt.sign(
...     ca1_csr, ca0_key, now, now + dt.timedelta(days=90), 0x123456,
...     basic_constraints=x509.BasicConstraints(ca=True, max_path_length=3))
...And finally, the intermediate CA signs a certificate for the
End Entity on the basis of a new CSR:>>> ee0_key = pk.ECC()
>>> _ = ee0_key.generate()
>>> ee0_csr = x509.CSR.new(ee0_key, "CN=End Entity", hashlib.sha256())
>>>
>>> ee0_crt = ca1_crt.sign(
...     ee0_csr, ca1_key, now, now + dt.timedelta(days=90), 0x987654)
...The emitting certificate can be used to verify the next certificate in
the chain:>>> ca1_crt.verify(ee0_crt)
True
>>> ca0_crt.verify(ca1_crt)
TrueNote, however, that this verification is only one step in a private key
infrastructure and does not take CRLs, path length, etc. into account.TLS and DTLS client and serverThembedtls.tlsmodule provides TLS clients and servers.  The API
follows the recommendations ofPEP 543.  Note, however, that the
Python standard SSL library does not follow the PEP so that this
library may not be a drop-in replacement.Connectionless DTLS is supported as well.See examples in theprograms/directory of the repository
andtests/test_tls.py.