| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Cardano.Crypto.KES.Class
Description
Abstract key evolving signatures.
Synopsis
- class (Typeable v, Show (VerKeyKES v), Eq (VerKeyKES v), Show (SigKES v), Eq (SigKES v), NoThunks (SigKES v), NoThunks (SignKeyKES v), NoThunks (VerKeyKES v), KnownNat (SeedSizeKES v), KnownNat (SizeVerKeyKES v), KnownNat (SizeSignKeyKES v), KnownNat (SizeSigKES v)) ⇒ KESAlgorithm v where
- data VerKeyKES v ∷ Type
- data SigKES v ∷ Type
- data SignKeyKES v ∷ Type
- type SeedSizeKES v ∷ Nat
- type SizeVerKeyKES v ∷ Nat
- type SizeSignKeyKES v ∷ Nat
- type SizeSigKES v ∷ Nat
- type ContextKES v ∷ Type
- type Signable v ∷ Type → Constraint
- algorithmNameKES ∷ proxy v → String
- hashVerKeyKES ∷ HashAlgorithm h ⇒ VerKeyKES v → Hash h (VerKeyKES v)
- verifyKES ∷ (Signable v a, HasCallStack) ⇒ ContextKES v → VerKeyKES v → Period → a → SigKES v → Either String ()
- totalPeriodsKES ∷ proxy v → Word
- rawSerialiseVerKeyKES ∷ VerKeyKES v → ByteString
- rawSerialiseSigKES ∷ SigKES v → ByteString
- rawDeserialiseVerKeyKES ∷ ByteString → Maybe (VerKeyKES v)
- rawDeserialiseSigKES ∷ ByteString → Maybe (SigKES v)
- deriveVerKeyKES ∷ (MonadST m, MonadThrow m) ⇒ SignKeyKES v → m (VerKeyKES v)
- signKES ∷ ∀ a m. (Signable v a, MonadST m, MonadThrow m) ⇒ ContextKES v → Period → a → SignKeyKES v → m (SigKES v)
- updateKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → ContextKES v → SignKeyKES v → Period → m (Maybe (SignKeyKES v))
- genKeyKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → MLockedSeed (SeedSizeKES v) → m (SignKeyKES v)
- forgetSignKeyKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → SignKeyKES v → m ()
- genKeyKES ∷ ∀ v m. (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ MLockedSeed (SeedSizeKES v) → m (SignKeyKES v)
- updateKES ∷ ∀ v m. (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ ContextKES v → SignKeyKES v → Period → m (Maybe (SignKeyKES v))
- forgetSignKeyKES ∷ (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ SignKeyKES v → m ()
- type Period = Word
- class KESAlgorithm v ⇒ OptimizedKESAlgorithm v where
- verifySigKES ∷ (Signable v a, HasCallStack) ⇒ ContextKES v → Period → a → SigKES v → Either String ()
- verKeyFromSigKES ∷ ContextKES v → Period → SigKES v → VerKeyKES v
- verifyOptimizedKES ∷ (OptimizedKESAlgorithm v, Signable v a, HasCallStack) ⇒ ContextKES v → VerKeyKES v → Period → a → SigKES v → Either String ()
- data SignKeyWithPeriodKES v = SignKeyWithPeriodKES {
- skWithoutPeriodKES ∷ !(SignKeyKES v)
- periodKES ∷ !Period
- updateKESWithPeriod ∷ (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ ContextKES v → SignKeyWithPeriodKES v → m (Maybe (SignKeyWithPeriodKES v))
- newtype SignedKES v a = SignedKES {}
- signedKES ∷ (KESAlgorithm v, Signable v a, MonadST m, MonadThrow m) ⇒ ContextKES v → Period → a → SignKeyKES v → m (SignedKES v a)
- verifySignedKES ∷ (KESAlgorithm v, Signable v a) ⇒ ContextKES v → VerKeyKES v → Period → a → SignedKES v a → Either String ()
- encodeVerKeyKES ∷ KESAlgorithm v ⇒ VerKeyKES v → Encoding
- decodeVerKeyKES ∷ ∀ v s. KESAlgorithm v ⇒ Decoder s (VerKeyKES v)
- encodeSigKES ∷ KESAlgorithm v ⇒ SigKES v → Encoding
- decodeSigKES ∷ ∀ v s. KESAlgorithm v ⇒ Decoder s (SigKES v)
- encodeSignedKES ∷ KESAlgorithm v ⇒ SignedKES v a → Encoding
- decodeSignedKES ∷ KESAlgorithm v ⇒ Decoder s (SignedKES v a)
- encodedVerKeyKESSizeExpr ∷ ∀ v. KESAlgorithm v ⇒ Proxy (VerKeyKES v) → Size
- encodedSignKeyKESSizeExpr ∷ ∀ v. KESAlgorithm v ⇒ Proxy (SignKeyKES v) → Size
- encodedSigKESSizeExpr ∷ ∀ v. KESAlgorithm v ⇒ Proxy (SigKES v) → Size
- sizeVerKeyKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word
- sizeSigKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word
- sizeSignKeyKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word
- seedSizeKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word
- class KESAlgorithm v ⇒ UnsoundKESAlgorithm v where
- rawDeserialiseSignKeyKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → ByteString → m (Maybe (SignKeyKES v))
- rawSerialiseSignKeyKES ∷ (MonadST m, MonadThrow m) ⇒ SignKeyKES v → m ByteString
- encodeSignKeyKES ∷ ∀ v m. (UnsoundKESAlgorithm v, MonadST m, MonadThrow m) ⇒ SignKeyKES v → m Encoding
- decodeSignKeyKES ∷ ∀ v s m. (UnsoundKESAlgorithm v, MonadST m, MonadThrow m) ⇒ Decoder s (m (Maybe (SignKeyKES v)))
- rawDeserialiseSignKeyKES ∷ (UnsoundKESAlgorithm v, MonadST m, MonadThrow m) ⇒ ByteString → m (Maybe (SignKeyKES v))
- class KESAlgorithm v ⇒ UnsoundPureKESAlgorithm v where
- data UnsoundPureSignKeyKES v ∷ Type
- unsoundPureSignKES ∷ ∀ a. Signable v a ⇒ ContextKES v → Period → a → UnsoundPureSignKeyKES v → SigKES v
- unsoundPureUpdateKES ∷ ContextKES v → UnsoundPureSignKeyKES v → Period → Maybe (UnsoundPureSignKeyKES v)
- unsoundPureGenKeyKES ∷ Seed → UnsoundPureSignKeyKES v
- unsoundPureDeriveVerKeyKES ∷ UnsoundPureSignKeyKES v → VerKeyKES v
- unsoundPureSignKeyKESToSoundSignKeyKES ∷ (MonadST m, MonadThrow m) ⇒ UnsoundPureSignKeyKES v → m (SignKeyKES v)
- rawSerialiseUnsoundPureSignKeyKES ∷ UnsoundPureSignKeyKES v → ByteString
- rawDeserialiseUnsoundPureSignKeyKES ∷ ByteString → Maybe (UnsoundPureSignKeyKES v)
- unsoundPureSignedKES ∷ (UnsoundPureKESAlgorithm v, Signable v a) ⇒ ContextKES v → Period → a → UnsoundPureSignKeyKES v → SignedKES v a
- encodeUnsoundPureSignKeyKES ∷ UnsoundPureKESAlgorithm v ⇒ UnsoundPureSignKeyKES v → Encoding
- decodeUnsoundPureSignKeyKES ∷ ∀ v s. UnsoundPureKESAlgorithm v ⇒ Decoder s (UnsoundPureSignKeyKES v)
- hashPairOfVKeys ∷ (KESAlgorithm d, HashAlgorithm h) ⇒ (VerKeyKES d, VerKeyKES d) → Hash h (VerKeyKES d, VerKeyKES d)
- mungeName ∷ String → String
- unsoundPureSignKeyKESToSoundSignKeyKESViaSer ∷ (MonadST m, MonadThrow m, UnsoundKESAlgorithm k, UnsoundPureKESAlgorithm k) ⇒ UnsoundPureSignKeyKES k → m (SignKeyKES k)
KES algorithm class
class (Typeable v, Show (VerKeyKES v), Eq (VerKeyKES v), Show (SigKES v), Eq (SigKES v), NoThunks (SigKES v), NoThunks (SignKeyKES v), NoThunks (VerKeyKES v), KnownNat (SeedSizeKES v), KnownNat (SizeVerKeyKES v), KnownNat (SizeSignKeyKES v), KnownNat (SizeSigKES v)) ⇒ KESAlgorithm v where Source #
Minimal complete definition
algorithmNameKES, verifyKES, totalPeriodsKES, rawSerialiseVerKeyKES, rawSerialiseSigKES, rawDeserialiseVerKeyKES, rawDeserialiseSigKES, deriveVerKeyKES, signKES, updateKESWith, genKeyKESWith, forgetSignKeyKESWith
Associated Types
data VerKeyKES v ∷ Type Source #
data SignKeyKES v ∷ Type Source #
type SeedSizeKES v ∷ Nat Source #
type SizeVerKeyKES v ∷ Nat Source #
type SizeSignKeyKES v ∷ Nat Source #
type SizeSigKES v ∷ Nat Source #
type ContextKES v ∷ Type Source #
Context required to run the KES algorithm
Unit by default (no context required)
type ContextKES v = ()
type Signable v ∷ Type → Constraint Source #
Methods
algorithmNameKES ∷ proxy v → String Source #
hashVerKeyKES ∷ HashAlgorithm h ⇒ VerKeyKES v → Hash h (VerKeyKES v) Source #
Arguments
| ∷ (Signable v a, HasCallStack) | |
| ⇒ ContextKES v | |
| → VerKeyKES v | |
| → Period | The current period for the key |
| → a | |
| → SigKES v | |
| → Either String () |
Full KES verification. This method checks that the signature itself
checks out (as per verifySigKES), and also makes sure that it matches
the provided VerKey.
totalPeriodsKES ∷ proxy v → Word Source #
Return the total number of KES periods supported by this algorithm. The KES algorithm is assumed to support a fixed maximum number of periods, not a variable number.
Do note that this is the total number of periods not the total number of evolutions. The difference is off-by-one. For example if there are 2 periods (period 0 and 1) then there is only one evolution.
rawSerialiseVerKeyKES ∷ VerKeyKES v → ByteString Source #
rawSerialiseSigKES ∷ SigKES v → ByteString Source #
rawDeserialiseVerKeyKES ∷ ByteString → Maybe (VerKeyKES v) Source #
rawDeserialiseSigKES ∷ ByteString → Maybe (SigKES v) Source #
deriveVerKeyKES ∷ (MonadST m, MonadThrow m) ⇒ SignKeyKES v → m (VerKeyKES v) Source #
Arguments
| ∷ ∀ a m. (Signable v a, MonadST m, MonadThrow m) | |
| ⇒ ContextKES v | |
| → Period | The current period for the key |
| → a | |
| → SignKeyKES v | |
| → m (SigKES v) |
Arguments
| ∷ (MonadST m, MonadThrow m) | |
| ⇒ MLockedAllocator m | |
| → ContextKES v | |
| → SignKeyKES v | |
| → Period | The current period for the key, not the target period. |
| → m (Maybe (SignKeyKES v)) |
genKeyKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → MLockedSeed (SeedSizeKES v) → m (SignKeyKES v) Source #
forgetSignKeyKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → SignKeyKES v → m () Source #
Forget a signing key synchronously, rather than waiting for GC. In some non-mock instances this provides a guarantee that the signing key is no longer in memory.
The precondition is that this key value will not be used again.
Instances
genKeyKES ∷ ∀ v m. (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ MLockedSeed (SeedSizeKES v) → m (SignKeyKES v) Source #
Key generation
Arguments
| ∷ ∀ v m. (KESAlgorithm v, MonadST m, MonadThrow m) | |
| ⇒ ContextKES v | |
| → SignKeyKES v | |
| → Period | The current period for the key, not the target period. |
| → m (Maybe (SignKeyKES v)) |
Update the KES signature key to the next period, given the current period.
It returns Nothing if the cannot be evolved any further.
The precondition (to get a Just result) is that the current KES period
of the input key is not the last period. The given period must be the
current KES period of the input key (not the next or target).
The postcondition is that in case a key is returned, its current KES period is incremented by one compared to before.
Note that you must track the current period separately, and to skip to a later period requires repeated use of this function, since it only increments one period at once.
forgetSignKeyKES ∷ (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ SignKeyKES v → m () Source #
Forget a signing key synchronously, rather than waiting for GC. In some non-mock instances this provides a guarantee that the signing key is no longer in memory.
The precondition is that this key value will not be used again.
The KES period. Periods are enumerated from zero.
Be careful of fencepost errors: if there are 2 periods (period 0 and 1) then there is only one key evolution.
class KESAlgorithm v ⇒ OptimizedKESAlgorithm v where Source #
Subclass for KES algorithms that embed a copy of the VerKey into the
signature itself, rather than relying on the externally supplied VerKey
alone. Some optimizations made in the CompactSingleKES
and CompactSumKES implementations require this
additional interface in order to avoid redundant computations.
Methods
Arguments
| ∷ (Signable v a, HasCallStack) | |
| ⇒ ContextKES v | |
| → Period | The current period for the key |
| → a | |
| → SigKES v | |
| → Either String () |
Partial verification: this method only verifies the signature itself,
but it does not check it against any externally-provided VerKey. Use
verifyKES for full KES verification.
verKeyFromSigKES ∷ ContextKES v → Period → SigKES v → VerKeyKES v Source #
Extract a VerKey from a SigKES. Note that a VerKey embedded in or
derived from a SigKES is effectively user-supplied, so it is not enough
to validate a SigKES against this VerKey (like verifySigKES does); you
must also compare the VerKey against an externally-provided key that you
want to verify against (see verifyKES).
Instances
| (KESAlgorithm (CompactSingleKES d), DSIGNMAlgorithm d) ⇒ OptimizedKESAlgorithm (CompactSingleKES d) Source # | |
Defined in Cardano.Crypto.KES.CompactSingle Methods verifySigKES ∷ (Signable (CompactSingleKES d) a, HasCallStack) ⇒ ContextKES (CompactSingleKES d) → Period → a → SigKES (CompactSingleKES d) → Either String () Source # verKeyFromSigKES ∷ ContextKES (CompactSingleKES d) → Period → SigKES (CompactSingleKES d) → VerKeyKES (CompactSingleKES d) Source # | |
| (KESAlgorithm (CompactSumKES h d), OptimizedKESAlgorithm d, HashAlgorithm h) ⇒ OptimizedKESAlgorithm (CompactSumKES h d) Source # | |
Defined in Cardano.Crypto.KES.CompactSum Methods verifySigKES ∷ (Signable (CompactSumKES h d) a, HasCallStack) ⇒ ContextKES (CompactSumKES h d) → Period → a → SigKES (CompactSumKES h d) → Either String () Source # verKeyFromSigKES ∷ ContextKES (CompactSumKES h d) → Period → SigKES (CompactSumKES h d) → VerKeyKES (CompactSumKES h d) Source # | |
verifyOptimizedKES ∷ (OptimizedKESAlgorithm v, Signable v a, HasCallStack) ⇒ ContextKES v → VerKeyKES v → Period → a → SigKES v → Either String () Source #
SignKeyWithPeriodKES wrapper
data SignKeyWithPeriodKES v Source #
A sign key bundled with its associated period.
Constructors
| SignKeyWithPeriodKES | |
Fields
| |
Instances
updateKESWithPeriod ∷ (KESAlgorithm v, MonadST m, MonadThrow m) ⇒ ContextKES v → SignKeyWithPeriodKES v → m (Maybe (SignKeyWithPeriodKES v)) Source #
SignedKES wrapper
signedKES ∷ (KESAlgorithm v, Signable v a, MonadST m, MonadThrow m) ⇒ ContextKES v → Period → a → SignKeyKES v → m (SignedKES v a) Source #
verifySignedKES ∷ (KESAlgorithm v, Signable v a) ⇒ ContextKES v → VerKeyKES v → Period → a → SignedKES v a → Either String () Source #
CBOR encoding and decoding
encodeVerKeyKES ∷ KESAlgorithm v ⇒ VerKeyKES v → Encoding Source #
decodeVerKeyKES ∷ ∀ v s. KESAlgorithm v ⇒ Decoder s (VerKeyKES v) Source #
encodeSigKES ∷ KESAlgorithm v ⇒ SigKES v → Encoding Source #
decodeSigKES ∷ ∀ v s. KESAlgorithm v ⇒ Decoder s (SigKES v) Source #
encodeSignedKES ∷ KESAlgorithm v ⇒ SignedKES v a → Encoding Source #
decodeSignedKES ∷ KESAlgorithm v ⇒ Decoder s (SignedKES v a) Source #
Encoded Size expressions
encodedVerKeyKESSizeExpr ∷ ∀ v. KESAlgorithm v ⇒ Proxy (VerKeyKES v) → Size Source #
Size expression for VerKeyKES which is using sizeVerKeyKES encoded
as Size.
encodedSignKeyKESSizeExpr ∷ ∀ v. KESAlgorithm v ⇒ Proxy (SignKeyKES v) → Size Source #
Size expression for SignKeyKES which is using sizeSignKeyKES encoded
as Size.
encodedSigKESSizeExpr ∷ ∀ v. KESAlgorithm v ⇒ Proxy (SigKES v) → Size Source #
Size expression for SigKES which is using sizeSigKES encoded as
Size.
Raw sizes
sizeVerKeyKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word Source #
sizeSigKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word Source #
sizeSignKeyKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word Source #
seedSizeKES ∷ ∀ v proxy. KESAlgorithm v ⇒ proxy v → Word Source #
Unsound APIs
class KESAlgorithm v ⇒ UnsoundKESAlgorithm v where Source #
Unsound operations on KES sign keys. These operations violate secure
forgetting constraints by leaking secrets to unprotected memory. Consider
using the DirectSerialise / DirectDeserialise APIs instead.
Methods
rawDeserialiseSignKeyKESWith ∷ (MonadST m, MonadThrow m) ⇒ MLockedAllocator m → ByteString → m (Maybe (SignKeyKES v)) Source #
rawSerialiseSignKeyKES ∷ (MonadST m, MonadThrow m) ⇒ SignKeyKES v → m ByteString Source #
Instances
encodeSignKeyKES ∷ ∀ v m. (UnsoundKESAlgorithm v, MonadST m, MonadThrow m) ⇒ SignKeyKES v → m Encoding Source #
decodeSignKeyKES ∷ ∀ v s m. (UnsoundKESAlgorithm v, MonadST m, MonadThrow m) ⇒ Decoder s (m (Maybe (SignKeyKES v))) Source #
rawDeserialiseSignKeyKES ∷ (UnsoundKESAlgorithm v, MonadST m, MonadThrow m) ⇒ ByteString → m (Maybe (SignKeyKES v)) Source #
class KESAlgorithm v ⇒ UnsoundPureKESAlgorithm v where Source #
Pure implementations of the core KES operations. These are unsound, because proper handling of KES secrets (seeds, sign keys) requires mlocking and deterministic erasure ("secure forgetting"), which is not possible in pure code. This API is only provided for testing purposes; it must not be used to generate or use real KES keys.
Associated Types
data UnsoundPureSignKeyKES v ∷ Type Source #
Methods
Arguments
| ∷ ∀ a. Signable v a | |
| ⇒ ContextKES v | |
| → Period | The current period for the key |
| → a | |
| → UnsoundPureSignKeyKES v | |
| → SigKES v |
Arguments
| ∷ ContextKES v | |
| → UnsoundPureSignKeyKES v | |
| → Period | The current period for the key, not the target period. |
| → Maybe (UnsoundPureSignKeyKES v) |
unsoundPureGenKeyKES ∷ Seed → UnsoundPureSignKeyKES v Source #
unsoundPureDeriveVerKeyKES ∷ UnsoundPureSignKeyKES v → VerKeyKES v Source #
unsoundPureSignKeyKESToSoundSignKeyKES ∷ (MonadST m, MonadThrow m) ⇒ UnsoundPureSignKeyKES v → m (SignKeyKES v) Source #
rawSerialiseUnsoundPureSignKeyKES ∷ UnsoundPureSignKeyKES v → ByteString Source #
rawDeserialiseUnsoundPureSignKeyKES ∷ ByteString → Maybe (UnsoundPureSignKeyKES v) Source #
Instances
unsoundPureSignedKES ∷ (UnsoundPureKESAlgorithm v, Signable v a) ⇒ ContextKES v → Period → a → UnsoundPureSignKeyKES v → SignedKES v a Source #
encodeUnsoundPureSignKeyKES ∷ UnsoundPureKESAlgorithm v ⇒ UnsoundPureSignKeyKES v → Encoding Source #
decodeUnsoundPureSignKeyKES ∷ ∀ v s. UnsoundPureKESAlgorithm v ⇒ Decoder s (UnsoundPureSignKeyKES v) Source #
Utility functions
hashPairOfVKeys ∷ (KESAlgorithm d, HashAlgorithm h) ⇒ (VerKeyKES d, VerKeyKES d) → Hash h (VerKeyKES d, VerKeyKES d) Source #
unsoundPureSignKeyKESToSoundSignKeyKESViaSer ∷ (MonadST m, MonadThrow m, UnsoundKESAlgorithm k, UnsoundPureKESAlgorithm k) ⇒ UnsoundPureSignKeyKES k → m (SignKeyKES k) Source #
Helper function for implementing unsoundPureSignKeyKESToSoundSignKeyKES
for KES algorithms that support both UnsoundKESAlgorithm and
UnsoundPureKESAlgorithm. For such KES algorithms, unsound sign keys can be
marshalled to sound sign keys by serializing and then deserializing them.