Public Key Module Level Design
This document describes the internal functionality of the mbed TLS Public Key Cryptography module.
The Public Key module provides asymmetric cryptography functions that are mainly used for:
The Public Key module does not interact with other modules, although it is loosely coupled with the RNG module, e.g. for prime number generation and blinding.
The component implements 4 cryptographic standards, namely: Diffie-Hellman-Merkle (DHM), Elliptic Curve Diffie-Hellman-Merkle (ECDH), RSA and Elliptic Curve Digital Signature Algorithm (ECDSA). Each of these cryptographic protocols is implemented as a separate sub-module and can be included or excluded at compile time. The following functions are provided:
The following naming convention is used for coherence: X_function
where X is the name of the protocol and function is the name of the cryptographic function e.g. rsa_private for encrypting a message using a private key.
A generic layer is provided to access the RSA / ECDSA functions in the form of the PK layer.
Each standard stores its keys in a dedicated context. The generic layer provides a generic public key contex. The RSA public/private keypair generation is mostly used for key exchange. The keys are stored in the RSA context. The RSA sub-module provides functions to check their integrity. The DHM sub-module provides for the secure calculation of a shared master secret by creating a secret part and sharing a public part.
Public and private key encryption are provided. Pre-allocated buffer parameters are used for the plain input message and the encrypted result-message.
Signature creation and verification (e.g. with RSA or ECDSA) are provided by the publi key layer that can be used for verifying message integrity, e.g. during key exchange.
The public key layer has a generic context structure. Each protocol has a separate context structure. Such structures can be considered as internal as the messages and signatures are handled using separate parameters.
The DHM, ECDSA and ECDH internal states should follow the well-known steps of the respective key exchanges.
The RSA internal state involves initialization and setting the keys.
The following scenarios are described:
Diffie-Hellman-Merkle key exchange
This scenario shows how a shared master secret is calculated.
Failure to encrypt a message
This scenario describes how an RSA encryption attempt fails, because the output buffer is too small.
Complex usage: signing a message
This scenario describes generating an RSA key pair and using it to sign a message.
All uses are: