# Migrating from Virgil Crypto 1.8 to Virgil Crypto 2.0

* [Features](#features)
  + [X25519 and Ed25519](#x25519-and-ed25519)
  + [New functions](#new-functions)
* [Changes](#changes)
  + [Migration to C++11](#migration-to-c11)
  + [New error handling model](#new-error-handling-model)
  + [Named constructors gone](#named-constructors-gone)
  + [Unimplemented elliptic curves was dropped](#unimplemented-elliptic-curves-was-dropped)
  + [Dropped "Default" key pair type](#dropped-default-key-pair-type)
  + [VirgilChunkCipher class API was totally redesigned](#virgilchunkcipher-class-api-was-totally-redesigned)
  + [ContentInfo is embedded to the cryptogram by default](#contentinfo-is-embedded-to-the-cryptogram-by-default)
  + [Changes in binaries](#changes-in-binaries)

## Features

This section describes new features that were added in the version 2.0.

### X25519 and Ed25519

Fast elliptic curve algorithms were added:

  * Curve25519 - elliptic curve used for ECDH operations;
  * Ed25519 - elliptic curve used for EdDSA and ECDH operations.

Mentioned algorithms are accessible via `VirgilKeyPair::Type::FAST_EC_X25519` and `VirgilKeyPair::Type::FAST_EC_ED25519` enumeration values.

Algorithms implementation is based on [SUPERCOP](http://bench.cr.yp.to/supercop.html) reference implementation, so it contains optimizations for AMD64 processor architecture.

See also:

  * [Ed25519 and X25519 keys format](https://tools.ietf.org/html/draft-ietf-curdle-pkix-01)
  * [EdDSA](https://www.ietf.org/id/draft-irtf-cfrg-eddsa-08.txt)
  * [X25519](https://tools.ietf.org/html/rfc7748)

### New functions

1. `VirgilKeyPair::`
    * `encryptPrivateKey()` - encrypt given private key and store it in the PKCS#8 format
    * `decryptPrivateKey()` - decrypt given private key and store it in the corresponding plain private key format
    * `generateRecommended()` - generate new key pair with recommended safest type
    * `extractPublicKey()` - extract public key from the private key
    * `publicKeyToPEM()` - convert given public key to the PEM format
    * `publicKeyToDER()` - convert given public key to the DER format
    * `privateKeyToPEM()` - convert given private key to the PEM format
    * `privateKeyToDER()` - convert given private key to the DER format

## Changes

This section describes changes to the library API 2.0 that are not compatible with API 1.8.

### Migration to C++11

1. Target compiler must be able to compile C++11 standard.
1. All enumerations were replaced with scoped enums.
1. Move semantic is used instead of 'shallow' copying.

### New error handling model

Now library produces only exceptions of type `VirgilCryptoException`. Produced exceptions can contain nested exceptions.
To get all error messages (including nested) function `virgil::crypto::backtrace_exception()` can be used.

Exception details are defined by specific error code and corresponding error category.

Error categories are:

  * `VirgilCryptoErrorCategory` - category that handles generic error codes defined in enum `VirgilCryptoError`;
  * `VirgilSystemCryptoErrorCategory` - category that handles error codes from the system crypto library (MbedTLS).

### Named constructors gone

Named constructors such as `VirgilHash::sha256()` were replaced with constructor that accepts corresponding enumeration value.

  * `VirgilHash::sha256()` with `VirgilHash(VirgilHash::Algorithm::SHA256)`, and so on;
  * `VirgilPBKDF::pbkdf2()` with `VirgilPBKDF(VirgilPBKDF::Algorithm::PBKDF2)`, and so on;
  * `VirgilPBE::pkcs5()` with `VirgilPBE(VirgilPBE::Algorithm::PKCS5)`, and so on;
  * `VirgilSymmetricCipher::aes256()` with `VirgilSymmetricCipher(VirgilSymmetricCipher::Algorithm::AES_256_GCM)`, and so on.

### Unimplemented elliptic curves were dropped

Dropped enumeration values that were represented as unimplemented algorithms:

  * `VirgilKeyPair::Type::EC_M221`
  * `VirgilKeyPair::Type::EC_M255`
  * `VirgilKeyPair::Type::EC_M383`
  * `VirgilKeyPair::Type::EC_M511`

### Dropped "Default" key pair type

Enumeration value `VirgilKeyPair::Type::Default` was replaced with function `VirgilKeyPair::generateRecommended()`

### VirgilChunkCipher class API was totally redesigned

Now `VirgilChunkCipher` class has the same interface as class `VirgilStreamCipher`, but the main difference is the way data is proceeded.

`VirgilChunkCipher` treats each data portion as separate data to be proceeded. So each encrypted data chunk contains encrypted data and verification tag.

### ContentInfo is embedded to the cryptogram by default

1. Default value of 2nd parameter `embedContentInfo` of function `VirgilCipher::encrypt()` is now true by default.
1. Default value of 3rd parameter `embedContentInfo` of function `VirgilStreamCipher::encrypt()` is now true by default.

### Changes in binaries

1. Change name for Apple frameworks: `VirgilCrypto.framework` to `VSCCrypto.framework`.
1. Remove support of OS X universal binaries.
1. Dropped AS3 support.