indispensable/at.asitplus.signum.indispensable.symmetric

Package-level declarations

Types

sealed interface AuthCapability<K : KeyType>

Defines whether a cipher is authenticated or not

abstract class BlockCipher<A : AuthCapability<K>, I : NonceTrait, K : KeyType>( val mode: BlockCipher.ModeOfOperation, val blockSize: BitLength) : SymmetricEncryptionAlgorithm<A, I, K>

Marker interface indicating a block cipher. Purely informational

Ciphertext

sealed interface Ciphertext<A : AuthCapability<out K>, I : NonceTrait, E : SymmetricEncryptionAlgorithm<A, I, K>, K : KeyType>

A generic ciphertext object, referencing the algorithm it was created by.

KeyType

sealed interface KeyType

MacAuthTagTransformation

typealias MacAuthTagTransformation = SymmetricEncryptionAlgorithm.Authenticated.EncryptThenMAC<*, *>.(macOutput: ByteArray) -> ByteArray

Typealias defining the signature of the lambda for processing the MAC output into an auth tag.

MacInputCalculation

typealias MacInputCalculation = SymmetricEncryptionAlgorithm.Authenticated.EncryptThenMAC<*, *>.(ciphertext: ByteArray, nonce: ByteArray, aad: ByteArray) -> ByteArray

Typealias defining the signature of the lambda for defining a custom MAC input calculation scheme.

NonceTrait

sealed interface NonceTrait

Marker, indicating whether a symmetric encryption algorithms requires or prohibits the use of a nonce/IV

SealedBox

sealed interface SealedBox<A : AuthCapability<out K>, I : NonceTrait, K : KeyType>

Represents symmetrically encrypted data in a structured manner. Construct using SymmetricEncryptionAlgorithm.sealedBoxFrom

SealedBoxBuilder

sealed class SealedBoxBuilder<A : AuthCapability<out K>, I : NonceTrait, out K : KeyType>

SealedBox builder from algorithm

SpecializedSymmetricKey

interface SpecializedSymmetricKey

StreamCipher

abstract class StreamCipher<A : AuthCapability<K>, I : NonceTrait, K : KeyType> : SymmetricEncryptionAlgorithm<A, I, K>

Marker interface indicating a block cipher. Purely informational

SymmetricEncryptionAlgorithm

sealed interface SymmetricEncryptionAlgorithm<out A : AuthCapability<out K>, out I : NonceTrait, out K : KeyType> : Identifiable

Base interface for every symmetric encryption algorithm. A Symmetric encryption algorithm is characterised by:

SymmetricKey

sealed interface SymmetricKey<A : AuthCapability<out K>, I : NonceTrait, K : KeyType>

Symmetric encryption key. Can only be used for the specified algorithm.

Properties

authTag

val SealedBox<out AuthCapability.Authenticated<*>, I, *>.authTag: ByteArray

authTagSize

val SymmetricEncryptionAlgorithm<AuthCapability.Authenticated<*>, *, *>.authTagSize: BitLength

DefaultMacAuthTagTransformation

val DefaultMacAuthTagTransformation: MacAuthTagTransformation

The default dedicated mac output transform as per RFC 7518, taking the first authTagSize many bytes of the MAC output as auth tag.

DefaultMacInputCalculation

val DefaultMacInputCalculation: MacInputCalculation

The default dedicated mac input calculation as per RFC 7518, authenticating all inputs: AAD || IV || Ciphertext || AAD Length, where AAD_length is a 64 bit big-endian representation of the aad length in bits

encryptionKey

val SymmetricKey<AuthCapability.Authenticated.WithDedicatedMac, I, out KeyType.WithDedicatedMacKey>.encryptionKey: KmmResult<ByteArray>

The encryption key bytes, if present.

macKey

val SymmetricKey<AuthCapability.Authenticated.WithDedicatedMac, I, out KeyType.WithDedicatedMacKey>.macKey: KmmResult<ByteArray>

The dedicated MAC key bytes, if present.

nonce

val SealedBox<*, NonceTrait.Required, *>.nonce: ByteArray

nonceSize

val SymmetricEncryptionAlgorithm<*, NonceTrait.Required, *>.nonceSize: BitLength

preferredMacKeyLength

val SymmetricEncryptionAlgorithm<AuthCapability.Authenticated.WithDedicatedMac, *, KeyType.WithDedicatedMacKey>.preferredMacKeyLength: BitLength

sealedBox

@get:JvmName(name = "boxWithNonceAuthenticated")

