Frequently Asked Questions

General

What is the philosophy behind PolarSSL

PolarSSL is designed to be readable, documented, tested, loosely coupled and portable.

PolarSSL has a lot of documentation online, including full doxygen API documentation, Design Documentation for security evaluations, example applications and more.

The automatic test suites contain over 1600 tests for regressions, code coverage and cryptographic validation.

The PolarSSL modules are as loosely coupled as possible. If you want to use AES, just copy aes.c and aes.h and you are set. No other files required! This is valid for all symmetric and hash algorithms. Other modules are either as simple, or also require the modules they are dependent on (Sounds logical, doesn't it?).

All portability code is also present in the modules themselves. Doesn't this create duplicate defines? Yes, in some cases it does. But putting it in a central header file would defeat the entire loose coupling we hold so dear!

What external function dependencies does PolarSSL have?

PolarSSL is as loosely coupled as possible and does not rely on any external libraries for its core code. It does use a number of standard libc function calls. The ExternalFunctions page describes which external calls are present and how easily they can be removed if no support for that function is available.

How can I reduce the PolarSSL memory footprint and storage footprint?

In most cases PolarSSL is used low-memory environments. PolarSSL can be optimized for these situations in a number of ways. Please look at the SizeOptimizations page for different methods.

What other projects use PolarSSL?

Who already uses PolarSSL is their projects? There are an increasing number of ProjectsUsingPolarSSL.

How can I get PolarSSL on Fedora / Red Hat?

On Fedora you can use the local packaging application yum to get the PolarSSL library.

yum search polarssl-devel
polarssl-devel.i686 : Development files for polarssl

Note that you must be the root/administrator to install the package. To install this package in Red Hat/Fedora Linux.

yum install polarssl-devel 

You can check the details of this package polarssl-devel

yum info polarssl-devel

PolarSSL fails to compile on my platform

Oops! This can happen. But we'd like to help you!

There are too many flavours of platforms, hardware and Operating Systems for us to test in advance. The solution is often quite simple. Please file a ticket or contact us directly.

How do I generate the API doc locally?

PolarSSL has full doxygen documentation which is also available on the site in the API Documentation.

In order to generate this locally, download and extract the latest tarball and run 'make apidoc' in the root.

This generates the doxygen documentation in the apidoc subdirectory.

Cryptography

RSA encryption of large data fails

RSA is only able to encrypt data to a maximum amount of your key size (2048 bits = 256 bytes) minus padding / header data (11 bytes for PKCS#1 v1.5 padding). It is also not meant for this purpose. If you want to encrypt more data, you can use something like:

1. Generate a 256-bit random keystring K
2. Encrypt your data with AES-CBC with K
3. Encrypt K with RSA
4. Send both to the other side

Of course you can use another key-size, symmetric algorithm and cipher mode, but you get the gist.

Implementation examples

For one reason or the other PolarSSL will not implement all functionality that it could. But it's often easy to actually implement those questions. Examples of implementations are provided.

Implementing Counter Mode (CTR) in PolarSSL

No code is included in the default library to perform CTR out-of-the-box. Then again, all the building blocks are here. The example shown in SymmetricCounterMode, shows you exactly how to do it!

Implementing AES_ENCRYPT() and AES_DECRYPT() from MySQL with PolarSSL

 MySQL has the internal functions AES_ENCRYPT() and AES_DECRYPT to save information in an encrypted format in the database. If you need to read or write data from a system that has no MySQL client, you need to implement the functions yourself. The example shown in MysqlAesEncryption, show you how to emulate the behaviour via PolarSSL.

Implementing reading of RSA public keys in PolarSSL

The code for reading a private key from file is already present in x509parse_keyfile(). But what if you only have a public key file? All versions after 0.99-pre3 include a x509parse_public_keyfile() as well. But if you are before that version? The example in ReadPublicKeyFromFile shows you how to implement this.