Z.Crypto.SafeMem

Password

data Password

A type for human readable, it have

The Key have the properties that:

• It's assumed to be UTF8 encoded and normalized, and does not have control-characters.
• There's no Eq instance, you should always compare Password via password hash.
• The Show or Print instance always print "**PASSWORD**".

Password is not intented to be saved or transmitted, it's only useful when you want to validate a user's input against password hash. See Z.Crypto.PwdHash.

Instances

Show Password

Defined in Z.Crypto.SafeMem

Methods

showsPrec :: Int -> Password -> ShowS

show :: Password -> String

showList :: [Password] -> ShowS

IsString Password

Defined in Z.Crypto.SafeMem

Methods

fromString :: String -> Password

Print Password

Defined in Z.Crypto.SafeMem

Methods

toUTF8BuilderP :: Int -> Password -> Builder ()

mkPassword :: HasCallStack => Text -> Password

Construct a password value from Text, if there're control-characters error will be thrown.

mkPasswordMaybe :: Text -> Maybe Password

Construct a password value from Text, return Nothing if contain control-characters.

passwordSize :: Password -> Int

Byte size of a password.

passwordToText :: Password -> Text

Get plaintext of a password.

withPasswordUnsafe :: Password -> (BA# Word8 -> IO r) -> IO r

Use password as null-terminated const char*, USE WITH UNSAFE FFI ONLY, PLEASE DO NOT MODIFY THE CONTENT.

withPasswordSafe :: Password -> (Ptr Word8 -> IO r) -> IO r

Use password as null-terminated const char*, PLEASE DO NOT MODIFY THE CONTENT.

data InvalidPasswordException

Constructors

PasswordContainsControlCharacter CallStack

Instances

Show InvalidPasswordException

Defined in Z.Crypto.SafeMem

Methods

showsPrec :: Int -> InvalidPasswordException -> ShowS

show :: InvalidPasswordException -> String

showList :: [InvalidPasswordException] -> ShowS

Exception InvalidPasswordException

Defined in Z.Crypto.SafeMem

Methods

toException :: InvalidPasswordException -> SomeException

fromException :: SomeException -> Maybe InvalidPasswordException

displayException :: InvalidPasswordException -> String

Nonce

type Nonce = Bytes

A value used only once in AEAD modes.

We use also this type to represent IV(initialization vector) for stream ciphers, but the way a nonce is generated is different: random IV is one generation choice which is usually fine, while Nonce can also be a counter, which is not ok for CBC mode.

Some common nonce size:

• 96bit for GCM AEAD, ChaCha20Poly1305.
• 128bit for XChaCha20Poly1305.
• Block size for CBC IV(e.g. 128 bits for AES).

rand96bitNonce :: RNG -> IO Nonce

Get 64-bit random nonce.

rand128bitNonce :: RNG -> IO Nonce

Get 128-bit random nonce.

rand192bitNonce :: RNG -> IO Nonce

Get 192-bit random nonce.

cnt32bitNonce :: Int32 -> Nonce

Get 32bit nonce from counter.

cnt64bitNonce :: Int64 -> Nonce

Get 64bit nonce from counter.

CEBytes

newtype CEBytes

Constant-time equal comparing bytes.

It comes with following property:

• The Eq instance gives you constant-time compare.
• The Show and Print instances give you hex encoding.

Constructors

CEBytes (PrimArray Word8)

Instances

Eq CEBytes

Defined in Z.Crypto.SafeMem

Methods

(==) :: CEBytes -> CEBytes -> Bool

(/=) :: CEBytes -> CEBytes -> Bool

Show CEBytes

Defined in Z.Crypto.SafeMem

Methods

showsPrec :: Int -> CEBytes -> ShowS

show :: CEBytes -> String

showList :: [CEBytes] -> ShowS

Print CEBytes

Defined in Z.Crypto.SafeMem

Methods

toUTF8BuilderP :: Int -> CEBytes -> Builder ()

ceBytesSize :: CEBytes -> Int

ceBytesBitSize :: CEBytes -> Int

newCEBytesUnsafe :: Int -> (MBA# Word8 -> IO r) -> IO CEBytes

Create a ceBytes from unsafe FFI.

newCEBytesSafe :: Int -> (Ptr Word8 -> IO r) -> IO CEBytes

Create a ceBytes from safe FFI.

ceBytes :: Bytes -> CEBytes

Create a CEBytes from Bytes.

unCEBytes :: CEBytes -> Bytes

Get CEBytes 's content as Bytes, by doing this you lose the constant-time comparing.

Secret

data Secret

Memory allocated by locked allocator and will be zeroed after used.

• It's allocated by botan's locking allocator(which means it will not get swapped to disk) if possible.
• It will zero the memory it used once get GCed.
• The Eq instance gives you constant-time compare.
• The Show or Print instance always print "**SECRET**".

Secret is not intented to be saved or transmitted, there're several way to obtain a Secret:

+ Use unsafeSecretFromBytes to convert a piece of Bytes to Secret. + Use key-exchanges from PubKey. + Unwrap a key, see KeyWrap.

Instances

Eq Secret

Constant-time compare

Defined in Z.Crypto.SafeMem

Methods

(==) :: Secret -> Secret -> Bool

(/=) :: Secret -> Secret -> Bool

Show Secret

Defined in Z.Crypto.SafeMem

Methods

showsPrec :: Int -> Secret -> ShowS

show :: Secret -> String

showList :: [Secret] -> ShowS

IsString Secret

This instance will break the no-tracing property by saving secret in compiled and loaded binary.

Defined in Z.Crypto.SafeMem

Methods

fromString :: String -> Secret

Print Secret

Defined in Z.Crypto.SafeMem

Methods

toUTF8BuilderP :: Int -> Secret -> Builder ()

secretSize :: Secret -> Int

Get secret key's byte length.

secretBitSize :: Secret -> Int

Get secret key's bit size.

unsafeSecretFromBytes :: Bytes -> IO Secret

Unsafe convert a Bytes to a Secret.

Note the original Bytes may get moved by GC or swapped to disk, which may defeat the purpose of using a Secret.

unsafeSecretToBytes :: Secret -> IO Bytes

Unsafe convert a Bytes from a Secret.

Note the result Bytes may get moved by GC or swapped to disk, which may defeat the purpose of using a Secret.

newSecret :: Int -> (Ptr Word8 -> IO r) -> IO Secret

Initialize a Secret which pass an allocated pointer pointing to zeros to a init function.

withSecret :: Secret -> (Ptr Word8 -> CSize -> IO r) -> IO r

Use Secret as a const char*, PLEASE DO NOT MODIFY THE CONTENT.