crypto2/README.md

# Crypto2

Kotlin Multiplatform cryptographic primitives using modern strong cryptography.

Cryptographic API works exactly the same and compiles to any platform supported listed below with no change in source code.

All primitives meant to send over the network or store are `kotlinx.serialization` compatible, serializers included.

# Important notes on upgrade

___Please upgrade to 0.7.1+___ as it has much more compact but not backward-compatible serialization format!

Since version __0.5.*__ key identity calculation for asymmetric keys is updated
to make it safer for theoretic future attack on blake2b hashing. Key.id values
are incompatible with older. Sorry for inconvenience.

# Usage

```kotlin
repositories {
  maven("https://gitea.sergeych.net/api/packages/SergeychWorks/maven")
}
dependencies {
  import("net.sergeych:crypto2:0.7.1-SNAPSHOT")  
}
```

# Documentation

Please see the current documentation [here](https://code.sergeych.net/docs/crypto2/).

# Supported platforms:

## Javascript

- All moder browsers, including mobile
- Node.js

## WasmJs

- All moder browsers, including mobile

## JVM

- Android
- Linux
- Windows
- MacOSX

## Native Apple platforms:

- IOS ARM64, X64, Simulator ARM64
- Macos ARM64, MacOS X64

## Native Windows

- Mingw X64

## Native Linux platforms

- Linux Arm64
- Linux X64

# Cryptographic primitives

## Diffie-Hellman safe key exchange

Using X25519 curves, it generates two symmetric keys with XSalsa20+Poly1305 for independent p2p ciphers and session token, same on both sides.

## Multi-signed container

A container with random binary or `kolinx.serialized` data, signed with one or more Ed25519 secret keys. Signatures could be added sequentially, each signature contains timestamp and the optional expiration. __Blake2b__ fast and strong hashing is used.

Signatures include public keys (as these are short for Ed25519) which can be used to easily identify the signing party.

## Multi-key encrypted contained.

The `koltlinx.serialized` message intended to be readable by owner of one of an arbitrary numbed of keys. Supports the following keys:
 
- __symmetric keys__ with XSalsa20+Poly1305
- Secret/Public keys Ed25519.
- password-derived keys (PBKDF generation parameters are stored in the container so the key could be derived from the password)

Once the container is decrypted with any of the intended keys, it could be re-encrypted with new data and/or new destination keys, keeping all existing keys events not having them. E.g., it allows "reply all" function even when not all recipients are known and even if the symmetric key cryptography is used. 

The proper keys are retrieved from the keyring (below) automatically.

## Keyring

Collection of various type keys:

- Signing/verifying Ed25519, 
- Secret decrypting and public encrypting 25519 
- symmetric XSalsa20
- session (pair of XSalsa20)

Keys could be associated with tags. Keyrings are used primarily to store keys in the encrypted containers (above) and to encrypt/decrypt it.

## Key derivation/password key derivation

Using very strong Argon_v2id, and adjustable complexity. Allows storing password key derivation parameters (included in the generated symmetric keys) to re-derive keys later, allows multiple keys derivation. All structures meant to be stored are serializable.

## Unified keys hierarchy

Allows the application code to use proper key abstraction and work with more key types in the future, e.g. `SigningKey`, `VerifyingKey`, `EncryptingKey` and `DecryptingKey`. Effective key generation and random byte sequence producers.

Secret key encryption and signing/verifying uses Edwards curves 25519 algorithms.


## Various tools

- Some Popular cryptographic hashes:
  - Blake2b
  - SHA3 256, 384, more are on the way.
- CRC-protected binary ID with magic numbers to implement human-friendly IDS with type checks

## Licensing

# Licensing

This is work in progress, not yet moved to public domain;
you need to obtain a license from https://8-rays.dev or [Sergey Chernov]. For open source projects it will most be free on some special terms.

It will be moved to open source; we also guarantee that it will be moved to open source immediately if the software export restrictions will be lifted. We do not support such practices here at 8-rays.dev and assume open source must be open.

[Sergey Chernov]: https://t.me/real_sergeych