mirror of
https://github.com/pgpainless/pgpainless.git
synced 2024-12-24 11:57:59 +01:00
Add kDoc to Kotlin classes
This commit is contained in:
parent
ee5201484c
commit
44774ac727
9 changed files with 193 additions and 8 deletions
|
@ -8,6 +8,14 @@ import org.pgpainless.algorithm.RevocationState
|
|||
import org.pgpainless.key.OpenPgpFingerprint
|
||||
import java.util.*
|
||||
|
||||
/**
|
||||
* A [CertSynopsis] is a proxy object containing information about a certificate.
|
||||
*
|
||||
* @param fingerprint [OpenPgpFingerprint] of the certificate
|
||||
* @param expirationTime optional expiration time of the certificate
|
||||
* @param revocationState [RevocationState] denoting whether the certificate is revoked or not
|
||||
* @param userIds [Map] of user-ids on the certificate, along with their revocation states
|
||||
*/
|
||||
data class CertSynopsis(
|
||||
val fingerprint: OpenPgpFingerprint,
|
||||
val expirationTime: Date?,
|
||||
|
|
|
@ -6,6 +6,20 @@ package org.pgpainless.wot.dijkstra.sq
|
|||
|
||||
import java.util.*
|
||||
|
||||
/**
|
||||
* A [Certification] is a signature issued by one certificate over a datum on another target certificate.
|
||||
* Such a datum could be either a user-id, or the primary key of the target certificate.
|
||||
*
|
||||
* @param issuer synopsis of the certificate that issued the [Certification]
|
||||
* @param target synopsis of the certificate that is target of this [Certification]
|
||||
* @param userId optional user-id. If this is null, the [Certification] is made over the primary key of the target.
|
||||
* @param creationTime creation time of the [Certification]
|
||||
* @param expirationTime optional expiration time of the [Certification]
|
||||
* @param exportable if false, the certification is marked as "not exportable"
|
||||
* @param trustAmount amount of trust the issuer places in the binding
|
||||
* @param trustDepth degree to which the issuer trusts the target as trusted introducer
|
||||
* @param regexes regular expressions for user-ids which the target is allowed to introduce
|
||||
*/
|
||||
data class Certification(
|
||||
val issuer: CertSynopsis,
|
||||
val target: CertSynopsis,
|
||||
|
@ -18,6 +32,15 @@ data class Certification(
|
|||
val regexes: RegexSet
|
||||
) {
|
||||
|
||||
/**
|
||||
* Construct a [Certification] with default values. The result is non-expiring, will be exportable and has a
|
||||
* trust amount of 120, a depth of 0 and a wildcard regex.
|
||||
*
|
||||
* @param issuer synopsis of the certificate that issued the [Certification]
|
||||
* @param target synopsis of the certificate that is target of this [Certification]
|
||||
* @param targetUserId optional user-id. If this is null, the [Certification] is made over the primary key of the target.
|
||||
* @param creationTime creation time of the [Certification]
|
||||
*/
|
||||
constructor(
|
||||
issuer: CertSynopsis,
|
||||
targetUserId: String?,
|
||||
|
|
|
@ -4,6 +4,17 @@
|
|||
|
||||
package org.pgpainless.wot.dijkstra.sq
|
||||
|
||||
/**
|
||||
* A [CertificationSet] is a set of [Certifications][Certification] made by the same issuer, on the same
|
||||
* target certificate.
|
||||
* In some sense, a [CertificationSet] can be considered an edge in the web of trust.
|
||||
*
|
||||
* @param issuer synopsis of the certificate that issued the [Certifications][Certification]
|
||||
* @param target synopsis of the certificate that is targeted by the [Certifications][Certification]
|
||||
* @param certifications [MutableMap] keyed by user-ids, whose values are [MutableLists][MutableList] of
|
||||
* [Certifications][Certification] that are calculated over the key user-id. Note, that the key can also be null for
|
||||
* [Certifications][Certification] over the targets primary key.
|
||||
*/
|
||||
data class CertificationSet(
|
||||
val issuer: CertSynopsis,
|
||||
val target: CertSynopsis,
|
||||
|
@ -11,11 +22,22 @@ data class CertificationSet(
|
|||
|
||||
companion object {
|
||||
|
||||
/**
|
||||
* Create an empty [CertificationSet].
|
||||
*
|
||||
* @param issuer the certificate that issued the [Certifications][Certification].
|
||||
* @param target the certificate that is targeted by the [Certifications][Certification].
|
||||
*/
|
||||
@JvmStatic
|
||||
fun empty(issuer: CertSynopsis, target: CertSynopsis): CertificationSet {
|
||||
return CertificationSet(issuer, target, HashMap())
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a [CertificationSet] from a single [Certification].
|
||||
*
|
||||
* @param certification certification
|
||||
*/
|
||||
@JvmStatic
|
||||
fun fromCertification(certification: Certification) : CertificationSet {
|
||||
val set = empty(certification.issuer, certification.target)
|
||||
|
@ -24,6 +46,12 @@ data class CertificationSet(
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge the given [CertificationSet] into this.
|
||||
* This method copies all [Certifications][Certification] from the other [CertificationSet] into [certifications].
|
||||
*
|
||||
* @param other [CertificationSet] with the same issuer fingerprint and target fingerprint as this object.
|
||||
*/
|
||||
fun merge(other: CertificationSet) {
|
||||
if (other == this) {
|
||||
return
|
||||
|
@ -39,6 +67,11 @@ data class CertificationSet(
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a single [Certification] into this objects [certifications].
|
||||
*
|
||||
* @param certification [Certification] with the same issuer fingerprint and target fingerprint as this object.
|
||||
*/
|
||||
fun add(certification : Certification) {
|
||||
require(issuer.fingerprint == certification.issuer.fingerprint) { "Issuer fingerprint mismatch." }
|
||||
require(target.fingerprint == certification.target.fingerprint) { "Target fingerprint mismatch." }
|
||||
|
|
|
@ -4,22 +4,34 @@
|
|||
|
||||
package org.pgpainless.wot.dijkstra.sq
|
||||
|
||||
/**
|
||||
* Depth of a trust signature.
|
||||
*/
|
||||
class Depth(val limit: Int?) : Comparable<Depth> {
|
||||
|
||||
companion object {
|
||||
/**
|
||||
* The target is trusted to an unlimited degree.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun unconstrained() : Depth {
|
||||
return Depth(null)
|
||||
}
|
||||
|
||||
/**
|
||||
* The target is trusted to a limited degree.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun limited(limit: Int): Depth {
|
||||
require(limit in 0..255) {
|
||||
"Trust depth MUST be a value between 0 and 255."
|
||||
require(limit in 0..254) {
|
||||
"Trust depth MUST be a value between 0 and 254."
|
||||
}
|
||||
return Depth(limit)
|
||||
}
|
||||
|
||||
/**
|
||||
* Deduce the trust degree automatically.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun auto(limit: Int): Depth {
|
||||
return if (limit == 255) {
|
||||
|
@ -30,10 +42,18 @@ class Depth(val limit: Int?) : Comparable<Depth> {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Return true, if the [Depth] is unconstrained.
|
||||
*/
|
||||
fun isUnconstrained() : Boolean {
|
||||
return limit == null
|
||||
}
|
||||
|
||||
/**
|
||||
* Decrease the trust depth by one and return the result.
|
||||
* If the [Depth] is unconstrained, the result will still be unconstrained.
|
||||
* @throws IllegalArgumentException if the [Depth] cannot be decreased any further
|
||||
*/
|
||||
fun decrease(value : Int) : Depth {
|
||||
return if (isUnconstrained()) {
|
||||
unconstrained()
|
||||
|
@ -46,6 +66,9 @@ class Depth(val limit: Int?) : Comparable<Depth> {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the minimum [Depth] of this and the other [Depth].
|
||||
*/
|
||||
fun min(other: Depth) : Depth {
|
||||
return if (compareTo(other) <= 0) {
|
||||
this
|
||||
|
@ -54,18 +77,18 @@ class Depth(val limit: Int?) : Comparable<Depth> {
|
|||
}
|
||||
}
|
||||
|
||||
override fun compareTo(o: Depth): Int {
|
||||
override fun compareTo(other: Depth): Int {
|
||||
return if (isUnconstrained()) {
|
||||
if (o.isUnconstrained()) {
|
||||
if (other.isUnconstrained()) {
|
||||
0
|
||||
} else {
|
||||
1
|
||||
}
|
||||
} else {
|
||||
if (o.isUnconstrained()) {
|
||||
if (other.isUnconstrained()) {
|
||||
-1
|
||||
} else {
|
||||
limit!!.compareTo(o.limit!!)
|
||||
limit!!.compareTo(other.limit!!)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
@ -30,11 +30,19 @@ class Network(
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The total number of edges on the network.
|
||||
*
|
||||
* @return number of edges
|
||||
*/
|
||||
val numberOfEdges: Int
|
||||
get() {
|
||||
return edges.values.sumOf { it.size }
|
||||
}
|
||||
|
||||
/**
|
||||
* The total number of signatures the network comprises.
|
||||
*/
|
||||
val numberOfSignatures: Int
|
||||
get() {
|
||||
return edges.values
|
||||
|
|
|
@ -6,14 +6,33 @@ package org.pgpainless.wot.dijkstra.sq
|
|||
|
||||
import kotlin.math.min
|
||||
|
||||
/**
|
||||
* A [Path] comprises a root [CertSynopsis], a list of edges ([Certifications][Certification]), as well as a
|
||||
* residual depth.
|
||||
*
|
||||
* @param root root of the path
|
||||
* @param edges list of edges from the root to the target
|
||||
* @param residualDepth residual depth that is decreased each time another edge is appended
|
||||
*/
|
||||
class Path(
|
||||
val root: CertSynopsis,
|
||||
val edges: MutableList<Certification>,
|
||||
var residualDepth: Depth
|
||||
) {
|
||||
|
||||
/**
|
||||
* Construct a [Path] only consisting of the trust root.
|
||||
* The [Path] will have an empty list of edges and an unconstrained residual [Depth].
|
||||
*
|
||||
* @param root trust root
|
||||
*/
|
||||
constructor(root: CertSynopsis) : this(
|
||||
root, mutableListOf<Certification>(), Depth.unconstrained())
|
||||
|
||||
/**
|
||||
* Current target of the path.
|
||||
* This corresponds to the target of the last entry in the edge list.
|
||||
*/
|
||||
val target: CertSynopsis
|
||||
get() {
|
||||
return if (edges.isEmpty()) {
|
||||
|
@ -23,6 +42,10 @@ class Path(
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* List of [CertSynopses][CertSynopsis] (nodes) of the path.
|
||||
* The first entry is the [root]. The other entries are the targets of the edges.
|
||||
*/
|
||||
val certificates: List<CertSynopsis>
|
||||
get() {
|
||||
val certs: MutableList<CertSynopsis> = ArrayList()
|
||||
|
@ -33,12 +56,23 @@ class Path(
|
|||
return certs
|
||||
}
|
||||
|
||||
/**
|
||||
* The length of the path, counted in nodes.
|
||||
* A path with a single edge between node A and B has length 2, the empty path with only a trust root has length 1.
|
||||
*/
|
||||
val length: Int
|
||||
get() = edges.size + 1
|
||||
|
||||
/**
|
||||
* List of edges.
|
||||
*/
|
||||
val certifications: List<Certification>
|
||||
get() = ArrayList(edges)
|
||||
|
||||
/**
|
||||
* Trust amount of the path.
|
||||
* This corresponds to the smallest trust amount of any edge in the path.
|
||||
*/
|
||||
val amount: Int
|
||||
get() = if (edges.isEmpty()) {
|
||||
120
|
||||
|
@ -50,6 +84,13 @@ class Path(
|
|||
min
|
||||
}
|
||||
|
||||
/**
|
||||
* Append an edge to the path and decrease the [residualDepth] of the path by 1.
|
||||
*
|
||||
* @throws IllegalArgumentException if the target at the end of the path is not equal to the issuer of the edge.
|
||||
* @throws IllegalArgumentException if the path runs out of residual depth
|
||||
* @throws IllegalArgumentException if the addition of the [Certification] would result in a cyclic path
|
||||
*/
|
||||
fun append(certification: Certification) {
|
||||
require(target.fingerprint == certification.issuer.fingerprint) {
|
||||
"Cannot append certification to path: Path's tail is not issuer of the certification."
|
||||
|
|
|
@ -4,11 +4,23 @@
|
|||
|
||||
package org.pgpainless.wot.dijkstra.sq
|
||||
|
||||
/**
|
||||
* List of individual [Paths][Path].
|
||||
*
|
||||
* @param paths list of paths
|
||||
*/
|
||||
class Paths(val paths: MutableList<Item>) {
|
||||
|
||||
constructor():
|
||||
this(mutableListOf<Item>())
|
||||
/**
|
||||
* Empty collection of paths.
|
||||
*/
|
||||
constructor(): this(mutableListOf<Item>())
|
||||
|
||||
/**
|
||||
* Add a [Path] to the list.
|
||||
*
|
||||
* @throws IllegalArgumentException if the given amount is smaller of equal to the paths trust amount.
|
||||
*/
|
||||
fun add(path: Path, amount: Int) {
|
||||
require(amount <= path.amount) {
|
||||
"Amount too small. TODO: Better error message"
|
||||
|
@ -16,11 +28,18 @@ class Paths(val paths: MutableList<Item>) {
|
|||
paths.add(Item(path, amount))
|
||||
}
|
||||
|
||||
/**
|
||||
* The summed trust amount of all paths in this collection.
|
||||
*/
|
||||
val amount: Int
|
||||
get() {
|
||||
return paths.sumOf { it.amount }
|
||||
}
|
||||
|
||||
/**
|
||||
* @param path path
|
||||
* @param amount trust amount
|
||||
*/
|
||||
data class Item(val path: Path, val amount: Int) {
|
||||
|
||||
}
|
||||
|
|
|
@ -6,11 +6,21 @@ package org.pgpainless.wot.dijkstra.sq
|
|||
|
||||
import java.util.*
|
||||
|
||||
/**
|
||||
* Reference time for Web of Trust calculations.
|
||||
*/
|
||||
interface ReferenceTime {
|
||||
|
||||
/**
|
||||
* Timestamp as [Date].
|
||||
*/
|
||||
val timestamp: Date
|
||||
|
||||
companion object {
|
||||
|
||||
/**
|
||||
* Create a [ReferenceTime] with a timestamp that corresponds to the current time.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun now(): ReferenceTime {
|
||||
val now = Date()
|
||||
|
@ -20,6 +30,9 @@ interface ReferenceTime {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a [ReferenceTime] from the given [stamp] timestamp.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun timestamp(stamp: Date): ReferenceTime {
|
||||
return object: ReferenceTime {
|
||||
|
|
|
@ -6,25 +6,42 @@ package org.pgpainless.wot.dijkstra.sq
|
|||
|
||||
import java.util.regex.Pattern
|
||||
|
||||
/**
|
||||
* Set of regular expressions.
|
||||
*/
|
||||
data class RegexSet(val regexStrings: Set<String>) {
|
||||
|
||||
companion object {
|
||||
|
||||
/**
|
||||
* Create a [RegexSet] from the given [List] of RegEx strings.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun fromExpressionList(regexList: List<String>): RegexSet {
|
||||
return RegexSet(regexList.toSet())
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a [RegexSet] from a single RegEx string.
|
||||
*/
|
||||
@JvmStatic
|
||||
fun fromExpression(regex: String): RegexSet {
|
||||
return fromExpressionList(listOf(regex))
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a wildcard RegEx (empty list of RegEx strings).
|
||||
*/
|
||||
@JvmStatic
|
||||
fun wildcard(): RegexSet {
|
||||
return fromExpressionList(listOf())
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Return true if the given [string] matches the [RegexSet].
|
||||
* That is if at least one RegEx in the set matches the [string], or if the set represents a wildcard.
|
||||
*/
|
||||
fun matches(string: String): Boolean {
|
||||
if (regexStrings.isEmpty()) {
|
||||
return true
|
||||
|
|
Loading…
Reference in a new issue