diff --git a/cryptography/CHANGELOG.md b/cryptography/CHANGELOG.md index 5ab0a8b..f9bbb73 100644 --- a/cryptography/CHANGELOG.md +++ b/cryptography/CHANGELOG.md @@ -1,3 +1,8 @@ +## 2.1.1 + +* Fixes small issues. +* Improves documentation. + ## 2.1.0 * Improves performance of Blake2b/Blake2s. diff --git a/cryptography/README.md b/cryptography/README.md index c24ff1e..2e3e136 100644 --- a/cryptography/README.md +++ b/cryptography/README.md @@ -23,7 +23,8 @@ Any feedback, issue reports, or pull requests are appreciated! ## Some packages that depend on this * [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). - * Android / iOS cryptography support. + * Improves performance in Flutter in some cases. This is done by moving computations away from + the UI isolate. * [jwk](https://pub.dev/packages/jwk) * JWK (JSON Web Key) support. @@ -197,7 +198,7 @@ dependencies: If you use Flutter, you may consider using [cryptography_flutter](https://pub.dev/packages/cryptography_flutter) for improving performance by -moving computations away from the UI thread. +moving computations away from the UI isolate. # Examples ## Digital signature diff --git a/cryptography/lib/helpers.dart b/cryptography/lib/helpers.dart index e44cad0..081eef7 100644 --- a/cryptography/lib/helpers.dart +++ b/cryptography/lib/helpers.dart @@ -335,6 +335,9 @@ abstract class DelegatingKeyExchangeAlgorithm extends _Delegating @override KeyExchangeAlgorithm get fallback; + @override + KeyPairType get keyPairType => fallback.keyPairType; + @override Future newKeyPair() { return fallback.newKeyPair(); diff --git a/cryptography/lib/src/cryptography/algorithms.dart b/cryptography/lib/src/cryptography/algorithms.dart index 3859bbb..4b543b5 100644 --- a/cryptography/lib/src/cryptography/algorithms.dart +++ b/cryptography/lib/src/cryptography/algorithms.dart @@ -7,11 +7,13 @@ import 'package:meta/meta.dart'; /// _AES-CBC_ (cipher block chaining mode) [Cipher]. /// -/// ## Available implementation -/// * In browsers, [BrowserAesCbc] is used by default. -/// * Otherwise [DartAesCbc] is used by default. -/// * The package [cryptography_flutter](https://pub.dev/packages/cryptography_flutter) -/// supports native implementation available in Android. +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartAesCbc] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. /// /// ## Things to know /// * Three possible key lengths: @@ -62,6 +64,7 @@ abstract class AesCbc extends Cipher { @protected const AesCbc.constructor(); + /// Constructs 128-bit AES-CBC. factory AesCbc.with128bits({required MacAlgorithm macAlgorithm}) { return AesCbc._( macAlgorithm: macAlgorithm, @@ -69,6 +72,7 @@ abstract class AesCbc extends Cipher { ); } + /// Constructs 192-bit AES-CBC. factory AesCbc.with192bits({required MacAlgorithm macAlgorithm}) { return AesCbc._( macAlgorithm: macAlgorithm, @@ -76,6 +80,7 @@ abstract class AesCbc extends Cipher { ); } + /// Constructs 256-bit AES-CBC. factory AesCbc.with256bits({required MacAlgorithm macAlgorithm}) { return AesCbc._( macAlgorithm: macAlgorithm, @@ -113,11 +118,13 @@ abstract class AesCbc extends Cipher { /// _AES-CTR_ (counter mode) [Cipher]. /// -/// ## Available implementation -/// * In browsers, [BrowserAesCtr] is used by default. -/// * Otherwise [DartAesCtr] is used by default. -/// * The package [cryptography_flutter](https://pub.dev/packages/cryptography_flutter) -/// supports native implementation available in Android. +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartAesCtr] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. /// /// ## Things to know /// * Three possible key lengths: @@ -170,6 +177,7 @@ abstract class AesCtr extends StreamingCipher { @protected const AesCtr.constructor(); + /// Constructs 128-bit AES-CTR. factory AesCtr.with128bits({ required MacAlgorithm macAlgorithm, }) { @@ -179,6 +187,7 @@ abstract class AesCtr extends StreamingCipher { ); } + /// Constructs 192-bit AES-CTR. factory AesCtr.with192bits({ required MacAlgorithm macAlgorithm, }) { @@ -188,6 +197,7 @@ abstract class AesCtr extends StreamingCipher { ); } + /// Constructs 256-bit AES-CTR. factory AesCtr.with256bits({ required MacAlgorithm macAlgorithm, }) { @@ -230,13 +240,13 @@ abstract class AesCtr extends StreamingCipher { /// _AES-GCM_ (Galois/Counter Mode) [Cipher]. /// -/// ## Available implementation -/// * In browsers, [BrowserAesGcm] is used by default. -/// * Otherwise [DartAesGcm] is used by default. -/// * The package [cryptography_flutter](https://pub.dev/packages/cryptography_flutter) -/// supports AES-GCM operating system APIs available in Android and iOS. -/// __We recommend you use "package:cryptography_flutter" for the best -/// performance and easier cryptographic compliance.__ +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartAesGcm] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. /// /// ## Things to know /// * Three possible key lengths: @@ -353,6 +363,8 @@ abstract class AesGcm extends StreamingCipher { /// algorithm can provide much better security than older algorithms such as /// [Pbkdf2]. /// +/// By default, [DartArgon2id] will be used. +/// /// ## Example /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -453,6 +465,8 @@ abstract class Argon2id extends KdfAlgorithm { /// _BLAKE2B_ ([RFC 7693](https://tools.ietf.org/html/rfc7693)) [HashAlgorithm]. /// +/// By default, [DartBlake2b] will be used. +/// /// ## Asynchronous usage /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -488,12 +502,6 @@ abstract class Argon2id extends KdfAlgorithm { /// print('Hash: ${hash.bytes}'); /// } /// ``` -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartBlake2b] in -/// _package:cryptography/dart.dart_. -/// abstract class Blake2b extends HashAlgorithm { factory Blake2b() { return Cryptography.instance.blake2b(); @@ -518,6 +526,8 @@ abstract class Blake2b extends HashAlgorithm { /// _BLAKE2S_ ([RFC 7693](https://tools.ietf.org/html/rfc7693)) [HashAlgorithm]. /// +/// By default, [DartBlake2s] will be used. +/// /// ## Asynchronous usage /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -530,8 +540,6 @@ abstract class Blake2b extends HashAlgorithm { /// } /// ``` /// -/// If you need synchronous computations, use [DartBlake2s]. -/// /// ## Streaming usage /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -554,11 +562,6 @@ abstract class Blake2b extends HashAlgorithm { /// } /// ``` /// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartBlake2s] in -/// _package:cryptography/dart.dart_. -/// abstract class Blake2s extends HashAlgorithm { factory Blake2s() { return Cryptography.instance.blake2s(); @@ -585,15 +588,21 @@ abstract class Blake2s extends HashAlgorithm { /// [StreamingCipher]. /// /// In almost every case, you should use constructor [Chacha20.poly1305Aead], -/// which does message authentication with a standard AEAD construction for -/// _ChaCha20_. The AEAD version of ChaCha20 is used by most protocols and -/// operating system APIs. +/// which returns _AEAD_CHACHA20_POLY1305_ cipher +/// (([RFC 7539](https://tools.ietf.org/html/rfc7539)). +/// +/// By default, [DartChacha20] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. /// /// ## Things to know /// * [secretKeyLength] is 32 bytes. /// * [nonceLength] is 12 bytes. -/// * Associated Authenticated Data (AAD) is supported by -/// [Chacha20.poly1305Aead]. +/// * If you use [Chacha20.poly1305Aead], then: +/// * MAC length is 16 bytes. +/// * Associated Authenticated Data (AAD) is supported. /// /// ## Example /// ```dart @@ -602,7 +611,7 @@ abstract class Blake2s extends HashAlgorithm { /// Future main() async { /// final message = [1,2,3]; /// -/// final algorithm = Chacha20(macAlgorithm: Hmac.sha256()); +/// final algorithm = Chacha20.poly1305(); /// final secretKey = await algorithm.newSecretKey(); /// /// // Encrypt @@ -623,16 +632,12 @@ abstract class Blake2s extends HashAlgorithm { /// } /// ``` /// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartChacha20] in -/// _package:cryptography/dart.dart_. -/// abstract class Chacha20 extends StreamingCipher { /// Constructs a ChaCha20 with any MAC. /// - /// Usually you should use [Chacha20.poly1305Aead()], which implements - /// AEAD version of the algorithm. + /// In almost every case, you should use constructor [Chacha20.poly1305Aead], + /// which returns _AEAD_CHACHA20_POLY1305_ cipher + /// (([RFC 7539](https://tools.ietf.org/html/rfc7539)). factory Chacha20({required MacAlgorithm macAlgorithm}) { return Cryptography.instance.chacha20(macAlgorithm: macAlgorithm); } @@ -641,16 +646,11 @@ abstract class Chacha20 extends StreamingCipher { @protected const Chacha20.constructor(); - /// _AEAD_CHACHA20_POLY1305_ ([https://tools.ietf.org/html/rfc7539](RFC 7539)) - /// [Cipher]. - /// - /// The returned cipher has-builtin [macAlgorithm] that calculates a 128-bit - /// MAC. AAD (Associated Authenticated Data) is supported by [encrypt()] and - /// [decrypt()]. + /// Constructs _AEAD_CHACHA20_POLY1305_ cipher + /// (([RFC 7539](https://tools.ietf.org/html/rfc7539)). /// - /// ## Things to know - /// * [secretKeyLength] is 32 bytes. - /// * [nonceLength] is 12 bytes.\ + /// The default implementation is [DartChacha20.poly1305Aead], which uses + /// [DartChacha20Poly1305AeadMacAlgorithm]. factory Chacha20.poly1305Aead() { return Cryptography.instance.chacha20Poly1305Aead(); } @@ -679,37 +679,42 @@ abstract class Chacha20 extends StreamingCipher { /// ECDH with P-256 / P-384 / P-521 elliptic curve. /// -/// Private keys can be instances of [EcSecretKey] or implementation-specific -/// subclasses of [SecretKey]. +/// Private keys must be instances of [EcKeyPair]. +/// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartEcdh] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. +/// +/// ## Things to know +/// * Private keys are instances of [EcKeyPair]. +/// * Public keys are instances of [EcPublicKey]. +/// * You can use [package:jwk](https://pub.dev/packages/jwk) to encode/decode +/// JSON Web Key (JWK) data. /// /// ## Example -/// ``` +/// ```dart /// import 'package:cryptography/cryptography.dart'; /// /// Future main() async { -/// // In this example, we use P-256 curve. /// final algorithm = Ecdh.p256(); /// -/// // Alice generates a key pair for herself. -/// final aliceSecretKey = await algorithm.newSecretKey(); -/// final alicePublicKey = await algorithm.publicKey(aliceSecretKey); +/// // We need the private key pair of Alice. +/// final aliceKeyPair = await algorithm.newKeyPair(); /// -/// // Bob generates a key pair for himself. -/// final bobSecretKey = await algorithm.newSecretKey(); -/// final bobPublicKey = await algorithm.publicKey(bobSecretKey); +/// // We need only public key of Bob. +/// final bobKeyPair = await algorithm.newKeyPair(); +/// final bobPublicKey = await bobKeyPair.extractPublicKey(); /// -/// // Each party calculates shared secret. -/// // Parties get the same symmetric key as a result. -/// final keyForAlice = await algorithm.sharedSecretKey( -/// localSecretKey: alicePublicKey, +/// // We can now calculate a 32-byte shared secret key. +/// final sharedSecretKey = await algorithm.sharedSecretKey( +/// keyPair: aliceKeyPair, /// remotePublicKey: bobPublicKey, /// ); -/// final keyForBob = await algorithm.sharedSecretKey( -/// localSecretKey: bobSecretKey, -/// remotePublicKey: alicePublicKey, -/// ); /// } -/// ``` abstract class Ecdh extends KeyExchangeAlgorithm { /// Constructor for classes that extend this class. @protected @@ -756,8 +761,21 @@ abstract class Ecdh extends KeyExchangeAlgorithm { /// [RFC 6090](https://www.ietf.org/rfc/rfc6090.txt) /// ("Fundamental Elliptic Curve Cryptography Algorithms"). /// -/// Secret keys can be instances of [EcSecretKey] or implementation-specific -/// subclasses of [SecretKey]. +/// Key pairs must be instances of [EcKeyPair]. +/// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartEcdsa] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. +/// +/// ## Things to know +/// * Private keys are instances of [EcKeyPair]. +/// * Public keys are instances of [EcPublicKey]. +/// * You can use [package:jwk](https://pub.dev/packages/jwk) to encode/decode +/// JSON Web Key (JWK) data. /// /// ## Example /// ``` @@ -833,20 +851,20 @@ abstract class Ecdsa extends SignatureAlgorithm { /// _Ed25519_ ([RFC 8032](https://tools.ietf.org/html/rfc8032)) signature /// algorithm. /// -/// ## Available implementation -/// * [DartEd25519] is used by default. -/// * The package [cryptography_flutter](https://pub.dev/packages/cryptography_flutter) -/// supports ED25519 operating system APIs available in Android and iOS. -/// __We recommend you use "package:cryptography_flutter" for the best -/// performance and easier cryptographic compliance.__ +/// By default, [DartEd25519] will be used. +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. /// /// ## Things to know -/// * Private key is any 32-byte sequence. -/// * Public key is 32 bytes. -/// * Signatures are 64 bytes. +/// * Private key is any 32 bytes ([SimpleKeyPair]). +/// * Public key is 32 bytes ([SimplePublicKey]). +/// * Output is 32 bytes. /// * RFC 8032 says that the signatures are deterministic, but some widely /// used implementations such as Apple CryptoKit return non-deterministic /// signatures. +/// * You can use [package:jwk](https://pub.dev/packages/jwk) to encode/decode +/// JSON Web Key (JWK) data. /// /// ## Example /// ``` @@ -934,13 +952,17 @@ abstract class Hchacha20 { /// _HKDF_ ([RFC 5869](https://tools.ietf.org/html/rfc5869)) /// key derivation algorithm. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartHkdf] will be used. +/// /// ## Example /// ``` /// import 'package:cryptography/cryptography.dart'; /// /// void main() async { /// final algorithm = Hkdf( -/// hmac: Hmac(Sha256()), +/// hmac: Hmac.sha256(), /// outputLength: 32, /// ); /// final secretKey = SecretKey([1,2,3]); @@ -987,14 +1009,18 @@ abstract class Hkdf extends KdfAlgorithm { /// _HMAC_ [MacAlgorithm]. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartHmac] will be used. +/// /// You should use: -/// * [Hmac.sha1()] for _HMAC-SHA1_. -/// * [Hmac.sha256()] for _HMAC-SHA256_. -/// * [Hmac.sha512()] for _HMAC-SHA512_. +/// * [Hmac.sha1] for _HMAC-SHA1_. +/// * [Hmac.sha256] for _HMAC-SHA256_. +/// * [Hmac.sha512] for _HMAC-SHA512_. /// * For other combinations, give hash algorithm in the constructor /// (example: `Hmac(Blake2s())`). /// -/// If you need synchronous computations, use [DartHmac]. +/// If you really need synchronous computations, use [DartHmac]. /// /// ## Example /// ``` @@ -1056,6 +1082,10 @@ abstract class Hmac extends MacAlgorithm { /// _PBKDF2_ password hashing algorithm implemented in pure Dart. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartPbkdf2] will be used. +/// /// ## Things to know /// * `macAlgorithm` can be any [MacAlgorithm] (such as [Hmac.sha256()]). /// * `iterations` should be at least 100 000 for reasonable security in @@ -1160,11 +1190,15 @@ abstract class Poly1305 extends MacAlgorithm { /// _RSA-PSS_ [SignatureAlgorithm]. /// -/// Secret keys can be instances of [RsaKeyPairData]. -/// Some implementations may support other subclasses [SecretKey]. -/// For example, _Web Cryptography API_ supports opaque non-exportable keys. +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartRsaPss] will be used. /// -/// Public keys should be instances of [RsaPublicKey]. +/// Private keys must be instances of [RsaKeyPair]. +/// Public keys must be instances of [RsaPublicKey]. +/// +/// You can use [package:jwk](https://pub.dev/packages/jwk) to encode/decode +/// JSON Web Key (JWK) data. /// /// ## Example /// ``` @@ -1237,11 +1271,15 @@ abstract class RsaPss extends SignatureAlgorithm { /// _RSA-SSA-PKCS1v15_ [SignatureAlgorithm]. /// -/// Secret keys can be instances of [RsaKeyPairData]. -/// Some implementations may support other subclasses [SecretKey]. -/// For example, _Web Cryptography API_ supports opaque non-exportable keys. +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartRsaSsaPkcs1v15] will be used. +/// +/// Private keys must be instances of [RsaKeyPair]. +/// Public keys must be instances of [RsaPublicKey]. /// -/// Public keys should be instances of [RsaPublicKey]. +/// You can use [package:jwk](https://pub.dev/packages/jwk) to encode/decode +/// JSON Web Key (JWK) data. /// /// ## Example /// ``` @@ -1307,6 +1345,10 @@ abstract class RsaSsaPkcs1v15 extends SignatureAlgorithm { /// _SHA-1_ [HashAlgorithm]. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartSha1] will be used. +/// /// ## Asynchronous usage (recommended) /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -1319,7 +1361,7 @@ abstract class RsaSsaPkcs1v15 extends SignatureAlgorithm { /// } /// ``` /// -/// If you need synchronous computations, use [DartSha1]. +/// If you really need synchronous computations, use [DartSha1]. /// /// ## Streaming usage /// This enables you to handle very large inputs without keeping everything in @@ -1342,12 +1384,6 @@ abstract class RsaSsaPkcs1v15 extends SignatureAlgorithm { /// print('Hash: ${hash.bytes}'); /// } /// ``` -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartSha1] in -/// _package:cryptography/dart.dart_. -/// abstract class Sha1 extends HashAlgorithm { factory Sha1() => Cryptography.instance.sha1(); @@ -1373,6 +1409,8 @@ abstract class Sha1 extends HashAlgorithm { /// _SHA-224_ (SHA2-224) [HashAlgorithm]. /// +/// By default, [DartSha224] will be used. +/// /// ## Asynchronous usage (recommended) /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -1385,7 +1423,7 @@ abstract class Sha1 extends HashAlgorithm { /// } /// ``` /// -/// If you need synchronous computations, use [DartSha224]. +/// If you really need synchronous computations, use [DartSha224]. /// /// ## Streaming usage /// This enables you to handle very large inputs without keeping everything in @@ -1408,12 +1446,6 @@ abstract class Sha1 extends HashAlgorithm { /// print('Hash: ${hash.bytes}'); /// } /// ``` -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartSha224] in -/// _package:cryptography/dart.dart_. -/// abstract class Sha224 extends HashAlgorithm { factory Sha224() => Cryptography.instance.sha224(); @@ -1439,6 +1471,10 @@ abstract class Sha224 extends HashAlgorithm { /// _SHA-256_ (SHA2-256) [HashAlgorithm]. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartSha256] will be used. +/// /// ## Asynchronous usage (recommended) /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -1451,7 +1487,7 @@ abstract class Sha224 extends HashAlgorithm { /// } /// ``` /// -/// If you need synchronous computations, use [DartSha256]. +/// If you really need synchronous computations, use [DartSha256]. /// /// ## Streaming usage /// This enables you to handle very large inputs without keeping everything in @@ -1474,12 +1510,6 @@ abstract class Sha224 extends HashAlgorithm { /// print('Hash: ${hash.bytes}'); /// } /// ``` -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartSha256] in -/// _package:cryptography/dart.dart_. -/// abstract class Sha256 extends HashAlgorithm { factory Sha256() => Cryptography.instance.sha256(); @@ -1505,6 +1535,10 @@ abstract class Sha256 extends HashAlgorithm { /// _SHA-384_ (SHA2-384) [HashAlgorithm]. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartSha384] will be used. +/// /// ## Asynchronous usage (recommended) /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -1517,7 +1551,7 @@ abstract class Sha256 extends HashAlgorithm { /// } /// ``` /// -/// If you need synchronous computations, use [DartSha384]. +/// If you really need synchronous computations, use [DartSha384]. /// /// ## Streaming usage /// This enables you to handle very large inputs without keeping everything in @@ -1540,12 +1574,6 @@ abstract class Sha256 extends HashAlgorithm { /// print('Hash: ${hash.bytes}'); /// } /// ``` -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartSha384] in -/// _package:cryptography/dart.dart_. -/// abstract class Sha384 extends HashAlgorithm { factory Sha384() => Cryptography.instance.sha384(); @@ -1571,6 +1599,10 @@ abstract class Sha384 extends HashAlgorithm { /// _SHA-512_ (SHA2-512) [HashAlgorithm]. /// +/// On browsers, the default implementation will use +/// [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). +/// On other platforms, [DartSha512] will be used. +/// /// ## Asynchronous usage (recommended) /// ``` /// import 'package:cryptography/cryptography.dart'; @@ -1583,7 +1615,7 @@ abstract class Sha384 extends HashAlgorithm { /// } /// ``` /// -/// If you need synchronous computations, use [DartSha512]. +/// If you really need synchronous computations, use [DartSha512]. /// /// ## Streaming usage /// This enables you to handle very large inputs without keeping everything in @@ -1606,12 +1638,6 @@ abstract class Sha384 extends HashAlgorithm { /// print('Hash: ${hash.bytes}'); /// } /// ``` -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartSha512] in -/// _package:cryptography/dart.dart_. -/// abstract class Sha512 extends HashAlgorithm { factory Sha512() => Cryptography.instance.sha512(); @@ -1636,7 +1662,7 @@ abstract class Sha512 extends HashAlgorithm { } /// Superclass of streaming ciphers such as [AesGcm] and [Chacha20] that allow -/// encrypter/decrypter to choose offset in the keystream. +/// encrypter/decrypter to choose an offset in the keystream. abstract class StreamingCipher extends Cipher { const StreamingCipher(); @@ -1674,37 +1700,38 @@ abstract class StreamingCipher extends Cipher { /// X25519 is an elliptic curve Diffie-Hellman key exchange algorithm that uses /// Curve25519. /// -/// ## Available implementation -/// * [DartX25519] is used by default. -/// * The package [cryptography_flutter](https://pub.dev/packages/cryptography_flutter) -/// supports X25519 operating system APIs available in Android and iOS. -/// __We recommend you use "package:cryptography_flutter" for the best -/// performance and easier cryptographic compliance.__ +/// By default, [DartX25519] will be used. +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. /// /// ## Things to know -/// * Private key is any 32-byte sequence. -/// * Public key is 32 bytes. +/// * Private key is any 32 bytes ([SimpleKeyPair]). +/// * Public key is 32 bytes ([SimplePublicKey]). /// * Output is 32 bytes. +/// * You can use [package:jwk](https://pub.dev/packages/jwk) to encode/decode +/// JSON Web Key (JWK) data. /// /// ## Example -/// ```dart +/// ``` /// import 'package:cryptography/cryptography.dart'; /// /// Future main() async { -/// final algorithm = Cryptography.instance.x25519(); +/// final algorithm = X25519(); /// -/// // Let's generate two keypairs. -/// final keyPair = await algorithm.newKeyPair(); -/// final remoteKeyPair = await algorithm.newKeyPair(); -/// final remotePublicKey = await remoteKeyPair.extractPublicKey(); +/// // We need the private key pair of Alice. +/// final aliceKeyPair = await algorithm.newKeyPair(); +/// +/// // We need only public key of Bob. +/// final bobKeyPair = await algorithm.newKeyPair(); +/// final bobPublicKey = await bobKeyPair.extractPublicKey(); /// -/// // We can now calculate the shared secret key +/// // We can now calculate a 32-byte shared secret key. /// final sharedSecretKey = await algorithm.sharedSecretKey( -/// keyPair: keyPair, -/// remotePublicKey: remotePublicKey, +/// keyPair: aliceKeyPair, +/// remotePublicKey: bobPublicKey, /// ); /// } -/// ``` /// /// ## In need of synchronous APIs? /// @@ -1740,22 +1767,18 @@ abstract class X25519 extends KeyExchangeAlgorithm { /// The only difference between _Xchacha20_ and [Chacha20] is that _Xchacha20_ /// uses 192-bit nonces whereas _Chacha20_ uses 96-bit nonces. /// +/// By default, [DartXchacha20] will be used. +/// +/// If you use Flutter, you can enable +/// [cryptography_flutter](https://pub.dev/packages/cryptography_flutter). +/// It can improve performance in many cases. +/// /// ## Things to know /// * [SecretKey] must be 32 bytes. /// * [Nonce] must be 24 bytes. /// * `keyStreamIndex` enables choosing index in the key stream. /// * It's dangerous to use the same (key, nonce) combination twice. /// * It's dangerous to use the cipher without authentication. -/// -/// ## Example -/// -/// See [chacha20]. -/// -/// ## In need of synchronous APIs? -/// -/// If you need to perform operations synchronously, use [DartXchacha20] in -/// _package:cryptography/dart.dart_. -/// abstract class Xchacha20 extends StreamingCipher { factory Xchacha20({required MacAlgorithm macAlgorithm}) { // ignore: deprecated_member_use_from_same_package diff --git a/cryptography/lib/src/cryptography/key_exchange_algorithm.dart b/cryptography/lib/src/cryptography/key_exchange_algorithm.dart index 67cf6d0..8e977d2 100644 --- a/cryptography/lib/src/cryptography/key_exchange_algorithm.dart +++ b/cryptography/lib/src/cryptography/key_exchange_algorithm.dart @@ -30,7 +30,7 @@ import 'package:cryptography/cryptography.dart'; /// Future main() async { /// // Generate a key pair. /// final algorithm = X25519(); -/// final keyPair = await algorithm.keyGenerator.newKeyPair(); +/// final keyPair = await algorithm.newKeyPair(); /// /// // Get a public key for our peer. /// final remoteKeyPair = await algorithm.keyGenerator.newKeyPair(); @@ -50,11 +50,40 @@ abstract class KeyExchangeAlgorithm { KeyPairType get keyPairType; - /// Generates a new [KeyPair] for this algorithm. + /// Generates a new [KeyPair] that can be used with this algorithm. /// - /// You can pass key generation preferences by specifying `options`. + /// ## Example + /// In this example, we use [X25519]: + /// ```dart + /// import 'package:cryptography/cryptography.dart'; + /// + /// Future main() async { + /// final algorithm = X25519(); + /// final keyPair = await algorithm.newKeyPair(); + /// } + ///``` Future newKeyPair(); + /// Generates a key pair from the seed. + /// + /// Throws [UnsupportedError] if the algorithm does not support generating + /// key pairs deterministically from the seed + /// + /// ## Example + /// In this example, we use [X25519] class: + /// ```dart + /// import 'dart:convert'; + /// import 'package:cryptography/cryptography.dart'; + /// + /// Future main() async { + /// // X25519 seed is any 32 bytes. + /// // We can use SHA256, which computes a 32-byte hash from any input. + /// final seed = (await Sha256().hash(utf8.encode('example'))).bytes; + /// + /// final algorithm = X25519(); + /// final keyPair = await algorithm.newKeyPairFromSeed(seed); + /// } + ///``` Future newKeyPairFromSeed(List seed) { throw UnsupportedError( 'newKeyPairFromSeed() is unsupported by this algorithm', @@ -62,6 +91,29 @@ abstract class KeyExchangeAlgorithm { } /// Calculates a shared [SecretKey]. + /// + /// ## Example + /// In this example, we use [X25519] class: + /// ```dart + /// import 'package:cryptography/cryptography.dart'; + /// + /// Future main() async { + /// final algorithm = X25519(); + /// + /// // We need the private key pair of Alice. + /// final aliceKeyPair = await algorithm.newKeyPair(); + /// + /// // We need only public key of Bob. + /// final bobKeyPair = await algorithm.newKeyPair(); + /// final bobPublicKey = await bobKeyPair.extractPublicKey(); + /// + /// // We can now calculate a 32-byte shared secret key. + /// final sharedSecretKey = await algorithm.sharedSecretKey( + /// keyPair: aliceKeyPair, + /// remotePublicKey: bobPublicKey, + /// ); + /// } + /// ``` Future sharedSecretKey({ required KeyPair keyPair, required PublicKey remotePublicKey, diff --git a/cryptography/lib/src/cryptography/signature_algorithm.dart b/cryptography/lib/src/cryptography/signature_algorithm.dart index f9fe487..65c2ed5 100644 --- a/cryptography/lib/src/cryptography/signature_algorithm.dart +++ b/cryptography/lib/src/cryptography/signature_algorithm.dart @@ -34,7 +34,7 @@ import 'package:cryptography/cryptography.dart'; /// final algorithm = Ed25519(); /// /// // Generate a new key pair -/// final keyPair = await algorithm.keyGenerator.newKeyPair(); +/// final keyPair = await algorithm.newKeyPair(); /// /// // Sign /// final message = [1,2,3]; diff --git a/cryptography/lib/src/dart/aes_cbc.dart b/cryptography/lib/src/dart/aes_cbc.dart index 4558cad..0d5387f 100644 --- a/cryptography/lib/src/dart/aes_cbc.dart +++ b/cryptography/lib/src/dart/aes_cbc.dart @@ -20,7 +20,8 @@ import 'aes_impl.dart'; /// [AesCbc] implemented in pure Dart. /// -/// Uses PKCS7 padding by default (for compatibility with Web Cryptography API). +/// For examples and more information about the algorithm, see documentation for +/// the class [AesCbc]. class DartAesCbc extends AesCbc with DartAesMixin { @override final MacAlgorithm macAlgorithm; diff --git a/cryptography/lib/src/dart/aes_ctr.dart b/cryptography/lib/src/dart/aes_ctr.dart index 848db6b..efbbe10 100644 --- a/cryptography/lib/src/dart/aes_ctr.dart +++ b/cryptography/lib/src/dart/aes_ctr.dart @@ -20,6 +20,9 @@ import '../utils.dart'; import 'aes_impl.dart'; /// [AesCtr] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [AesCtr]. class DartAesCtr extends AesCtr with DartAesMixin { @override final MacAlgorithm macAlgorithm; diff --git a/cryptography/lib/src/dart/aes_gcm.dart b/cryptography/lib/src/dart/aes_gcm.dart index 302c953..4bf094a 100644 --- a/cryptography/lib/src/dart/aes_gcm.dart +++ b/cryptography/lib/src/dart/aes_gcm.dart @@ -23,6 +23,9 @@ import 'aes_impl.dart'; const _bit32 = 0x100 * 0x100 * 0x100 * 0x100; /// [AesGcm] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [AesGcm]. // // The implementation was written based on the original specification: // https://csrc.nist.gov/publications/detail/sp/800-38d/final diff --git a/cryptography/lib/src/dart/argon2.dart b/cryptography/lib/src/dart/argon2.dart index b1762be..5893ef4 100644 --- a/cryptography/lib/src/dart/argon2.dart +++ b/cryptography/lib/src/dart/argon2.dart @@ -18,6 +18,9 @@ import 'package:cryptography/cryptography.dart'; import 'package:cryptography/dart.dart'; /// [Argon2id] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Argon2id]. class DartArgon2id extends Argon2id { @override final int parallelism; diff --git a/cryptography/lib/src/dart/blake2b.dart b/cryptography/lib/src/dart/blake2b.dart index a9e971b..cf820e7 100644 --- a/cryptography/lib/src/dart/blake2b.dart +++ b/cryptography/lib/src/dart/blake2b.dart @@ -18,22 +18,10 @@ import 'package:cryptography/dart.dart'; import 'blake2b_impl_vm.dart' if (dart.library.html) 'blake2b_impl_browser.dart'; -const List sigmaConstants = [ - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, // 16 bytes - 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3, - 11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4, - 7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8, - 9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13, - 2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9, - 12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11, - 13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10, - 6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5, - 10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0, - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, - 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 -]; - /// [Blake2b] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Blake2b]. class DartBlake2b extends Blake2b with DartHashAlgorithmMixin { const DartBlake2b() : super.constructor(); diff --git a/cryptography/lib/src/dart/blake2b_impl_browser.dart b/cryptography/lib/src/dart/blake2b_impl_browser.dart index cd6d5cd..e734f13 100644 --- a/cryptography/lib/src/dart/blake2b_impl_browser.dart +++ b/cryptography/lib/src/dart/blake2b_impl_browser.dart @@ -49,12 +49,28 @@ class Blake2bSink extends DartHashSink { 0x5BE0CD19, ]; static const _bit32 = uint32mask + 1; + static const _sigma = [ + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, // 16 bytes + 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3, + 11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4, + 7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8, + 9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13, + 2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9, + 12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11, + 13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10, + 6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5, + 10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, + 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 + ]; + final _hash = Uint32List(32); final _bufferAsUint32List = Uint32List(32); Uint8List? _bufferAsBytes; int _length = 0; Hash? _result; bool _isClosed = false; + final _localValues = Uint32List(32); Blake2bSink() { @@ -170,8 +186,6 @@ class Blake2bSink extends DartHashSink { v[29] ^= uint32mask; } - final sigma = sigmaConstants; - // 12 rounds for (var round = 0; round < 12; round++) { // Sigma index @@ -179,15 +193,15 @@ class Blake2bSink extends DartHashSink { // Each 64-bit integer takes two elements in the Uint32List, // so we need to multiply the indices. - g(v, 0, 8, 16, 24, m, sigma[si + 0], sigma[si + 1]); - g(v, 2, 10, 18, 26, m, sigma[si + 2], sigma[si + 3]); - g(v, 4, 12, 20, 28, m, sigma[si + 4], sigma[si + 5]); - g(v, 6, 14, 22, 30, m, sigma[si + 6], sigma[si + 7]); - - g(v, 0, 10, 20, 30, m, sigma[si + 8], sigma[si + 9]); - g(v, 2, 12, 22, 24, m, sigma[si + 10], sigma[si + 11]); - g(v, 4, 14, 16, 26, m, sigma[si + 12], sigma[si + 13]); - g(v, 6, 8, 18, 28, m, sigma[si + 14], sigma[si + 15]); + g(v, 0, 8, 16, 24, m, _sigma[si + 0], _sigma[si + 1]); + g(v, 2, 10, 18, 26, m, _sigma[si + 2], _sigma[si + 3]); + g(v, 4, 12, 20, 28, m, _sigma[si + 4], _sigma[si + 5]); + g(v, 6, 14, 22, 30, m, _sigma[si + 6], _sigma[si + 7]); + + g(v, 0, 10, 20, 30, m, _sigma[si + 8], _sigma[si + 9]); + g(v, 2, 12, 22, 24, m, _sigma[si + 10], _sigma[si + 11]); + g(v, 4, 14, 16, 26, m, _sigma[si + 12], _sigma[si + 13]); + g(v, 6, 8, 18, 28, m, _sigma[si + 14], _sigma[si + 15]); } // Copy. diff --git a/cryptography/lib/src/dart/blake2b_impl_vm.dart b/cryptography/lib/src/dart/blake2b_impl_vm.dart index c54ce22..4b50554 100644 --- a/cryptography/lib/src/dart/blake2b_impl_vm.dart +++ b/cryptography/lib/src/dart/blake2b_impl_vm.dart @@ -32,10 +32,25 @@ class Blake2bSink extends DartHashSink { 0x5BE0CD19137E2179, ]; static const int _uint64mask = 0xFFFFFFFFFFFFFFFF; + static const _sigma = [ + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, // 16 bytes + 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3, + 11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4, + 7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8, + 9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13, + 2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9, + 12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11, + 13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10, + 6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5, + 10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, + 14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3 + ]; final _hash = Uint64List(16); final _bufferAsUint64List = Uint64List(16); Uint8List? _bufferAsBytes; int _length = 0; + Hash? _result; bool _isClosed = false; @@ -150,20 +165,19 @@ class Blake2bSink extends DartHashSink { v[14] ^= _uint64mask; } - final sigma = sigmaConstants; for (var round = 0; round < 12; round++) { // Sigma index final si = round * 16; - g(v, 0, 4, 8, 12, m, sigma[si + 0], sigma[si + 1]); - g(v, 1, 5, 9, 13, m, sigma[si + 2], sigma[si + 3]); - g(v, 2, 6, 10, 14, m, sigma[si + 4], sigma[si + 5]); - g(v, 3, 7, 11, 15, m, sigma[si + 6], sigma[si + 7]); + g(v, 0, 4, 8, 12, m, _sigma[si + 0], _sigma[si + 1]); + g(v, 1, 5, 9, 13, m, _sigma[si + 2], _sigma[si + 3]); + g(v, 2, 6, 10, 14, m, _sigma[si + 4], _sigma[si + 5]); + g(v, 3, 7, 11, 15, m, _sigma[si + 6], _sigma[si + 7]); - g(v, 0, 5, 10, 15, m, sigma[si + 8], sigma[si + 9]); - g(v, 1, 6, 11, 12, m, sigma[si + 10], sigma[si + 11]); - g(v, 2, 7, 8, 13, m, sigma[si + 12], sigma[si + 13]); - g(v, 3, 4, 9, 14, m, sigma[si + 14], sigma[si + 15]); + g(v, 0, 5, 10, 15, m, _sigma[si + 8], _sigma[si + 9]); + g(v, 1, 6, 11, 12, m, _sigma[si + 10], _sigma[si + 11]); + g(v, 2, 7, 8, 13, m, _sigma[si + 12], _sigma[si + 13]); + g(v, 3, 4, 9, 14, m, _sigma[si + 14], _sigma[si + 15]); } // Copy. diff --git a/cryptography/lib/src/dart/blake2s.dart b/cryptography/lib/src/dart/blake2s.dart index 82fdae9..7226e55 100644 --- a/cryptography/lib/src/dart/blake2s.dart +++ b/cryptography/lib/src/dart/blake2s.dart @@ -19,6 +19,9 @@ import 'package:cryptography/dart.dart'; import 'package:cryptography/src/utils.dart'; /// [Blake2s] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Blake2s]. class DartBlake2s extends Blake2s with DartHashAlgorithmMixin { const DartBlake2s() : super.constructor(); diff --git a/cryptography/lib/src/dart/chacha20.dart b/cryptography/lib/src/dart/chacha20.dart index 78c2844..abfe397 100644 --- a/cryptography/lib/src/dart/chacha20.dart +++ b/cryptography/lib/src/dart/chacha20.dart @@ -20,13 +20,13 @@ import 'package:cryptography/src/utils.dart'; /// [Chacha20] implemented in pure Dart. /// -/// In almost every case, you should use constructor -/// [DartChacha20.poly1305Aead], -/// which does message authentication with a standard AEAD construction for -/// _ChaCha20_. The AEAD version of ChaCha20 is used by most protocols and -/// operating system APIs. +/// In almost every case, you should use constructor [DartChacha20.poly1305Aead], +/// which returns _AEAD_CHACHA20_POLY1305_ cipher +/// (([RFC 7539](https://tools.ietf.org/html/rfc7539)). +/// The AEAD implementation uses [DartChacha20Poly1305AeadMacAlgorithm]. /// -/// See [Chacha20] for more documentation. +/// For examples and more information about the algorithm, see documentation for +/// the class [Chacha20]. class DartChacha20 extends Chacha20 { static const int _rounds = 20; @@ -35,14 +35,16 @@ class DartChacha20 extends Chacha20 { /// Constructs [DartChacha20] with any MAC. /// - /// Usually you should use [Chacha20.poly1305Aead], which implements - /// AEAD version of the algorithm. + /// In almost every case, you should use constructor [DartChacha20.poly1305Aead], + /// which returns _AEAD_CHACHA20_POLY1305_ cipher + /// (([RFC 7539](https://tools.ietf.org/html/rfc7539)). + /// The AEAD implementation uses [DartChacha20Poly1305AeadMacAlgorithm]. const DartChacha20({ required this.macAlgorithm, }) : super.constructor(); - /// Constructs the AEAD version of ChaCha20 is used by most protocols and - /// operating system APIs. + /// Constructs _AEAD_CHACHA20_POLY1305_ cipher + /// (([RFC 7539](https://tools.ietf.org/html/rfc7539)). /// /// The implementation uses [DartChacha20Poly1305AeadMacAlgorithm]. const DartChacha20.poly1305Aead() diff --git a/cryptography/lib/src/dart/chacha20_poly1305_aead.dart b/cryptography/lib/src/dart/chacha20_poly1305_aead.dart index 3961dc8..d9adeb4 100644 --- a/cryptography/lib/src/dart/chacha20_poly1305_aead.dart +++ b/cryptography/lib/src/dart/chacha20_poly1305_aead.dart @@ -31,6 +31,23 @@ class DartChacha20Poly1305AeadMacAlgorithm extends MacAlgorithm { final Poly1305 _poly1305; final bool _useStaticBuffer; + /// Constructs _AEAD_CHACHA20_POLY1305_. + /// + /// Optional parameter [chacha20] defines the non-AEAD _ChaCha20_ + /// implementation used by this algorithm. The default is [DartChacha20]. + /// + /// Optional parameter [poly1305] defines the _Poly1305_ implementation used + /// by this algorithm. The default is [DartPoly1305]. + /// + /// ## Example + /// ```dart + /// import 'package:cryptography/dart.dart'; + /// + /// void main() { + /// final algorithm = DartChacha20Poly1305AeadMacAlgorithm(); + /// // ... + /// } + /// ``` const DartChacha20Poly1305AeadMacAlgorithm({ Chacha20? chacha20, Poly1305? poly1305, @@ -59,6 +76,9 @@ class DartChacha20Poly1305AeadMacAlgorithm extends MacAlgorithm { List nonce = const [], List aad = const [], }) async { + if (_chacha20.macAlgorithm is DartChacha20Poly1305AeadMacAlgorithm) { + throw StateError('Chacha20 must be non-AEAD'); + } final secretKeyForPoly1305 = await _poly1305SecretKeyFromChacha20( secretKey: secretKey, nonce: nonce, diff --git a/cryptography/lib/src/dart/cryptography.dart b/cryptography/lib/src/dart/cryptography.dart index 48404a6..f71b265 100644 --- a/cryptography/lib/src/dart/cryptography.dart +++ b/cryptography/lib/src/dart/cryptography.dart @@ -62,7 +62,7 @@ class DartCryptography extends Cryptography { AesCtr aesCtr({ required MacAlgorithm macAlgorithm, int secretKeyLength = 32, - int counterBits = 64, + int counterBits = AesCtr.defaultCounterBits, }) { return DartAesCtr( macAlgorithm: macAlgorithm, @@ -112,37 +112,37 @@ class DartCryptography extends Cryptography { @override Chacha20 chacha20Poly1305Aead() { - return chacha20(macAlgorithm: DartChacha20Poly1305AeadMacAlgorithm()); + return const DartChacha20.poly1305Aead(); } @override Ecdh ecdhP256({required int length}) { - throw UnimplementedError(); + return DartEcdh.p256(); } @override Ecdh ecdhP384({required int length}) { - throw UnimplementedError(); + return DartEcdh.p384(); } @override Ecdh ecdhP521({required int length}) { - throw UnimplementedError(); + return DartEcdh.p521(); } @override Ecdsa ecdsaP256(HashAlgorithm hashAlgorithm) { - throw UnimplementedError(); + return DartEcdsa.p256(hashAlgorithm); } @override Ecdsa ecdsaP384(HashAlgorithm hashAlgorithm) { - throw UnimplementedError(); + return DartEcdsa.p384(hashAlgorithm); } @override Ecdsa ecdsaP521(HashAlgorithm hashAlgorithm) { - throw UnimplementedError(); + return DartEcdsa.p521(hashAlgorithm); } @override @@ -230,6 +230,6 @@ class DartCryptography extends Cryptography { @override Xchacha20 xchacha20Poly1305Aead() { - return DartXchacha20.poly1305Aead(); + return const DartXchacha20.poly1305Aead(); } } diff --git a/cryptography/lib/src/dart/ecdh.dart b/cryptography/lib/src/dart/ecdh.dart index 1883e66..c571e0f 100644 --- a/cryptography/lib/src/dart/ecdh.dart +++ b/cryptography/lib/src/dart/ecdh.dart @@ -14,7 +14,11 @@ import 'package:cryptography/cryptography.dart'; -/// A stub for [Ecdh] (P256, P384, P521) implemented in pure Dart. +/// [Ecdh] (P256, P384, P521) implementation in pure Dart. Currently it throws +/// [UnimplementedError] if you try to use it. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Ecdh]. class DartEcdh extends Ecdh { @override final KeyPairType keyPairType; diff --git a/cryptography/lib/src/dart/ecdsa.dart b/cryptography/lib/src/dart/ecdsa.dart index 5194e4e..44a064d 100644 --- a/cryptography/lib/src/dart/ecdsa.dart +++ b/cryptography/lib/src/dart/ecdsa.dart @@ -14,7 +14,11 @@ import 'package:cryptography/cryptography.dart'; -/// A stub for [Ecdsa] (P256, P384, P521) implemented in pure Dart. +/// [Ecdsa] (P256, P384, P521) implementation in pure Dart. Currently it throws +/// [UnimplementedError] if you try to use it. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Ecdsa]. class DartEcdsa extends Ecdsa { @override final KeyPairType keyPairType; diff --git a/cryptography/lib/src/dart/ed25519.dart b/cryptography/lib/src/dart/ed25519.dart index d8f4747..65025f1 100644 --- a/cryptography/lib/src/dart/ed25519.dart +++ b/cryptography/lib/src/dart/ed25519.dart @@ -20,6 +20,9 @@ import '../utils.dart'; import 'ed25519_impl.dart'; /// [Ed25519] signature algorithm implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Ed25519]. class DartEd25519 extends Ed25519 { final Sha512 _sha512; diff --git a/cryptography/lib/src/dart/hchacha20.dart b/cryptography/lib/src/dart/hchacha20.dart index 5e6b5df..5569e58 100644 --- a/cryptography/lib/src/dart/hchacha20.dart +++ b/cryptography/lib/src/dart/hchacha20.dart @@ -20,6 +20,9 @@ import 'package:cryptography/dart.dart'; import 'chacha20.dart'; /// [Hchacha20] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Hchacha20]. class DartHChacha20 extends Hchacha20 { const DartHChacha20() : super.constructor(); diff --git a/cryptography/lib/src/dart/hkdf.dart b/cryptography/lib/src/dart/hkdf.dart index 7b94dff..6dceeb4 100644 --- a/cryptography/lib/src/dart/hkdf.dart +++ b/cryptography/lib/src/dart/hkdf.dart @@ -17,6 +17,9 @@ import 'dart:typed_data'; import 'package:cryptography/cryptography.dart'; /// [Hkdf] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Hkdf]. class DartHkdf extends Hkdf { @override final Hmac hmac; diff --git a/cryptography/lib/src/dart/hmac.dart b/cryptography/lib/src/dart/hmac.dart index 6bef71e..3ee562a 100644 --- a/cryptography/lib/src/dart/hmac.dart +++ b/cryptography/lib/src/dart/hmac.dart @@ -18,6 +18,9 @@ import 'package:cryptography/cryptography.dart'; import 'package:cryptography/dart.dart'; /// An implementation of [Hmac] in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Hmac]. class DartHmac extends Hmac with DartMacAlgorithmMixin { /// Hash algorithm used by this HMAC. @override diff --git a/cryptography/lib/src/dart/pbkdf2.dart b/cryptography/lib/src/dart/pbkdf2.dart index 440f993..c90f4b9 100644 --- a/cryptography/lib/src/dart/pbkdf2.dart +++ b/cryptography/lib/src/dart/pbkdf2.dart @@ -17,6 +17,9 @@ import 'dart:typed_data'; import 'package:cryptography/cryptography.dart'; /// [Pbkdf2] implemented in pure Dart. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Pbkdf2]. class DartPbkdf2 extends Pbkdf2 { @override final MacAlgorithm macAlgorithm; diff --git a/cryptography/lib/src/dart/poly1305.dart b/cryptography/lib/src/dart/poly1305.dart index 80c7fad..4f6ccfe 100644 --- a/cryptography/lib/src/dart/poly1305.dart +++ b/cryptography/lib/src/dart/poly1305.dart @@ -18,8 +18,11 @@ import 'package:cryptography/cryptography.dart'; /// [Poly1305] implemented in pure Dart. /// +/// For examples and more information about the algorithm, see documentation for +/// the class [Poly1305]. +/// /// ## Known limitations -/// * Currently uses [BigInt] +/// * Currently uses [BigInt], which makes the implementation slow. class DartPoly1305 extends Poly1305 { const DartPoly1305() : super.constructor(); diff --git a/cryptography/lib/src/dart/rsa_pss.dart b/cryptography/lib/src/dart/rsa_pss.dart index c6d8d09..1b9cb3f 100644 --- a/cryptography/lib/src/dart/rsa_pss.dart +++ b/cryptography/lib/src/dart/rsa_pss.dart @@ -14,7 +14,11 @@ import 'package:cryptography/cryptography.dart'; -/// [RsaPss] implemented in pure Dart. +/// [RsaPss] implementation in pure Dart. Currently it throws +/// [UnimplementedError] if you try to use it. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [RsaPss]. class DartRsaPss extends RsaPss { @override final HashAlgorithm hashAlgorithm; diff --git a/cryptography/lib/src/dart/rsa_ssa_pkcs1v15.dart b/cryptography/lib/src/dart/rsa_ssa_pkcs1v15.dart index b42cf0c..4b1f61d 100644 --- a/cryptography/lib/src/dart/rsa_ssa_pkcs1v15.dart +++ b/cryptography/lib/src/dart/rsa_ssa_pkcs1v15.dart @@ -14,7 +14,11 @@ import 'package:cryptography/cryptography.dart'; -/// An implementation of [DartRsaSsaPkcs1v15] in pure Dart. +/// [DartRsaSsaPkcs1v15] implementation in pure Dart. Currently it throws +/// [UnimplementedError] if you try to use it. +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Ecdh]. class DartRsaSsaPkcs1v15 extends RsaSsaPkcs1v15 { @override final HashAlgorithm hashAlgorithm; diff --git a/cryptography/lib/src/dart/sha1_sha2.dart b/cryptography/lib/src/dart/sha1_sha2.dart index 316b5af..9f77876 100644 --- a/cryptography/lib/src/dart/sha1_sha2.dart +++ b/cryptography/lib/src/dart/sha1_sha2.dart @@ -21,6 +21,9 @@ import 'package:meta/meta.dart'; /// [Sha1] implemented by using in [package:crypto](https://pub.dev/packages/crypto) /// (a package by Google). +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Sha1]. class DartSha1 extends Sha1 with DartHashAlgorithmMixin, _HashMixin { @literal const DartSha1() : super.constructor(); @@ -31,6 +34,9 @@ class DartSha1 extends Sha1 with DartHashAlgorithmMixin, _HashMixin { /// [Sha224] implemented by using in [package:crypto](https://pub.dev/packages/crypto) /// (a package by Google). +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Sha224]. class DartSha224 extends Sha224 with DartHashAlgorithmMixin, _HashMixin { @literal const DartSha224() : super.constructor(); @@ -41,6 +47,9 @@ class DartSha224 extends Sha224 with DartHashAlgorithmMixin, _HashMixin { /// [Sha256] implemented by using in [package:crypto](https://pub.dev/packages/crypto) /// (a package by Google). +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Sha256]. class DartSha256 extends Sha256 with DartHashAlgorithmMixin, _HashMixin { @literal const DartSha256() : super.constructor(); @@ -51,6 +60,9 @@ class DartSha256 extends Sha256 with DartHashAlgorithmMixin, _HashMixin { /// [Sha385] implemented by using in [package:crypto](https://pub.dev/packages/crypto) /// (a package by Google). +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Sha384]. class DartSha384 extends Sha384 with DartHashAlgorithmMixin, _HashMixin { @literal const DartSha384() : super.constructor(); @@ -61,6 +73,9 @@ class DartSha384 extends Sha384 with DartHashAlgorithmMixin, _HashMixin { /// [Sha512] implemented by using in [package:crypto](https://pub.dev/packages/crypto) /// (a package by Google). +/// +/// For examples and more information about the algorithm, see documentation for +/// the class [Sha512]. class DartSha512 extends Sha512 with DartHashAlgorithmMixin, _HashMixin { @literal const DartSha512() : super.constructor(); diff --git a/cryptography/lib/src/dart/x25519.dart b/cryptography/lib/src/dart/x25519.dart index 257045c..99452e7 100644 --- a/cryptography/lib/src/dart/x25519.dart +++ b/cryptography/lib/src/dart/x25519.dart @@ -21,6 +21,9 @@ import 'ed25519_impl.dart'; import 'x25519_impl.dart'; /// [X25519] implemented in pure Dart. +/// +/// For more information about the algorithm and examples, see documentation +/// for the class [X25519]. class DartX25519 extends X25519 with DartKeyExchangeAlgorithmMixin { static final Uint8List _constant9 = () { final result = Uint8List(32); diff --git a/cryptography/lib/src/dart/xchacha20.dart b/cryptography/lib/src/dart/xchacha20.dart index f1e50b1..58163b7 100644 --- a/cryptography/lib/src/dart/xchacha20.dart +++ b/cryptography/lib/src/dart/xchacha20.dart @@ -37,24 +37,31 @@ Future _xchacha20SecretKey({ } /// [Xchacha20] implemented in pure Dart. +/// +/// For more information about the algorithm and examples, see documentation +/// for the class [Xchacha20]. class DartXchacha20 extends StreamingCipher implements Xchacha20 { final Chacha20 _chacha20; @override final MacAlgorithm macAlgorithm; + /// AEAD version of [Xchacha20]. const DartXchacha20.poly1305Aead() : _chacha20 = const DartChacha20.poly1305Aead(), - macAlgorithm = const _DartXChacha20Poly1305Aead( + macAlgorithm = const _DartXChacha20MacAlgorithm( DartChacha20Poly1305AeadMacAlgorithm(), ); + /// Constructs [DartChacha20] with any [MacAlgorithm]. DartXchacha20({required this.macAlgorithm}) : _chacha20 = Chacha20(macAlgorithm: macAlgorithm); + /// Constructs a [DartXchacha20] with a custom [Chacha20] implementation and + /// any [MacAlgorithm]. DartXchacha20.withChacha20({required Chacha20 chacha20}) : _chacha20 = chacha20, - macAlgorithm = _DartXChacha20Poly1305Aead(chacha20.macAlgorithm); + macAlgorithm = _DartXChacha20MacAlgorithm(chacha20.macAlgorithm); @override int get nonceLength => 24; @@ -140,10 +147,10 @@ class DartXchacha20 extends StreamingCipher implements Xchacha20 { } } -class _DartXChacha20Poly1305Aead extends MacAlgorithm { +class _DartXChacha20MacAlgorithm extends MacAlgorithm { final MacAlgorithm _macAlgorithm; - const _DartXChacha20Poly1305Aead(this._macAlgorithm); + const _DartXChacha20MacAlgorithm(this._macAlgorithm); @override int get macLength => _macAlgorithm.macLength; diff --git a/cryptography/pubspec.yaml b/cryptography/pubspec.yaml index 5c9f8ca..41d3635 100644 --- a/cryptography/pubspec.yaml +++ b/cryptography/pubspec.yaml @@ -1,5 +1,5 @@ name: cryptography -version: 2.1.0 +version: 2.1.1 homepage: https://github.com/dint-dev/cryptography description: Cryptographic algorithms for encryption, digital signatures, key agreement, authentication, and