Migration help

In order to make the migration from PolarSSL 1.2 to PolarSSL 1.3 as easy as possible, we have introduced the include/polarssl/compat-1.2.h header file. If you include this header in your application (immediately below including config.h), then most changes will be covered by the appropriate typedef and include functions. You will still have to handle the prototype changes yourself of course.

API Changes

SHA2 and SHA4 have been renamed

At the time of conception SHA4 seemed a reasonable name for the SHA-512 implementation within PolarSSL.In light of the new SHA-3 standard, the name of the SHA4 module is confusing.

What changed?

  • sha2 => sha256
    • sha2.h is now sha256.h
    • sha2.c is now sha256.c
    • POLARSSL_SHA2_C is now POLARSSL_SHA256_C
    • sha2_context is now sha256_context
    • all functions prefixed with sha2_ are now prefixed with sha256_
  • sha4 => sha512
    • sha4.h is now sha512.h
    • sha4.c is now sha512.c
    • POLARSSL_SHA4_C is now POLARSSL_SHA512_C
    • sha4_context is now sha512_context
    • all functions prefixed with sha4_ are now prefixed with sha512_

Cipher layer has been restructured

With the addition of the RC4 stream cipher and the GCM cipher mode into the cipher layer, some restructuring was done.

What changed?

  • int cipher_reset( cipher_context_t *ctx, unsigned char *iv ) is split into:
    • int cipher_reset( cipher_context_t *ctx ), responsible for resetting all information about the current stream
    • int cipher_set_iv( cipher_context_t *ctx, unsigned char *iv, size_t ivlen ), responsible for setting the IV (if required by the current cipher and mode)

GCM module generalized

The GCM module in the PolarSSL 1.2 branch can only handle AES as it's block cipher. In the PolarSSL 1.3 branch the GCM module uses the generic cipher layer and can use any 128-bit based block cipher.

What changed?

int gcm_init( gcm_context *ctx, const unsigned char *key, unsigned int keylen);

changed to:

int gcm_init( gcm_context *ctx, cipher_id_t cipher, const unsigned char *key,
              unsigned int keysize );

Where cipher indicates the base cipher to use, e.g. POLARSSL_CIPHER_ID_AES.

RSA module has been restructured

In order to add blinding defense against timing attacks, random data is required in some operations when using RSA_PRIVATE. Functions were adapted to cope. This means you might need to add a random data source to your code if you don't have one yet, read our article on how to add a random generator.

In addition the RSA module now uses the MD layer instead of specific hash algorithms.

What changed?

  • rsa_private(), rsa_pkcs1_verify() and rsa_pkcs1_decrypt() now expect f_rng and p_rng as their second and third parameters to perform blinding.
  • rsa_pkcs1_verify() uses an md_type_t, such as POLARSSL_MD_SHA1, instead of SIG_RSA_SHA1 to indicate the hash to use. Use POLARSSL_MD_NONE instead of the old SIG_RSA_RAW.

DHM module has been restructured

In order to add blinding defense against timing attacks, random data is required in some Diffie Hellman operations. Function prototypes were adapted to cope. This means you might need to add a random data source to your code if you don't have one yet, read our article on how to add a random generator.

What changed?

  • dhm_calc_secret(), now expects f_rng and p_rng as its last two parameters.

SSL ciphersuites extracted from SSL module

The SSL ciphersuites are now in their own module. In most cases you will not notice the difference. If you used ssl_default_ciphersuites in your code though, you will need to use ssl_list_ciphersuites() instead.

In addition, those ciphersuites are now the default list when using the SSL module. So if you used ssl_default_ciphersuites in your call to ssl_set_ciphersuites(), you can just omit the call!

SSL layer and X509 Parse module now uses public key layer

Elliptic Curve keys and certificates were added in this release. The SSL and X509 Parse modules now use the new public key (PK) layer (see pk.h) to handle keys and certificates. As a result functions like x509parse_key() now expect a pk_context instead of a rsa_context.

What changed?

  • x509parse_key_*() changed the first argument from rsa_context *ctx, to pk_context *ctx
  • ssl_set_own_cert() changed the first argument from rsa_context *ctx, to pk_context *ctx
  • Internally X509 certificates (x509_cert) now have a pk member and not the rsa member they used to. You can still easily use it as an rsa_context * with for instance pk_rsa(crt->pk)

You can still use the RSA-only variants by appending _rsa to some functions, e.g. x509parse_key_rsa() and ssl_set_own_cert_rsa().

X509 Write module fully restructured

The X509 write module was changed to include a number of big features, such as correct Certificate Signing Request (CSR) generation, writing and signing of X509 certificates. Please read the header file (x509write.h) for more documentation.

Anything missing?

Did we miss anything? Please let us know!

Did this help?