Skip to content

Commit 0741284

Browse files
whyolegwhyoleg
committed
Update documentation a bit
1 parent 1140b43 commit 0741284

File tree

3 files changed

+99
-54
lines changed

3 files changed

+99
-54
lines changed

‎README.md‎

Lines changed: 37 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,10 @@ Detailed documentation can be found on
1818
cryptography-kotlin provides multiplatform API which consists of multiple components:
1919

2020
* [Secure random][Secure random] with [kotlin.Random][kotlin.Random] like API which can be used independently of other modules
21-
* common API to use different cryptography operations, like [ciphers][ciphers], [digests][digests] and [signatures][signatures]
22-
* multiple algorithms definitions, like [AES][AES], [RSA][RSA], [ECDSA][ECDSA] and [SHA][SHA]
21+
* common API to use different cryptography operations,
22+
like [ciphers][ciphers], [digests][digests], [signatures][signatures], [key derivation][key derivation], [Key agreement][Key agreement]
23+
* multiple algorithms definitions, like [AES][AES], [RSA][RSA], [ECDSA][ECDSA], [ECDH][ECDH], [SHA][SHA256], [HMAC][HMAC]
24+
and [PBKDF2][PBKDF2]
2325
* multiple cryptography [providers][providers], like [OpenSSL][OpenSSL], [WebCrypto][WebCrypto] and [JDK][JDK]
2426