val <K : KeyType, A : AuthCapability.Authenticated<out K>> SymmetricEncryptionAlgorithm<A, NonceTrait.Required, K>.sealedBox: SealedBoxBuilder.WithNonce.Awaiting<A, K>

@get:JvmName(name = "boxWithoutNonceAuthenticatedGeneric")

val SymmetricEncryptionAlgorithm<AuthCapability.Authenticated<*>, NonceTrait.Without, *>.sealedBox: SealedBoxBuilder.Without.Authenticated<AuthCapability.Authenticated<*>, *>

@get:JvmName(name = "boxWithoutNonceAuthenticatedIntegrated")

val SymmetricEncryptionAlgorithm<AuthCapability.Authenticated<KeyType.Integrated>, NonceTrait.Without, KeyType.Integrated>.sealedBox: SealedBoxBuilder.Without.Authenticated<AuthCapability.Authenticated<KeyType.Integrated>, KeyType.Integrated>

@get:JvmName(name = "boxWithoutNonceAuthenticatedDedicated")

val SymmetricEncryptionAlgorithm<AuthCapability.Authenticated<KeyType.WithDedicatedMacKey>, NonceTrait.Without, KeyType.WithDedicatedMacKey>.sealedBox: SealedBoxBuilder.Without.Authenticated<AuthCapability.Authenticated<KeyType.WithDedicatedMacKey>, KeyType.WithDedicatedMacKey>

@get:JvmName(name = "boxWithNonceUnauthenticated")

val SymmetricEncryptionAlgorithm<AuthCapability.Unauthenticated, NonceTrait.Required, KeyType.Integrated>.sealedBox: SealedBoxBuilder.WithNonce.Awaiting<AuthCapability.Unauthenticated, KeyType.Integrated>

@get:JvmName(name = "boxWithoutNonceUnauthenticated")

val SymmetricEncryptionAlgorithm<AuthCapability.Unauthenticated, NonceTrait.Without, KeyType.Integrated>.sealedBox: SealedBoxBuilder.Without<AuthCapability.Unauthenticated, KeyType.Integrated>

Creates a SealedBoxBuilder matching this algorithm's characteristics:

secretKey

val <A : AuthCapability<out KeyType.Integrated>, I : NonceTrait> SymmetricKey<A, I, out KeyType.Integrated>.secretKey: KmmResult<ByteArray>

The actual encryption key bytes

Functions

from

fun SealedBoxBuilder.WithNonce.Having<AuthCapability.Unauthenticated, KeyType.Integrated>.from( encryptedData: ByteArray): KmmResult<SealedBox<AuthCapability.Unauthenticated, NonceTrait.Required, KeyType.Integrated>>

fun <A : AuthCapability.Authenticated<out K>, K : KeyType> SealedBoxBuilder.WithNonce.Having<A, K>.from( encryptedData: ByteArray, authTag: ByteArray): KmmResult<SealedBox<A, NonceTrait.Required, K>>

Creates a SealedBox matching the characteristics of the underlying SealedBoxBuilder.algorithm. Use this function to load external encrypted data for decryption. Returns a KmmResult purely for the sake of consistency, even though this operation will always success

@JvmName(name = "fromUnauthenticatedWithoutNonce")

fun SealedBoxBuilder.Without<AuthCapability.Unauthenticated, KeyType.Integrated>.from( encryptedData: ByteArray): KmmResult<SealedBox<AuthCapability.Unauthenticated, NonceTrait.Without, KeyType.Integrated>>

@JvmName(name = "fromAuthenticatedGeneric")

fun SealedBoxBuilder.Without.Authenticated<AuthCapability.Authenticated<*>, *>.from( encryptedData: ByteArray, authTag: ByteArray): KmmResult<SealedBox<AuthCapability.Authenticated<*>, NonceTrait.Without, *>>

@JvmName(name = "fromAuthenticatedWihtKeyType")

fun <K : KeyType> SealedBoxBuilder.Without.Authenticated<AuthCapability.Authenticated<out K>, K>.from( encryptedData: ByteArray, authTag: ByteArray): KmmResult<SealedBox<AuthCapability.Authenticated<out K>, NonceTrait.Without, K>>

Creates a SealedBox matching the characteristics of the underlying SealedBoxBuilder.algorithm. Use this function to load external encrypted data for decryption.

hasDedicatedMac

@JvmName(name = "hasDedicatedMacAlias")

fun SymmetricEncryptionAlgorithm<*, I, *>.hasDedicatedMac(): Boolean

Use to smart-cast this algorithm

hasDedicatedMacKey

fun <A : AuthCapability<*>, I : NonceTrait> SymmetricKey<A, I, *>.hasDedicatedMacKey(): Boolean

