From c98b9947b4f22ca35a22d1be09ee4405edd4d314 Mon Sep 17 00:00:00 2001 From: Hugo Pointcheval Date: Wed, 5 Apr 2023 17:02:38 +0200 Subject: [PATCH] docs: update readmes/licences --- README.md | 14 +- packages/native_crypto/LICENSE | 4 +- packages/native_crypto/README.md | 134 +----------------- packages/native_crypto_android/LICENSE | 4 +- packages/native_crypto_android/README.md | 16 +-- packages/native_crypto_ios/LICENSE | 4 +- packages/native_crypto_ios/README.md | 14 +- .../README.md | 6 +- 8 files changed, 37 insertions(+), 159 deletions(-) diff --git a/README.md b/README.md index ed6621c..c01bf49 100644 --- a/README.md +++ b/README.md @@ -102,13 +102,25 @@ Please take a look a the compatibility table below to check if your target is su ## Usage +#### Compatibility + First, check compatibility with your targets. | iOS | Android | MacOS | Linux | Windows | Web | | --- | ------- | ----- | ----- | ------- | --- | | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | -> Warning: NativeCrypto 0.2.0+ is not compatible with lower NativeCrypto versions. Especially, with NativeCrypto 0.0. X because the cipher mode is not the same. Now, NativeCrypto uses AES-GCM mode instead of AES-CBC mode. (See [Changelog](./CHANGELOG.md)) +> Warning: NativeCrypto 0.2.0+ is not compatible with lower NativeCrypto versions. Especially, with NativeCrypto 0.0. X because the cipher mode is not the same. Now, NativeCrypto uses AES-GCM mode instead of AES-CBC mode. (See [Changelog](./CHANGELOG.md)) + +NativeCrypto ciphertexts are formatted as follow: + +``` ++------------------+--------------------+------------------+ +| Nonce (12 bytes) | Cipher text (n-28) | Tag (16 bytes) | ++------------------+--------------------+------------------+ +``` + +> Warning: If your data comes from another source, make sur to use the same format. #### Hash diff --git a/packages/native_crypto/LICENSE b/packages/native_crypto/LICENSE index 082d930..67b1d53 100644 --- a/packages/native_crypto/LICENSE +++ b/packages/native_crypto/LICENSE @@ -2,7 +2,7 @@ NativeCrypto MIT License -Copyright (c) 2019 - 2022 Hugo Pointcheval +Copyright (c) 2019 - 2023 Hugo Pointcheval Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -20,4 +20,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. diff --git a/packages/native_crypto/README.md b/packages/native_crypto/README.md index 507b7ec..f412888 100644 --- a/packages/native_crypto/README.md +++ b/packages/native_crypto/README.md @@ -1,133 +1,3 @@ -

- -

Fast and powerful cryptographic functions for Flutter.
-

+# NativeCrypto -

- -Style: Wyatt Analysis - - - -Maintained with Melos - - - -Build Status - -

