PGPainless/pgpainless
PGPainless/pgpainless
1
0
Fork 0
mirror of https://github.com/pgpainless/pgpainless.git synced 2025-09-10 18:59:39 +02:00
Code Issues Releases Wiki Activity

Update documentation of AEADAlgorithm

Browse source
This commit is contained in:
Paul Schaub 2025-05-13 13:10:21 +02:00
parent bf5e3b6296
commit 31b2edc651
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
1 changed files with 37 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

40
pgpainless-core/src/main/kotlin/org/pgpainless/algorithm/AEADAlgorithm.kt
View file

@ -6,38 +6,72 @@ package org.pgpainless.algorithm
import org.bouncycastle.openpgp.api.MessageEncryptionMechanism import org.bouncycastle.openpgp.api.MessageEncryptionMechanism
/**
* AEAD Algorithm.
* @param algorithmId numeric algorithm id
* @param ivLength length of the initialization vector
* @param tagLength length of the tag
*
* @see [RFC9580 - AEAD Algorithms](https://www.rfc-editor.org/rfc/rfc9580.html#name-aead-algorithms)
*/
enum class AEADAlgorithm(val algorithmId: Int, val ivLength: Int, val tagLength: Int) { enum class AEADAlgorithm(val algorithmId: Int, val ivLength: Int, val tagLength: Int) {
/** /**
* Encrypt-then-Authenticate-then-Translate mode. * Encrypt-then-Authenticate-then-Translate mode.
* https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-eax-mode *
* @see [RFC9580 - EAX Mode](https://www.rfc-editor.org/rfc/rfc9580.html#name-eax-mode)
*/ */
EAX(1, 16, 16), EAX(1, 16, 16),
/** /**
* Offset-Codebook mode. OCB is mandatory to implement in crypto-refresh. Favored by GnuPG. Is * Offset-Codebook mode. OCB is mandatory to implement in crypto-refresh. Favored by GnuPG. Is
* not yet FIPS compliant, but supported by most implementations and therefore favorable. * not yet FIPS compliant, but supported by most implementations and therefore favorable.
* https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-ocb-mode *
* @see [RFC9580 - OCB Mode](https://www.rfc-editor.org/rfc/rfc9580.html#name-ocb-mode)
*/ */
OCB(2, 15, 16), OCB(2, 15, 16),
/** /**
* Galois/Counter-Mode. GCM is controversial. Some say it is hard to get right. Some * Galois/Counter-Mode. GCM is controversial. Some say it is hard to get right. Some
* implementations like GnuPG therefore avoid it. May be necessary to achieve FIPS compliance. * implementations like GnuPG therefore avoid it. May be necessary to achieve FIPS compliance.
* https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-gcm-mode *
* @see [RFC9580 - GCM Mode](https://www.rfc-editor.org/rfc/rfc9580.html#name-gcm-mode)
*/ */
GCM(3, 12, 16), GCM(3, 12, 16),
; ;
/**
* Return a [MessageEncryptionMechanism] instance representing AEAD using this algorithm and
* the given [SymmetricKeyAlgorithm].
*
* @param ciphermode symmetric key algorithm
* @return MessageEncryptionMechanism representing aead(this, ciphermode)
*/
fun toMechanism(ciphermode: SymmetricKeyAlgorithm): MessageEncryptionMechanism = fun toMechanism(ciphermode: SymmetricKeyAlgorithm): MessageEncryptionMechanism =
MessageEncryptionMechanism.aead(ciphermode.algorithmId, this.algorithmId) MessageEncryptionMechanism.aead(ciphermode.algorithmId, this.algorithmId)
companion object { companion object {
/**
* Parse an [AEADAlgorithm] from an algorithm id.
* If no matching [AEADAlgorithm] is known, return `null`.
*
* @param id algorithm id
* @return aeadAlgorithm or null
*/
@JvmStatic @JvmStatic
fun fromId(id: Int): AEADAlgorithm? { fun fromId(id: Int): AEADAlgorithm? {
return values().firstOrNull { algorithm -> algorithm.algorithmId == id } return values().firstOrNull { algorithm -> algorithm.algorithmId == id }
} }
/**
* Parse an [AEADAlgorithm] from an algorithm id.
* If no matching [AEADAlgorithm] is known, throw a [NoSuchElementException].
*
* @param id algorithm id
* @return aeadAlgorithm
* @throws NoSuchElementException for unknown algorithm ids
*/
@JvmStatic @JvmStatic
fun requireFromId(id: Int): AEADAlgorithm { fun requireFromId(id: Int): AEADAlgorithm {
return fromId(id) ?: throw NoSuchElementException("No AEADAlgorithm found for id $id") return fromId(id) ?: throw NoSuchElementException("No AEADAlgorithm found for id $id")