Use to smart cast

hasNonce

fun <A : AuthCapability<out K>, K : KeyType, I : NonceTrait> SealedBox<A, I, out K>.hasNonce(): Boolean

Use to smart-cast this sealed box

isAuthenticated

fun <A : AuthCapability<out K>, K : KeyType, I : NonceTrait> SealedBox<A, I, out K>.isAuthenticated(): Boolean

Use to smart-cast this sealed box

@JvmName(name = "isAuthenticatedAlias")

fun SymmetricEncryptionAlgorithm<*, I, K>.isAuthenticated(): Boolean

Use to smart-cast this algorithm

fun <A : AuthCapability<K>, K : KeyType, I : NonceTrait> SymmetricKey<A, I, K>.isAuthenticated(): Boolean

Use to smart cast

isBlockCipher

@JvmName(name = "isBlockCipherAlias")

fun <A : AuthCapability<out K>, I : NonceTrait, K : KeyType> SymmetricEncryptionAlgorithm<A, I, K>.isBlockCipher(): Boolean

Use to smart-cast this algorithm

isIntegrated

@JvmName(name = "isIntegrated")

fun SymmetricEncryptionAlgorithm<AuthCapability.Authenticated<*>, I, *>.isIntegrated(): Boolean

Use to smart-cast this algorithm

fun <A : AuthCapability.Authenticated<*>, I : NonceTrait> SymmetricKey<A, I, *>.isIntegrated(): Boolean

Use to smart cast

isStreamCipher

@JvmName(name = "isStreamCipherAlias")

fun <A : AuthCapability<out K>, I : NonceTrait, K : KeyType> SymmetricEncryptionAlgorithm<A, I, K>.isStreamCipher(): Boolean

Use to smart-cast this algorithm

keyFrom

@JvmName(name = "fixedKeyAuthenticatedIntegrated")

fun SymmetricEncryptionAlgorithm<AuthCapability.Authenticated<KeyType.Integrated>, I, KeyType.Integrated>.keyFrom( secretKey: ByteArray): KmmResult<SymmetricKey<AuthCapability.Authenticated.Integrated, I, KeyType.Integrated>>

@JvmName(name = "fixedKeyIntegrated")

fun SymmetricEncryptionAlgorithm<AuthCapability<KeyType.Integrated>, I, KeyType.Integrated>.keyFrom( secretKey: ByteArray): KmmResult<SymmetricKey<AuthCapability<KeyType.Integrated>, I, KeyType.Integrated>>

Creates a SymmetricKey from the specified secretKey. Returns KmmResult.failure in case the provided bytes don't match SymmetricEncryptionAlgorithm.keySize

@JvmName(name = "fixedKeyDedicatedMacKey")

fun <A : AuthCapability<KeyType.WithDedicatedMacKey>, I : NonceTrait> SymmetricEncryptionAlgorithm<A, I, KeyType.WithDedicatedMacKey>.keyFrom( encryptionKey: ByteArray, macKey: ByteArray): KmmResult<SymmetricKey<A, I, KeyType.WithDedicatedMacKey>>

Creates a SymmetricKey from the specified encryptionKey and macKey. Returns KmmResult.failure in case the provided bytes don't match SymmetricEncryptionAlgorithm.keySize or the specified macKey is empty.

randomKey

suspend fun <A : AuthCapability<out K>, I : NonceTrait, K : KeyType> SymmetricEncryptionAlgorithm<A, I, K>.randomKey(): SymmetricKey<A, I, out K>

Generates a fresh random key for this algorithm.

@JvmName(name = "randomKeyAndMacKey")

suspend fun SymmetricEncryptionAlgorithm<AuthCapability.Authenticated.WithDedicatedMac, I, KeyType.WithDedicatedMacKey>.randomKey( macKeyLength: BitLength): SymmetricKey.WithDedicatedMac

Generates a fresh random key for this algorithm. macKeyLength can be specified to override preferredMacKeyLength.

randomNonce

fun SymmetricEncryptionAlgorithm<*, NonceTrait.Required, *>.randomNonce(): ByteArray

Generates a new random nonce matching the Nonce size of this algorithm. You typically don't want to use this, but have your nonces auto-generated during the encryption process

requiresNonce

@JvmName(name = "requiresNonceAlias")

fun <A : AuthCapability<out K>, K : KeyType> SymmetricEncryptionAlgorithm<A, *, K>.requiresNonce(): Boolean

Use to smart-cast this algorithm

fun <A : AuthCapability<K>, K : KeyType> SymmetricKey<A, *, K>.requiresNonce(): Boolean

Use to smart cast