Safe Haskell	None
Language	Haskell2010

Z.Crypto.SafeMem

Contents

Password
Nonce
CEBytes
Secret

Synopsis

data Password
mkPassword :: HasCallStack => Text -> Password
mkPasswordMaybe :: Text -> Maybe Password
passwordSize :: Password -> Int
passwordToText :: Password -> Text
withPasswordUnsafe :: Password -> (BA# Word8 -> IO r) -> IO r
withPasswordSafe :: Password -> (Ptr Word8 -> IO r) -> IO r
data InvalidPasswordException = PasswordContainsControlCharacter CallStack
type Nonce = Bytes
rand96bitNonce :: RNG -> IO Nonce
rand128bitNonce :: RNG -> IO Nonce
rand192bitNonce :: RNG -> IO Nonce
cnt32bitNonce :: Int32 -> Nonce
cnt64bitNonce :: Int64 -> Nonce
newtype CEBytes = CEBytes (PrimArray Word8)
ceBytesSize :: CEBytes -> Int
ceBytesBitSize :: CEBytes -> Int
newCEBytesUnsafe :: Int -> (MBA# Word8 -> IO r) -> IO CEBytes
newCEBytesSafe :: Int -> (Ptr Word8 -> IO r) -> IO CEBytes
ceBytes :: Bytes -> CEBytes
unCEBytes :: CEBytes -> Bytes
data Secret
secretSize :: Secret -> Int
secretBitSize :: Secret -> Int
unsafeSecretFromBytes :: Bytes -> IO Secret
unsafeSecretToBytes :: Secret -> IO Bytes
newSecret :: Int -> (Ptr Word8 -> IO r) -> IO Secret
withSecret :: Secret -> (Ptr Word8 -> CSize -> IO r) -> IO r

Password

data Password Source #

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

Instances details

Show Password Source #
Instance details Defined in Z.Crypto.SafeMem Methods showsPrec :: Int -> Password -> ShowS # show :: Password -> String # showList :: [Password] -> ShowS #
IsString Password Source #
Instance details Defined in Z.Crypto.SafeMem Methods fromString :: String -> Password #
Print Password Source #
Instance details Defined in Z.Crypto.SafeMem Methods toUTF8BuilderP :: Int -> Password -> Builder () #

mkPassword :: HasCallStack => Text -> Password Source #

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

mkPasswordMaybe :: Text -> Maybe Password Source #

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

passwordSize :: Password -> Int Source #

Byte size of a password.

passwordToText :: Password -> Text Source #

Get plaintext of a password.

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

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 Source #

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

data InvalidPasswordException Source #

Constructors

PasswordContainsControlCharacter CallStack

Instances

Instances details

Show InvalidPasswordException Source #
Instance details Defined in Z.Crypto.SafeMem Methods showsPrec :: Int -> InvalidPasswordException -> ShowS # show :: InvalidPasswordException -> String # showList :: [InvalidPasswordException] -> ShowS #
Exception InvalidPasswordException Source #
Instance details Defined in Z.Crypto.SafeMem Methods toException :: InvalidPasswordException -> SomeException # fromException :: SomeException -> Maybe InvalidPasswordException # displayException :: InvalidPasswordException -> String #

Nonce

type Nonce = Bytes Source #

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 Source #

Get 64-bit random nonce.

rand128bitNonce :: RNG -> IO Nonce Source #

Get 128-bit random nonce.

rand192bitNonce :: RNG -> IO Nonce Source #

Get 192-bit random nonce.

cnt32bitNonce :: Int32 -> Nonce Source #

Get 32bit nonce from counter.

cnt64bitNonce :: Int64 -> Nonce Source #

Get 64bit nonce from counter.

CEBytes

newtype CEBytes Source #

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

Instances details

Eq CEBytes Source #
Instance details Defined in Z.Crypto.SafeMem Methods (==) :: CEBytes -> CEBytes -> Bool # (/=) :: CEBytes -> CEBytes -> Bool #
Show CEBytes Source #
Instance details Defined in Z.Crypto.SafeMem Methods showsPrec :: Int -> CEBytes -> ShowS # show :: CEBytes -> String # showList :: [CEBytes] -> ShowS #
Print CEBytes Source #
Instance details Defined in Z.Crypto.SafeMem Methods toUTF8BuilderP :: Int -> CEBytes -> Builder () #

ceBytesSize :: CEBytes -> Int Source #

ceBytesBitSize :: CEBytes -> Int Source #

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

Create a ceBytes from unsafe FFI.

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

Create a ceBytes from safe FFI.

ceBytes :: Bytes -> CEBytes Source #

Create a CEBytes from Bytes.

unCEBytes :: CEBytes -> Bytes Source #

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

Secret

data Secret Source #

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

Instances details

Eq Secret Source #	Constant-time compare
Instance details Defined in Z.Crypto.SafeMem Methods (==) :: Secret -> Secret -> Bool # (/=) :: Secret -> Secret -> Bool #
Show Secret Source #
Instance details Defined in Z.Crypto.SafeMem Methods showsPrec :: Int -> Secret -> ShowS # show :: Secret -> String # showList :: [Secret] -> ShowS #
IsString Secret Source #	This instance will break the no-tracing property by saving secret in compiled and loaded binary.
Instance details Defined in Z.Crypto.SafeMem Methods fromString :: String -> Secret #
Print Secret Source #
Instance details Defined in Z.Crypto.SafeMem Methods toUTF8BuilderP :: Int -> Secret -> Builder () #

secretSize :: Secret -> Int Source #

Get secret key's byte length.

secretBitSize :: Secret -> Int Source #

Get secret key's bit size.

unsafeSecretFromBytes :: Bytes -> IO Secret Source #

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 Source #

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 Source #

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

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

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