2527
The library doesn't implement any cryptography algorithm on its own, but wraps well-known future-proof solutions
@@ -31,28 +33,28 @@ For supported algorithms, primitives and targets, please consult [Providers docu
3133

3234
## Using in your projects
3335

34-
Make sure that you use Kotlin 1.9.10+.
36+
Make sure that you use Kotlin 2.0.20+.
3537
Using an earlier Kotlin version could still work, but not tested.
36-
Additionally, it's possible to use [BOM][BOM] or [Gradle version catalog][Gradle version catalog] to add dependencies easier
38+
Additionally, it's possible to use [BOM][BOM] or [Gradle version catalog][Gradle version catalog] to add dependencies easier.
39+
The library is published to Maven Central, so make sure, that it’s added to repositories.
3740

3841
```kotlin
39-
repositories {
40-
mavenCentral()
41-
}
42-
4342
kotlin {
4443
sourceSets {
4544
commonMain.dependencies {
46-
implementation(project.dependencies.platform("dev.whyoleg.cryptography:cryptography-bom:0.3.1"))
47-
implementation("dev.whyoleg.cryptography:cryptography-core")
45+
implementation("dev.whyoleg.cryptography:cryptography-core:0.3.1")
4846
}
49-
androidMain.dependencies {
50-
implementation("dev.whyoleg.cryptography:cryptography-provider-jdk")
47+
// or androidMain
48+
jvmMain.dependencies {
49+
implementation("dev.whyoleg.cryptography:cryptography-provider-jdk:0.3.1")
5150
}
52-
iosMain.dependencies {
53-
implementation("dev.whyoleg.cryptography:cryptography-provider-openssl3-prebuilt")
54-
// or `apple` provider
55-
// implementation("dev.whyoleg.cryptography:cryptography-provider-apple")
51+
appleMain.dependencies {
52+
implementation("dev.whyoleg.cryptography:cryptography-provider-apple:0.3.1")
53+
// or openssl3 provider with better algorithms coverage and other native targets support
54+
// implementation("dev.whyoleg.cryptography:cryptography-provider-openssl3-prebuilt:0.3.1")
55+
}
56+
wasmJsMain.dependencies {
57+
implementation("dev.whyoleg.cryptography:cryptography-provider-webcrypto:0.3.1")
5658
}
5759
}
5860
}
@@ -68,8 +70,6 @@ repositories {
6870
}
6971
dependencies {
7072
implementation("dev.whyoleg.cryptography:cryptography-core:0.4.0-SNAPSHOT")
71-
// some provider
72-
implementation("dev.whyoleg.cryptography:cryptography-provider-jdk:0.4.0-SNAPSHOT")
7373
}
7474
```
7575

@@ -100,19 +100,31 @@ For bugs, questions and discussions, please use the [GitHub Issues](https://gith
100100

101101
[kotlin.Random]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.random/-random/
102102

103-
[ciphers]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.cipher/index.html
103+
[ciphers]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-cipher/index.html
104+
105+
[digests]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-hasher/index.html
106+
107+
[signatures]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-signature-generator/index.html
108+
109+
[key derivation]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-secret-derivation/index.html
110+
111+
[Key agreement]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-shared-secret-derivation/index.html
112+
113+
[SHA256]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-s-h-a256/index.html
114+
115+
[AES]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-a-e-s/index.html
104116

105-
[digests]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.hash/index.html
117+
[HMAC]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-h-m-a-c/index.html
106118

107-
[signatures]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.signature/index.html
119+
[RSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-r-s-a/index.html
108120

109-
[AES]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.symmetric/-a-e-s/index.html
121+
[ECDSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-e-c-d-s-a/index.html
110122

111-
[RSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.asymmetric/-r-s-a/index.html
123+
[ECDH]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-e-c-d-h/index.html
112124

113-
[ECDSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.asymmetric/-e-c-d-s-a/index.html
125+
[PBKDF2]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-p-b-k-d-f2/index.html
114126

115-
[SHA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.digest/index.html
127+
[HKDF]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-h-k-d-f/index.html
116128

117129
[providers]: https://whyoleg.github.io/cryptography-kotlin/providers/
118130

‎cryptography-core/README.md‎

Lines changed: 35 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ dependencies {
3434

3535
[CryptographyAlgorithm]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography/-cryptography-algorithm/index.html
3636

37-
[AES]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.symmetric/-a-e-s/index.html
37+
[AES]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-a-e-s/index.html
3838

39-
[cipher]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.cipher/-cipher/index.html
39+
[cipher]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-cipher/index.html
4040

4141
# Package dev.whyoleg.cryptography
4242

@@ -47,56 +47,62 @@ and [CryptographyProvider][CryptographyProvider]
4747

4848
[CryptographyAlgorithm]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography/-cryptography-algorithm/index.html
4949

50-
# Package dev.whyoleg.cryptography.algorithms.digest
50+
# Package dev.whyoleg.cryptography.algorithms
5151

52-
Provides common digest algorithms, like [SHA256][SHA256] and [SHA512][SHA512]
52+
Provides common algorithms:
5353

54-
[SHA256]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.digest/-s-h-a256/index.html
54+
* digests (e.g [SHA256][SHA256] and [SHA512][SHA512])
55+
* symmetric ciphers ([AES][AES])
56+
* asymmetric encryption and signature ([RSA][RSA] and [ECDSA][ECDSA])
57+
* MAC ([HMAC][HMAC])
58+
* Key derivation ([PBKDF2][PBKDF2] and [HKDF][HKDF])
59+
* Key agreement ([ECDH][ECDH])
5560

56-
[SHA512]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.digest/-s-h-a512/index.html
61+
[SHA256]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-s-h-a256/index.html
5762

58-
# Package dev.whyoleg.cryptography.algorithms.symmetric
63+
[SHA512]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-s-h-a512/index.html
5964

60-
Provides common symmetric ciphers and MAC algorithms, like [AES][AES] and [HMAC][HMAC]
65+
[AES]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-a-e-s/index.html
6166

62-
[AES]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.symmetric/-a-e-s/index.html
67+
[HMAC]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-h-m-a-c/index.html
6368

64-
[HMAC]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.symmetric/-h-m-a-c/index.html
69+
[RSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-r-s-a/index.html
6570

66-
# Package dev.whyoleg.cryptography.algorithms.asymmetric
71+
[ECDSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-e-c-d-s-a/index.html
6772

68-
Provides common asymmetric encryption and signature algorithms, like [RSA][RSA] and [ECDSA][ECDSA]
73+
[ECDH]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-e-c-d-h/index.html
6974

70-
[RSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.asymmetric/-r-s-a/index.html
75+
[PBKDF2]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-p-b-k-d-f2/index.html
7176

72-
[ECDSA]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms.asymmetric/-e-c-d-s-a/index.html
77+
[HKDF]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.algorithms/-h-k-d-f/index.html
7378

74-
# Package dev.whyoleg.cryptography.operations.cipher
79+
# Package dev.whyoleg.cryptography.operations
7580

76-
Provides API for [encryption][Encryptor]/[decryption][Decryptor] and
77-
Authenticated [encryption][AuthenticatedEncryptor]/[decryption][AuthenticatedDecryptor]
81+
Provides APIs to perform cryptography operations:
7882

79-
[Encryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.cipher/-encryptor/index.html
83+
* [hashing][Hasher]
84+
* [encryption][Encryptor]/[decryption][Decryptor] and
85+
Authenticated [encryption][AuthenticatedEncryptor]/[decryption][AuthenticatedDecryptor]
86+
* signature [verification][SignatureVerifier] and [generation][SignatureGenerator]
87+
* [secret derivation][SecretDerivation] (KDF/PRF) and [shared secret derivation][SharedSecretDerivation] (Key agreement)
8088

81-
[Decryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.cipher/-decryptor/index.html
89+
[Encryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-encryptor/index.html
8290

83-
[AuthenticatedEncryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.cipher/-authenticated-encryptor/index.html
91+
[Decryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-decryptor/index.html
8492

85-
[AuthenticatedDecryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.cipher/-authenticated-decryptor/index.html
93+
[AuthenticatedEncryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-authenticated-encryptor/index.html
8694

87-
# Package dev.whyoleg.cryptography.operations.hash
95+
[AuthenticatedDecryptor]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-authenticated-decryptor/index.html
8896

89-
Provides [hashing][Hasher] operation
97+
[Hasher]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-hasher/index.html
9098

91-
[Hasher]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.hash/-hasher/index.html
99+
[SignatureVerifier]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-signature-verifier/index.html
92100

93-
# Package dev.whyoleg.cryptography.operations.signature
101+
[SignatureGenerator]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-signature-generator/index.html
94102

95-
Provides signature [verification][SignatureVerifier] and [generation][SignatureGenerator] API
103+
[SecretDerivation]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-secret-derivation/index.html
96104

97-
[SignatureVerifier]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.signature/-signature-verifier/index.html
98-
99-
[SignatureGenerator]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations.signature/-signature-generator/index.html
105+
[SharedSecretDerivation]: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-core/dev.whyoleg.cryptography.operations/-shared-secret-derivation/index.html
100106

101107
# Package dev.whyoleg.cryptography.materials.key
102108

‎docs/gradle-version-catalog.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,30 @@ dependencies {
2626
implementation(cryptographyLibs.provider.jdk)
2727
}
2828
```
29+
30+
## Using with an existing version catalog
31+
32+
Paste into `libs.versions.toml`:
33+
34+
```toml
35+
[versions]
36+
cryptography = "0.3.1"
37+
38+
[libraries]
39+
cryptography-core = { group = "dev.whyoleg.cryptography", name = "cryptography-core", version.ref = "cryptography" }
40+
cryptography-provider-apple = { group = "dev.whyoleg.cryptography", name = "cryptography-provider-apple", version.ref = "cryptography" }
41+
cryptography-provider-jdk = { group = "dev.whyoleg.cryptography", name = "cryptography-provider-jdk", version.ref = "cryptography" }
42+
cryptography-provider-openssl3-prebuilt = { group = "dev.whyoleg.cryptography", name = "cryptography-provider-openssl3-prebuilt", version.ref = "cryptography" }
43+
cryptography-provider-webcrypto = { group = "dev.whyoleg.cryptography", name = "cryptography-provider-webcrypto", version.ref = "cryptography" }
44+
cryptography-random = { group = "dev.whyoleg.cryptography", name = "cryptography-random", version.ref = "cryptography" }
45+
```
46+
47+
Use version catalog in any of `build.gradle.kts`:
48+
49+
```kotlin
50+
dependencies {
51+
implementation(libc.cryptography.core)
52+
// some provider
53+
implementation(libs.cryptography.provider.jdk)
54+
}
55+
```

0 commit comments

Comments
 (0)