Easy to use cryptographic framework for data protection: secure messaging with forward secrecy and secure data storage. Has unified APIs across 14 platforms.
This is a hotfix for Apple platforms: ObjCThemis and SwiftThemis, running on iOS and macOS, when installed via Carthage or CocoaPods.
themis
pod is now restored to use dynamic linkage again@rpath
when using CocoaPodsarm64e
architecture slice from Carthage builds for iOS which prevented CocoaPods from functioning correctlyCode:
This is a hotfix for Apple platforms: ObjCThemis and SwiftThemis, running on macOS, when installed via Carthage.
iOS platform is not affected. Installations via CocoaPods are not affected too. You can continue using Themis 0.13.4 there.
Code:
Objective-C / Swift
This is a hotfix for Apple platforms: ObjCThemis and SwiftThemis, running on iOS and macOS, installed via Carthage or CocoaPods.
Note that this hotfix is not compatible with Xcode 11. (Future releases of Themis will also require Xcode 12+) If you are using Xcode 11, please use older versions of Themis:
pod 'themis', '0.13.0'
github "cossacklabs/themis" "0.13.0"
Code:
Updated Themis podspec to be compatible with Xcode12:
iOS:
Xcode 12: use pod themis, "0.13.3"
. It excludes arm64-iphonesimulator architecture slice for now. Resulting app can be submitted to App Store.
Xcode 11: use pod themis, "0.13.0"
. It is compatible with Xcode 11, not with Xcode 12.
See https://github.com/cossacklabs/themis/issues/715, https://github.com/cossacklabs/themis/issues/725.
macOS:
If you use macOS, use 0.13.3, and please exclude mac-arm64 for now (set Build Active Architecture Only = YES
). This will build correct x86_64 application.
iOS: Exclude arm64-iphonesimulator architecture slice for now (see https://github.com/cossacklabs/themis/issues/713).
macOS:
If you use macOS, use 0.13.3, and please exclude mac-arm64 for now (set Build Active Architecture Only = YES
). This will build correct x86_64 application.
See https://github.com/cossacklabs/themis/issues/725, https://github.com/cossacklabs/themis/issues/713.
Hotfix for Carthage, removing dysfunctional ObjCThemis.xcodeproj
.
Breaking changes and deprecations:
themis.framework
once again.Code:
Objective-C
Breaking changes
ObjCThemis framework built by Carthage is now called themis.framework
once again (#704).
ObjCThemis 0.13.0 has initiated renaming of the framework produced by Carthage into objcthemis.framework
from its historical name themis.framework
. This decision has been a mistake. More information is available in the pull request linked above.
objcthemis.framework
is removed and should not be used.
Please continue linking your applications to themis.framework
. Note as well that starting with ObjCThemis 0.13.1, you do not have to embed openssl.framework
anymore when ObjCThemis is installed via Carthage.
TL;DR:
Code:
Core
Android
Go
Node.js
WebAssembly
Swift
Objective-C
Infrastructure:
TL;DR:
Breaking changes and deprecations:
objcthemis
instead of just themis
(read more).Code:
Core
Added support for building with sanitizers like ASan and UBSan, enabled by WITH_ASAN=1
flags (#548, #556).
Fixed a number of possible use-after-free conditions (#546).
Themis Core is now compiled with -O2
optimizations enabled by default (#543).
Themis Core is now compiled with even more paranoid compiler flags (#578).
Fixed various edge-case correctness issues pointed out by sanitizers, clang-tidy, and compiler warnings (#540, #545, #554, #570, #597, #613).
Improved memory wiping, making sure that sensitive data doesn't stay in memory longer than absolutely necessary (#584, #585, #586, #612).
Soter (low-level security core used by Themis)
soter_pbkdf2_sha256()
can be used to derive encryption keys from passphrases with PBKDF2 algorithm (#574).Key generation
themis_gen_sym_key()
can be used to securely generate symmetric keys for Secure Cell (#560).Secure Cell
Secure Session
secure_session_save()
and secure_session_load()
methods (#658).Breaking changes
Secure Cell compatibility with Themis 0.9.6 is now disabled by default (#614).
Old versions of Themis have been calculating encrypted data length incorrectly, which made Secure Cells encrypted on 64-bit machines impossible to decrypt on 32-bit machines (see #279 for details).
Themis 0.10 and later versions include a fix for that issue and a compatiblity workaround that allows to decrypt data encrypted by Themis 0.9.6 on 64-bit platforms. This workaround was enabled by default and could be disabled by setting the NO_SCELL_COMPAT
varible.
Since Themis 0.13 the workaround for Themis 0.9.6 compatibility is disabled by default (as it has performance implications). It can be enabled if needed by compling with WITH_SCELL_COMPAT
.
We are planning to remove the workaround completely after Themis 0.9.6 reaches end-of-life in December 2020. Please use this time to migrate existing data if you have been using Themis 0.9.6. To migrate the data, decrypt it and encrypt it back with the latest Themis version.
Themis is known to be broken on big-endian architectures (#623, #592).
Themis has never committed to supporting machines with big-endian architectures. However, it was expected to accidentally work to some degree on such machines, with certain compatibility restrictions on interaction with little-endian machines.
Recent changes in Themis Core are known to introduce compatibility issues on big-endian architectures. If you believe you are affected by this change, please reach out to us via [email protected].
Android
See also: Java API updates.
Kotlin is now officially supported language on Android (#637).
Fixed a crash when decrypting corrupted Secure Cell data (#639).
Updated embedded BoringSSL to the latest version (#643).
Fixed broken SecureSession#save
and SecureSession#restore
methods (#658).
Breaking changes
Android build now uses Gradle 5.6 and requires Java 8 (#633).
It is no longer possible to build AndroidThemis with Java 7. Please upgrade to Java 8 or later version.
Deprecations
Unqualified Gradle targets are now deprecated (#633).
To build Themis for Android, run
./gradlew :android:assembleRelease
instead of
./gradlew assembleRelease
The unqualified form still works for now, but may break in future releases.
C++
Secure Cell API updates (#588)
ThemisPP now supports passphrase API of Secure Cell in Seal mode:
#include <themispp/secure_cell.hpp>
auto cell = themispp::secure_cell_seal_with_passphrase("string");
uint8_t[] plaintext = "message";
std::vector<uint8_t> encrypted = cell.encrypt(plaintext);
std::vector<uint8_t> decrypted = cell.decrypt(encrypted);
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (themispp::secure_cell_seal
and other modes) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by themispp::gen_sym_key()
(#561). Use passphrase API with human-readable passphrases.
All modes of Secure Cell get a new initialisation API to avoid ambiguity over whether Secure Cell is secured with a passphrase or a master key (since both are effectively byte arrays in C++):
themispp::secure_cell_seal_with_key(master_key)
themispp::secure_cell_token_protect_with_key(master_key)
themispp::secure_cell_context_imprint_with_key(master_key)
New API has additional benefits:
std::vector
, std::array
, std::span
, C arrays, etc.Deprecated API
The following classes are deprecated:
themispp::secure_cell_seal_t
themispp::secure_cell_token_protect_t
themispp::secure_cell_context_imprint_t
They should be replaced with their _with_key
counterparts. In most cases migration should be a trivial renaming but there are caveats with Token Protect mode and iterator usage. Please see #588 for details.
New function themispp::gen_sym_key()
can be used to generate symmetric keys for Secure Cell (#561, #576).
Updated test suite to test C++14 and C++17 (in addition to C++11 and C++03) (#572).
Breaking changes
get_pub_key_by_id()
method of secure_session_callback_interface_t
now has to return non-const vector (#540).
Change your implementation like this:
-const std::vector<uint8_t> get_pub_key_by_id(const std::vector<uint8_t>& id) override
+std::vector<uint8_t> get_pub_key_by_id(const std::vector<uint8_t>& id) override
{
// ...
}
Go
New function keys.NewSymmetricKey()
can be used to generate symmetric keys for Secure Cell (#561).
Improved ThemisError
introspection: added error constants, numeric error codes (#622).
Secure Cell API updates:
New API with improved usability and consistent naming (#624).
func SealWithKey(key *keys.SymmetricKey) (*SecureCellSeal, error)
func (sc *SecureCellSeal) Encrypt(plaintext, context []byte) ([]byte, error)
func (sc *SecureCellSeal) Decrypt(encrypted, context []byte) ([]byte, error)
func TokenProtectWithKey(key *keys.SymmetricKey) (*SecureCellTokenProtect, error)
func (sc *SecureCellTokenProtect) Encrypt(plaintext, context []byte) (encrypted, token []byte, error)
func (sc *SecureCellTokenProtect) Decrypt(encrypted, token, context []byte) ([]byte, error)
func ContextImprintWithKey(key *keys.SymmetricKey) (*SecureCellContextImprint, error)
func (sc *SecureCellContextImprint) Encrypt(plaintext, context []byte) ([]byte, error)
func (sc *SecureCellContextImprint) Decrypt(encrypted, context []byte) ([]byte, error)
This API is less ambiguous and more convenient to use.
GoThemis now supports passphrase API in Seal mode (#625).
scell, err := cell.SealWithPassphrase("secret")
if err != nil {
return err
}
encrypted, err := scell.Encrypt([]byte("message"), nil)
if err != nil {
return err
}
decrypted, err := scell.Decrypt(encrypted, nil)
if err != nil {
return err
}
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (cell.SealWithKey()
or cell.New()
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by keys.NewSymmetricKey()
(#561). Use passphrase API with human-readable passphrases.
Deprecated API
Run-time mode-setting for Secure Cell is deprecated (#624).
Please use new constructors cell.SealWithKey()
instead of cell.New()
and cell.ModeSeal...
constants. Encryption is now performed with Encrypt()
method instead of Protect()
. For decryption use Decrypt()
instead of Unprotect()
.
Old API is retained for compatibility.
iOS and macOS
New function TSGenerateSymmetricKey()
(available in Objective-C and Swift) can be used to generate symmetric keys for Secure Cell (#561).
Mac Catalyst is explicitly disabled (#598).
Improved test coverage of platforms (#599, #607, #610, #642).
SwiftThemis is now tested with Swift 5 (#605).
iPadOS is now officially supported target for ObjCThemis (#641).
Secure Cell API updates:
New encryption/decryption API with consistent naming: encrypt
and decrypt
(#606).
Improved Token Protect API (#606):
NSData
now which bridges with Swift Data
directly.TSCellTokenEncryptedData
object.ObjCThemis now supports passphrase API of in Seal mode (#609).
In Swift:
let cell = TSCellSeal(passphrase: "secret")
let encrypted = try cell.encrypt("message".data(using: .utf8)!)
let decrypted = try cell.decrypt(encrypted)
In Objective-C:
TSCellSeal *cell = [[TSCellSeal alloc] initWithPassphrase:@"secret"];
NSData *encrypted = [cell encrypt:[@"message" dataUsingEncoding:NSUTF8StringEncoding]];
NSData *decrypted = [cell decrypt:encrypted];
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (TSCellSeal(key: ...)
or initWithKey:...
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by TSGenerateSymmetricKey()
(#561). Use passphrase API with human-readable passphrases.
Deprecated API
Secure Cell wrapData/unwrapData renamed into encrypt/decrypt (#606).
As a result, the following methods are deprecated. There are no plans for their removal.
Mode | Deprecation | Replacement |
---|---|---|
TSCellSeal |
wrap(_:, context:) wrap |
encrypt(_:, context:) encrypt |
unwrapData(_:, context:) unwrapData |
decrypt(_:, context:) decrypt |
|
TSCellToken |
wrap(_:, context:) wrap |
encrypt(_:, context:) encrypt |
unwrapData(_:, context:) unwrapData |
decrypt(_:, token:, context:) decrypt(_:, token:) |
|
TSCellContextImprint |
wrap(_:, context:) wrap |
encrypt(_:, context:) encrypt |
unwrapData(_:, context:) unwrapData |
decrypt(_:, context:) decrypt |
Mode | Deprecation | Replacement |
---|---|---|
TSCellSeal |
wrapData:context:error: wrapData:error: |
encrypt:context:error: encrypt:error: |
unwrapData:context:error: unwrapData:error: |
decrypt:context:error: decrypt:error: |
|
TSCellToken |
wrapData:context:error: wrapData:error: |
encrypt:context:error: encrypt:error: |
unwrapData:context:error: unwrapData:error: |
decrypt:token:context:error: decrypt:token:error: |
|
TSCellContextImprint |
wrapData:context:error: wrapData:error: |
encrypt:context:error: encrypt:error: |
unwrapData:context:error: unwrapData:error: |
decrypt:context:error: decrypt:error: |
Breaking changes
ObjCThemis framework built by Carthage is now called objcthemis.framework
(#604).
We have renamed the Carthage framework from themis.framework
to objcthemis.framework
in order to improve compatibility with CocoaPods and avoid possible import conflicts with Themis Core.
⚠️ Please migrate to
objcthemis.framework
in a timely manner.themis.framework
is deprecated since Themis 0.13 and will be removed in the next release due to maintainability issues.ℹ️ Installations via CocoaPods are not affected. If you get Themis via CocoaPods then no action is necessary.
After upgrading to Themis 0.13 and running carthage update
you will notice that two Themis projects have been built:
*** Building scheme "OpenSSL (iOS)" in OpenSSL.xcodeproj
*** Building scheme "ObjCThemis (iOS)" in ObjCThemis.xcodeproj
*** Building scheme "Themis (iOS)" in Themis.xcodeproj
Your project is currently using “Themis”. In order to migrate to “ObjCThemis” you need to do the following:
update #import
statements in code (for Objective-C only)
link against objcthemis.framework
in Xcode project
remove link to themis.framework
in Xcode project
Use the new syntax to import ObjCThemis in Objective-C projects:
// NEW:
#import <objcthemis/objcthemis.h>
// old and deprecated:
#import <themis/themis.h>
The new syntax is now the same as used by CocoaPods.
If you are using Swift, the import syntax is unchanged:
import themis
After updating imports you also need to link against the new framework (regardless of the language).
Add objcthemis.framework
to your project (can be found in Carthage/Build/iOS
or Mac
).
For each Xcode target:
objcthemis.framework
there. Select Embed & Sign if necessary.themis.framework
from dependencies.Finally, remove themis.framework
reference from the project.
Migration is complete, your project should build successfully now.
We are sorry for the inconvenience.
JDK location is now detected automatically in most cases, you should not need to set JAVA_HOME or JDK_INCLUDE_PATH manually (#551).
JNI libraries are now available as libthemis-jni
packages for supported Linux systems (#552, #553).
Fixed a NullPointerException bug in SecureSocket
initialisation (#557).
Some Themis exceptions have been converted from checked Exception
to unchecked RuntimeException
, relaxing requirements for throws
specifiers (#563).
Introduced IKey
interface with accessors to raw key data (#564).
New class SymmetricKey
can be used to generate symmetric keys for Secure Cell (#565).
It is now possible to build desktop Java with Gradle. Run ./gradlew :desktop:tasks
to learn more (#633).
Kotlin is now officially supported language for JavaThemis (#637).
Fixed broken SecureSession#save
and SecureSession#restore
methods (#658).
Java source code is now ASCII-only for improved compatibility (#655).
Secure Cell API updates:
New encryption/decryption API with consistent naming: encrypt
and decrypt
(#634).
Improved Token Protect API (#634).
Decryption no longer requires an intermediate SecureCellData
object.
SecureCellData
can now be destructured in Kotlin (#638).
// You can now write like this:
val (encrypted, authToken) = cellTP.encrypt(message, context)
// Instead of having to spell it out like this:
val result = cellTP.protect(context, message)
val encrypted = result.protectedData
val authToken = result.additionalData
Secure Cell mode can now be selected by instantiating an appropriate interface:
New API | Old API |
---|---|
SecureCell.SealWithKey(key) |
new SecureCell(key, SecureCell.MODE_SEAL) |
SecureCell.SealWithPassphrase(passphrase) |
not available |
SecureCell.TokenProtectWithKey(key) |
new SecureCell(key, SecureCell.MODE_TOKEN_PROTECT) |
SecureCell.ContextImprintWithKey(key) |
new SecureCell(key, SecureCell.MODE_CONTEXT_IMPRINT) |
JavaThemis now supports passphrase API of in Seal mode (#635).
In Kotlin:
import com.cossacklabs.themis.SecureCell
val cell = SecureCell.SealWithPassphrase("secret")
val message = "message".toByteArray()
val encrypted = cell.encrypt(message)
val decrypted = cell.decrypt(encrypted)
assertArrayEquals(decrypted, message)
In Java:
import com.cossacklabs.themis.SecureCell;
SecureCell.Seal cell = SecureCell.SealWithPassphrase("secret");
byte[] message = "message".getBytes(StandardCharsets.UTF_8);
byte[] encrypted = cell.encrypt(message);
byte[] decrypted = cell.decrypt(encrypted);
assertArrayEquals(decrypted, message);
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing symmetric key API (SecureCell.SealWithKey(...)
or new SecureCell(...)
) should not be used with passphrases or passwords. Use symmetric key API with symmetric encryption keys, such as generated by SymmetricKey
(#565). Use passphrase API with human-readable passphrases.
Deprecated API
Secure Cell has received API overhaul which deprecates old API (#636).
The following items are deprecated:
new SecureCell(int mode)
new SecureCell(byte[] key)
new SecureCell(byte[] key, int mode)
new SecureCell(String password)
⚠️ not recommended, insecure
new SecureCell(String password, int mode)
⚠️ not recommended, insecure
protect(byte[] key, byte[] context, byte[] data)
protect(byte[] constext, byte[] data)
protect(String password, String context, byte[] data)
⚠️ not recommended, insecure
protect(String context, byte[] data)
unprotect(byte[] key, byte[] context, SecureCellData protected)
unprotect(byte[] context, SecureCellData protected)
unprotect(String password, String context, SecureCellData protected)
⚠️ not recommended, insecure
unprotect(String context, SecureCellData protected)
SecureCell.MODE_SEAL
SecureCell.MODE_TOKEN_PROTECT
SecureCell.MODE_CONTEXT_IMPRINT
Some methods are not secure when used with short passphrases, consider using new passphrase API instead. Other methods have easier to use replacements in the new API, consider using them instead.
Deprecated API is still supported, there are no plans for its removal.
SecureSession
methods save
and restore
are now deprecated (#659).
An improved API for serialisation might appear in some next version of JavaThemis. For now, please refrain from using SecureSession#save
and SecureSession#restore
which may be removed in the future.
Node.js
New class SymmetricKey
can be used to generate symmetric keys for Secure Cell (#562).
New makefile target make jsthemis
can be used to build JsThemis from source (#618).
SecureCell
now allows null
to explicitly specify omitted encryption context (#620).
SecureMessage
now allows null
for omitted keys in sign/verify mode (#620).
Fixed a crash when an exception is thrown from SecureSession
callback (#620).
Node.js v14 is now supported (#654).
Passphrase API support in Secure Cell (#621).
JsThemis now supports passphrase API of Secure Cell in Seal mode:
const themis = require('jsthemis')
let cell = themis.SecureCellSeal.withPassphrase('secret')
let encrypted = cell.encrypt(Buffer.from('message data'))
let decrypted = cell.decrypt(encrypted)
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (available as themis.SecureCellSeal.withKey(...)
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by SymmetricKey
(#562). Use passphrase API with human-readable passphrases.
Deprecated API
Secure Cell construction with new
is deprecated (#621).
Passphrase API makes it ambiguous whether a Secure Cell is initialised with a master key or a passphrase. All Secure Cell classes – SecureCellSeal
, SecureCellTokenProtect
, SecureCellContextImprint
– get a static factory method withKey
to reduce the ambiguity. Please use it instead:
// NEW, write like this:
let cell = themis.SecureCellSeal.withKey(secret)
// old, avoid this:
let cell = new themis.SecureCellSeal(secret)
new
constructors are not recommended for use but they are still supported and will always work with master keys, as they did before.
PHP
New function phpthemis_gen_sym_key()
can be used to generate symmetric keys for Secure Cell (#561).
Resolved PHP Composer checksum issues once and for all (#566, #567).
PHPThemis now supports passphrase API of Secure Cell in Seal mode (#594, #601).
$encrypted = phpthemis_scell_seal_encrypt_with_passphrase('passphrase', 'message');
$decrypted = phpthemis_scell_seal_decrypt_with_passphrase('passphrase', $encrypted);
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (phpthemis_scell_seal_{encrypt,decrypt}
and other modes) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by phpthemis_gen_sym_key()
(#561). Use passphrase API with human-readable passphrases.
Python
Fixed compatibility issues on 32-bit platforms (#555).
New function skeygen.GenerateSymmetricKey()
can be used to generate symmetric keys for Secure Cell (#561).
PyThemis now supports passphrase API of Secure Cell in Seal mode (#596).
from pythemis.scell import SCellSeal
cell = SCellSeal(passphrase='my passphrase')
encrypted = cell.encrypt(b'message data')
decrypted = cell.decrypt(encrypted)
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (SCellSeal(key=...)
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by GenerateSymmetricKey()
(#561). Use passphrase API with human-readable passphrases.
Python 2 is no longer supported (#648).
Python 2 had reached EOL on 2020-01-01.
In fact, we are not making any changes in this release that break compatibility, but we no longer officially support it. This means that we do not run any CI tests for Python 2, and in the future we will develop code compatible only with Python 3+.
Ruby
New function Themis::gen_sym_key()
can be used to generate symmetric keys for Secure Cell (#561).
Secure Cell API updates (#603).
RbThemis now supports passphrase API of Secure Cell in Seal mode:
require 'rbthemis'
cell = Themis::ScellSealPassphrase.new('secret string')
encrypted = cell.encrypt('message data')
decrypted = cell.decrypt(encrypted)
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (Themis::Scell...
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by Themis::gen_sym_key
(#561). Use passphrase API with human-readable passphrases.
Secure Cell mode can now be selected by instantiating an appropriate subclass:
New API | Old API |
---|---|
Themis::ScellSeal.new(key) |
Themis::Scell.new(key, Themis::Scell::SEAL_MODE) |
Themis::ScellSealPassphrase.new(passphrase) |
not available |
Themis::ScellTokenProtect.new(key) |
Themis::Scell.new(key, Themis::Scell::TOKEN_PROTECT_MODE) |
Themis::ScellContextImprint.new(key |
Themis::Scell.new(key, Themis::Scell::CONTEXT_IMPRINT_MODE) |
Themis::Scell
class is deprecated and should be replaced with new API.
Token Protect mode now accepts encrypted data and token as separate arguments instead of requiring an array:
decrypted = cell.decrypt([encrypted, token], context) # old
decrypted = cell.decrypt(encrypted, token, context) # new
(Arrays are still accepted for compatibility but this API is deprecated.)
Rust
New object themis::keys::SymmetricKey
can be used to generate symmetric keys for Secure Cell (#561, #631).
Significantly reduced compilation time by removing bindgen
crate from dependencies (#626).
Bindgen 0.54.1 or later is now required for RustThemis development (#664).
Passphrase API support in Secure Cell (#630).
RustThemis now supports passphrase API of Secure Cell in Seal mode:
use themis::secure_cell::SecureCell;
let cell = SecureCell::with_passphase("secret")?.seal();
let encrypted = cell.encrypt(b"message data")?;
let decrypted = cell.decrypt(&encrypted)?;
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (available as SecureCell::with_key(...)
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by themis::keys::SymmetricKey
(#561). Use passphrase API with human-readable passphrases.
Miscellaneous minor improvements in code quality (#571, #591).
WebAssembly
New class SymmetricKey
can be used to generate symmetric keys for Secure Cell (#561).
Fixed an issue with webpack Terser plugin (#568).
Updated Emscripten toolchain to the latest version (#550, #569, #602, #653).
Updated embedded BoringSSL and other dependencies to the latest versions (#608, #643).
Node.js v14 is now supported (#654).
Passphrase API support in Secure Cell (#616).
WasmThemis now supports passphrase API of Secure Cell in Seal mode:
const themis = require('wasm-themis')
let cell = themis.SecureCellSeal.withPassphrase('secret')
let encrypted = cell.encrypt(Buffer.from('message data'))
let decrypted = cell.decrypt(encrypted)
You can safely and securely use short, human-readable passphrases as strings with this new API.
Existing master key API (available as themis.SecureCellSeal.withKey(...)
) should not be used with passphrases or passwords. Use master key API with symmetric encryption keys, such as generated by SymmetricKey
(#561). Use passphrase API with human-readable passphrases.
Deprecated API
Secure Cell construction with new
is deprecated (#616).
Passphrase API makes it ambiguous whether a Secure Cell is initialised with a master key or a passphrase. All Secure Cell classes –
SecureCellSeal
, SecureCellTokenProtect
, SecureCellContextImprint
– get a static factory method withKey
to reduce the ambiguity. Please use it instead:
// NEW, write like this:
let cell = themis.SecureCellSeal.withKey(secret)
// old, avoid this:
let cell = new themis.SecureCellSeal(secret)
new
constructors are not recommended for use but they are still supported and will always work with master keys, as they did before.
Docs:
Infrastructure:
Changed name of the tarball produced by make dist
to themis_X.Y.Z.tar.gz
(#544).
Fixed Doxygen support (#559).
Automated benchmarking harness is now tracking Themis performance. See benches
(#580, #582).
Automated regular fuzzing of the code with AFL (#579, #583).
Added automated tests for all code samples in documentation, ensuring they are always up-to-date (#600).
All 13 supported platforms are verified on GitHub Actions, along with existing CircleCI and Bitrise tests (#600).
New Makefile targets:
make jsthemis
builds JsThemis from source (#618).Resolved issues with library search paths on CentOS when Themis Core is built from source and installed with make install
(#645.
Resolved issues with library search paths on Debian when Themis Core is installed from packages (#651).
Introduced ./configure
script to significantly improve rebuild performance (#611, #628).
Improved package installation testing and platform coverage (#595, #650).
Miscellaneous minor improvements and updates in the build system (#542, #573, #615, #617, #629, #627, #632, #644, #646, #649, #656).
Breaking changes
Java 7 is no longer supported (#633).
Updates in Gradle build infrastructure require Java 8.
Debian 8 “Jessie” is no longer supported (#633).
This version is no longer maintained by the Debian team and it lacks Java 8. We no longer provide binary packages for this distribution.
Python 2 is no longer supported (#648).
Python 2 had finally reached EOL on 2020-01-01. PyThemis 0.13 is the last version guaranteed to be compatible with Python 2.
Fixed an issue in WasmThemis which caused an error when packaging with webpack (#568).
This is a small change required only for Themis iOS/macOS to link themis.podspec
to correct tag.
TL;DR:
Breaking changes:
/usr
to /usr/local
. If you’re affected, read the instructions on how to make a clean upgrade below.rubythemis
gem has been completely removed in favour of rbthemis
.Code:
Core
Soter (low-level security core used by Themis)
Improved security and code quality, implemented better handling of secrets and memory management. These changes decrease the chance of potential memory leaks.
Introduced new internal function: soter_wipe()
.
It can be used to securely wipe sensitive data from memory after it's no longer needed.
All Themis cryptosystems now use this new API (#488).
Improved usage and error handling of OpenSSL/BoringSSL PRNGs. Thank you, @veorq for bringing up this issue (#485).
Improved memory safety and fixed potential corner-case issues in OpenSSL/BoringSSL usage. Thanks, @outspace for identifying these issues (#501, #524, #525, #535).
Key generation
Improved key validity checks across all Themis cryptosystems. Now it’s harder to use wrong keys or misuse them (#486).
Improved error handling for EC key generator that could produce an invalid public key without returning an error. Thanks, @vixentael for finding this issue (#500).
Secure Cell
Library ABI
Themis shared libraries now have a formal ABI version. This ensures that no compatibility issues arise if we ever need to introduce breaking changes in the ABI (#454).
Removed private symbols from public export lists. Themis has been accidentally exporting various private utility functions. Private functions not intended for public use are now hidden (#458, #472).
Themis now installs to /usr/local
by default when building from source on Linux (#448).
This may be a breaking change if your system has non-standard precedence rules. If you install Themis from source code directly, please do a clean upgrade the following way:
make uninstall PREFIX=/usr
make install PREFIX=/usr/local
Please consider using binary repositories to install Themis. If your system or package manager is not supported yet, please let us know via [email protected].
Themis packages now support multiarch installations (#512).
Multiarch enables parallel installation of 32-bit and 64-bit versions of the library. This is particularly important on CentOS where some tools like pkg-config would fail to locate Themis due to non-standard installation path.
Updated Makefile to support a number of standard GNU variables like libdir
(#453, #455).
Improved accuracy of package dependencies to make sure you don't have to install anything manually after installing Themis from package repositories (#446).
NSIS installer is now available for Windows. To build NSIS installer, use make nsis_installer
command in MSYS2 environment.
You can read more about MSYS2 target here (#474).
Dependency updates
Other changes
Android
C++
ThemisPP is now available as a system package through Cossack Labs repositories (#506).
Use
libthemispp-dev
for Debian and Ubuntu,libthemispp-devel
for CentOS.Go
Breaking changes
Some APIs have been renamed to conform with the Go naming conventions (#424).
The old names are now deprecated and scheduled for removal in the next release. Please migrate to using the new names when you upgrade.
Old API | New API |
---|---|
cell.CELL_MODE_SEAL |
cell.ModeSeal |
compare.COMPARE_MATCH |
compare.Match |
keys.KEYTYPE_EC |
keys.TypeEC |
session.STATE_ESTABLISHED |
session.StateEstablished |
(*session.SecureSession) GetRemoteId |
GetRemoteID |
GoThemis is now compatible with Go 1.11 modules starting with this release. For example, you are now able to pin a specific version of GoThemis in your projects (#505).
iOS, macOS
Java
Node.js
PHP
Ruby
Breaking changes
rubythemis
gem has been completely removed after being deprecated in Themis 0.11.
Please use require 'rbthemis'
in your projects (#508).Rust
WebAssembly
WasmThemis brings Themis to Web using WebAssembly. Thank you to @ilammy for adding it.
WasmThemis supports the full functionality of other Themis wrappers:
Secure Cell, Secure Message, Secure Session, and Secure Comparator.
WasmThemis package is available via npm as wasm-themis
,
sample code can be found in docs/examples/js,
and the How-To guide is available on the documentation server (#457, #461, #462, #473, #482, #489, #490, #491, #492,#494, #495, #498, #507, #513).
WasmThemis is tested with current Node.js LTS versions, popular Web browsers, and Electron framework. It is also tested for compatibility with other Themis wrappers (#509, #510, #511).
Windows
It is now possible to compile Themis Core for Windows using MSYS2 environment. See the instructions here (#469).
NSIS installer is now provided for the distribution of Themis on Windows. It's compatible with the new MSYS2 builds (#474).
It is now possible to compile JsThemis on Windows, given that Themis Core is installed (#475).
Miscellaneous compatibility fixes should make it possible to compile Themis Core with Microsoft Visual Studio. This platform does not have full official support yet, though (#470, #471).
Docs:
Themis GitHub Wiki is being deprecated. Please find the latest documentation for Themis on Cossack Labs Documentation Server. If you're used to using the Themis Wiki or have bookmarked a few pages for further use, don't worry - its pages and table of contents stay where they were, but each will now link to its corresponding Cossack Labs Documentation Server counterpart.
Code of Conduct has been introduced to make sure that Themis project has a welcoming environment (#518).
Improved and updated installation guides for numerous languages and platforms.
Infrastructure:
New Makefile targets and use cases:
emmake make all
builds WasmThemis in Emscripten environment (#475);make all
can be run in MSYS2 environment on Windows now (#469);make nsis_installer
builds NSIS installer for Windows binaries (#474);make deb
and make rpm
now build ThemisPP packages, too (#506);NO_NIST_STS
environment variable can be used to disable the long-running NIST statistical test suite when doing make test
(#456).Removed Makefile targets:
rubythemis
targets have been completely removed.
Use make rbthemis_install
to install RubyThemis instead (#508).Multiple updates in the way Themis is installed and packaged.
The most significant are switch to /usr/local
for installation from source code and added support for multiarch installation packages (Read more).
JsThemis and WasmThemis are now tested on all current LTS versions of Node.js (#502, #510).
Integration tests are getting stronger with WebAssembly platform being added to the suite (#511).
CI servers are now using the latest RVM for testing RubyThemis (#503, #504).