- ---- - -[[Changelog]](./CHANGELOG.md) | [[License]](./LICENSE) - ---- - -## About - -The goal of this plugin is to provide a fast and powerful cryptographic functions by calling native libraries. On Android, it uses [javax.cypto](https://developer.android.com/reference/javax/crypto/package-summary), and on iOS, it uses [CommonCrypto](https://opensource.apple.com/source/CommonCrypto/) and [CryptoKit](https://developer.apple.com/documentation/cryptokit/) - -I started this projet because I wanted to add cryptographic functions on a Flutter app. But I faced a problem with the well-known [Pointy Castle](https://pub.dev/packages/pointycastle) library: the performance was very poor. Here some benchmarks and comparison: - -![](resources/benchmarks.png) - -For comparison, on a *iPhone 13*, you can encrypt/decrypt a message of **2MiB** in **~5.6s** with PointyCastle and in **~40ms** with NativeCrypto. And on an *OnePlus 5*, you can encrypt/decrypt a message of **50MiB** in **~6min30** with PointyCastle and in less than **~1s** with NativeCrypto. - -In short, NativeCrypto is incomparable with PointyCastle. - -## Usage - -First, check compatibility with your targets. - -| iOS | Android | MacOS | Linux | Windows | Web | -| --- | ------- | ----- | ----- | ------- | --- | -| ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | - -#### Hash - -To digest a message, you can use the following function: - -```dart -Uint8List hash = await HashAlgorithm.sha256.digest(message); -``` - -> In NativeCrypto, you can use the following hash functions: SHA-256, SHA-384, SHA-512 - -#### Keys - -You can build a `SecretKey` from a utf8, base64, base16 (hex) strings or raw bytes. You can also generate a SecretKey from secure random. - -```dart -SecretKey secretKey = SecretKey(Uint8List.fromList([0x73, 0x65, 0x63, 0x72, 0x65, 0x74])); -SecretKey secretKey = SecretKey.fromUtf8('secret'); -SecretKey secretKey = SecretKey.fromBase64('c2VjcmV0'); -SecretKey secretKey = SecretKey.fromBase16('63657274'); -SecretKey secretKey = await SecretKey.fromSecureRandom(256); -``` - -#### Key derivation - -You can derive a `SecretKey` using **PBKDF2**. - -First, you need to initialize a `Pbkdf2` object. - -```dart -Pbkdf2 pbkdf2 = Pbkdf2( - keyBytesCount: 32, - iterations: 1000, - algorithm: HashAlgorithm.sha512, -); -``` - -Then, you can derive a `SecretKey` from a password and salt. - -```dart -SecretKey secretKey = await pbkdf2.derive(password: password, salt: 'salt'); -``` - -> In NativeCrypto, you can use the following key derivation function: PBKDF2 - -#### Cipher - -And now, you can use the `SecretKey` to encrypt/decrypt a message. - -First, you need to initialize a `Cipher` object. - -```dart -AES cipher = AES(secretKey); -``` - -Then, you can encrypt your message. - -```dart -CipherTextWrapper wrapper = await cipher.encrypt(message); - -CipherText cipherText = wrapper.unwrap(); -// same as -CipherText cipherText = wrapper.single; - -// or - -List cipherTexts = wrapper.unwrap>(); -// same as -List cipherTexts = wrapper.list; -``` - -After an encryption you obtain a `CipherTextWrapper` which contains `CipherText` or `List` depending on the message size. It's up to you to know how to unwrap the `CipherTextWrapper` depending the chunk size you configured. - -Uppon receiving encrypted message, you can decrypt it. -You have to reconstruct the wrapper before decrypting. - -```dart -CipherTextWrapper wrapper = CipherTextWrapper.fromBytes( - data, - ivLength: AESMode.gcm.ivLength, - tagLength: AESMode.gcm.tagLength, -); -``` - -Then, you can decrypt your message. - -```dart -Uint8List message = await cipher.decrypt(wrapper); -``` \ No newline at end of file +Readme available at [project root](../../README.md). diff --git a/packages/native_crypto_android/LICENSE b/packages/native_crypto_android/LICENSE index dd5d33b..84320e5 100644 --- a/packages/native_crypto_android/LICENSE +++ b/packages/native_crypto_android/LICENSE @@ -2,7 +2,7 @@ NativeCrypto - Android Implementation MIT License -Copyright (c) 2019 - 2022 Hugo Pointcheval +Copyright (c) 2019 - 2023 Hugo Pointcheval Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -20,4 +20,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. diff --git a/packages/native_crypto_android/README.md b/packages/native_crypto_android/README.md index 48b93a5..0c65720 100644 --- a/packages/native_crypto_android/README.md +++ b/packages/native_crypto_android/README.md @@ -1,15 +1,13 @@ -# native_crypto_android +# NativeCrypto - Android Implementation -A new flutter plugin project. +Android Implementation of [NativeCrypto][1] Plugin. ## Getting Started -This project is a starting point for a Flutter -[plug-in package](https://flutter.dev/developing-packages/), -a specialized package that includes platform-specific implementation code for -Android and/or iOS. +This project is a starting point for a Flutter [plug-in package][2], a specialized package that includes platform-specific implementation code for Android and/or iOS. -For help getting started with Flutter, view our -[online documentation](https://flutter.dev/docs), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +For help getting started with Flutter, view our [online documentation][3], which offers tutorials, samples, guidance on mobile development, and a full API reference. +[1]: ../../README.md +[2]: https://flutter.dev/developing-packages/ +[3]: https://flutter.dev/docs diff --git a/packages/native_crypto_ios/LICENSE b/packages/native_crypto_ios/LICENSE index 8c5c1f7..d243b55 100644 --- a/packages/native_crypto_ios/LICENSE +++ b/packages/native_crypto_ios/LICENSE @@ -2,7 +2,7 @@ NativeCrypto - iOS Implementation MIT License -Copyright (c) 2019 - 2022 Hugo Pointcheval +Copyright (c) 2019 - 2023 Hugo Pointcheval Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -20,4 +20,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. diff --git a/packages/native_crypto_ios/README.md b/packages/native_crypto_ios/README.md index a60dd49..beb7c0e 100644 --- a/packages/native_crypto_ios/README.md +++ b/packages/native_crypto_ios/README.md @@ -1,15 +1,13 @@ # NativeCrypto - iOS Implementation -iOS Implementation of NativeCrypto Plugin. +iOS Implementation of [NativeCrypto][1] Plugin. ## Getting Started -This project is a starting point for a Flutter -[plug-in package](https://flutter.dev/developing-packages/), -a specialized package that includes platform-specific implementation code for -Android and/or iOS. +This project is a starting point for a Flutter [plug-in package][2], a specialized package that includes platform-specific implementation code for Android and/or iOS. -For help getting started with Flutter, view our -[online documentation](https://flutter.dev/docs), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +For help getting started with Flutter, view our [online documentation][3], which offers tutorials, samples, guidance on mobile development, and a full API reference. +[1]: ../../README.md +[2]: https://flutter.dev/developing-packages/ +[3]: https://flutter.dev/docs diff --git a/packages/native_crypto_platform_interface/README.md b/packages/native_crypto_platform_interface/README.md index 4aec31b..07bd2a9 100644 --- a/packages/native_crypto_platform_interface/README.md +++ b/packages/native_crypto_platform_interface/README.md @@ -1,12 +1,12 @@ # NativeCrypto - Platform Interface -A common platform interface for the [`native_crypto`][1] plugin. +A common platform interface for the [NativeCrypto][1] plugin. This interface allows platform-specific implementations of the `native_crypto` plugin, as well as the plugin itself, to ensure they are supporting the same interface. ## Usage -To implement a new platform-specific implementation of `native_crypto`, extend [`NativeCryptoPlatform`][2] with an implementation that performs the platform-specific behavior, and when you register your plugin, set the default `NativeCryptoPlatform` by calling `NativeCryptoPlatform.instance = MyNativeCryptoPlatform()`. +To implement a new platform-specific implementation of `native_crypto`, extend [`NativeCryptoPlatform`][1] with an implementation that performs the platform-specific behavior, and when you register your plugin, set the default `NativeCryptoPlatform` by calling `NativeCryptoPlatform.instance = MyNativeCryptoPlatform()`. ## Pigeon @@ -16,5 +16,5 @@ Run generator with `flutter pub run pigeon --input pigeons/messages.dart`. > Note: Make sure the `lib/src/gen` folder exists before running the generator. -[1]: ../native_crypto +[1]: ../../README.md [2]: lib/native_crypto_platform_interface.dart