# Public Key Module Level Design

## 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:

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:

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

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: