PolarSSL Asymmetric Cryptography (Asym) module MLD

Introduction

This document describes the internal functionality of the PolarSSL Asymmetric Cryptography module.

Component overview

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

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

The Asym module does not interact with other modules, although it is loosely coupled with the RNG module, e.g. for prime number generation.

Component design

The component implements 2 cryptographic standards, namely: Diffie-Hellman-Merkle (DHM) and RSA. 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.

Key handling

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

RSA signature creation and verification are provided that can be used for message integrity, e.g. during key exchange.

Used structures

Each protocol has a context structure. Such structures can be considered as internal as the messages and signatures are handled using separate parameters.

Internal state

The DHM internal state should follow the well-known steps of the Diffie-Hellman key exchange ¹ and is omitted for simplicity.

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 RSA key pair. Such a key pair is used for key exchange.
• 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.