Introduction

This document describes the internal functionality of the mbed TLS Public Key Cryptography module.

Component overview

The Public Key module provides asymmetric cryptography functions that are mainly used for:

  • Public/private keypair generation.
  • Parsing and writing keys.
  • Key exchange.
  • Message signing and verification.
  • Message encryption/decryption.

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.

Component design

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:

  • Generating a public/private keypair.
  • Encrypting a message.
  • Decrypting a message.
  • Signing a message.
  • Verifying a signature.

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.

Key handling

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.

Encryption/decryption

Public and private key encryption are provided. Pre-allocated buffer parameters are used for the plain input message and the encrypted result-message.

Signatures

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.

Used structures

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.

Internal state

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.

Scenarios

The following scenarios are described:

  • Diffie-Hellman-Merkle key exchange
  • Failure to encrypt a message
  • Complex usage: signing a message

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.

Use cases

All uses are:

  • Generate an public key pair. Such a key pair is used for key exchange.
  • Parse a private key. A private key is needed to sign or decrypt a message.
  • Encrypt a message.
  • Decrypt a message.
  • Sign a message. A signature is used for authentication purposes.
  • Verify a signature. After verification, the signer is authenticated.
  • Perform a key exchange.