Z-Botan 0.1.1.2 → 0.2.0.0

raw patch · 82 files changed

+22001/−525 lines, 82 filesdep ~Z-IOPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: Z-IO

API changes (from Hackage documentation)

Files

• ChangeLog.md +7/−1
• Z-Botan.cabal +10/−2
• Z/Botan/FFI.hsc +2/−0
• Z/Crypto/Cipher.hs +20/−0
• Z/Crypto/FPE.hs +9/−3
• Z/Crypto/Hash.hs +6/−1
• Z/Crypto/KDF.hs +20/−16
• Z/Crypto/KeyWrap.hs +5/−2
• Z/Crypto/MAC.hs +6/−4
• Z/Crypto/MPI.hs +32/−5
• Z/Crypto/OTP.hs +16/−6
• Z/Crypto/PubKey.hs +159/−146
• Z/Crypto/PwdHash.hs +6/−2
• Z/Crypto/RNG.hs +14/−7
• Z/Crypto/X509.hs +69/−13
• third_party/botan/botan_all.cpp too large to diff
• third_party/botan/doc/abi.rst +21/−0
• third_party/botan/doc/api_ref/bigint.rst +279/−0
• third_party/botan/doc/api_ref/block_cipher.rst +361/−0
• third_party/botan/doc/api_ref/cipher_modes.rst +384/−0
• third_party/botan/doc/api_ref/compression.rst +90/−0
• third_party/botan/doc/api_ref/contents.rst +39/−0
• third_party/botan/doc/api_ref/credentials_manager.rst +186/−0
• third_party/botan/doc/api_ref/cryptobox.rst +32/−0
• third_party/botan/doc/api_ref/ecc.rst +284/−0
• third_party/botan/doc/api_ref/env_vars.rst +20/−0
• third_party/botan/doc/api_ref/ffi.rst +1203/−0
• third_party/botan/doc/api_ref/filters.rst +733/−0
• third_party/botan/doc/api_ref/fpe.rst +98/−0
• third_party/botan/doc/api_ref/hash.rst +348/−0
• third_party/botan/doc/api_ref/kdf.rst +106/−0
• third_party/botan/doc/api_ref/keywrap.rst +60/−0
• third_party/botan/doc/api_ref/message_auth_codes.rst +268/−0
• third_party/botan/doc/api_ref/otp.rst +98/−0
• third_party/botan/doc/api_ref/passhash.rst +219/−0
• third_party/botan/doc/api_ref/pbkdf.rst +190/−0
• third_party/botan/doc/api_ref/pkcs11.rst +1419/−0
• third_party/botan/doc/api_ref/psk_db.rst +108/−0
• third_party/botan/doc/api_ref/pubkey.rst +954/−0
• third_party/botan/doc/api_ref/python.rst +668/−0
• third_party/botan/doc/api_ref/rng.rst +281/−0
• third_party/botan/doc/api_ref/roughtime.rst +6/−0
• third_party/botan/doc/api_ref/secmem.rst +31/−0
• third_party/botan/doc/api_ref/srp.rst +77/−0
• third_party/botan/doc/api_ref/stream_ciphers.rst +211/−0
• third_party/botan/doc/api_ref/tls.rst +1926/−0
• third_party/botan/doc/api_ref/tpm.rst +113/−0
• third_party/botan/doc/api_ref/tss.rst +45/−0
• third_party/botan/doc/api_ref/versions.rst +100/−0
• third_party/botan/doc/api_ref/x509.rst +914/−0
• third_party/botan/doc/authors.txt +102/−0
• third_party/botan/doc/building.rst +1019/−0
• third_party/botan/doc/cli.rst +406/−0
• third_party/botan/doc/contents.rst +25/−0
• third_party/botan/doc/credits.rst +156/−0
• third_party/botan/doc/deprecated.rst +297/−0
• third_party/botan/doc/dev_ref/configure.rst +407/−0
• third_party/botan/doc/dev_ref/contents.rst +20/−0
• third_party/botan/doc/dev_ref/continuous_integration.rst +75/−0
• third_party/botan/doc/dev_ref/contributing.rst +268/−0
• third_party/botan/doc/dev_ref/fuzzing.rst +91/−0
• third_party/botan/doc/dev_ref/mistakes.rst +77/−0
• third_party/botan/doc/dev_ref/oids.rst +43/−0
• third_party/botan/doc/dev_ref/os.rst +61/−0
• third_party/botan/doc/dev_ref/reading_list.rst +93/−0
• third_party/botan/doc/dev_ref/release_process.rst +129/−0
• third_party/botan/doc/dev_ref/test_framework.rst +314/−0
• third_party/botan/doc/dev_ref/todo.rst +199/−0
• third_party/botan/doc/goals.rst +131/−0
• third_party/botan/doc/index.rst +58/−0
• third_party/botan/doc/old_news.rst +4336/−0
• third_party/botan/doc/packaging.rst +59/−0
• third_party/botan/doc/pgpkey.txt +198/−0
• third_party/botan/doc/roadmap.rst +54/−0
• third_party/botan/doc/security.rst +352/−0
• third_party/botan/doc/side_channels.rst +449/−0
• third_party/botan/doc/support.rst +70/−0
• third_party/botan/src/bogo_shim/config.json +128/−0
• third_party/botan/src/lib/ffi/ffi.h +2/−0
• third_party/botan/src/lib/ffi/ffi_cert.cpp +34/−1
• third_party/cacert.md +1/−1
• third_party/cacert.pem +94/−315

@@ -1,8 +1,14 @@ # Revision history for z-botan +## 0.2.0.0  -- 2020-05-12++* Simplify `KeyType` in `Z.Crypto.PubKey`.+* Add `sm2Encrypt`, `sm2Decrypt` to `Z.Crypto.PubKey`.+* Add `systemCertStore`, `mozillaCertStore` to `Z.Crypto.X509`.+ ## 0.1.1.2  -- 2020-05-11 -* Export 'KeySpec' from `Z.Crypto.Cipher`.+* Export `KeySpec` from `Z.Crypto.Cipher`.  ## 0.1.0.0  -- 2020-05-11 

@@ -1,6 +1,6 @@ cabal-version:      2.4 name:               Z-Botan-version:            0.1.1.2+version:            0.2.0.0 synopsis:           Crypto for Haskell description:        Crypto for Haskell, based on <http://botan.randombit.net/ Botan> license:            BSD-3-Clause@@ -23,10 +23,16 @@   third_party/botan/src/**/*.h   third_party/botan/src/**/*.in   third_party/botan/src/**/*.txt+  third_party/botan/src/**/*.json+  third_party/botan/doc/**/*.txt+  third_party/botan/doc/**/*.rst   third_party/botan/build/include/external/cabal.placeholder   third_party/cacert.md   third_party/cacert.pem +-- https://curl.se/docs/caextract.html+data-files:         third_party/cacert.pem+ custom-setup   setup-depends:     , base       >=4.5     && <5.0@@ -55,6 +61,8 @@     Z.Crypto.PwdHash     Z.Crypto.RNG     Z.Crypto.X509+  other-modules:    Paths_Z_Botan+  autogen-modules:  Paths_Z_Botan    build-depends:     , base         >=4.12  && <5.0@@ -64,7 +72,7 @@     , stm          ^>=2.5     , time         == 1.11.*     , Z-Data       >=0.8.2 && < 0.9-    , Z-IO         ^>=0.8+    , Z-IO         >=0.8 && < 0.9    include-dirs:     include third_party/botan third_party/botan/build/include

@@ -668,6 +668,8 @@  foreign import ccall unsafe botan_x509_certstore_load_file :: MBA## BotanStructT -> BA## Word8 -> IO CInt +foreign import ccall unsafe botan_x509_certstore_load_system :: MBA## BotanStructT -> IO CInt+ foreign import ccall unsafe "&botan_x509_certstore_destroy" botan_x509_certstore_destroy :: FunPtr (BotanStructT -> IO ())  --------------------------------------------------------------------------------

@@ -175,6 +175,7 @@   deriving anyclass (T.Print, JSON)  blockCipherTypeToCBytes :: BlockCipherType -> CBytes+{-# INLINABLE blockCipherTypeToCBytes #-} blockCipherTypeToCBytes b = case b of     AES128           ->    "AES-128"     AES192           ->    "AES-192"@@ -233,6 +234,7 @@  -- | Pass 'BlockCipher' to FFI as 'botan_block_cipher_t'. withBlockCipher :: HasCallStack => BlockCipher -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withBlockCipher #-} withBlockCipher (BlockCipher bc _ _ _) = withBotanStruct bc  data KeySpec = KeySpec@@ -246,6 +248,7 @@ -- | Create a new block cipher. -- newBlockCipher :: HasCallStack => BlockCipherType -> IO BlockCipher+{-# INLINABLE newBlockCipher #-} newBlockCipher typ = do     let name = blockCipherTypeToCBytes typ     bc <- newBotanStruct@@ -266,6 +269,7 @@ -- | Set the cipher key, which is required before encrypting or decrypting. -- setBlockCipherKey :: HasCallStack => BlockCipher -> V.Bytes -> IO ()+{-# INLINABLE setBlockCipherKey #-} setBlockCipherKey (BlockCipher bc _ _ _) key =     withBotanStruct bc $ \ pbc -> do         withPrimVectorUnsafe key $ \ pkey key_off key_len -> do@@ -274,6 +278,7 @@  -- | Clear the internal state (such as keys) of this cipher object. clearBlockCipher :: HasCallStack => BlockCipher -> IO ()+{-# INLINABLE clearBlockCipher #-} clearBlockCipher (BlockCipher bc _ _ _) =     withBotanStruct bc (throwBotanIfMinus_ . botan_block_cipher_clear) @@ -285,6 +290,7 @@               -> V.Bytes    -- ^ blocks of data, length must be equal to block_size * number_of_blocks               -> Int        -- ^ number of blocks               -> IO V.Bytes+{-# INLINABLE encryptBlocks #-} encryptBlocks (BlockCipher bc _ blockSiz _) blocks n = do     let inputLen = V.length blocks     when (inputLen /= blockSiz * n) $@@ -303,6 +309,7 @@               -> V.Bytes    -- ^ blocks of data, length must be equal to block_size * number_of_blocks               -> Int        -- ^ number of blocks               -> IO V.Bytes+{-# INLINABLE decryptBlocks #-} decryptBlocks (BlockCipher bc _ blockSiz _) blocks n = do     let inputLen = V.length blocks     when (inputLen /= blockSiz * n) $@@ -345,6 +352,7 @@   deriving anyclass (T.Print, JSON)  streamCipherTypeToCBytes :: StreamCipherType -> CBytes+{-# INLINABLE streamCipherTypeToCBytes #-} streamCipherTypeToCBytes s = case s of     CTR_BE b  -> CB.concat ["CTR-BE(", blockCipherTypeToCBytes b, ")"]     OFB b     -> CB.concat ["OFB(", blockCipherTypeToCBytes b, ")"]@@ -358,6 +366,7 @@ -- | Create a new stream cipher. -- newStreamCipher :: HasCallStack => StreamCipherType -> CipherDirection -> IO Cipher+{-# INLINABLE newStreamCipher #-} newStreamCipher typ dir = do     let name = streamCipherTypeToCBytes typ     ci <- newBotanStruct@@ -499,6 +508,7 @@   deriving anyclass (T.Print, JSON)  cipherTypeToCBytes :: CipherMode -> CBytes+{-# INLINABLE cipherTypeToCBytes #-} cipherTypeToCBytes ct = case ct of     ChaCha20Poly1305 -> "ChaCha20Poly1305"     GCM        bct -> blockCipherTypeToCBytes bct <> "/GCM"@@ -535,11 +545,13 @@  -- | Pass 'Cipher' to FFI as 'botan_cipher_t'. withCipher :: HasCallStack => Cipher -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withCipher #-} withCipher (Cipher c _ _ _ _ _) = withBotanStruct c  -- | Create a new cipher. -- newCipher :: HasCallStack => CipherMode -> CipherDirection -> IO Cipher+{-# INLINABLE newCipher #-} newCipher typ dir = do     let name = cipherTypeToCBytes typ     ci <- newBotanStruct@@ -568,6 +580,7 @@ -- | Clear the internal state (such as keys) of this cipher object. -- clearCipher :: HasCallStack => Cipher -> IO ()+{-# INLINABLE clearCipher #-} clearCipher (Cipher ci _ _ _ _ _) =     withBotanStruct ci (throwBotanIfMinus_ . botan_cipher_clear) @@ -579,12 +592,14 @@ -- by botan_cipher_set_key with the original key. -- resetCipher :: HasCallStack => Cipher -> IO ()+{-# INLINABLE resetCipher #-} resetCipher (Cipher ci _ _ _ _ _) =     withBotanStruct ci (throwBotanIfMinus_ . botan_cipher_reset)  -- | Set the key for this cipher object -- setCipherKey :: HasCallStack => Cipher -> V.Bytes -> IO ()+{-# INLINABLE setCipherKey #-} setCipherKey (Cipher ci _ _ _ _ _) key =     withBotanStruct ci $ \ pci -> do         withPrimVectorUnsafe key $ \ pkey key_off key_len -> do@@ -594,6 +609,7 @@ -- | Set the associated data. Will fail if cipher is not an AEAD. -- setAssociatedData :: HasCallStack => Cipher -> V.Bytes -> IO ()+{-# INLINABLE setAssociatedData #-} setAssociatedData (Cipher ci _ _ _ _ _) ad =     withBotanStruct ci $ \ pci -> do         withPrimVectorUnsafe ad $ \ pad ad_off ad_len -> do@@ -606,6 +622,7 @@             => Cipher             -> V.Bytes      -- ^ nonce             -> IO ()+{-# INLINABLE startCipher #-} startCipher (Cipher ci _ _ _ _ _) nonce =     withBotanStruct ci $ \ pci -> do         withPrimVectorUnsafe nonce $ \ pnonce nonce_off nonce_len -> do@@ -620,6 +637,7 @@              => Cipher              -> V.Bytes              -> IO (V.Bytes, V.Bytes)   -- ^ trailing input, output+{-# INLINABLE updateCipher #-} updateCipher (Cipher ci _ _ _ _ _) input =     withBotanStruct ci $ \ pci -> do         withPrimVectorUnsafe input $ \ in_p in_off in_len -> do@@ -636,6 +654,7 @@              => Cipher              -> V.Bytes              -> IO V.Bytes+{-# INLINABLE finishCipher #-} finishCipher (Cipher ci _ ug _ tag_len _) input =     withBotanStruct ci $ \ pci -> do         withPrimVectorUnsafe input $ \ in_p in_off in_len -> do@@ -656,6 +675,7 @@ -- which may not be suitable for arbitrary bytes streams. -- cipherBIO :: HasCallStack => Cipher -> IO (BIO V.Bytes V.Bytes)+{-# INLINABLE cipherBIO #-} cipherBIO c = do     trailingRef <- newIORef V.empty     return $ \ k mbs -> case mbs of

@@ -31,9 +31,11 @@ -- | Initialize an FPE operation to encrypt/decrypt integers less than n. It is --   expected that n is trivially factorable into small integers. Common usage --   would be n to be a power of 10.-newFPE :: MPI     -- ^ mod (n)+newFPE :: HasCallStack+       => MPI     -- ^ mod (n)        -> V.Bytes -- ^ key        -> IO FPE+{-# INLINABLE newFPE #-} newFPE mpi key =     withMPI mpi $ \ mpi' ->     withPrimVectorUnsafe key $ \ key' keyOff keyLen ->@@ -42,10 +44,12 @@             botan_fpe_destroy  -- | Encrypts the value x modulo the value n using the key and tweak specified. Returns an integer less than n. The tweak is a value that does not need to be secret that parameterizes the encryption function. For instance, if you were encrypting a database column with a single key, you could use a per-row-unique integer index value as the tweak. The same tweak value must be used during decryption.-encryptFPE :: FPE+encryptFPE :: HasCallStack+           =>FPE            -> MPI            -> V.Bytes   -- ^ tweak            -> IO MPI+{-# INLINABLE encryptFPE #-} encryptFPE (FPE fpe) mpi tweak = do     mpi' <- copyMPI mpi     withBotanStruct fpe $ \ fpe' ->@@ -57,10 +61,12 @@  -- | Decrypts an FE1 ciphertext. The tweak must be the same as that provided to the encryption function. Returns the plaintext integer. -- Note that there is not any implicit authentication or checking of data in FE1, so if you provide an incorrect key or tweak the result is simply a random integer.-decryptFPE :: FPE+decryptFPE :: HasCallStack+           => FPE            -> MPI            -> V.Bytes   -- ^ tweak            -> IO MPI+{-# INLINABLE decryptFPE #-} decryptFPE (FPE fpe) mpi tweak = do     mpi' <- copyMPI mpi     withBotanStruct fpe $ \ fpe' ->

@@ -179,10 +179,12 @@  -- | Pass Hash to FFI as @botan_hash_t@ withHash :: HasCallStack => Hash -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withHash #-} withHash (Hash h _ _) = withBotanStruct h  -- | Create a new 'Hash' object. newHash :: HasCallStack => HashType -> IO Hash+{-# INLINABLE newHash #-} newHash typ = do     let name = hashTypeToCBytes typ     bs <- newBotanStruct@@ -196,6 +198,7 @@  -- | Copies the state of the hash object to a new hash object. copyHash :: HasCallStack => Hash -> IO Hash+{-# INLINABLE copyHash #-} copyHash (Hash bts0 name siz) = do     s <- newBotanStruct         (\ bts -> withBotanStruct bts0 $ \ pbts0 ->@@ -205,11 +208,13 @@  -- | Reset the state of Hash object back to clean, as if no input has been supplied. clearHash :: HasCallStack => Hash -> IO ()+{-# INLINABLE clearHash #-} clearHash (Hash bts _ _) =     throwBotanIfMinus_ (withBotanStruct bts botan_hash_clear)  -- | Feed a chunk of input into a hash object.-updateHash :: Hash -> V.Bytes -> IO ()+updateHash :: HasCallStack => Hash -> V.Bytes -> IO ()+{-# INLINABLE updateHash #-} updateHash (Hash bts _ _) bs =     withBotanStruct bts $ \ pbts ->         withPrimVectorUnsafe bs $ \ pbs off len ->

@@ -14,7 +14,6 @@ module Z.Crypto.KDF (   -- * KDF     KDFType(..)-  , BlockCipherType (..)   , HashType(..)   , MACType(..)   , kdf@@ -30,7 +29,6 @@  import           Z.Botan.Exception import           Z.Botan.FFI-import           Z.Crypto.Cipher   (BlockCipherType (..)) import           Z.Crypto.Hash     (HashType (..), hashTypeToCBytes) import           Z.Crypto.MAC      (MACType (..), macTypeToCBytes) import           Z.Data.CBytes     (CBytes, withCBytes, withCBytesUnsafe)@@ -90,13 +88,14 @@ kdfTypeToCBytes (SP800_56C mt         ) = CB.concat [ "SP800-56C(" , macTypeToCBytes mt, ")"]  -- | Derive a key using the given KDF algorithm.-kdf-  :: KDFType    -- ^ the name of the given PBKDF algorithm-  -> Int        -- ^ length of output key-  -> V.Bytes    -- ^ secret-  -> V.Bytes    -- ^ salt-  -> V.Bytes    -- ^ label-  -> IO V.Bytes+kdf :: HasCallStack+    => KDFType    -- ^ the name of the given PBKDF algorithm+    -> Int        -- ^ length of output key+    -> V.Bytes    -- ^ secret+    -> V.Bytes    -- ^ salt+    -> V.Bytes    -- ^ label+    -> IO V.Bytes+{-# INLINABLE kdf #-} kdf algo siz secret salt label =     withCBytesUnsafe (kdfTypeToCBytes algo) $ \ algoBA ->         withPrimVectorUnsafe secret $ \ secretBA secretOff secretLen ->@@ -112,11 +111,12 @@                                 labelBA labelOff labelLen)  -- | Derive a key using the given KDF algorithm, with default empty salt and label.-kdf'-  :: KDFType    -- ^ the name of the given PBKDF algorithm-  -> Int        -- ^ length of output key-  -> V.Bytes    -- ^ secret-  -> IO V.Bytes+kdf' :: HasCallStack+     => KDFType    -- ^ the name of the given PBKDF algorithm+     -> Int        -- ^ length of output key+     -> V.Bytes    -- ^ secret+     -> IO V.Bytes+{-# INLINABLE kdf' #-} kdf' algo siz secret = kdf algo siz secret mempty mempty  --------------------------------------------@@ -152,11 +152,13 @@ pbkdfTypeToParam (OpenPGP_S2K ht i) = (CB.concat [ "OpenPGP-S2K(" , hashTypeToCBytes ht, ")"], i, 0, 0)  -- | Derive a key from a passphrase for a number of iterations using the given PBKDF algorithm and params.-pbkdf :: PBKDFType  -- ^ PBKDF algorithm type+pbkdf :: HasCallStack+      => PBKDFType  -- ^ PBKDF algorithm type       -> Int        -- ^ length of output key       -> CBytes     -- ^ passphrase       -> V.Bytes    -- ^ salt       -> IO V.Bytes+{-# INLINABLE pbkdf #-} pbkdf typ siz pwd salt = do     withCBytesUnsafe algo $ \ algoBA ->         withCBytesUnsafe pwd $ \ pwdBA ->@@ -174,12 +176,14 @@  -- | Derive a key from a passphrase using the given PBKDF algorithm, the iteration params are -- ignored and PBKDF is run until given milliseconds have passed.-pbkdfTimed :: PBKDFType  -- ^ the name of the given PBKDF algorithm+pbkdfTimed :: HasCallStack+           => PBKDFType  -- ^ the name of the given PBKDF algorithm            -> Int        -- ^ run until milliseconds have passwd            -> Int        -- ^ length of output key            -> CBytes     -- ^ passphrase            -> V.Bytes    -- ^ salt            -> IO V.Bytes+{-# INLINABLE pbkdfTimed #-} pbkdfTimed typ msec siz pwd s = do     -- we want run it in new OS thread without stop GC from running     -- if the expected time is too long(>0.1s)

@@ -12,12 +12,14 @@ -} module Z.Crypto.KeyWrap where +import           Z.Botan.Exception import           Z.Botan.FFI import qualified Z.Data.Vector as V import           Z.Foreign  -- | Wrap the input key using kek (the key encryption key), and return the result. It will be 8 bytes longer than the input key.-keyWrap :: V.Bytes -- ^ key+keyWrap :: HasCallStack+        => V.Bytes -- ^ key         -> V.Bytes -- ^ kek         -> IO V.Bytes {-# INLINABLE keyWrap #-}@@ -28,7 +30,8 @@         hs_botan_key_wrap3394 key' keyOff keyLen kek' kekOff kekLen  -- | Unwrap a key wrapped with rfc3394_keywrap.-keyUnwrap :: V.Bytes -- ^ wrapped key+keyUnwrap :: HasCallStack+          => V.Bytes -- ^ wrapped key           -> V.Bytes -- ^ kek           -> IO V.Bytes {-# INLINABLE keyUnwrap #-}

@@ -46,8 +46,6 @@ data MACType = CMAC BlockCipherType                 -- ^ A modern CBC-MAC variant that avoids the security problems of plain CBC-MAC.                 -- Approved by NIST. Also sometimes called OMAC.-             | OMAC BlockCipherType-               -- ^              | GMAC BlockCipherType                -- ^ GMAC is related to the GCM authenticated cipher mode.                -- It is quite slow unless hardware support for carryless multiplications is available.@@ -74,7 +72,6 @@  macTypeToCBytes :: MACType -> CBytes macTypeToCBytes (CMAC bc   ) = CB.concat ["CMAC(", blockCipherTypeToCBytes bc, ")"]-macTypeToCBytes (OMAC bc   ) = CB.concat ["OMAC(", blockCipherTypeToCBytes bc, ")"] macTypeToCBytes (GMAC bc   ) = CB.concat ["GMAC(", blockCipherTypeToCBytes bc, ")"] macTypeToCBytes (CBC_MAC bc) = CB.concat ["CBC-MAC(", blockCipherTypeToCBytes bc, ")"] macTypeToCBytes (HMAC ht)    = CB.concat ["HMAC(", hashTypeToCBytes ht, ")"]@@ -94,10 +91,12 @@  -- | Pass MAC to FFI as 'botan_mac_t'. withMAC :: HasCallStack => MAC -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withMAC #-} withMAC (MAC m _ _) = withBotanStruct m  -- | Create a new 'MAC' object.-newMAC :: MACType -> IO MAC+newMAC :: HasCallStack => MACType -> IO MAC+{-# INLINABLE newMAC #-} newMAC typ = do     let name = macTypeToCBytes typ     bs <- newBotanStruct@@ -111,6 +110,7 @@  -- | Set the random key. setKeyMAC :: HasCallStack => MAC -> V.Bytes -> IO ()+{-# INLINABLE setKeyMAC #-} setKeyMAC (MAC bts _ _) bs =     withBotanStruct bts $ \pbts->         withPrimVectorUnsafe bs $ \pbs off len ->@@ -118,6 +118,7 @@  -- | Feed a chunk of input into a 'MAC' object. updateMAC :: HasCallStack => MAC -> V.Bytes -> IO ()+{-# INLINABLE updateMAC #-} updateMAC (MAC bts _ _) bs =     withBotanStruct bts $ \ pbts ->         withPrimVectorUnsafe bs $ \ pbs off len ->@@ -132,6 +133,7 @@  -- | Reset the state of MAC object back to clean, as if no input has been supplied. clearMAC :: HasCallStack => MAC -> IO ()+{-# INLINABLE clearMAC #-} clearMAC (MAC bts _ _) =     throwBotanIfMinus_ (withBotanStruct bts hs_botan_mac_clear) 

@@ -324,35 +324,42 @@ zero = unsafeNewMPI (\ _ -> return ())  newMPI :: (BotanStructT -> IO a) -> IO MPI+{-# INLINABLE newMPI #-} newMPI f = do     mp <- newBotanStruct (\ bts -> botan_mp_init bts) botan_mp_destroy     _ <- withBotanStruct mp f     return (MPI mp)  newMPI' :: (BotanStructT -> IO a) -> IO (MPI, a)+{-# INLINABLE newMPI' #-} newMPI' f = do     mp <- newBotanStruct (\ bts -> botan_mp_init bts) botan_mp_destroy     r <- withBotanStruct mp f     return (MPI mp, r)  copyMPI :: MPI -> IO MPI+{-# INLINABLE copyMPI #-} copyMPI (MPI a) = do     withBotanStruct a $ \ btsa -> do         newMPI (\ bts -> botan_mp_set_from_mp bts btsa)  withMPI :: MPI -> (BotanStructT -> IO a) -> IO a+{-# INLINABLE withMPI #-} withMPI (MPI bts) f = withBotanStruct bts f  unsafeWithMPI :: MPI -> (BotanStructT -> IO a) -> a+{-# INLINABLE unsafeWithMPI #-} unsafeWithMPI (MPI bts) f = unsafeDupablePerformIO (withBotanStruct bts f)  unsafeNewMPI :: (BotanStructT -> IO a) -> MPI+{-# INLINABLE unsafeNewMPI #-} unsafeNewMPI f = unsafeDupablePerformIO $ do     mp <- newBotanStruct (\ bts -> botan_mp_init bts) botan_mp_destroy     _ <- withBotanStruct mp f     return (MPI mp)  unsafeNewMPI' :: (BotanStructT -> IO a) -> (MPI, a)+{-# INLINABLE unsafeNewMPI' #-} unsafeNewMPI' f = unsafeDupablePerformIO $ do     mp <- newBotanStruct (\ bts -> botan_mp_init bts) botan_mp_destroy     r <- withBotanStruct mp f@@ -360,26 +367,31 @@  -- | Get 'MPI' 's byte size. byteSize :: MPI -> Int+{-# INLINABLE byteSize #-} byteSize mp = fromIntegral @CSize . fst . unsafeWithMPI mp $ \ bts ->     allocPrimUnsafe (botan_mp_num_bytes bts)  -- | Get 'MPI' 's bit size. bitSize :: MPI -> Int+{-# INLINABLE bitSize #-} bitSize mp = fromIntegral @CSize . fst . unsafeWithMPI mp $ \ bts ->     allocPrimUnsafe (botan_mp_num_bits bts)  -- | Set 'MPI' from an integer value. fromCInt :: CInt -> MPI+{-# INLINABLE fromCInt #-} fromCInt x = unsafeNewMPI $ \ bts ->     botan_mp_set_from_int bts x  -- | Convert a MPI to 'Word32', the sign is ignored.-toWord32 :: HasCallStack => MPI -> Word32+toWord32 :: MPI -> Word32+{-# INLINABLE toWord32 #-} toWord32 mp = fst . unsafeWithMPI mp $ \ bts ->     allocPrimUnsafe (botan_mp_to_uint32 bts)  -- | Write a 'MPI' in decimal format, with negative sign if < 0. toDecimal :: MPI -> B.Builder ()+{-# INLINABLE toDecimal #-} toDecimal mp = do     when (isNegative mp) (B.word8 MINUS)     -- botan write \NUL terminator@@ -389,6 +401,7 @@  -- | Parse a 'MPI' in decimal format, parse leading minus sign. fromDecimal :: P.Parser MPI+{-# INLINABLE fromDecimal #-} fromDecimal = do     sign <- P.peek     let neg = sign == MINUS@@ -404,6 +417,7 @@  -- | Write a 'MPI' in hexadecimal format(without '0x' prefix), the sign is ignored. toHex :: MPI -> B.Builder ()+{-# INLINABLE toHex #-} toHex mp =     -- botan write \NUL terminator     let !siz = byteSize mp `unsafeShiftL` 1@@ -414,6 +428,7 @@  -- | Parse a 'MPI' in hexadecimal format(without '0x' prefix), no sign is allowed. fromHex :: P.Parser MPI+{-# INLINABLE fromHex #-} fromHex = do     v@(V.PrimVector (A.PrimArray ba#) s l) <- P.takeWhile1 isHexDigit     let (x, r) = unsafeNewMPI' $ \ bts -> hs_botan_mp_set_from_hex bts ba# s l@@ -422,21 +437,25 @@     else return x  isNegative :: MPI -> Bool+{-# INLINABLE isNegative #-} isNegative mp = unsafeWithMPI mp $ \ bts -> do     r <- botan_mp_is_negative bts     return $! r == 1  isZero :: MPI -> Bool+{-# INLINABLE isZero #-} isZero mp = unsafeWithMPI mp $ \ bts -> do     r <- botan_mp_is_zero bts     return $! r == 1  isOdd :: MPI -> Bool+{-# INLINABLE isOdd #-} isOdd mp = unsafeWithMPI mp $ \ bts -> do     r <- botan_mp_is_odd bts     return $! r == 1  isEven :: MPI -> Bool+{-# INLINABLE isEven #-} isEven mp = unsafeWithMPI mp $ \ bts -> do     r <- botan_mp_is_even bts     return $! r == 1@@ -445,6 +464,7 @@  -- | mulMod x y mod = x times y modulo mod mulMod :: MPI -> MPI -> MPI -> MPI+{-# INLINABLE mulMod #-} mulMod x y m =     unsafeNewMPI $ \ btsr ->         withMPI x $ \ btsx ->@@ -455,6 +475,7 @@  -- | Modular exponentiation. powMod base exp mod = base power exp module mod powMod :: MPI -> MPI -> MPI -> MPI+{-# INLINABLE powMod #-} powMod x y m =     unsafeNewMPI $ \ btsr ->         withMPI x $ \ btsx ->@@ -466,6 +487,7 @@ -- -- If no modular inverse exists (for instance because in and modulus are not relatively prime), return 0. modInverse :: MPI -> MPI -> MPI+{-# INLINABLE modInverse #-} modInverse x y =     unsafeNewMPI $ \ btsr ->         withMPI x $ \ btsx ->@@ -473,17 +495,20 @@                     botan_mp_mod_inverse btsr btsx btsy  -- | Create a random 'MPI' of the specified bit size.-randBits :: RNG -> Int -> IO MPI+randBits :: HasCallStack => RNG -> Int -> IO MPI+{-# INLINABLE randBits #-} randBits rng x = do     newMPI $ \ bts ->         withRNG rng $ \ bts_rng ->             throwBotanIfMinus_ (botan_mp_rand_bits bts bts_rng (fromIntegral (max x 0)))  -- | Create a random 'MPI' within the provided range.-randRange :: RNG+randRange :: HasCallStack+          => RNG           -> MPI     -- ^ lower bound           -> MPI     -- ^ upper bound           -> IO MPI+{-# INLINABLE randRange #-} randRange rng lower upper = do     newMPI $ \ bts ->         withRNG rng $ \ bts_rng ->@@ -493,10 +518,11 @@  -- | Compute the greatest common divisor of x and y. gcd :: MPI -> MPI -> MPI+{-# INLINABLE gcd #-} gcd x y = unsafeNewMPI $ \ bts ->     withMPI x $ \ bts_x ->         withMPI y $ \ bts_y ->-            throwBotanIfMinus_ (botan_mp_gcd bts bts_x bts_y)+            botan_mp_gcd bts bts_x bts_y  -- | Test if n is prime. --@@ -504,7 +530,8 @@ -- set test_prob to the desired assurance level. -- For example if test_prob is 64, then sufficient Miller-Rabin iterations will run to -- assure there is at most a 1/2**64 chance that n is composite.-isPrim :: RNG -> MPI -> Int -> IO Bool+isPrim :: HasCallStack => RNG -> MPI -> Int -> IO Bool+{-# INLINABLE isPrim #-} isPrim rng x prob = do     withRNG rng $ \ bts_rng ->         withMPI x $ \ bts_x -> do

@@ -57,7 +57,8 @@ pattern OTP_DIGIT_7 = 7 pattern OTP_DIGIT_8 = 8 -newHOTP :: V.Bytes -> OTPAlgo -> OTPDigitLen -> IO HOTP+newHOTP :: HasCallStack => V.Bytes -> OTPAlgo -> OTPDigitLen -> IO HOTP+{-# INLINABLE newHOTP #-} newHOTP key otpAlgo digits =     withPrimVectorUnsafe key $ \ key' keyOff keyLen ->     withCBytesUnsafe (hashTypeToCBytes otpAlgo) $ \ hashAlgo' ->@@ -66,19 +67,23 @@             botan_hotp_destroy  -- | Generate a HOTP code for the provided counter.-genHOTP :: HOTP   -- ^ the HOTP object+genHOTP :: HasCallStack+        => HOTP   -- ^ the HOTP object         -> Word64 -- ^ HOTP counter         -> IO Word32+{-# INLINABLE genHOTP #-} genHOTP (HOTP hotp) counter =     withBotanStruct hotp $ \ hotp' ->     fst <$> allocPrimUnsafe (\ code -> botan_hotp_generate hotp' code counter)  -- | Verify a HOTP code.-checkHOTP :: HOTP   -- ^ the HOTP object+checkHOTP :: HasCallStack+          => HOTP   -- ^ the HOTP object           -> Word32 -- ^ the presented HOTP code           -> Word64 -- ^ the HOTP counter           -> Int    -- ^ resync range           -> IO (Bool, Word64)+{-# INLINABLE checkHOTP #-} checkHOTP (HOTP totp) code c range = do     withBotanStruct totp $ \ totp' -> do         (nc, ret) <- allocPrimUnsafe $ \ nc' ->@@ -96,7 +101,8 @@     deriving (Show, Generic)     deriving anyclass T.Print -newTOTP :: V.Bytes -> OTPAlgo -> OTPDigitLen -> Int -> IO TOTP+newTOTP :: HasCallStack => V.Bytes -> OTPAlgo -> OTPDigitLen -> Int -> IO TOTP+{-# INLINABLE newTOTP #-} newTOTP key otpAlgo digits timeStep =     withPrimVectorUnsafe key $ \ key' keyOff keyLen ->     withCBytesUnsafe (hashTypeToCBytes otpAlgo) $ \ hashAlgo' ->@@ -105,20 +111,24 @@             botan_totp_destroy  -- | Generate a TOTP code for the provided timestamp.-genTOTP :: TOTP   -- ^ the TOTP object+genTOTP :: HasCallStack+        => TOTP   -- ^ the TOTP object         -> Word64 -- ^ the current local timestamp         -> IO Word32+{-# INLINABLE genTOTP #-} genTOTP (TOTP totp) timestamp =     withBotanStruct totp $ \ totp' ->     fst <$> allocPrimUnsafe (\ code -> botan_totp_generate totp' code timestamp)  -- | Verify a TOTP code.-checkTOTP :: TOTP   -- ^ the TOTP object+checkTOTP :: HasCallStack+          => TOTP   -- ^ the TOTP object           -> Word32 -- ^ the presented OTP           -> Word64 -- ^ timestamp the current local timestamp           -> Int    -- ^ specifies the acceptable amount of clock drift                     --   (in terms of time steps) between the two hosts.           -> IO Bool+{-# INLINABLE checkTOTP #-} checkTOTP (TOTP totp) code timestamp driftAmount = do     withBotanStruct totp $ \ totp' -> do         ret <- botan_totp_check totp' code timestamp (fromIntegral driftAmount)

@@ -8,14 +8,12 @@ Stability   : experimental Portability : non-portable -This module is used for Public Key Cryptography.-Public key cryptography (also called asymmetric cryptography) is a collection of techniques allowing for encryption, signatures, and key agreement.+This module is used for Public key cryptography. Public key cryptography (also called asymmetric cryptography) is a collection of techniques allowing for encryption, signatures, and key agreement. -}  module Z.Crypto.PubKey (   -- * Asymmetric cryptography algorithms-    KeyType(..), pattern RSADefault, pattern McElieceDefault, pattern XMSSDefault-  , ECCType(..), DLType(..)+    KeyType(..)   -- * Key generation and manipulation   , PrivKey(..), PubKey(..)   , newPrivKey, newKeyPair, privKeyToPubKey@@ -34,6 +32,8 @@   -- * Encrypt & Decrypt   , pkEncrypt   , pkDecrypt+  , sm2Encrypt+  , sm2Decrypt   , EMEPadding(..)   -- * Sign & verify   , EMSA(..), SignFmt(..)@@ -159,49 +159,43 @@ -- Key Types -- --------------- --- | Public Key Cryptography Algorithms.+-- | Public key cryptography algorithms. data KeyType-    = Curve25519-    | -- | RSA key of the given size, namely n bits-        RSA Word32-     -- | eXtended Merkle Signature Scheme, see <xmss https://botan.randombit.net/handbook/api_ref/pubkey.html#extended-merkle-signature-scheme-xmss>-    | XMSS XMSSType-      -- | Ed25519 high-speed high-security signatures-    | Ed25519-      -- | Elliptic-curve cryptography, see 'ECCType'-    | ECC ECCType ECGroup-      -- | Asymmetric algorithm based on the discrete logarithm problem, see 'DLType'-    | DL DLType DLGroup-      -- | McEliece is a cryptographic scheme based on error correcting codes which is thought to be resistant to quantum computers. See <mceliece https://botan.randombit.net/handbook/api_ref/pubkey.html#mceliece>.-    | McEliece-        Word32 -- ^ n-        Word32 -- ^ t-+    = RSA Word32        -- ^ RSA key of the given size, namely n bits, support encryption and signature.+    | SM2 ECGroup       -- ^ Public key algorithms specified by China, support encryption and signature.+    | ElGamal DLGroup   -- ^ ElGamal encryption system, support encryption. -keyTypeToCBytes :: KeyType -> (CBytes, CBytes)-keyTypeToCBytes keyType' = case keyType' of-    Curve25519 -> ("Curve25519", "")-    RSA bits -> ("RSA", CB.buildCBytes $ B.int bits)-    McEliece n t -> ("McEliece", CB.buildCBytes $ B.int n >> B.char8 ',' >> B.int t)-    XMSS xmss -> ("XMSS", xmss)-    Ed25519 -> ("Ed25519", "")-    ECC ecc grp -> (eccToCBytes ecc, grp)-    DL dl grp -> (dlToCBytes dl, grp)+    | DSA DLGroup     -- ^ Digital Signature Algorithm based on the discrete logarithm problem.+    | ECDSA ECGroup   -- ^ Digital Signature Algorithm which uses elliptic curve cryptography.+    | ECKCDSA ECGroup -- ^ Korean Certificate-based Digital Signature Algorithm.+    | ECGDSA ECGroup  -- ^ Elliptic Curve German Digital Signature Algorithm.+    | GOST_34'10 ECGroup -- ^ Cryptographic algorithms defined by the Russian national standards, support signature.+    | Ed25519         -- ^ Ed25519 elliptic-curve signatures, see <https://ed25519.cr.yp.to/ ed25519>.+    | XMSS XMSSType   -- ^ eXtended Merkle Signature Scheme, see <xmss https://botan.randombit.net/handbook/api_ref/pubkey.html#extended-merkle-signature-scheme-xmss>. --- | Default RSA Key type(3072 bits).-pattern RSADefault :: KeyType-pattern RSADefault = RSA 3072+    | DH DLGroup        -- ^ The Diffie–Hellman key exchange.+    | ECDH ECGroup      -- ^ The Elliptic-curve Diffie–Hellman key exchange.+    | Curve25519        -- ^ The Curve25519 Diffie–Hellman key exchange. --- | Default McEliece key type.-pattern McElieceDefault :: KeyType-pattern McElieceDefault = McEliece 2960 57+keyTypeToCBytes :: KeyType -> (CBytes, CBytes)+keyTypeToCBytes keyType = case keyType of+    RSA bits    -> ("RSA", CB.buildCBytes $ B.int bits)+    SM2 grp     -> ("SM2", grp)+    ElGamal grp -> ("ElGamal", grp)+    DSA grp         -> ("DSA", grp)+    ECDSA grp       -> ("ECDSA", grp)+    ECKCDSA grp     -> ("ECKCDSA", grp)+    ECGDSA grp      -> ("ECGDSA", grp)+    GOST_34'10 grp  -> ("GOST_34.10", grp)+    Ed25519         -> ("Ed25519", "")+    XMSS xms        -> ("XMSS", xms)+    DH grp      -> ("DH", grp)+    ECDH grp    -> ("ECDH", grp)+    Curve25519  -> ("Curve25519", "")  -- | A type wrapper. type XMSSType = CBytes -pattern XMSSDefault :: KeyType-pattern XMSSDefault = XMSS XMSS_SHA2_10_512- pattern XMSS_SHA2_10_256 :: XMSSType pattern XMSS_SHA2_10_256 = "XMSS-SHA2_10_256" @@ -238,24 +232,6 @@ pattern XMSS_SHAKE_20_512 :: XMSSType pattern XMSS_SHAKE_20_512 = "XMSS-SHAKE_20_512" --- | Algorithms based on elliptic curve.-data ECCType-    = ECDSA | ECDH | ECKCDSA | ECGDSA | SM2 | SM2_Sig-    | SM2_Enc | GOST_34_10 | GOST_34_10_2012_256 | GOST_34_10_2012_512--eccToCBytes :: ECCType -> CBytes-eccToCBytes = \ case-    ECDSA -> "ECDSA"-    ECDH -> "ECDH"-    ECKCDSA -> "ECKCDSA"-    ECGDSA -> "ECGDSA"-    SM2 -> "SM2"-    SM2_Sig -> "SM2_Sig"-    SM2_Enc -> "SM2_Enc"-    GOST_34_10 -> "GOST-34.10"-    GOST_34_10_2012_256 -> "GOST-34.10-2012-256"-    GOST_34_10_2012_512 -> "GOST-34.10-2012-512"- -- | An elliptic curve. type ECGroup = CBytes @@ -340,18 +316,6 @@ pattern Sm2p256v1 :: ECGroup pattern Sm2p256v1 = "sm2p256v1" --- | Discrete Logarithm-data DLType-    = DH        -- ^ Diffie-Hellman key exchange-    | DSA       -- ^ Digital Signature Algorithm-    | ElGamal--dlToCBytes :: DLType -> CBytes-dlToCBytes = \ case-    DH -> "DH"-    DSA -> "DSA"-    ElGamal -> "ElGamal"- -- | Discrete Logarithm Group type DLGroup = CBytes @@ -433,15 +397,16 @@ -- | Pass 'PrivKey' to FFI. withPrivKey :: HasCallStack             => PrivKey -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withPrivKey  #-} withPrivKey (PrivKey key) = withBotanStruct key  -- | Creating a new key pair. ---newKeyPair ::-    -- | Algorithm name and some algorithm specific arguments.-    KeyType ->-    RNG ->-    IO (PrivKey, PubKey)+newKeyPair :: HasCallStack+           => KeyType   -- ^ Algorithm name and some algorithm specific arguments.+           -> RNG+           -> IO (PrivKey, PubKey)+{-# INLINABLE newKeyPair  #-} newKeyPair kt rng = do     priv <- newPrivKey kt rng     let !pub = privKeyToPubKey priv@@ -454,11 +419,11 @@ -- * a source of random numbers -- * some algorithm specific arguments that define the security level of the resulting key. ---newPrivKey ::-    -- | Algorithm name and some algorithm specific arguments.-    KeyType ->-    RNG ->-    IO PrivKey+newPrivKey :: HasCallStack+           => KeyType   -- ^ Algorithm name and some algorithm specific arguments.+           -> RNG+           -> IO PrivKey+{-# INLINABLE newPrivKey  #-} newPrivKey keyTyp rng =     withRNG rng $ \ rng' ->     CB.withCBytes algo $ \ algo' ->@@ -470,12 +435,13 @@         (algo, args) = keyTypeToCBytes keyTyp  -- | Load a private key. If the key is encrypted, password will be used to attempt decryption.-loadPrivKey ::+loadPrivKey :: HasCallStack =>     RNG ->     V.Bytes ->     -- | Password.     CBytes ->     IO PrivKey+{-# INLINABLE loadPrivKey  #-} loadPrivKey rng buf passwd =     withRNG rng $ \ rng' ->     withPrimVectorUnsafe buf $ \ buf' off len ->@@ -485,13 +451,14 @@             botan_privkey_destroy  -- | Get the algorithm name of a private key.-privKeyAlgoName :: PrivKey -> IO V.Bytes+privKeyAlgoName :: PrivKey -> IO T.Text+{-# INLINABLE privKeyAlgoName  #-} privKeyAlgoName key =-    withPrivKey key $ allocBotanBufferUnsafe 16 . botan_privkey_algo_name+    withPrivKey key $ allocBotanBufferUTF8Unsafe 16 . botan_privkey_algo_name  -- | Export a private key in DER binary format. exportPrivKeyDER :: HasCallStack => PrivKey -> V.Bytes-{-# INLINE exportPrivKeyDER #-}+{-# INLINABLE exportPrivKeyDER  #-} exportPrivKeyDER key = unsafePerformIO $     withPrivKey key $ \ key' ->     allocBotanBufferUnsafe V.smallChunkSize $ \ buf siz ->@@ -499,16 +466,18 @@  -- | Export a private key in PEM textual format. exportPrivKeyPEM :: HasCallStack => PrivKey -> T.Text-{-# INLINE exportPrivKeyPEM #-}+{-# INLINABLE exportPrivKeyPEM  #-} exportPrivKeyPEM key = unsafePerformIO $     withPrivKey key $ \ key' ->     allocBotanBufferUTF8Unsafe V.smallChunkSize $ \ buf siz ->     botan_privkey_export key' buf siz 1  -- | Export a private key with password.-exportPrivKeyEncryptedDER :: PrivKey -> RNG+exportPrivKeyEncryptedDER :: HasCallStack+                          => PrivKey -> RNG                           -> CBytes        -- ^ password                           -> IO V.Bytes+{-# INLINABLE exportPrivKeyEncryptedDER  #-} exportPrivKeyEncryptedDER key rng pwd =     withPrivKey key $ \ key' ->     withRNG rng $ \ rng' ->@@ -518,9 +487,11 @@     botan_privkey_export_encrypted key' buf siz rng' pwd' pbe' 0  -- | Export a private key with password in PEM textual format.-exportPrivKeyEncryptedPEM :: PrivKey -> RNG+exportPrivKeyEncryptedPEM :: HasCallStack+                          => PrivKey -> RNG                           -> CBytes        -- ^ password                           -> IO T.Text+{-# INLINABLE exportPrivKeyEncryptedPEM  #-} exportPrivKeyEncryptedPEM key rng pwd =     withPrivKey key $ \ key' ->     withRNG rng $ \ rng' ->@@ -531,7 +502,7 @@  -- | Export a public key from a given key pair. privKeyToPubKey :: PrivKey -> PubKey-{-# INLINE privKeyToPubKey #-}+{-# INLINABLE privKeyToPubKey  #-} privKeyToPubKey (PrivKey priv) = unsafePerformIO $ do     withBotanStruct priv $ \ priv' ->         PubKey <$> newBotanStruct (`botan_privkey_export_pubkey` priv') botan_privkey_destroy@@ -541,7 +512,7 @@              => PrivKey      -- ^ key              -> CBytes       -- ^ field name              -> MPI-{-# INLINE privKeyParam #-}+{-# INLINABLE privKeyParam  #-} privKeyParam key name =     unsafeNewMPI $ \ mp ->     withPrivKey key $ \ key' -> do@@ -553,21 +524,20 @@     deriving anyclass T.Print  -- | Pass 'PubKey' to FFI.-withPubKey :: HasCallStack-            => PubKey -> (BotanStructT -> IO r) -> IO r+withPubKey :: PubKey -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withPubKey  #-} withPubKey (PubKey key) = withBotanStruct key  -- | Load a publickey.-loadPubKey :: HasCallStack-           => V.Bytes -> IO PubKey-{-# INLINE loadPubKey #-}+loadPubKey :: HasCallStack => V.Bytes -> IO PubKey+{-# INLINABLE loadPubKey  #-} loadPubKey buf = do     withPrimVectorUnsafe buf $ \ buf' off len ->         PubKey <$> newBotanStruct (\ pubKey -> hs_botan_pubkey_load pubKey buf' off len) botan_pubkey_destroy  -- | Export a public key in DER binary format.. exportPubKeyDER :: HasCallStack => PubKey -> V.Bytes-{-# INLINE exportPubKeyDER #-}+{-# INLINABLE exportPubKeyDER  #-} exportPubKeyDER pubKey = unsafePerformIO $     withPubKey pubKey $ \ pubKey' ->     allocBotanBufferUnsafe V.smallChunkSize $ \ buf siz ->@@ -575,7 +545,7 @@  -- | Export a public key in PEM textual format. exportPubKeyPEM :: HasCallStack => PubKey -> T.Text-{-# INLINE exportPubKeyPEM #-}+{-# INLINABLE exportPubKeyPEM  #-} exportPubKeyPEM pubKey = unsafePerformIO $     withPubKey pubKey $ \ pubKey' ->     allocBotanBufferUTF8Unsafe V.smallChunkSize $ \ buf siz ->@@ -583,7 +553,7 @@  -- | Get the algorithm name of a public key. pubKeyAlgoName :: PubKey -> CBytes-{-# INLINE pubKeyAlgoName #-}+{-# INLINABLE pubKeyAlgoName  #-} pubKeyAlgoName pubKey = unsafePerformIO $     withPubKey pubKey $ \ pubKey' ->         CB.fromBytes <$> allocBotanBufferUnsafe 16@@ -591,7 +561,7 @@  -- | Estimate the strength of a public key. estStrength :: PubKey -> Int-{-# INLINE estStrength #-}+{-# INLINABLE estStrength  #-} estStrength pubKey = unsafePerformIO $     withPubKey pubKey $ \ pubKey' -> do         (a, _) <- allocPrimUnsafe @CSize $ \ est ->@@ -600,7 +570,7 @@  -- | Fingerprint a given publickey. fingerPrintPubKey :: PubKey -> HashType -> V.Bytes-{-# INLINE fingerPrintPubKey #-}+{-# INLINABLE fingerPrintPubKey  #-} fingerPrintPubKey pubKey ht = unsafePerformIO $     withPubKey pubKey $ \ pubKey' ->     CB.withCBytesUnsafe (hashTypeToCBytes ht) $ \ hash' ->@@ -608,10 +578,10 @@     botan_pubkey_fingerprint pubKey' hash' buf siz  -- | Read an algorithm specific field from the public key object.-pubKeyParam :: HasCallStack-                    => PubKey       -- ^ key-                    -> CBytes       -- ^ field name-                    -> MPI+pubKeyParam :: PubKey       -- ^ key+            -> CBytes       -- ^ field name+            -> MPI+{-# INLINABLE pubKeyParam  #-} pubKeyParam pubKey name =     unsafeNewMPI $ \ mp ->     withPubKey pubKey $ \ pubKey' -> do@@ -632,6 +602,7 @@ -- getRSAParams :: PrivKey              -> (MPI, MPI, MPI, MPI, MPI)   -- ^ (p, q, n, d, e)+{-# INLINABLE getRSAParams  #-} getRSAParams key = (p, q, n, d, e)   where     !p = privKeyParam key "p"@@ -647,13 +618,15 @@ -- getRSAPubParams :: PubKey                 -> (MPI, MPI)   -- ^ (n, e)+{-# INLINABLE getRSAPubParams  #-} getRSAPubParams key = (n, e)   where     !n = pubKeyParam key "n"     !e = pubKeyParam key "e"  -- | Initialize a RSA key pair using arguments p, q, and e.-newRSAPrivKey :: MPI -> MPI -> MPI -> PrivKey+newRSAPrivKey :: HasCallStack => MPI -> MPI -> MPI -> PrivKey+{-# INLINABLE newRSAPrivKey  #-} newRSAPrivKey p q e =     unsafeWithMPI p $ \ p' ->     withMPI q $ \ q' ->@@ -663,7 +636,8 @@             botan_privkey_destroy  -- | Initialize a public RSA key using arguments n and e.-newRSAPubKey :: MPI -> MPI -> PubKey+newRSAPubKey :: HasCallStack => MPI -> MPI -> PubKey+{-# INLINABLE newRSAPubKey  #-} newRSAPubKey n e = do     unsafeWithMPI n $ \ n' ->         withMPI e $ \ e' ->@@ -679,7 +653,8 @@ -- * Set x to the private key -- getDSAPrivParams :: PrivKey-             -> (MPI, MPI, MPI, MPI)   -- ^ (p, q, g, x)+                 -> (MPI, MPI, MPI, MPI)   -- ^ (p, q, g, x)+{-# INLINABLE getDSAPrivParams  #-} getDSAPrivParams key = (p, q, g, x)   where     !p = privKeyParam key "p"@@ -688,7 +663,8 @@     !x = privKeyParam key "x"  -- | Initialize a DSA key pair using arguments p, q, g and x.-newDSAPrivKey :: MPI -> MPI -> MPI -> MPI -> PrivKey+newDSAPrivKey :: HasCallStack => MPI -> MPI -> MPI -> MPI -> PrivKey+{-# INLINABLE newDSAPrivKey  #-} newDSAPrivKey p q g x =     unsafeWithMPI p $ \ p' ->     withMPI q $ \ q' ->@@ -705,6 +681,7 @@ -- getDSAPubParams :: PubKey                 -> (MPI, MPI, MPI, MPI)   -- ^ (p, q, g, y)+{-# INLINABLE getDSAPubParams  #-} getDSAPubParams key = (p, q, g, y)   where     !p = pubKeyParam key "p"@@ -713,7 +690,8 @@     !y = pubKeyParam key "y"  -- | Initialize a DSA public key using arguments p, q, g and y.-newDSAPubKey :: MPI -> MPI -> MPI -> MPI -> PubKey+newDSAPubKey :: HasCallStack => MPI -> MPI -> MPI -> MPI -> PubKey+{-# INLINABLE newDSAPubKey  #-} newDSAPubKey p q g y =     unsafeWithMPI p $ \ p' ->     withMPI q $ \ q' ->@@ -734,13 +712,15 @@ -- getElGamalPrivParams :: PrivKey                  -> (MPI, MPI, MPI)   -- ^ (p, g, x)+{-# INLINABLE getElGamalPrivParams  #-} getElGamalPrivParams key = (p, g, x)   where     !p = privKeyParam key "p"     !g = privKeyParam key "g"     !x = privKeyParam key "x" -newElGamalPrivKey :: MPI -> MPI -> MPI -> PrivKey+newElGamalPrivKey :: HasCallStack => MPI -> MPI -> MPI -> PrivKey+{-# INLINABLE newElGamalPrivKey  #-} newElGamalPrivKey p g x =     unsafeWithMPI p $ \ p' ->     withMPI g $ \ g' ->@@ -756,13 +736,15 @@ -- getElGamalPubParams :: PubKey                     -> (MPI, MPI, MPI)   -- ^ (p, g, y)+{-# INLINABLE getElGamalPubParams  #-} getElGamalPubParams key = (p, g, y)   where     !p = pubKeyParam key "p"     !g = pubKeyParam key "g"     !y = pubKeyParam key "y" -newElGamalPubKey :: MPI -> MPI -> MPI -> PubKey+newElGamalPubKey :: HasCallStack => MPI -> MPI -> MPI -> PubKey+{-# INLINABLE newElGamalPubKey  #-} newElGamalPubKey p g y =     unsafeWithMPI p $ \ p' ->     withMPI g $ \ g' ->@@ -782,13 +764,15 @@ -- getDHPrivParams :: PrivKey                  -> (MPI, MPI, MPI)   -- ^ (p, g, x)+{-# INLINABLE getDHPrivParams  #-} getDHPrivParams key = (p, g, x)   where     !p = privKeyParam key "p"     !g = privKeyParam key "g"     !x = privKeyParam key "x" -newDHPrivKey :: MPI -> MPI -> MPI -> PrivKey+newDHPrivKey :: HasCallStack => MPI -> MPI -> MPI -> PrivKey+{-# INLINABLE newDHPrivKey  #-} newDHPrivKey p g x = do     unsafeWithMPI p $ \ p' -> withMPI g $ \ g' -> withMPI x $ \ x' ->         PrivKey <$> newBotanStruct (\ key -> botan_privkey_load_dh key p' g' x') botan_privkey_destroy@@ -800,13 +784,15 @@ -- getDHPubParams :: PubKey                -> (MPI, MPI, MPI)   -- ^ (p, g, y)+{-# INLINABLE getDHPubParams  #-} getDHPubParams key = (p, g, y)   where     !p = pubKeyParam key "p"     !g = pubKeyParam key "g"     !y = pubKeyParam key "y" -newDHPubKey :: MPI -> MPI -> MPI -> PubKey+newDHPubKey :: HasCallStack => MPI -> MPI -> MPI -> PubKey+{-# INLINABLE newDHPubKey  #-} newDHPubKey p g y = do     unsafeWithMPI p $ \ p' ->         withMPI g $ \ g' ->@@ -828,6 +814,7 @@     | EME_OAEP' HashType HashType CBytes    -- ^ hash, mask gen hash, labal  emeToCBytes :: EMEPadding -> CBytes+{-# INLINABLE emeToCBytes  #-} emeToCBytes EME_RAW              = "Raw" emeToCBytes EME_PKCS1_v1'5       = "PKCS1v15" emeToCBytes (EME_OAEP  ht label)@@ -842,19 +829,31 @@  -- |  Encrypt a message, returning the ciphertext. ----- Though botan support DLIES and ECIES but only EME are exported via FFI, please use an algorithm that directly--- support encryption such as RSA and ElGamal.+-- Though botan support DLIES and ECIES but only EME are exported via FFI, please use an algorithm that directly support eme encryption such as RSA and ElGamal. ---pkEncrypt :: PubKey -> EMEPadding -> RNG+pkEncrypt :: HasCallStack+          => PubKey -> EMEPadding -> RNG           -> V.Bytes        -- ^ plaintext           -> IO V.Bytes     -- ^ ciphertext-pkEncrypt pubKey padding rng ptext = do-    let paddingStr = emeToCBytes padding+{-# INLINABLE pkEncrypt  #-}+pkEncrypt pubKey padding = encrypt_ pubKey (emeToCBytes padding)++-- |  Encrypt a message using SM2, returning the ciphertext.+sm2Encrypt :: HasCallStack+           => PubKey -> HashType -> RNG+           -> V.Bytes        -- ^ plaintext+           -> IO V.Bytes     -- ^ ciphertext+{-# INLINABLE sm2Encrypt  #-}+sm2Encrypt pubKey ht = encrypt_ pubKey (hashTypeToCBytes ht)++encrypt_ :: HasCallStack => PubKey -> CBytes -> RNG -> V.Bytes -> IO V.Bytes+{-# INLINABLE encrypt_  #-}+encrypt_ pubKey param rng ptext = do     encryptor <-         withPubKey pubKey $ \ pubKey' ->-        CB.withCBytesUnsafe paddingStr $ \ padding' ->+        CB.withCBytesUnsafe param $ \ param' ->             newBotanStruct-                (\ op -> botan_pk_op_encrypt_create op pubKey' padding' 0) -- Flags should be 0 in this version.+                (\ op -> botan_pk_op_encrypt_create op pubKey' param' 0) -- Flags should be 0 in this version.                 botan_pk_op_encrypt_destroy      withBotanStruct encryptor $ \ op -> do@@ -866,21 +865,31 @@             allocBotanBufferUnsafe (fromIntegral len) $ \ out len' ->                 hs_botan_pk_op_encrypt op rng' out len' ptext' ptextOff' ptextLen' --- |  Decrypt a message, returning the ciphertext.+-- |  Decrypt a message, returning the plaintext. ----- Though botan support DLIES and ECIES but only EME are exported via FFI, please use an algorithm that directly--- support decryption such as RSA and ElGamal.+-- Though botan support DLIES and ECIES but only EME are exported via FFI, please use an algorithm that directly support decryption such as 'RSA' and 'ElGamal'. ---pkDecrypt :: PrivKey -> EMEPadding+pkDecrypt :: HasCallStack => PrivKey -> EMEPadding           -> V.Bytes        -- ^ ciphertext           -> V.Bytes        -- ^ plaintext-pkDecrypt key padding ctext = unsafePerformIO $ do-    let paddingStr = emeToCBytes padding+{-# INLINABLE pkDecrypt  #-}+pkDecrypt pubKey padding = decrypt_ pubKey (emeToCBytes padding)++-- |  Decrypt a message using SM2, returning the plaintext.+sm2Decrypt :: HasCallStack => PrivKey -> HashType+           -> V.Bytes        -- ^ plaintext+           -> V.Bytes     -- ^ ciphertext+{-# INLINABLE sm2Decrypt  #-}+sm2Decrypt privKey ht = decrypt_ privKey (hashTypeToCBytes ht)++decrypt_ :: HasCallStack => PrivKey -> CBytes -> V.Bytes -> V.Bytes+{-# INLINABLE decrypt_  #-}+decrypt_ key param ctext = unsafePerformIO $ do     decryptor <-         withPrivKey key $ \ key' ->-        CB.withCBytesUnsafe paddingStr $ \ padding' ->+        CB.withCBytesUnsafe param $ \ param' ->             newBotanStruct-                (\ op -> botan_pk_op_decrypt_create op key' padding' 0) -- Flags should be 0 in this version.+                (\ op -> botan_pk_op_decrypt_create op key' param' 0) -- Flags should be 0 in this version.                 botan_pk_op_decrypt_destroy      withBotanStruct decryptor $ \ op -> do@@ -912,6 +921,7 @@     | EMSA_Raw  emsaToCBytes :: EMSA -> CBytes+{-# INLINABLE emsaToCBytes  #-} emsaToCBytes (EMSA1 ht) = CB.concat ["EMSA1(", hashTypeToCBytes ht, ")"] emsaToCBytes (EMSA3_RAW (Just ht)) =     CB.concat ["EMSA3(Raw,", hashTypeToCBytes ht, ")"]@@ -946,6 +956,7 @@     deriving anyclass T.Print  signFmtToFlag :: SignFmt -> Word32+{-# INLINABLE signFmtToFlag  #-} signFmtToFlag DER_SEQUENCE = 1 signFmtToFlag IEEE_1363    = 0 @@ -958,7 +969,8 @@     deriving (Show, Generic)     deriving anyclass T.Print -newSigner :: PrivKey -> EMSA -> SignFmt -> IO Signer+newSigner :: HasCallStack => PrivKey -> EMSA -> SignFmt -> IO Signer+{-# INLINABLE newSigner  #-} newSigner key emsa fmt = do     let name = emsaToCBytes emsa     withPrivKey key $ \ key' ->@@ -971,7 +983,8 @@                     throwBotanIfMinus_ $ botan_pk_op_sign_output_length op' siz')             return (Signer op name fmt (fromIntegral siz)) -updateSigner :: Signer -> V.Bytes -> IO ()+updateSigner :: HasCallStack => Signer -> V.Bytes -> IO ()+{-# INLINABLE updateSigner  #-} updateSigner (Signer op _ _ _) msg =     withBotanStruct op $ \ op' ->     withPrimVectorUnsafe msg $ \ m moff mlen ->@@ -979,7 +992,8 @@  -- | Produce a signature over all of the bytes passed to 'Signer'. -- Afterwards, the sign operator is reset and may be used to sign a new message.-finalSigner :: Signer -> RNG -> IO V.Bytes+finalSigner :: HasCallStack => Signer -> RNG -> IO V.Bytes+{-# INLINABLE finalSigner  #-} finalSigner (Signer op _ _ siz) rng =     withBotanStruct op $ \ op' ->     withRNG rng $ \ rng' ->@@ -987,7 +1001,7 @@  -- | Trun 'Signer' to a 'V.Bytes' sink, update 'Signer' by write bytes to the sink. ---sinkToSigner :: HasCallStack => Signer -> Sink V.Bytes+sinkToSigner :: HasCallStack => HasCallStack => Signer -> Sink V.Bytes {-# INLINABLE sinkToSigner #-} sinkToSigner h = \ k mbs -> case mbs of     Just bs -> updateSigner h bs@@ -1027,7 +1041,8 @@     deriving (Show, Generic)     deriving anyclass T.Print -newVerifier :: PubKey -> EMSA -> SignFmt -> IO Verifier+newVerifier :: HasCallStack => PubKey -> EMSA -> SignFmt -> IO Verifier+{-# INLINABLE newVerifier  #-} newVerifier pubKey emsa fmt = do     let name = emsaToCBytes emsa     withPubKey pubKey $ \ pubKey' ->@@ -1037,15 +1052,15 @@                 botan_pk_op_verify_destroy             return (Verifier op name fmt) -updateVerifier :: Verifier -> V.Bytes -> IO ()+updateVerifier :: HasCallStack => Verifier -> V.Bytes -> IO ()+{-# INLINABLE updateVerifier  #-} updateVerifier (Verifier op _ _) msg = do     withBotanStruct op $ \ op' ->         withPrimVectorUnsafe msg $ \ msg' off len ->             throwBotanIfMinus_ $ hs_botan_pk_op_verify_update op' msg' off len -finalVerifier :: Verifier-              -> V.Bytes-              -> IO Bool+finalVerifier :: HasCallStack => Verifier -> V.Bytes -> IO Bool+{-# INLINABLE finalVerifier  #-} finalVerifier (Verifier op _ _) msg =     withBotanStruct op $ \ op' ->     withPrimVectorUnsafe msg $ \ msg' off len -> do@@ -1058,7 +1073,7 @@ -- | Trun 'Verifier' to a 'V.Bytes' sink, update 'Verifier' by write bytes to the sink. -- sinkToVerifier :: HasCallStack => Verifier -> Sink V.Bytes-{-# INLINABLE sinkToVerifier #-}+{-# INLINABLE sinkToVerifier  #-} sinkToVerifier h = \ k mbs -> case mbs of     Just bs -> updateVerifier h bs     _       -> k EOF@@ -1081,7 +1096,7 @@            -> [V.Bytes]            -> V.Bytes           -- ^ signature            -> Bool-{-# INLINABLE verifyChunks #-}+{-# INLINABLE verifyChunks  #-} verifyChunks key emsa fmt inps sig = unsafePerformIO $ do     m <- newVerifier key emsa fmt     mapM_ (updateVerifier m) inps@@ -1101,15 +1116,10 @@  -- | Create a new key agreement operation with a given key pair and KDF algorithm. ----- Use a key type that support key agreement, such as 'DH' or 'ECDH',--- Botan implements the following key agreement methods:--- * ECDH over GF(p) Weierstrass curves--- * ECDH over x25519--- * DH over prime fields--- * McEliece--- * NewHope+-- Please use a key type that support key agreement, such as 'DH', 'ECDH', or 'Curve25519'. ---newKeyAgreement :: PrivKey -> KDFType -> IO KeyAgreement+newKeyAgreement :: HasCallStack => PrivKey -> KDFType -> IO KeyAgreement+{-# INLINABLE newKeyAgreement  #-} newKeyAgreement key kdf =     withPrivKey key $ \ key' ->     CB.withCBytesUnsafe (kdfTypeToCBytes kdf) $ \ kdf' -> do@@ -1121,19 +1131,22 @@                 throwBotanIfMinus_ $ botan_pk_op_key_agreement_size op' siz')         return (KeyAgreement op (fromIntegral siz)) -exportKeyAgreementPublic :: PrivKey -> IO V.Bytes+exportKeyAgreementPublic :: HasCallStack => PrivKey -> IO V.Bytes+{-# INLINABLE exportKeyAgreementPublic  #-} exportKeyAgreementPublic key =     withPrivKey key $ \ key' ->     allocBotanBufferUnsafe 128 $ botan_pk_op_key_agreement_export_public key'  -- | How key agreement works is that you trade public values with some other party, and then each of you runs a computation with the other’s value and your key (this should return the same result to both parties). keyAgree ::+    HasCallStack =>     KeyAgreement ->     -- | other key     V.Bytes ->     -- | salt     V.Bytes ->     IO V.Bytes+{-# INLINABLE keyAgree  #-} keyAgree (KeyAgreement op siz) others salt =     withBotanStruct op $ \ op' ->     withPrimVectorUnsafe others $ \ others' others_off others_len ->

@@ -42,10 +42,12 @@ -- -- The bcrypt work factor must be at least 4 (though at this work factor bcrypt is not very secure). The bcrypt format allows up to 31, but Botan currently rejects all work factors greater than 18 since even that work factor requires roughly 15 seconds of computation on a fast machine. ---genBcrypt :: V.Bytes    -- ^ password.+genBcrypt :: HasCallStack+          => V.Bytes    -- ^ password.           -> RNG           -> Int        -- ^ work factors (4 <= n <= 18).           -> IO V.Bytes+{-# INLINABLE genBcrypt #-} genBcrypt pwd rng n = do     withPrimVectorUnsafe pwd $ \ pwd_p pwd_off pwd_len ->         withRNG rng $ \ rng_p -> do@@ -61,9 +63,11 @@  -- | Takes a password and a bcrypt output and returns true if the password is the same as the one that was used to generate the bcrypt hash. ---validBcrypt :: V.Bytes -- ^ password.+validBcrypt :: HasCallStack+            => V.Bytes -- ^ password.             -> V.Bytes -- ^ hash generated by 'genBcrypt'.             -> IO Bool+{-# INLINABLE validBcrypt #-} validBcrypt pwd hash = do     withPrimVectorUnsafe pwd $ \ pwd_p pwd_off pwd_l ->         withPrimVectorUnsafe hash $ \ hash_p hash_off hash_l -> do

@@ -45,7 +45,8 @@     deriving anyclass T.Print  -- | Initialize a random number generator object from the given 'RNGType'-newRNG :: RNGType -> IO RNG+newRNG :: HasCallStack => RNGType -> IO RNG+{-# INLINABLE newRNG #-} newRNG typ = RNG <$> newBotanStruct     (\ bts -> withCBytesUnsafe (rngTypeCBytes typ) (botan_rng_init bts))     botan_rng_destroy@@ -55,7 +56,8 @@     rngTypeCBytes ProcessorRNG  = "hwrng"  -- | Use RNG as a `botan_rng_t` object.-withRNG :: RNG -> (BotanStructT -> IO a) -> IO a+withRNG :: HasCallStack => RNG -> (BotanStructT -> IO a) -> IO a+{-# INLINABLE withRNG #-} withRNG (RNG rng) f = withBotanStruct rng f  -- | Get an autoseeded RNG from a global RNG pool divide by haskell capability.@@ -63,7 +65,8 @@ -- Botan internal use a lock to protect user-space RNG, which may cause contention if shared. -- This function will fetch an autoseeded RNG from a global RNG pool, which is recommended under -- concurrent settings.-getRNG :: IO RNG+getRNG :: HasCallStack => IO RNG+{-# INLINABLE getRNG #-} getRNG = do     (cap, _) <- threadCapability =<< myThreadId     rngArray <- readIORef rngArrayRef@@ -80,19 +83,22 @@         newIORef irngArray  -- | Get random bytes from a random number generator.-getRandom :: RNG -> Int -> IO V.Bytes+getRandom :: HasCallStack => RNG -> Int -> IO V.Bytes+{-# INLINABLE getRandom #-} getRandom r siz =  withRNG r $ \ rng -> do     (b, _) <- allocPrimVectorUnsafe siz $ \ buf ->         throwBotanIfMinus_ (botan_rng_get rng buf (fromIntegral siz))     return b  -- | Reseeds the random number generator with bits number of bits from the 'SystemRNG'.-reseedRNG :: RNG -> Int -> IO ()+reseedRNG :: HasCallStack => RNG -> Int -> IO ()+{-# INLINABLE reseedRNG #-} reseedRNG r siz = withRNG r $ \ rng -> do     throwBotanIfMinus_ (botan_rng_reseed rng (fromIntegral siz))  -- | Reseeds the random number generator with bits number of bits from the given source RNG.-reseedRNGFromRNG :: RNG -> RNG -> Int -> IO ()+reseedRNGFromRNG :: HasCallStack => RNG -> RNG -> Int -> IO ()+{-# INLINABLE reseedRNGFromRNG #-} reseedRNGFromRNG r1 r2 siz =     withRNG r1 $ \ rng1 -> do         withRNG r2 $ \ rng2 -> do@@ -101,7 +107,8 @@ -- | Adds the provided seed material to the internal RNG state. -- -- This call may be ignored by certain RNG instances (such as 'ProcessorRNG' or, on some systems, the 'SystemRNG').-addEntropyRNG :: RNG -> V.Bytes -> IO ()+addEntropyRNG :: HasCallStack => RNG -> V.Bytes -> IO ()+{-# INLINABLE addEntropyRNG #-} addEntropyRNG r seed =     withRNG r $ \ rng -> do         withPrimVectorUnsafe seed $ \ pseed offseed lseed -> do

@@ -39,6 +39,8 @@   , CertStore   , withCertStore   , loadCertStoreFile+  , mozillaCertStore+  , systemCertStore   -- * constants   , KeyUsageConstraint   , pattern NO_CONSTRAINTS@@ -69,6 +71,7 @@ import           Z.Foreign import           Z.Foreign.CPtr import           System.IO.Unsafe+import           Paths_Z_Botan           (getDataFileName)  ------------------------ -- X.509 Certificates --@@ -85,10 +88,12 @@     deriving anyclass T.Print  withCert :: HasCallStack => Cert -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withCert #-} withCert (Cert cert) = withBotanStruct cert  -- | Load a certificate from the DER or PEM representation. loadCert :: HasCallStack => V.Bytes -> IO Cert+{-# INLINABLE loadCert #-} loadCert cert = do     withPrimVectorUnsafe cert $ \ cert' off len ->         Cert <$> newBotanStruct@@ -97,6 +102,7 @@  -- | Load a certificate from a file. loadCertFile :: HasCallStack => CBytes -> IO Cert+{-# INLINABLE loadCertFile #-} loadCertFile name = do     CB.withCBytesUnsafe name $ \ name' ->         Cert <$> newBotanStruct@@ -105,6 +111,7 @@  -- | Create a new object that refers to the same certificate. dupCert :: HasCallStack => Cert -> IO Cert+{-# INLINABLE dupCert #-} dupCert cert = do     withCert cert $ \ cert' ->         Cert <$> newBotanStruct@@ -135,18 +142,21 @@  -- | Return the time the certificate becomes valid, as a 'T.Text' in form “YYYYMMDDHHMMSSZ” where Z is a literal character reflecting that this time is relative to UTC. certStartText :: Cert -> IO T.Text+{-# INLINABLE certStartText #-} certStartText cert =     withCert cert $ \ cert' ->     allocBotanBufferUTF8Unsafe 16 (botan_x509_cert_get_time_starts cert')  -- | Return the time the certificate expires, as a 'T.Text' in form “YYYYMMDDHHMMSSZ” where Z is a literal character reflecting that this time is relative to UTC. certExpireText :: Cert -> IO T.Text+{-# INLINABLE certExpireText #-} certExpireText cert =     withCert cert $ \ cert' ->     allocBotanBufferUTF8Unsafe 16 (botan_x509_cert_get_time_expires cert')  -- | Return the time the certificate becomes valid, as seconds since epoch. certStart :: Cert -> IO Word64+{-# INLINABLE certStart #-} certStart cert =     withCert cert $ \ cert' -> do         (a, _) <- allocPrimUnsafe @Word64 $ botan_x509_cert_not_before cert'@@ -154,12 +164,14 @@  -- | Return the time the certificate becomes valid. certStart' :: Cert -> IO SystemTime+{-# INLINABLE certStart' #-} certStart' cert = do     !r <- fromIntegral <$> certStart cert     return (MkSystemTime r 0)  -- | Return the time the certificate expires, as 'SystemTime'. certExpire :: Cert -> IO Word64+{-# INLINABLE certExpire #-} certExpire cert =     withCert cert $ \ cert' -> do         (a, _) <- allocPrimUnsafe @Word64 $ botan_x509_cert_not_after cert'@@ -167,12 +179,14 @@  -- | Return the time the certificate expires, as 'SystemTime'. certExpire' :: Cert -> IO SystemTime+{-# INLINABLE certExpire' #-} certExpire' cert = do     !r <- fromIntegral <$> certExpire cert     return (MkSystemTime r 0)  -- | Return the finger print of the certificate. certFingerPrint :: Cert -> HashType -> IO T.Text+{-# INLINABLE certFingerPrint #-} certFingerPrint cert ht =     withCert cert $ \ cert' ->     CB.withCBytesUnsafe (hashTypeToCBytes ht) $ \ ht' ->@@ -181,6 +195,7 @@  -- | Return the serial number of the certificate. certSerial :: Cert -> IO V.Bytes+{-# INLINABLE certSerial #-} certSerial cert =     withCert cert $ \ cert' ->     allocBotanBufferUnsafe 64 $@@ -188,6 +203,7 @@  -- | Return the authority key ID set in the certificate, which may be empty. certIDAuthority :: Cert -> IO V.Bytes+{-# INLINABLE certIDAuthority #-} certIDAuthority cert =     withCert cert $ \ cert' ->     allocBotanBufferUnsafe 64 $@@ -195,6 +211,7 @@  -- | Return the subject key ID set in the certificate, which may be empty. certIDSubject :: Cert -> IO V.Bytes+{-# INLINABLE certIDSubject #-} certIDSubject cert =     withCert cert $ \ cert' ->     allocBotanBufferUnsafe 64 $@@ -202,6 +219,7 @@  -- | Get the serialized representation of the public key included in this certificate. certPubBits :: Cert -> IO V.Bytes+{-# INLINABLE certPubBits #-} certPubBits cert =     withCert cert $ \ cert' ->     allocBotanBufferUnsafe V.smallChunkSize $@@ -209,34 +227,39 @@  -- | Get the public key included in this certificate. certPubKey :: Cert -> IO PubKey+{-# INLINABLE certPubKey #-} certPubKey cert = do     withCert cert $ \ cert' ->         PubKey <$> newBotanStruct             (cert' `botan_x509_cert_get_public_key`)             botan_pubkey_destroy --- | Get a value from the issuer DN field.+-- | Get a value from the issuer DN field, throw exception if not exists. certDNIssuer ::+    HasCallStack =>     Cert ->     -- | key     CBytes ->     -- | index     Int ->     IO T.Text+{-# INLINABLE  certDNIssuer #-} certDNIssuer cert key ix =     withCert cert $ \ cert' ->     CB.withCBytesUnsafe key $ \ key' -> do     allocBotanBufferUTF8Unsafe 64 $         botan_x509_cert_get_issuer_dn cert' key' ix --- | Get a value from the subject DN field.+-- | Get a value from the subject DN field, throw exception if not exists. certDNSubject ::-  Cert ->-  -- | key-  CBytes ->-  -- | index-  Int ->-  IO T.Text+    HasCallStack =>+    Cert ->+    -- | key+    CBytes ->+    -- | index+    Int ->+    IO T.Text+{-# INLINABLE  certDNSubject #-} certDNSubject cert key ix =     withCert cert $ \ cert' ->     CB.withCBytesUnsafe key $ \ key' ->@@ -244,14 +267,16 @@         botan_x509_cert_get_subject_dn cert' key' ix  -- | Format the certificate as a free-form string.-certToText :: Cert -> IO T.Text+certToText :: HasCallStack => Cert -> IO T.Text+{-# INLINABLE certToText #-} certToText cert =     withCert cert $ \ cert' ->     T.Text . V.unsafeInit <$>         allocBotanBufferUnsafe V.smallChunkSize (botan_x509_cert_to_string cert')  -- | Change cert's 'KeyUsageConstraint'.-certUsage :: Cert -> KeyUsageConstraint -> IO ()+certUsage :: HasCallStack => Cert -> KeyUsageConstraint -> IO ()+{-# INLINABLE certUsage #-} certUsage cert usage =     withCert cert $ \ cert' ->     throwBotanIfMinus_ $ botan_x509_cert_allowed_usage cert' usage@@ -259,6 +284,7 @@ -- Verify a certificate. Returns 'Nothing' if validation was successful, 'Just reason' if unsuccessful. -- verifyCert ::+    HasCallStack =>     -- | Intermediate certificates, set to @[]@ if not needed.     [Cert] ->     -- | Trusted certificates, set to @[]@ if not needed.@@ -272,6 +298,7 @@     -- | The certificate to be verified.     Cert ->     IO (Maybe CBytes)+{-# INLINABLE verifyCert #-} verifyCert intermediates trusted strength hostname refTime cert =     withCert cert $ \ cert' ->     withCPtrsUnsafe (map certStruct intermediates) $ \ intermediates' intermediatesLen ->@@ -288,6 +315,7 @@  -- | Return a (statically allocated) CString associated with the verification result. certValidateStatus :: CInt -> CBytes+{-# INLINABLE certValidateStatus #-} certValidateStatus r =     unsafeDupablePerformIO $ CB.fromCString =<< botan_x509_cert_validation_status r @@ -296,6 +324,7 @@ -- Verify a certificate. Returns 'Nothing' if validation was successful, 'Just reason' if unsuccessful. -- verifyCertCRL ::+    HasCallStack =>     -- | Intermediate certificates, set to @[]@ if not needed.     [Cert] ->     -- | Trusted certificates, set to @[]@ if not needed.@@ -311,6 +340,7 @@     -- | The certificate to be verified.     Cert ->     IO (Maybe CBytes)+{-# INLINABLE verifyCertCRL #-} verifyCertCRL intermediates trusted crls strength hostname refTime cert =     withCert cert $ \ cert' ->     withCPtrsUnsafe (map certStruct intermediates) $ \ intermediates' intermediatesLen ->@@ -332,6 +362,7 @@ -- Verify a certificate. Returns 'Nothing' if validation was successful, 'Just reason' if unsuccessful. -- verifyCertCRL' ::+    HasCallStack =>     -- | Intermediate certificates, set to @[]@ if not needed.     [Cert] ->     -- | Trusted certificates in 'CertStore'@@ -347,6 +378,7 @@     -- | The certificate to be verified.     Cert ->     IO (Maybe CBytes)+{-# INLINABLE verifyCertCRL' #-} verifyCertCRL' intermediates store crls strength hostname refTime cert =     withCert cert $ \ cert' ->     withCertStore store $ \ store' ->@@ -380,10 +412,12 @@     deriving anyclass T.Print  withCRL :: HasCallStack => CRL -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withCRL #-} withCRL (CRL crl) = withBotanStruct crl  -- | Load a CRL from the DER or PEM representation.-loadCRL :: V.Bytes -> IO CRL+loadCRL :: HasCallStack => V.Bytes -> IO CRL+{-# INLINABLE loadCRL #-} loadCRL src =     withPrimVectorUnsafe src $ \ src' off len ->     CRL <$> newBotanStruct@@ -391,7 +425,8 @@         botan_x509_crl_destroy  -- | Load a CRL from a file.-loadCRLFile :: CBytes -> IO CRL+loadCRLFile :: HasCallStack => CBytes -> IO CRL+{-# INLINABLE loadCRLFile #-} loadCRLFile src =     CB.withCBytesUnsafe src $ \ src' ->     CRL <$> newBotanStruct@@ -400,6 +435,7 @@  -- | Check whether a given crl contains a given cert. Return True when the certificate is revoked, False otherwise. isRevokedX509 :: HasCallStack => CRL -> Cert -> IO Bool+{-# INLINABLE isRevokedX509 #-} isRevokedX509 crl cert =     withCRL crl $ \ crl' ->     withCert cert $ \ cert' -> do@@ -421,12 +457,32 @@  -- | Use 'CertStore' as a 'botan_x509_certstore_t'. withCertStore :: HasCallStack => CertStore -> (BotanStructT -> IO r) -> IO r+{-# INLINABLE withCertStore #-} withCertStore (CertStore c) = withBotanStruct c  -- | Load a CertStore from a file.-loadCertStoreFile :: CBytes -> IO CertStore+loadCertStoreFile :: HasCallStack => CBytes -> IO CertStore+{-# INLINABLE loadCertStoreFile #-} loadCertStoreFile src =     CB.withCBytesUnsafe src $ \ src' ->     CertStore <$> newBotanStruct         (`botan_x509_certstore_load_file` src')+        botan_x509_certstore_destroy++-- | The built-in mozilla CA 'CertStore'.+--+-- This is a certstore extracted from Mozilla, see <https://curl.se/docs/caextract.html>.+mozillaCertStore :: CertStore+{-# NOINLINE mozillaCertStore #-}+mozillaCertStore = unsafePerformIO $ do+    f <- getDataFileName "third_party/cacert.pem"+    loadCertStoreFile (CB.pack f)++-- | The CA 'CertStore' on your system.+--+systemCertStore :: CertStore+{-# NOINLINE systemCertStore #-}+systemCertStore = unsafePerformIO $ do+    CertStore <$> newBotanStruct+        botan_x509_certstore_load_system         botan_x509_certstore_destroy

file too large to diff

@@ -0,0 +1,21 @@++ABI Stability+====================++Botan uses semantic versioning for the API; if API features are added the minor+version increases, whereas if API compatibility breaks occur the major version+is increased.++However no guarantees about ABI are made between releases. Maintaining an ABI+compatible release in a complex C++ API is exceedingly expensive in development+time; just adding a single member variable or virtual function is enough to+cause ABI issues.++If ABI changes, the soname revision will increase to prevent applications from+linking against a potentially incompatible version at runtime.++If you are concerned about long-term ABI issues, considering using the C API+instead; this subset *is* ABI stable.++You can review a report on ABI changes to Botan at+https://abi-laboratory.pro/tracker/timeline/botan/

@@ -0,0 +1,279 @@+BigInt+========================================++``BigInt`` is Botan's implementation of a multiple-precision integer. Thanks to+C++'s operator overloading features, using ``BigInt`` is often quite similar to+using a native integer type. The number of functions related to ``BigInt`` is+quite large, and not all of them are documented here. You can find the complete+declarations in ``botan/bigint.h`` and ``botan/numthry.h``.++.. cpp:class:: BigInt++   .. cpp:function:: BigInt()++      Create a BigInt with value zero++   .. cpp:function:: BigInt(uint64_t n)++      Create a BigInt with value *n*++   .. cpp:function:: BigInt(const std::string& str)++      Create a BigInt from a string. By default decimal is expected. With an 0x+      prefix instead it is treated as hexadecimal.++   .. cpp:function:: BigInt(const uint8_t buf[], size_t length)++      Create a BigInt from a binary array (big-endian encoding).++   .. cpp:function:: BigInt(RandomNumberGenerator& rng, size_t bits, bool set_high_bit = true)++      Create a random BigInt of the specified size.++   .. cpp:function:: BigInt operator+(const BigInt& x, const BigInt& y)++      Add ``x`` and ``y`` and return result.++   .. cpp:function:: BigInt operator+(const BigInt& x, word y)++      Add ``x`` and ``y`` and return result.++   .. cpp:function:: BigInt operator+(word x, const BigInt& y)++      Add ``x`` and ``y`` and return result.++   .. cpp:function:: BigInt operator-(const BigInt& x, const BigInt& y)++      Subtract ``y`` from ``x`` and return result.++   .. cpp:function:: BigInt operator-(const BigInt& x, word y)++      Subtract ``y`` from ``x`` and return result.++   .. cpp:function:: BigInt operator*(const BigInt& x, const BigInt& y)++      Multiply ``x`` and ``y`` and return result.++   .. cpp:function:: BigInt operator/(const BigInt& x, const BigInt& y)++      Divide ``x`` by ``y`` and return result.++   .. cpp:function:: BigInt operator%(const BigInt& x, const BigInt& y)++      Divide ``x`` by ``y`` and return remainder.++   .. cpp:function:: word operator%(const BigInt& x, word y)++      Divide ``x`` by ``y`` and return remainder.++   .. cpp:function:: word operator<<(const BigInt& x, size_t n)++      Left shift ``x`` by ``n`` and return result.++   .. cpp:function:: word operator>>(const BigInt& x, size_t n)++      Right shift ``x`` by ``n`` and return result.++   .. cpp:function:: BigInt& operator+=(const BigInt& y)++      Add y to ``*this``++   .. cpp:function:: BigInt& operator+=(word y)++      Add y to ``*this``++   .. cpp:function:: BigInt& operator-=(const BigInt& y)++      Subtract y from ``*this``++   .. cpp:function:: BigInt& operator-=(word y)++      Subtract y from ``*this``++   .. cpp:function:: BigInt& operator*=(const BigInt& y)++      Multiply ``*this`` with y++   .. cpp:function:: BigInt& operator*=(word y)++      Multiply ``*this`` with y++   .. cpp:function:: BigInt& operator/=(const BigInt& y)++      Divide ``*this`` by y++   .. cpp:function:: BigInt& operator%=(const BigInt& y)++      Divide ``*this`` by y and set ``*this`` to the remainder.++   .. cpp:function:: word operator%=(word y)++      Divide ``*this`` by y and set ``*this`` to the remainder.++   .. cpp:function:: word operator<<=(size_t shift)++      Left shift ``*this`` by *shift* bits++   .. cpp:function:: word operator>>=(size_t shift)++      Right shift ``*this`` by *shift* bits++   .. cpp:function:: BigInt& operator++()++      Increment ``*this`` by 1++   .. cpp:function:: BigInt& operator--()++      Decrement ``*this`` by 1++   .. cpp:function:: BigInt operator++(int)++      Postfix increment ``*this`` by 1++   .. cpp:function:: BigInt operator--(int)++      Postfix decrement ``*this`` by 1++   .. cpp:function:: BigInt operator-() const++      Negation operator++   .. cpp:function:: bool operator !() const++      Return true unless ``*this`` is zero++   .. cpp:function:: void clear()++      Set ``*this`` to zero++   .. cpp:function:: size_t bytes() const++      Return number of bytes need to represent value of ``*this``++   .. cpp:function:: size_t bits() const++      Return number of bits need to represent value of ``*this``++   .. cpp:function:: bool is_even() const++      Return true if ``*this`` is even++   .. cpp:function:: bool is_odd() const++      Return true if ``*this`` is odd++   .. cpp:function:: bool is_nonzero() const++      Return true if ``*this`` is not zero++   .. cpp:function:: bool is_zero() const++      Return true if ``*this`` is zero++   .. cpp:function:: void set_bit(size_t n)++      Set bit *n* of ``*this``++   .. cpp:function:: void clear_bit(size_t n)++      Clear bit *n* of ``*this``++   .. cpp:function:: bool get_bit(size_t n) const++      Get bit *n* of ``*this``++   .. cpp:function:: uint32_t to_u32bit() const++      Return value of ``*this`` as a 32-bit integer, if possible.+      If the integer is negative or not in range, an exception is thrown.++   .. cpp:function:: bool is_negative() const++      Return true if ``*this`` is negative++   .. cpp:function:: bool is_positive() const++      Return true if ``*this`` is negative++   .. cpp:function:: BigInt abs() const++      Return absolute value of ``*this``++   .. cpp:function:: void binary_encode(uint8_t buf[]) const++      Encode this BigInt as a big-endian integer. The sign is ignored.++   .. cpp:function:: void binary_encode(uint8_t buf[], size_t len) const++      Encode this BigInt as a big-endian integer. The sign is ignored.+      If ``len`` is less than ``bytes()`` then only the low ``len``+      bytes are output. If ``len`` is greater than ``bytes()`` then+      the output is padded with leading zeros.++   .. cpp:function:: void binary_decode(uint8_t buf[])++      Decode this BigInt as a big-endian integer.++   .. cpp:function:: std::string to_dec_string() const++      Encode the integer as a decimal string.++   .. cpp:function:: std::string to_hex_string() const++      Encode the integer as a hexadecimal string.++Number Theory+----------------------------------------++Number theoretic functions available include:++.. cpp:function:: BigInt gcd(BigInt x, BigInt y)++  Returns the greatest common divisor of x and y++.. cpp:function:: BigInt lcm(BigInt x, BigInt y)++  Returns an integer z which is the smallest integer such that z % x+  == 0 and z % y == 0++.. cpp:function:: BigInt jacobi(BigInt a, BigInt n)++  Return Jacobi symbol of (a|n).++.. cpp:function:: BigInt inverse_mod(BigInt x, BigInt m)++  Returns the modular inverse of x modulo m, that is, an integer+  y such that (x*y) % m == 1. If no such y exists, returns zero.++.. cpp:function:: BigInt power_mod(BigInt b, BigInt x, BigInt m)++  Returns b to the xth power modulo m. If you are doing many+  exponentiations with a single fixed modulus, it is faster to use a+  ``Power_Mod`` implementation.++.. cpp:function:: BigInt ressol(BigInt x, BigInt p)++  Returns the square root modulo a prime, that is, returns a number y+  such that (y*y) % p == x. Returns -1 if no such integer exists.++.. cpp:function:: bool is_prime(BigInt n, RandomNumberGenerator& rng, \+                                size_t prob = 56, double is_random = false)++  Test *n* for primality using a probabilistic algorithm (Miller-Rabin).  With+  this algorithm, there is some non-zero probability that true will be returned+  even if *n* is actually composite. Modifying *prob* allows you to decrease the+  chance of such a false positive, at the cost of increased runtime. Sufficient+  tests will be run such that the chance *n* is composite is no more than 1 in+  2\ :sup:`prob`. Set *is_random* to true if (and only if) *n* was randomly+  chosen (ie, there is no danger it was chosen maliciously) as far fewer tests+  are needed in that case.++.. cpp:function:: BigInt random_prime(RandomNumberGenerator& rng, \+                                      size_t bits, \+                                      BigInt coprime = 1, \+                                      size_t equiv = 1, \+                                      size_t equiv_mod = 2)++  Return a random prime number of ``bits`` bits long that is+  relatively prime to ``coprime``, and equivalent to ``equiv`` modulo+  ``equiv_mod``.

@@ -0,0 +1,361 @@+Block Ciphers+=======================++Block ciphers are a n-bit permutation for some small n, typically 64 or 128+bits.  They are a cryptographic primitive used to generate higher level+operations such as authenticated encryption.++.. warning::++   In almost all cases, a bare block cipher is not what you should be using.+   You probably want an authenticated cipher mode instead (see :ref:`cipher_modes`)+   This interface is used to build higher level operations (such as cipher+   modes or MACs), or in the very rare situation where ECB is required,+   eg for compatibility with an existing system.++.. cpp:class:: BlockCipher++  .. cpp:function:: static std::unique_ptr<BlockCipher> create(const std::string& algo_spec, \+                                                               const std::string& provider = "")++      Create a new block cipher object, or else return null.++  .. cpp:function:: static std::unique_ptr<BlockCipher> create_or_throw(const std::string& algo_spec, \+                                                                        const std::string& provider = "")++      Like ``create``, except instead of returning null an exception is thrown+      if the cipher is not known.++  .. cpp:function:: void set_key(const uint8_t* key, size_t length)++      This sets the key to the value specified. Most algorithms only accept keys+      of certain lengths. If you attempt to call ``set_key`` with a key length+      that is not supported, the exception ``Invalid_Key_Length`` will be+      thrown.++      In all cases, ``set_key`` must be called on an object before any data+      processing (encryption, decryption, etc) is done by that object. If this+      is not done, an exception will be thrown.+      thrown.++  .. cpp:function:: bool valid_keylength(size_t length) const++     This function returns true if and only if *length* is a valid keylength for+     this algorithm.++  .. cpp:function:: size_t minimum_keylength() const++     Return the smallest key length (in bytes) that is acceptable for the+     algorithm.++  .. cpp:function:: size_t maximum_keylength() const++     Return the largest key length (in bytes) that is acceptable for the+     algorithm.++  .. cpp:function:: std::string name() const++      Return a human readable name for this algorithm. This is guaranteed to round-trip with+      ``create`` and ``create_or_throw`` calls, ie create("Foo")->name() == "Foo"++  .. cpp:function:: void clear()++     Zero out the key. The key must be reset before the cipher object can be used.++  .. cpp:function:: BlockCipher* clone() const++     Return a newly allocated BlockCipher object of the same type as this one.++  .. cpp:function:: size_t block_size() const++      Return the size (in *bytes*) of the cipher.++  .. cpp:function:: size_t parallelism() const++     Return the parallelism underlying this implementation of the cipher. This+     value can vary across versions and machines. A return value of N means that+     encrypting or decrypting with N blocks can operate in parallel.++  .. cpp:function:: size_t parallel_bytes() const++     Returns ``parallelism`` multiplied by the block size as well as a small+     fudge factor. That's because even ciphers that have no implicit parallelism+     typically see a small speedup for being called with several blocks due to+     caching effects.++  .. cpp:function:: std::string provider() const++     Return the provider type. Default value is "base" but can be any arbitrary string.+     Other example values are "sse2", "avx2", "openssl".++  .. cpp:function:: void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const++     Encrypt *blocks* blocks of data, taking the input from the array *in* and+     placing the ciphertext into *out*. The two pointers may be identical, but+     should not overlap ranges.++  .. cpp:function:: void decrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const++     Decrypt *blocks* blocks of data, taking the input from the array *in* and+     placing the plaintext into *out*. The two pointers may be identical, but+     should not overlap ranges.++  .. cpp:function:: void encrypt(const uint8_t in[], uint8_t out[]) const++     Encrypt a single block. Equivalent to :cpp:func:`encrypt_n`\ (in, out, 1).++  .. cpp:function:: void encrypt(uint8_t block[]) const++     Encrypt a single block. Equivalent to :cpp:func:`encrypt_n`\ (block, block, 1)++  .. cpp:function:: void decrypt(const uint8_t in[], uint8_t out[]) const++     Decrypt a single block. Equivalent to :cpp:func:`decrypt_n`\ (in, out, 1)++  .. cpp:function:: void decrypt(uint8_t block[]) const++     Decrypt a single block. Equivalent to :cpp:func:`decrypt_n`\ (block, block, 1)++  .. cpp:function:: template<typename Alloc> void encrypt(std::vector<uint8_t, Alloc>& block) const++     Assumes ``block`` is of a multiple of the block size.++  .. cpp:function:: template<typename Alloc> void decrypt(std::vector<uint8_t, Alloc>& block) const++     Assumes ``block`` is of a multiple of the block size.++Code Example+-----------------++For sheer demonstrative purposes, the following code encrypts a provided single+block of plaintext with AES-256 using two different keys.++.. code-block:: cpp++    #include <botan/block_cipher.h>+    #include <botan/hex.h>+    #include <iostream>+    int main ()+       {+       std::vector<uint8_t> key = Botan::hex_decode("000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F");+       std::vector<uint8_t> block = Botan::hex_decode("00112233445566778899AABBCCDDEEFF");+       std::unique_ptr<Botan::BlockCipher> cipher(Botan::BlockCipher::create("AES-256"));+       cipher->set_key(key);+       cipher->encrypt(block);+       std::cout << std::endl <<cipher->name() << "single block encrypt: " << Botan::hex_encode(block);++       //clear cipher for 2nd encryption with other key+       cipher->clear();+       key = Botan::hex_decode("1337133713371337133713371337133713371337133713371337133713371337");+       cipher->set_key(key);+       cipher->encrypt(block);++       std::cout << std::endl << cipher->name() << "single block encrypt: " << Botan::hex_encode(block);+       return 0;+       }++Available Ciphers+---------------------++Botan includes a number of block ciphers that are specific to particular countries, as+well as a few that are included mostly due to their use in specific protocols such as PGP+but not widely used elsewhere. If you are developing new code and have no particular+opinion, use AES-256. If you desire an alternative to AES, consider Serpent, SHACAL2 or+Threefish.++.. warning:: Avoid any 64-bit block cipher in new designs. There are+             combinatoric issues that affect any 64-bit cipher that render it+             insecure when large amounts of data are processed.++AES+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++Comes in three variants, AES-128, AES-192, and AES-256.++The standard 128-bit block cipher. Many modern platforms offer hardware+acceleration. However, on platforms without hardware support, AES+implementations typically are vulnerable to side channel attacks. For x86+systems with SSSE3 but without AES-NI, Botan has an implementation which avoids+known side channels.++Available if ``BOTAN_HAS_AES`` is defined.++ARIA+~~~~~~++South Korean cipher used in industry there. No reason to use it otherwise.++Available if ``BOTAN_HAS_ARIA`` is defined.++Blowfish+~~~~~~~~~++A 64-bit cipher popular in the pre-AES era. Very slow key setup. Also used (with+bcrypt) for password hashing.++Available if ``BOTAN_HAS_BLOWFISH`` is defined.++CAST-128+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 64-bit cipher, commonly used in OpenPGP.++Available if ``BOTAN_HAS_CAST128`` is defined.++CAST-256+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 128-bit cipher that was a contestant in the NIST AES competition.+Almost never used in practice. Prefer AES or Serpent.++Available if ``BOTAN_HAS_CAST256`` is defined.++.. warning::+   Support for CAST-256 is deprecated and will be removed in a future major release.++Camellia+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++Comes in three variants, Camellia-128, Camellia-192, and Camellia-256.++A Japanese design standardized by ISO, NESSIE and CRYPTREC.+Rarely used outside of Japan.++Available if ``BOTAN_HAS_CAMELLIA`` is defined.++Cascade+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++Creates a block cipher cascade, where each block is encrypted by two ciphers+with independent keys. Useful if you're very paranoid. In practice any single+good cipher (such as Serpent, SHACAL2, or AES-256) is more than sufficient.++Available if ``BOTAN_HAS_CASCADE`` is defined.++DES, 3DES, DESX+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++Originally designed by IBM and NSA in the 1970s. Today, DES's 56-bit key renders+it insecure to any well-resourced attacker. DESX and 3DES extend the key length,+and are still thought to be secure, modulo the limitation of a 64-bit block.+All are somewhat common in some industries such as finance. Avoid in new code.++.. warning::+   Support for DESX is deprecated and it will be removed in a future major release.++Available if ``BOTAN_HAS_DES`` is defined.++GOST-28147-89+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++Aka "Magma". An old 64-bit Russian cipher. Possible security issues, avoid+unless compatibility is needed.++Available if ``BOTAN_HAS_GOST_28147_89`` is defined.++.. warning::+   Support for this cipher is deprecated and will be removed in a future major release.++IDEA+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++An older but still unbroken 64-bit cipher with a 128-bit key. Somewhat common+due to its use in PGP. Avoid in new designs.++Available if ``BOTAN_HAS_IDEA`` is defined.++Kasumi+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 64-bit cipher used in 3GPP mobile phone protocols. There is no reason to use+it outside of this context.++Available if ``BOTAN_HAS_KASUMI`` is defined.++.. warning::+   Support for Kasumi is deprecated and will be removed in a future major release.++Lion+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A "block cipher construction" which can encrypt blocks of nearly arbitrary+length.  Built from a stream cipher and a hash function. Useful in certain+protocols where being able to encrypt large or arbitrary length blocks is+necessary.++Available if ``BOTAN_HAS_LION`` is defined.++MISTY1+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 64-bit Japanese cipher standardized by NESSIE and ISO. Seemingly secure, but+quite slow and saw little adoption. No reason to use it in new code.++Available if ``BOTAN_HAS_MISTY1`` is defined.++.. warning::+   Support for MISTY1 is deprecated and will be removed in a future major release.++Noekeon+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A fast 128-bit cipher by the designers of AES. Easily secured against side+channels.++Available if ``BOTAN_HAS_NOEKEON`` is defined.++SEED+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A older South Korean cipher, widely used in industry there. No reason to choose it otherwise.++Available if ``BOTAN_HAS_SEED`` is defined.++SHACAL2+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++The 256-bit block cipher used inside SHA-256. Accepts up to a 512-bit key.+Fast, especially when SIMD or SHA-2 acceleration instructions are available.+Standardized by NESSIE but otherwise obscure.++Available if ``BOTAN_HAS_SHACAL2`` is defined.++SM4+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 128-bit Chinese national cipher, required for use in certain commercial+applications in China. Quite slow. Probably no reason to use it outside of legal+requirements.++Available if ``BOTAN_HAS_SM4`` is defined.++Serpent+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++An AES contender. Widely considered the most conservative design. Fairly slow+unless SIMD instructions are available.++Available if ``BOTAN_HAS_SERPENT`` is defined.++Threefish-512+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 512-bit tweakable block cipher that was used in the Skein hash function.+Very fast on 64-bit processors.++Available if ``BOTAN_HAS_THREEFISH_512`` is defined.++Twofish+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 128-bit block cipher that was one of the AES finalists. Has a somewhat complicated key+setup and a "kitchen sink" design.++Available if ``BOTAN_HAS_TWOFISH`` is defined.++XTEA+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++A 64-bit cipher popular for its simple implementation. Avoid in new code.++Available if ``BOTAN_HAS_XTEA`` is defined.

@@ -0,0 +1,384 @@+.. _cipher_modes:++Cipher Modes+=====================++A block cipher by itself, is only able to securely encrypt a single data block.+To be able to securely encrypt data of arbitrary length, a mode of operation+applies the block cipher's single block operation repeatedly to encrypt+an entire message.++All cipher mode implementations are are derived from the base class+:cpp:class:`Cipher_Mode`, which is declared in ``botan/cipher_mode.h``.++.. warning::+   Using an unauthenticted cipher mode without combining it with a+   :ref:`mac` is insecure. Prefer using an :ref:`aead`.++.. cpp:class:: Cipher_Mode++  .. cpp:function:: void set_key(const uint8_t* key, size_t length)++    Set the symmetric key to be used.++  .. cpp:function:: bool valid_keylength(size_t length) const++     This function returns true if and only if *length* is a valid+     keylength for the algorithm.++  .. cpp:function:: size_t minimum_keylength() const++     Return the smallest key length (in bytes) that is acceptable for the+     algorithm.++  .. cpp:function:: size_t maximum_keylength() const++     Return the largest key length (in bytes) that is acceptable for the+     algorithm.++  .. cpp:function:: size_t default_nonce_length() const++    Return the default (preferable) nonce size for this cipher mode.++  .. cpp:function:: bool valid_nonce_length(size_t nonce_len) const++    Return true if *nonce_len* is a valid length for a nonce with this+    algorithm.++  .. cpp:function:: bool authenticated() const++    Return true if this cipher mode is authenticated++  .. cpp:function:: size_t tag_size() const++    Return the length in bytes of the authentication tag this algorithm+    generates. If the mode is not authenticated, this will return 0. If the mode+    is authenticated, it will return some positive value (typically somewhere+    between 8 and 16).++  .. cpp:function:: void clear()++    Clear all internal state. The object will act exactly like one which was+    just allocated.++  .. cpp:function:: void reset()++    Reset all message state. For example if you called :cpp:func:`start_msg`,+    then :cpp:func:`process` to process some ciphertext, but then encounter an+    IO error and must abandon the current message, you can call `reset`. The+    object will retain the key (unlike calling :cpp:func:`clear` which also+    resets the key) but the nonce and current message state will be erased.++  .. cpp:function:: void start_msg(const uint8_t* nonce, size_t nonce_len)++    Set up for processing a new message. This function must be called with a new+    random value for each message. For almost all modes (excepting SIV), if the+    same nonce is ever used twice with the same key, the encryption scheme loses+    its confidentiality and/or authenticity properties.++  .. cpp:function:: void start(const std::vector<uint8_t> nonce)++    Acts like :cpp:func:`start_msg`\ (nonce.data(), nonce.size()).++  .. cpp:function:: void start(const uint8_t* nonce, size_t nonce_len)++    Acts like :cpp:func:`start_msg`\ (nonce, nonce_len).++  .. cpp:function:: virtual size_t update_granularity() const++    The :cpp:class:`Cipher_Mode` interface requires message processing in multiples of the block size.+    Returns size of required blocks to update and 1, if the mode can process messages of any length.++  .. cpp:function:: virtual size_t process(uint8_t* msg, size_t msg_len)++    Process msg in place and returns the number of bytes written. *msg* must+    be a multiple of :cpp:func:`update_granularity`.++  .. cpp:function:: void update(secure_vector<uint8_t>& buffer, size_t offset = 0)++    Continue processing a message in the buffer in place. The passed buffer's+    size must be a multiple of :cpp:func:`update_granularity`.  The first+    *offset* bytes of the buffer will be ignored.++  .. cpp:function:: size_t minimum_final_size() const++    Returns the minimum size needed for :cpp:func:`finish`.++  .. cpp:function:: void finish(secure_vector<uint8_t>& final_block, size_t offset = 0)++    Finalize the message processing with a final block of at least :cpp:func:`minimum_final_size` size.+    The first *offset* bytes of the passed final block will be ignored.++Code Example+---------------------++The following code encrypts the specified plaintext using AES-128/CBC+with PKCS#7 padding.++.. warning::+   This example ignores the requirement to authenticate the ciphertext++.. note::+   Simply replacing the string "AES-128/CBC/PKCS7" string in the example below+   with "AES-128/GCM" suffices to use authenticated encryption.++.. code-block:: cpp++    #include <botan/rng.h>+    #include <botan/auto_rng.h>+    #include <botan/cipher_mode.h>+    #include <botan/hex.h>+    #include <iostream>++    int main()+       {+       Botan::AutoSeeded_RNG rng;++       const std::string plaintext("Your great-grandfather gave this watch to your granddad for good luck. Unfortunately, Dane's luck wasn't as good as his old man's.");+       const std::vector<uint8_t> key = Botan::hex_decode("2B7E151628AED2A6ABF7158809CF4F3C");++       std::unique_ptr<Botan::Cipher_Mode> enc = Botan::Cipher_Mode::create("AES-128/CBC/PKCS7", Botan::ENCRYPTION);+       enc->set_key(key);++       //generate fresh nonce (IV)+       Botan::secure_vector<uint8_t> iv = rng.random_vec(enc->default_nonce_length());++       // Copy input data to a buffer that will be encrypted+       Botan::secure_vector<uint8_t> pt(plaintext.data(), plaintext.data()+plaintext.length());++       enc->start(iv);+       enc->finish(pt);++       std::cout << enc->name() << " with iv " << Botan::hex_encode(iv) << " " << Botan::hex_encode(pt) << "\n";+       return 0;+       }+++Available Unauthenticated Cipher Modes+-----------------------------------------++.. note::+   CTR and OFB modes are also implemented, but these are treated as+   :cpp:class:`Stream_Cipher`\s instead.++CBC+~~~~~~~~~~~~++Available if ``BOTAN_HAS_MODE_CBC`` is defined.++CBC requires the plaintext be padded using a reversible rule. The following+padding schemes are implemented++PKCS#7 (RFC5652)+  The last byte in the padded block defines the padding length p, the remaining padding bytes are set to p as well.+ANSI X9.23+  The last byte in the padded block defines the padding length, the remaining padding is filled with 0x00.+OneAndZeros (ISO/IEC 7816-4)+  The first padding byte is set to 0x80, the remaining padding bytes are set to 0x00.++Ciphertext stealing (CTS) is also implemented. This scheme allows the+ciphertext to have the same length as the plaintext, however using CTS+requires the input be at least one full block plus one byte. It is+also less commonly implemented.++CFB+~~~~~~~~~~~~++Available if ``BOTAN_HAS_MODE_CFB`` is defined.++CFB uses a block cipher to create a self-synchronizing stream cipher. It is used+for example in the OpenPGP protocol. There is no reason to prefer it, as it has+worse performance characteristics than modes such as CTR or CBC.++XTS+~~~~~~~~~++Available if ``BOTAN_HAS_MODE_XTS`` is defined.++XTS is a mode specialized for encrypting disk or database storage+where ciphertext expansion is not possible. XTS requires all inputs be+at least one full block (16 bytes for AES), however for any acceptable+input length, there is no ciphertext expansion.++.. _aead:++AEAD Mode+---------------------------++AEAD (Authenticated Encryption with Associated Data) modes provide message+encryption, message authentication, and the ability to authenticate additional+data that is not included in the ciphertext (such as a sequence number or+header). It is a subclass of :cpp:class:`Cipher_Mode`.++.. cpp:class:: AEAD_Mode++  .. cpp:function:: void set_key(const SymmetricKey& key)++       Set the key++  .. cpp:function:: Key_Length_Specification key_spec() const++       Return the key length specification++  .. cpp:function:: void set_associated_data(const uint8_t ad[], size_t ad_len)++       Set any associated data for this message. For maximum portability between+       different modes, this must be called after :cpp:func:`set_key` and before+       :cpp:func:`start`.++       If the associated data does not change, it is not necessary to call this+       function more than once, even across multiple calls to :cpp:func:`start`+       and :cpp:func:`finish`.++  .. cpp:function:: void start(const uint8_t nonce[], size_t nonce_len)++       Start processing a message, using *nonce* as the unique per-message+       value. It does not need to be random, simply unique (per key).++       .. warning::+          With almost all AEADs, if the same nonce is ever used to encrypt two+          different messages under the same key, all security is lost. If+          reliably generating unique nonces is difficult in your environment,+          use SIV mode which retains security even if nonces are repeated.++  .. cpp:function:: void update(secure_vector<uint8_t>& buffer, size_t offset = 0)++       Continue processing a message. The *buffer* is an in/out parameter and+       may be resized. In particular, some modes require that all input be+       consumed before any output is produced; with these modes, *buffer* will+       be returned empty.++       On input, the buffer must be sized in blocks of size+       :cpp:func:`update_granularity`. For instance if the update granularity+       was 64, then *buffer* could be 64, 128, 192, ... bytes.++       The first *offset* bytes of *buffer* will be ignored (this allows in+       place processing of a buffer that contains an initial plaintext header)++  .. cpp:function:: void finish(secure_vector<uint8_t>& buffer, size_t offset = 0)++       Complete processing a message with a final input of *buffer*, which is+       treated the same as with :cpp:func:`update`. It must contain at least+       :cpp:func:`final_minimum_size` bytes.++       Note that if you have the entire message in hand, calling finish without+       ever calling update is both efficient and convenient.++       .. note::++          During decryption, if the supplied authentication tag does not+          validate, finish will throw an instance of Invalid_Authentication_Tag+          (aka Integrity_Failure, which was the name for this exception in+          versions before 2.10, a typedef is included for compatability).++          If this occurs, all plaintext previously output via calls to update+          must be destroyed and not used in any way that an attacker could+          observe the effects of. This could be anything from echoing the+          plaintext back (perhaps in an error message), or by making an external+          RPC whose destination or contents depend on the plaintext. The only+          thing you can do is buffer it, and in the event of an invalid tag,+          erase the previously decrypted content from memory.++          One simply way to assure this could never happen is to never+          call update, and instead always marshal the entire message+          into a single buffer and call finish on it when decrypting.++  .. cpp:function:: size_t update_granularity() const++       The AEAD interface requires :cpp:func:`update` be called with blocks of+       this size. This will be 1, if the mode can process any length inputs.++  .. cpp:function:: size_t final_minimum_size() const++       The AEAD interface requires :cpp:func:`finish` be called with at least+       this many bytes (which may be zero, or greater than+       :cpp:func:`update_granularity`)++  .. cpp:function:: bool valid_nonce_length(size_t nonce_len) const++       Returns true if *nonce_len* is a valid nonce length for this scheme. For+       EAX and GCM, any length nonces are allowed. OCB allows any value between+       8 and 15 bytes.++  .. cpp:function:: size_t default_nonce_length() const++       Returns a reasonable length for the nonce, typically either 96+       bits, or the only supported length for modes which don't+       support 96 bit nonces.+++Available AEAD Modes+-------------------------++If in doubt about what to use, pick ChaCha20Poly1305, AES-256/GCM, or AES-256/SIV.+Both ChaCha20Poly1305 and AES with GCM are widely implemented. SIV is somewhat+more obscure (and is slower than either GCM or ChaCha20Poly1305), but has+excellent security properties.++ChaCha20Poly1305+~~~~~~~~~~~~~~~~~~++Available if ``BOTAN_HAS_AEAD_CHACHA20_POLY1305`` is defined.++Unlike the other AEADs which are based on block ciphers, this mode is based on+the ChaCha stream cipher and the Poly1305 authentication code. It is very fast+on all modern platforms.++ChaCha20Poly1305 supports 64-bit, 96-bit, and (since 2.8) 192-bit nonces. 64-bit nonces+are the "classic" ChaCha20Poly1305 design. 96-bit nonces are used by the IETF standard+version of ChaCha20Poly1305. And 192-bit nonces is the XChaCha20Poly1305 construction,+which is somewhat less common.++For best interop use the IETF version with 96-bit nonces. However 96 bits is small enough+that it can be dangerous to generate nonces randomly if more than ~ 2^32 messages are+encrypted under a single key, since if a nonce is ever reused ChaCha20Poly1305 becomes+insecure. It is better to use a counter for the nonce in this case.++If you are encrypting many messages under a single key and cannot maintain a counter for+the nonce, prefer XChaCha20Poly1305 since a 192 bit nonce is large enough that randomly+chosen nonces are extremely unlikely to repeat.++GCM+~~~~~++Available if ``BOTAN_HAS_AEAD_GCM`` is defined.++NIST standard, commonly used. Requires a 128-bit block cipher. Fairly slow,+unless hardware support for carryless multiplies is available.++OCB+~~~~~++Available if ``BOTAN_HAS_AEAD_OCB`` is defined.++A block cipher based AEAD. Supports 128-bit, 256-bit and 512-bit block ciphers.+This mode is very fast and easily secured against side channels. Adoption has+been poor because it is patented in the United States, though a license is+available allowing it to be freely used by open source software.++EAX+~~~~~++Available if ``BOTAN_HAS_AEAD_EAX`` is defined.++A secure composition of CTR mode and CMAC. Supports 128-bit, 256-bit and 512-bit+block ciphers.++SIV+~~~~~~++Available if ``BOTAN_HAS_AEAD_SIV`` is defined.++Requires a 128-bit block cipher. Unlike other AEADs, SIV is "misuse resistant";+if a nonce is repeated, SIV retains security, with the exception that if the+same nonce is used to encrypt the same message multiple times, an attacker can+detect the fact that the message was duplicated (this is simply because if both+the nonce and the message are reused, SIV will output identical ciphertexts).++CCM+~~~~~++Available if ``BOTAN_HAS_AEAD_CCM`` is defined.++A composition of CTR mode and CBC-MAC. Requires a 128-bit block cipher. This is+a NIST standard mode, but that is about all to recommend it. Prefer EAX.

@@ -0,0 +1,90 @@+Lossless Data Compression+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Some lossless data compression algorithms are available in botan, currently all+via third party libraries - these include zlib (including deflate and gzip+formats), bzip2, and lzma. Support for these must be enabled at build time;+you can check for them using the macros ``BOTAN_HAS_ZLIB``, ``BOTAN_HAS_BZIP2``,+and ``BOTAN_HAS_LZMA``.++.. note::+   You should always compress *before* you encrypt, because encryption seeks to+   hide the redundancy that compression is supposed to try to find and remove.++Compression is done through the ``Compression_Algorithm`` and+``Decompression_Algorithm`` classes, both defined in `compression.h`++Compression and decompression both work in three stages: starting a+message (``start``), continuing to process it (``update``), and then+finally completing processing the stream (``finish``).++.. cpp:class:: Compression_Algorithm++  .. cpp:function:: void start(size_t level)++       Initialize the compression engine. This must be done before calling+       ``update`` or ``finish``. The meaning of the `level` parameter varies by+       the algorithm but generally takes a value between 1 and 9, with higher+       values implying typically better compression from and more memory and/or+       CPU time consumed by the compression process. The decompressor can always+       handle input from any compressor.++  .. cpp:function::  void update(secure_vector<uint8_t>& buf, \+                                 size_t offset = 0, bool flush = false)++       Compress the material in the in/out parameter ``buf``. The leading+       ``offset`` bytes of ``buf`` are ignored and remain untouched; this can be+       useful for ignoring packet headers.  If ``flush`` is true, the+       compression state is flushed, allowing the decompressor to recover the+       entire message up to this point without having the see the rest of the+       compressed stream.++   .. cpp::function:: void finish(secure_vector<uint8_t>& buf, size_t offset = 0)++       Finish compressing a message. The ``buf`` and ``offset`` parameters are+       treated as in ``update``. It is acceptable to call ``start`` followed by+       ``finish`` with the entire message, without any intervening call to+       ``update``.++.. cpp:class:: Decompression_Algorithm++  .. cpp:function:: void start()++       Initialize the decompression engine. This must be done before calling+       ``update`` or ``finish``. No level is provided here; the decompressor+       can accept input generated by any compression parameters.++  .. cpp:function::  void update(secure_vector<uint8_t>& buf, \+                                 size_t offset = 0)++       Decompress the material in the in/out parameter ``buf``. The leading+       ``offset`` bytes of ``buf`` are ignored and remain untouched; this can be+       useful for ignoring packet headers.++       This function may throw if the data seems to be invalid.++   .. cpp::function:: void finish(secure_vector<uint8_t>& buf, size_t offset = 0)++       Finish decompressing a message. The ``buf`` and ``offset`` parameters are+       treated as in ``update``. It is acceptable to call ``start`` followed by+       ``finish`` with the entire message, without any intervening call to+       ``update``.++       This function may throw if the data seems to be invalid.++The easiest way to get a compressor is via the functions++.. cpp:function:: Compression_Algorithm* make_compressor(std::string type)+.. cpp:function:: Decompression_Algorithm* make_decompressor(std::string type)++Supported values for `type` include `zlib` (raw zlib with no checksum),+`deflate` (zlib's deflate format), `gzip`, `bz2`, and `lzma`. A null pointer+will be returned if the algorithm is unavailable.++To use a compression algorithm in a `Pipe` use the adapter types+`Compression_Filter` and `Decompression_Filter` from `comp_filter.h`. The+constructors of both filters take a `std::string` argument (passed to+`make_compressor` or `make_decompressor`), the compression filter also takes a+`level` parameter. Finally both constructors have a parameter `buf_sz` which+specifies the size of the internal buffer that will be used - inputs will be+broken into blocks of this size. The default is 4096.

@@ -0,0 +1,39 @@++API Reference+===================++.. toctree::+   :maxdepth: 1++   versions+   secmem+   rng+   hash+   block_cipher+   stream_ciphers+   message_auth_codes+   cipher_modes+   pubkey+   x509+   tls+   credentials_manager+   bigint+   kdf+   pbkdf+   keywrap+   passhash+   cryptobox+   srp+   psk_db+   filters+   fpe+   tss+   ecc+   compression+   pkcs11+   tpm+   otp+   roughtime+   ffi+   env_vars+   python

@@ -0,0 +1,186 @@++Credentials Manager+==================================================++A ``Credentials_Manager`` is a way to abstract how the application+stores credentials. The main user is the :doc:`tls` implementation.++.. cpp:class:: Credentials_Manager++   .. cpp:function:: std::vector<Certificate_Store*> \+         trusted_certificate_authorities( \+         const std::string& type, \+         const std::string& context)++      Return the list of certificate stores, each of which is assumed+      to contain (only) trusted certificate authorities. The+      ``Credentials_Manager`` retains ownership of the+      Certificate_Store pointers.++      .. note::++         It would have been a better API to return a vector of+         ``shared_ptr`` here.  This may change in a future major release.++      When *type* is "tls-client", *context* will be the hostname of+      the server, or empty if the hostname is not known. This allows+      using a different set of certificate stores in different contexts,+      for example using the system certificate store unless contacting+      one particular server which uses a cert issued by an internal CA.++      When *type* is "tls-server", the *context* will again be the+      hostname of the server, or empty if the client did not send a+      server name indicator. For TLS servers, these CAs are the ones+      trusted for signing of client certificates. If you do not want+      the TLS server to ask for a client cert,+      ``trusted_certificate_authorities`` should return an empty list+      for *type* "tls-server".++      The default implementation returns an empty list.++   .. cpp:function:: std::vector<X509_Certificate> find_cert_chain( \+                     const std::vector<std::string>& cert_key_types, \+                     const std::vector<X509_DN>& acceptable_CAs, \+                     const std::string& type, \+                     const std::string& context)++      Return the certificate chain to use to identify ourselves. The+      ``acceptable_CAs`` parameter gives a list of CAs the peer trusts.+      This may be empty.++      .. warning::+         If this function returns a certificate that is not one of the+         types given in ``cert_key_types`` confusing handshake+         failures will result.++   .. cpp:function:: std::vector<X509_Certificate> cert_chain( \+         const std::vector<std::string>& cert_key_types, \+         const std::string& type, \+         const std::string& context)++      Return the certificate chain to use to identify ourselves. Starting in+      2.5, prefer ``find_cert_chain`` which additionally provides the CA list.++   .. cpp:function:: std::vector<X509_Certificate> cert_chain_single_type( \+         const std::string& cert_key_type, \+         const std::string& type, \+         const std::string& context)++      Return the certificate chain to use to identifier ourselves, if+      we have one of type *cert_key_type* and we would like to use a+      certificate in this *type*/*context*.++   .. cpp:function:: Private_Key* private_key_for(const X509_Certificate& cert, \+                                                  const std::string& type, \+                                                  const std::string& context)++      Return the private key for this certificate. The *cert* will be+      the leaf cert of a chain returned previously by ``cert_chain``+      or ``cert_chain_single_type``.++In versions before 1.11.34, there was an additional function on `Credentials_Manager`++   .. cpp::function:: void verify_certificate_chain( \+         const std::string& type, \+         const std::string& hostname, \+         const std::vector<X509_Certificate>& cert_chain)++This function has been replaced by `TLS::Callbacks::tls_verify_cert_chain`.++SRP Authentication+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++``Credentials_Manager`` contains the hooks used by TLS clients and+servers for SRP authentication.++.. note::++   Support for TLS-SRP is deprecated, and will be removed in a future+   major release. When that occurs these APIs will be removed. Prefer+   instead performing a standard TLS handshake, then perform a PAKE+   authentication inside of (and cryptographically bound to) the TLS+   channel.++.. cpp:function:: bool attempt_srp(const std::string& type, \+                                   const std::string& context)++   Returns if we should consider using SRP for authentication++.. cpp:function:: std::string srp_identifier(const std::string& type, \+                                             const std::string& context)++   Returns the SRP identifier we'd like to use (used by client)++.. cpp:function:: std::string srp_password(const std::string& type, \+                                           const std::string& context, \+                                           const std::string& identifier)++   Returns the password for *identifier* (used by client)++.. cpp:function:: bool srp_verifier(const std::string& type, \+                                    const std::string& context, \+                                    const std::string& identifier, \+                                    std::string& group_name, \+                                    BigInt& verifier, \+                                    std::vector<uint8_t>& salt, \+                                    bool generate_fake_on_unknown)++    Returns the SRP verifier information for *identifier* (used by server)++Preshared Keys+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++TLS supports the use of pre shared keys for authentication.++.. cpp:function:: SymmetricKey psk(const std::string& type, \+                                   const std::string& context, \+                                   const std::string& identity)++    Return a symmetric key for use with *identity*++    One important special case for ``psk`` is where *type* is+    "tls-server", *context* is "session-ticket" and *identity* is an+    empty string. If a key is returned for this case, a TLS server+    will offer session tickets to clients who can use them, and the+    returned key will be used to encrypt the ticket. The server is+    allowed to change the key at any time (though changing the key+    means old session tickets can no longer be used for resumption,+    forcing a full re-handshake when the client next connects). One+    simple approach to add support for session tickets in your server+    is to generate a random key the first time ``psk`` is called to+    retrieve the session ticket key, cache it for later use in the+    ``Credentials_Manager``, and simply let it be thrown away when the+    process terminates. See :rfc:`4507` for more information about TLS+    session tickets.++    A similar special case exists for DTLS cookie verification. In+    this case *type* will be "tls-server" and *context* is+    "dtls-cookie-secret". If no key is returned, then DTLS cookies are+    not used. Similar to the session ticket key, the DTLS cookie+    secret can be chosen during server startup and rotated at any time+    with no ill effect.++    .. warning::++       If DTLS cookies are not used then the server is prone to be+       abused as a DoS amplifier, where the attacker sends a+       relatively small client hello in a UDP packet with a forged+       return address, and then the server replies to the victim with+       several messages that are larger. This not only hides the+       attackers address from the victim, but increases their+       effective bandwidth. This is not an issue when using DTLS over+       SCTP or TCP.++.. cpp:function:: std::string psk_identity_hint(const std::string& type, \+                                                const std::string& context)++    Returns an identity hint which may be provided to the client. This+    can help a client understand what PSK to use.++.. cpp:function:: std::string psk_identity(const std::string& type, \+                                           const std::string& context, \+                                           const std::string& identity_hint)++    Returns the identity we would like to use given this *type* and+    *context* and the optional *identity_hint*. Not all servers or+    protocols will provide a hint.

@@ -0,0 +1,32 @@++Cryptobox+========================================++Encryption using a passphrase+----------------------------------------++.. versionadded:: 1.8.6++This is a set of simple routines that encrypt some data using a+passphrase. There are defined in the header `cryptobox.h`, inside+namespace `Botan::CryptoBox`.++It generates cipher and MAC keys using 8192 iterations of PBKDF2 with+HMAC(SHA-512), then encrypts using Serpent in CTR mode and authenticates using a+HMAC(SHA-512) mac of the ciphertext, truncated to 160 bits.++ .. cpp:function:: std::string encrypt(const uint8_t input[], size_t input_len, \+                                       const std::string& passphrase, \+                                       RandomNumberGenerator& rng)++    Encrypt the contents using *passphrase*.++ .. cpp:function:: std::string decrypt(const uint8_t input[], size_t input_len, \+                                       const std::string& passphrase)++    Decrypts something encrypted with encrypt.++ .. cpp:function:: std::string decrypt(const std::string& input, \+                                       const std::string& passphrase)++    Decrypts something encrypted with encrypt.

@@ -0,0 +1,284 @@+Elliptic Curve Operations+============================++In addition to high level operations for signatures, key agreement,+and message encryption using elliptic curve cryptography, the library+contains lower level interfaces for performing operations such as+elliptic curve point multiplication.++Only curves over prime fields are supported.++Many of these functions take a workspace, either a vector of words or+a vector of BigInts. These are used to minimize memory allocations+during common operations.++.. warning::+   You should only use these interfaces if you know what you are doing.++.. cpp:class:: EC_Group++      .. cpp:function:: EC_Group(const OID& oid)++         Initialize an ``EC_Group`` using an OID referencing the curve+         parameters.++      .. cpp:function:: EC_Group(const std::string& name)++         Initialize an ``EC_Group`` using a name or OID (for example+         "secp256r1", or "1.2.840.10045.3.1.7")++      .. cpp:function:: EC_Group(const BigInt& p, \+               const BigInt& a, \+               const BigInt& b, \+               const BigInt& base_x, \+               const BigInt& base_y, \+               const BigInt& order, \+               const BigInt& cofactor, \+               const OID& oid = OID())++          Initialize an elliptic curve group from the relevant parameters. This+          is used for example to create custom (application-specific) curves.++      .. cpp:function:: EC_Group(const std::vector<uint8_t>& ber_encoding)++         Initialize an ``EC_Group`` by decoding a DER encoded parameter block.++      .. cpp:function:: std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const++         Return the DER encoding of this group.++      .. cpp:function:: std::string PEM_encode() const++         Return the PEM encoding of this group (base64 of DER encoding plus+         header/trailer).++      .. cpp:function:: bool a_is_minus_3() const++         Return true if the ``a`` parameter is congruent to -3 mod p.++      .. cpp:function:: bool a_is_zero() const++         Return true if the ``a`` parameter is congruent to 0 mod p.++      .. cpp:function:: size_t get_p_bits() const++         Return size of the prime in bits.++      .. cpp:function:: size_t get_p_bytes() const++         Return size of the prime in bytes.++      .. cpp:function:: size_t get_order_bits() const++         Return size of the group order in bits.++      .. cpp:function:: size_t get_order_bytes() const++         Return size of the group order in bytes.++      .. cpp:function:: const BigInt& get_p() const++         Return the prime modulus.++      .. cpp:function:: const BigInt& get_a() const++         Return the ``a`` parameter of the elliptic curve equation.++      .. cpp:function:: const BigInt& get_b() const++         Return the ``b`` parameter of the elliptic curve equation.++      .. cpp:function:: const PointGFp& get_base_point() const++         Return the groups base point element.++      .. cpp:function:: const BigInt& get_g_x() const++         Return the x coordinate of the base point element.++      .. cpp:function:: const BigInt& get_g_y() const++         Return the y coordinate of the base point element.++      .. cpp:function:: const BigInt& get_order() const++         Return the order of the group generated by the base point.++      .. cpp:function:: const BigInt& get_cofactor() const++         Return the cofactor of the curve. In most cases this will be 1.++      .. cpp:function:: BigInt mod_order(const BigInt& x) const++         Reduce argument ``x`` modulo the curve order.++      .. cpp:function:: BigInt inverse_mod_order(const BigInt& x) const++         Return inverse of argument ``x`` modulo the curve order.++      .. cpp:function:: BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const++         Multiply ``x`` and ``y`` and reduce the result modulo the curve order.++      .. cpp:function:: bool verify_public_element(const PointGFp& y) const++         Return true if ``y`` seems to be a valid group element.++      .. cpp:function:: const OID& get_curve_oid() const++         Return the OID used to identify the curve. May be empty.++      .. cpp:function:: PointGFp point(const BigInt& x, const BigInt& y) const++         Create and return a point with affine elements ``x`` and ``y``. Note+         this function *does not* verify that ``x`` and ``y`` satisfy the curve+         equation.++      .. cpp:function:: PointGFp point_multiply(const BigInt& x, const PointGFp& pt, const BigInt& y) const++         Multi-exponentiation. Returns base_point*x + pt*y. Not constant time.+         (Ordinarily used for signature verification.)++      .. cpp:function:: PointGFp blinded_base_point_multiply(const BigInt& k, \+                                            RandomNumberGenerator& rng, \+                                            std::vector<BigInt>& ws) const++         Return ``base_point*k`` in a way that attempts to resist side channels.++      .. cpp:function:: BigInt blinded_base_point_multiply_x(const BigInt& k, \+                                           RandomNumberGenerator& rng, \+                                           std::vector<BigInt>& ws) const++         Like `blinded_base_point_multiply` but returns only the x coordinate.++      .. cpp:function:: PointGFp blinded_var_point_multiply(const PointGFp& point, \+                                          const BigInt& k, \+                                          RandomNumberGenerator& rng, \+                                          std::vector<BigInt>& ws) const++         Return ``point*k`` in a way that attempts to resist side channels.++      .. cpp:function:: BigInt random_scalar(RandomNumberGenerator& rng) const++         Return a random scalar (ie an integer between 1 and the group order).++      .. cpp:function:: PointGFp zero_point() const++         Return the zero point (aka the point at infinity).++      .. cpp:function:: PointGFp OS2ECP(const uint8_t bits[], size_t len) const++         Decode a point from the binary encoding. This function verifies that+         the decoded point is a valid element on the curve.++      .. cpp:function:: bool verify_group(RandomNumberGenerator& rng, bool strong = false) const++         Attempt to verify the group seems valid.++      .. cpp:function:: static const std::set<std::string>& known_named_groups()++         Return a list of known groups, ie groups for which ``EC_Group(name)``+         will succeed.++.. cpp:class:: PointGFp++   Stores elliptic curve points in Jacobian representation.++   .. cpp:function:: std::vector<uint8_t> encode(PointGFp::Compression_Type format) const++      Encode a point in a way that can later be decoded with `EC_Group::OS2ECP`.++   .. cpp:function:: PointGFp& operator+=(const PointGFp& rhs)++      Point addition.++   .. cpp:function:: PointGFp& operator-=(const PointGFp& rhs)++      Point subtraction.++   .. cpp:function:: PointGFp& operator*=(const BigInt& scalar)++      Point multiplication using Montgomery ladder.++      .. warning::+         Prefer the blinded functions in ``EC_Group``++   .. cpp:function:: PointGFp& negate()++      Negate this point.++   .. cpp:function:: BigInt get_affine_x() const++      Return the affine ``x`` coordinate of the point.++   .. cpp:function:: BigInt get_affine_y() const++      Return the affine ``y`` coordinate of the point.++   .. cpp:function:: void force_affine()++      Convert the point to its equivalent affine coordinates. Throws+      if this is the point at infinity.++   .. cpp:function:: static void force_all_affine(std::vector<PointGFp>& points, \+                                                  secure_vector<word>& ws)++      Force several points to be affine at once. Uses Montgomery's+      trick to reduce number of inversions required, so this is much+      faster than calling ``force_affine`` on each point in sequence.++   .. cpp:function:: bool is_affine() const++      Return true if this point is in affine coordinates.++   .. cpp:function:: bool is_zero() const++      Return true if this point is zero (aka point at infinity).++   .. cpp:function:: bool on_the_curve() const++      Return true if this point is on the curve.++   .. cpp:function:: void randomize_repr(RandomNumberGenerator& rng)++      Randomize the point representation.++   .. cpp:function:: bool operator==(const PointGFp& other) const++      Point equality. This compares the affine representations.++   .. cpp:function:: void add(const PointGFp& other, std::vector<BigInt>& workspace)++      Point addition, taking a workspace.++   .. cpp:function:: void add_affine(const PointGFp& other, std::vector<BigInt>& workspace)++      Mixed (Jacobian+affine) addition, taking a workspace.++      .. warning::++         This function assumes that ``other`` is affine, if this is+         not correct the result will be invalid.++   .. cpp:function:: void mult2(std::vector<BigInt>& workspace)++      Point doubling.++   .. cpp:function:: void mult2i(size_t i, std::vector<BigInt>& workspace)++      Repeated point doubling.++   .. cpp:function:: PointGFp plus(const PointGFp& other, std::vector<BigInt>& workspace) const++      Point addition, returning the result.++   .. cpp:function:: PointGFp double_of(std::vector<BigInt>& workspace) const++      Point doubling, returning the result.++   .. cpp:function:: PointGFp zero() const++      Return the point at infinity+++

@@ -0,0 +1,20 @@+Environment Variables+======================++Certain environment variables can affect or tune the behavior of the+library. The variables and their behavior are described here.++* ``BOTAN_THREAD_POOL_SIZE`` controls the number of threads which will be+  created for a thread pool used for some purposes within the library. If not+  set then it defaults to the number of CPUs available on the system.++* ``BOTAN_MLOCK_POOL_SIZE`` controls the total amount of memory which will be+  locked in memory using ``mlock`` or ``VirtualLock`` and managed in a memory+  pool. If set to ``0`` (or indeed any value smaller than the system page size),+  then the memory pool is disabled.++* ``BOTAN_FFI_PRINT_EXCEPTIONS`` if this variable is set (to any value), then+  if an exception is caught by the FFI layer, before returning an error code, it+  will print the text message of the exception to stderr. This is primarily+  intended for debugging.+

@@ -0,0 +1,1203 @@++FFI (C Binding)+========================================++.. versionadded:: 1.11.14++Botan's ffi module provides a C89 binding intended to be easily usable with other+language's foreign function interface (FFI) libraries. For instance the included+Python wrapper uses Python's ``ctypes`` module and the C89 API. This API is of+course also useful for programs written directly in C.++Code examples can be found in+`the tests <https://github.com/randombit/botan/blob/master/src/tests/test_ffi.cpp>`_.++Return Codes+---------------++Almost all functions in the Botan C interface return an ``int`` error code.  The+only exceptions are a handful of functions (like+:cpp:func:`botan_ffi_api_version`) which cannot fail in any circumstances.++The FFI functions return a non-negative integer (usually 0) to indicate success,+or a negative integer to represent an error. A few functions (like+:cpp:func:`botan_block_cipher_block_size`) return positive integers instead of+zero on success.++The error codes returned in certain error situations may change over time.  This+especially applies to very generic errors like+:cpp:enumerator:`BOTAN_FFI_ERROR_EXCEPTION_THROWN` and+:cpp:enumerator:`BOTAN_FFI_ERROR_UNKNOWN_ERROR`. For instance, before 2.8, setting+an invalid key length resulted in :cpp:enumerator:`BOTAN_FFI_ERROR_EXCEPTION_THROWN`+but now this is specially handled and returns+:cpp:enumerator:`BOTAN_FFI_ERROR_INVALID_KEY_LENGTH` instead.++The following enum values are defined in the FFI header:++.. cpp:enumerator:: BOTAN_FFI_SUCCESS = 0++   Generally returned to indicate success++.. cpp:enumerator:: BOTAN_FFI_INVALID_VERIFIER = 1++   Note this value is positive, but still represents an error condition.  In+   indicates that the function completed successfully, but the value provided+   was not correct. For example :cpp:func:`botan_bcrypt_is_valid` returns this+   value if the password did not match the hash.++.. cpp:enumerator:: BOTAN_FFI_ERROR_INVALID_INPUT = -1++   The input was invalid. (Currently this error return is not used.)++.. cpp:enumerator:: BOTAN_FFI_ERROR_BAD_MAC = -2++   While decrypting in an AEAD mode, the tag failed to verify.++.. cpp:enumerator:: BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE = -10++   Functions which write a variable amount of space return this if the indicated+   buffer length was insufficient to write the data. In that case, the output+   length parameter is set to the size that is required.++.. cpp:enumerator:: BOTAN_FFI_ERROR_EXCEPTION_THROWN = -20++   An exception was thrown while processing this request, but no further+   details are available.++   .. note::++      If the environment variable ``BOTAN_FFI_PRINT_EXCEPTIONS`` is set to any+      non-empty value, then any exception which is caught by the FFI layer will+      first print the exception message to stderr before returning an+      error. This is sometimes useful for debugging.++.. cpp:enumerator:: BOTAN_FFI_ERROR_OUT_OF_MEMORY = -21++   Memory allocation failed++.. cpp:enumerator:: BOTAN_FFI_ERROR_BAD_FLAG = -30++   A value provided in a `flag` variable was unknown.++.. cpp:enumerator:: BOTAN_FFI_ERROR_NULL_POINTER = -31++   A null pointer was provided as an argument where that is not allowed.++.. cpp:enumerator:: BOTAN_FFI_ERROR_BAD_PARAMETER = -32++   An argument did not match the function.++.. cpp:enumerator:: BOTAN_FFI_ERROR_KEY_NOT_SET = -33++   An object that requires a key normally must be keyed before use (eg before+   encrypting or MACing data). If this is not done, the operation will fail and+   return this error code.++.. cpp:enumerator:: BOTAN_FFI_ERROR_INVALID_KEY_LENGTH = -34++   An invalid key length was provided with a call to ``x_set_key``.++.. cpp:enumerator:: BOTAN_FFI_ERROR_NOT_IMPLEMENTED = -40++   This is returned if the functionality is not available for some reason.  For+   example if you call :cpp:func:`botan_hash_init` with a named hash function+   which is not enabled, this error is returned.++.. cpp:enumerator:: BOTAN_FFI_ERROR_INVALID_OBJECT = -50++   This is used if an object provided did not match the function.  For example+   calling :cpp:func:`botan_hash_destroy` on a ``botan_rng_t`` object will cause+   this return.++.. cpp:enumerator:: BOTAN_FFI_ERROR_UNKNOWN_ERROR = -100++   Something bad happened, but we are not sure why or how.++Versioning+----------------------------------------++.. cpp:function:: uint32_t botan_ffi_api_version()++   Returns the version of the currently supported FFI API.  This is+   expressed in the form YYYYMMDD of the release date of this version+   of the API.++.. cpp:function:: int botan_ffi_supports_api(uint32_t version)++   Returns 0 iff the FFI version specified is supported by this+   library. Otherwise returns -1. The expression+   botan_ffi_supports_api(botan_ffi_api_version()) will always+   evaluate to 0. A particular version of the library may also support+   other (older) versions of the FFI API.++.. cpp:function:: const char* botan_version_string()++   Returns a free-form string describing the version.  The return+   value is a statically allocated string.++.. cpp:function:: uint32_t botan_version_major()++   Returns the major version of the library++.. cpp:function:: uint32_t botan_version_minor()++   Returns the minor version of the library++.. cpp:function:: uint32_t botan_version_patch()++   Returns the patch version of the library++.. cpp:function:: uint32_t botan_version_datestamp()++   Returns the date this version was released as an integer YYYYMMDD,+   or 0 if an unreleased version+++FFI Versions+^^^^^^^^^^^^^++This maps the FFI API version to the first version of the library that+supported it.++============== ===================+FFI Version    Supported Starting+============== ===================+20191214       2.13.0+20180713       2.8.0+20170815       2.3.0+20170327       2.1.0+20150515       2.0.0+============== ===================++Utility Functions+----------------------------------------++.. const char* botan_error_description(int err)++   Return a string representation of the provided error code. If the error code+   is unknown, returns the string "Unknown error". The return values are static+   constant strings and should not be freed.++.. cpp:function:: int botan_same_mem(const uint8_t* x, const uint8_t* y, size_t len)++   Returns 0 if `x[0..len] == y[0..len]`, -1 otherwise.++.. cpp:function:: int botan_hex_encode(const uint8_t* x, size_t len, char* out, uint32_t flags)++   Performs hex encoding of binary data in *x* of size *len* bytes.+   The output buffer *out* must be of at least *x*2* bytes in size.+   If *flags* contains ``BOTAN_FFI_HEX_LOWER_CASE``, hex encoding+   will only contain lower-case letters, upper-case letters otherwise.+   Returns 0 on success, 1 otherwise.++.. cpp:function:: int botan_hex_decode(const char* hex_str, size_t in_len, uint8_t* out, size_t* out_len)++   Hex decode some data++Random Number Generators+----------------------------------------++.. cpp:type:: opaque* botan_rng_t++   An opaque data type for a random number generator. Don't mess with it.++.. cpp:function:: int botan_rng_init(botan_rng_t* rng, const char* rng_type)++   Initialize a random number generator object from the given+   *rng_type*: "system" (or ``nullptr``): ``System_RNG``,+   "user": ``AutoSeeded_RNG``,+   "user-threadsafe": serialized ``AutoSeeded_RNG``,+   "null": ``Null_RNG`` (always fails),+   "hwrnd" or "rdrand": ``Processor_RNG`` (if available)++.. cpp:function:: int botan_rng_get(botan_rng_t rng, uint8_t* out, size_t out_len)++   Get random bytes from a random number generator.++.. cpp:function:: int botan_rng_reseed(botan_rng_t rng, size_t bits)++   Reseeds the random number generator with *bits* number of bits+   from the `System_RNG`.++.. cpp:function:: int botan_rng_reseed_from_rng(botan_rng_t rng, botan_rng_t src, size_t bits)++   Reseeds the random number generator with *bits* number of bits+   taken from the given source RNG.++.. cpp:function:: int botan_rng_add_entropy(botan_rng_t rng, const uint8_t seed[], size_t len)++   Adds the provided seed material to the internal RNG state.++   This call may be ignored by certain RNG instances (such as RDRAND+   or, on some systems, the system RNG).++.. cpp:function:: int botan_rng_destroy(botan_rng_t rng)++   Destroy the object created by :cpp:func:`botan_rng_init`.++Block Ciphers+----------------------------------------++.. versionadded:: 2.1.0++This is a 'raw' interface to ECB mode block ciphers. Most applications+want the higher level cipher API which provides authenticated+encryption. This API exists as an escape hatch for applications which+need to implement custom primitives using a PRP.++.. cpp:type:: opaque* botan_block_cipher_t++   An opaque data type for a block cipher. Don't mess with it.++.. cpp:function:: int botan_block_cipher_init(botan_block_cipher_t* bc, const char* cipher_name)++   Create a new cipher mode object, `cipher_name` should be for example "AES-128" or "Threefish-512"++.. cpp:function:: int botan_block_cipher_block_size(botan_block_cipher_t bc)++   Return the block size of this cipher.++.. cpp:function:: int botan_block_cipher_name(botan_block_cipher_t cipher, \+                                              char* name, size_t* name_len)++   Return the name of this block cipher algorithm, which may nor may not exactly+   match what was passed to :cpp:func:`botan_block_cipher_init`.++.. cpp:function:: int botan_block_cipher_get_keyspec(botan_block_cipher_t cipher, \+                                                     size_t* out_minimum_keylength, \+                                                     size_t* out_maximum_keylength, \+                                                     size_t* out_keylength_modulo)++   Return the limits on the key which can be provided to this cipher. If any of the+   parameters are null, no output is written to that field. This allows retrieving only+   (say) the maximum supported keylength, if that is the only information needed.++.. cpp:function:: int botan_block_cipher_clear(botan_block_cipher_t bc)++   Clear the internal state (such as keys) of this cipher object, but do not deallocate it.++.. cpp:function:: int botan_block_cipher_set_key(botan_block_cipher_t bc, const uint8_t key[], size_t key_len)++   Set the cipher key, which is required before encrypting or decrypting.++.. cpp:function:: int botan_block_cipher_encrypt_blocks(botan_block_cipher_t bc, const uint8_t in[], uint8_t out[], size_t blocks)++   The key must have been set first with :cpp:func:`botan_block_cipher_set_key`.+   Encrypt *blocks* blocks of data stored in *in* and place the ciphertext into *out*.+   The two parameters may be the same buffer, but must not overlap.++.. cpp:function:: int botan_block_cipher_decrypt_blocks(botan_block_cipher_t bc, const uint8_t in[], uint8_t out[], size_t blocks)++   The key must have been set first with :cpp:func:`botan_block_cipher_set_key`.+   Decrypt *blocks* blocks of data stored in *in* and place the ciphertext into *out*.+   The two parameters may be the same buffer, but must not overlap.++.. cpp:function:: int botan_block_cipher_destroy(botan_block_cipher_t rng)++   Destroy the object created by :cpp:func:`botan_block_cipher_init`.+++Hash Functions+----------------------------------------++.. cpp:type:: opaque* botan_hash_t++   An opaque data type for a hash. Don't mess with it.++.. cpp:function:: botan_hash_t botan_hash_init(const char* hash, uint32_t flags)++   Creates a hash of the given name, e.g., "SHA-384".+   Returns null on failure. Flags should always be zero in this version of the API.++.. cpp:function:: int botan_hash_destroy(botan_hash_t hash)++   Destroy the object created by :cpp:func:`botan_hash_init`.++.. cpp:function:: int botan_hash_name(botan_hash_t hash, char* name, size_t* name_len)++   Write the name of the hash function to the provided buffer.++.. cpp:function:: int botan_hash_copy_state(botan_hash_t* dest, const botan_hash_t source)++   Copies the state of the hash object to a new hash object.++.. cpp:function:: int botan_hash_clear(botan_hash_t hash)++   Reset the state of this object back to clean, as if no input has+   been supplied.++.. cpp:function:: size_t botan_hash_output_length(botan_hash_t hash)++   Return the output length of the hash function.++.. cpp:function:: int botan_hash_update(botan_hash_t hash, const uint8_t* input, size_t len)++   Add input to the hash computation.++.. cpp:function:: int botan_hash_final(botan_hash_t hash, uint8_t out[])++   Finalize the hash and place the output in out. Exactly+   :cpp:func:`botan_hash_output_length` bytes will be written.++Message Authentication Codes+----------------------------------------+.. cpp:type:: opaque* botan_mac_t++    An opaque data type for a MAC. Don't mess with it, but do remember+    to set a random key first.++.. cpp:function:: botan_mac_t botan_mac_init(const char* mac, uint32_t flags)++   Creates a MAC of the given name, e.g., "HMAC(SHA-384)".+   Returns null on failure. Flags should always be zero in this version of the API.++.. cpp:function:: int botan_mac_destroy(botan_mac_t mac)++   Destroy the object created by :cpp:func:`botan_mac_init`.++.. cpp:function:: int botan_mac_clear(botan_mac_t mac)++   Reset the state of this object back to clean, as if no key and input have+   been supplied.++.. cpp:function:: size_t botan_mac_output_length(botan_mac_t mac)++   Return the output length of the MAC.++.. cpp:function:: int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len)++   Set the random key.++.. cpp:function:: int botan_mac_update(botan_mac_t mac, uint8_t buf[], size_t len)++   Add input to the MAC computation.++.. cpp:function:: int botan_mac_final(botan_mac_t mac, uint8_t out[], size_t* out_len)++   Finalize the MAC and place the output in out. Exactly+   :cpp:func:`botan_mac_output_length` bytes will be written.++Symmetric Ciphers+----------------------------------------++.. cpp:type:: opaque* botan_cipher_t++    An opaque data type for a symmetric cipher object. Don't mess with it, but do remember+    to set a random key first. And please use an AEAD.++.. cpp:function:: botan_cipher_t botan_cipher_init(const char* cipher_name, uint32_t flags)++    Create a cipher object from a name such as "AES-256/GCM" or "Serpent/OCB".++    Flags is a bitfield; the low bitof ``flags`` specifies if encrypt or decrypt,+    ie use 0 for encryption and 1 for decryption.++.. cpp:function:: int botan_cipher_destroy(botan_cipher_t cipher)++.. cpp:function:: int botan_cipher_clear(botan_cipher_t hash)++.. cpp:function:: int botan_cipher_set_key(botan_cipher_t cipher, \+                  const uint8_t* key, size_t key_len)++.. cpp:function:: int botan_cipher_is_authenticated(botan_cipher_t cipher)++.. cpp:function:: size_t botan_cipher_get_tag_length(botan_cipher_t cipher, size_t* tag_len)++   Write the tag length of the cipher to ``tag_len``. This will be zero for non-authenticated+   ciphers.++.. cpp:function:: int botan_cipher_valid_nonce_length(botan_cipher_t cipher, size_t nl)++   Returns 1 if the nonce length is valid, or 0 otherwise. Returns -1 on error (such as+   the cipher object being invalid).++.. cpp:function:: size_t botan_cipher_get_default_nonce_length(botan_cipher_t cipher, size_t* nl)++   Return the default nonce length++.. cpp:function:: int botan_cipher_set_associated_data(botan_cipher_t cipher, \+                                               const uint8_t* ad, size_t ad_len)++   Set associated data. Will fail unless the cipher is an AEAD.++.. cpp:function:: int botan_cipher_start(botan_cipher_t cipher, \+                                 const uint8_t* nonce, size_t nonce_len)++   Start processing a message using the provided nonce.++.. cpp:function:: int botan_cipher_update(botan_cipher_t cipher, \+                                  uint32_t flags, \+                                  uint8_t output[], \+                                  size_t output_size, \+                                  size_t* output_written, \+                                  const uint8_t input_bytes[], \+                                  size_t input_size, \+                                  size_t* input_consumed)++    Encrypt or decrypt data.++PBKDF+----------------------------------------++.. cpp:function:: int botan_pbkdf(const char* pbkdf_algo, \+                          uint8_t out[], size_t out_len, \+                          const char* passphrase, \+                          const uint8_t salt[], size_t salt_len, \+                          size_t iterations)++   Derive a key from a passphrase for a number of iterations+   using the given PBKDF algorithm, e.g., "PBKDF2".++.. cpp:function:: int botan_pbkdf_timed(const char* pbkdf_algo, \+                                uint8_t out[], size_t out_len, \+                                const char* passphrase, \+                                const uint8_t salt[], size_t salt_len, \+                                size_t milliseconds_to_run, \+                                size_t* out_iterations_used)++   Derive a key from a passphrase using the given PBKDF algorithm,+   e.g., "PBKDF2". If *out_iterations_used* is zero, instead the+   PBKDF is run until *milliseconds_to_run* milliseconds have passed.+   In this case, the number of iterations run will be written to+   *out_iterations_used*.++KDF+----------------------------------------++.. cpp:function:: int botan_kdf(const char* kdf_algo, \+                        uint8_t out[], size_t out_len, \+                        const uint8_t secret[], size_t secret_len, \+                        const uint8_t salt[], size_t salt_len, \+                        const uint8_t label[], size_t label_len)++   Derive a key using the given KDF algorithm, e.g., "SP800-56C".+   The derived key of length *out_len* bytes will be placed in *out*.++Multiple Precision Integers+----------------------------------------++.. versionadded: 2.1.0++.. cpp:type:: opaque* botan_mp_t++   An opaque data type for a multiple precision integer. Don't mess with it.++.. cpp:function:: int botan_mp_init(botan_mp_t* mp)++   Initialize a ``botan_mp_t``. Initial value is zero, use `botan_mp_set_X` to load a value.++.. cpp:function:: int botan_mp_destroy(botan_mp_t mp)++   Free a ``botan_mp_t``++.. cpp:function:: int botan_mp_to_hex(botan_mp_t mp, char* out)++   Writes exactly ``botan_mp_num_bytes(mp)*2 + 1`` bytes to out++.. cpp:function:: int botan_mp_to_str(botan_mp_t mp, uint8_t base, char* out, size_t* out_len)++   Base can be either 10 or 16.++.. cpp:function:: int botan_mp_set_from_int(botan_mp_t mp, int initial_value)++   Set ``botan_mp_t`` from an integer value.++.. cpp:function:: int botan_mp_set_from_mp(botan_mp_t dest, botan_mp_t source)++   Set ``botan_mp_t`` from another MP.++.. cpp:function:: int botan_mp_set_from_str(botan_mp_t dest, const char* str)++   Set ``botan_mp_t`` from a string. Leading prefix of "0x" is accepted.++.. cpp:function:: int botan_mp_num_bits(botan_mp_t n, size_t* bits)++   Return the size of ``n`` in bits.++.. cpp:function:: int botan_mp_num_bytes(botan_mp_t n, size_t* uint8_ts)++   Return the size of ``n`` in bytes.++.. cpp:function:: int botan_mp_to_bin(botan_mp_t mp, uint8_t vec[])++   Writes exactly ``botan_mp_num_bytes(mp)`` to ``vec``.++.. cpp:function:: int botan_mp_from_bin(botan_mp_t mp, const uint8_t vec[], size_t vec_len)++   Loads ``botan_mp_t`` from a binary vector (as produced by ``botan_mp_to_bin``).++.. cpp:function:: int botan_mp_is_negative(botan_mp_t mp)++   Return 1 if ``mp`` is negative, otherwise 0.++.. cpp:function:: int botan_mp_flip_sign(botan_mp_t mp)++   Flip the sign of ``mp``.++.. cpp:function:: int botan_mp_add(botan_mp_t result, botan_mp_t x, botan_mp_t y)++   Add two ``botan_mp_t`` and store the output in ``result``.++.. cpp:function:: int botan_mp_sub(botan_mp_t result, botan_mp_t x, botan_mp_t y)++   Subtract two ``botan_mp_t`` and store the output in ``result``.++.. cpp:function:: int botan_mp_mul(botan_mp_t result, botan_mp_t x, botan_mp_t y)++   Multiply two ``botan_mp_t`` and store the output in ``result``.++.. cpp:function:: int botan_mp_div(botan_mp_t quotient, botan_mp_t remainder, \+                           botan_mp_t x, botan_mp_t y)++   Divide ``x`` by ``y`` and store the output in ``quotient`` and ``remainder``.++.. cpp:function:: int botan_mp_mod_mul(botan_mp_t result, botan_mp_t x, botan_mp_t y, botan_mp_t mod)++   Set ``result`` to ``x`` times ``y`` modulo ``mod``.++.. cpp:function:: int botan_mp_equal(botan_mp_t x, botan_mp_t y)++   Return 1 if ``x`` is equal to ``y``, 0 if ``x`` is not equal to ``y``++.. cpp:function:: int botan_mp_is_zero(const botan_mp_t x)++   Return 1 if ``x`` is equal to zero, otherwise 0.++.. cpp:function:: int botan_mp_is_odd(const botan_mp_t x)++   Return 1 if ``x`` is odd, otherwise 0.++.. cpp:function:: int botan_mp_is_even(const botan_mp_t x)++   Return 1 if ``x`` is even, otherwise 0.++.. cpp:function:: int botan_mp_is_positive(const botan_mp_t x)++   Return 1 if ``x`` is greater than or equal to zero.++.. cpp:function:: int botan_mp_is_negative(const botan_mp_t x)++   Return 1 if ``x`` is less than zero.++.. cpp:function:: int botan_mp_to_uint32(const botan_mp_t x, uint32_t* val)++   If x fits in a 32-bit integer, set val to it and return 0. If x is out of+   range an error is returned.++.. cpp:function:: int botan_mp_cmp(int* result, botan_mp_t x, botan_mp_t y)++   Three way comparison: set result to -1 if ``x`` is less than ``y``,+   0 if ``x`` is equal to ``y``, and 1 if ``x`` is greater than ``y``.++.. cpp:function:: int botan_mp_swap(botan_mp_t x, botan_mp_t y)++   Swap two ``botan_mp_t`` values.++.. cpp:function:: int botan_mp_powmod(botan_mp_t out, botan_mp_t base, botan_mp_t exponent, botan_mp_t modulus)++   Modular exponentiation.++.. cpp:function:: int botan_mp_lshift(botan_mp_t out, botan_mp_t in, size_t shift)++   Left shift by specified bit count, place result in ``out``.++.. cpp:function:: int botan_mp_rshift(botan_mp_t out, botan_mp_t in, size_t shift)++   Right shift by specified bit count, place result in ``out``.++.. cpp:function:: int botan_mp_mod_inverse(botan_mp_t out, botan_mp_t in, botan_mp_t modulus)++   Compute modular inverse. If no modular inverse exists (for instance because ``in`` and+   ``modulus`` are not relatively prime), then sets ``out`` to -1.++.. cpp:function:: int botan_mp_rand_bits(botan_mp_t rand_out, botan_rng_t rng, size_t bits)++   Create a random ``botan_mp_t`` of the specified bit size.++.. cpp:function:: int botan_mp_rand_range(botan_mp_t rand_out, botan_rng_t rng, \+                                  botan_mp_t lower_bound, botan_mp_t upper_bound)++   Create a random ``botan_mp_t`` within the provided range.++.. cpp:function:: int botan_mp_gcd(botan_mp_t out, botan_mp_t x, botan_mp_t y)++   Compute the greatest common divisor of ``x`` and ``y``.++.. cpp:function:: int botan_mp_is_prime(botan_mp_t n, botan_rng_t rng, size_t test_prob)++   Test if ``n`` is prime. The algorithm used (Miller-Rabin) is probabilistic,+   set ``test_prob`` to the desired assurance level. For example if+   ``test_prob`` is 64, then sufficient Miller-Rabin iterations will run to+   assure there is at most a ``1/2**64`` chance that ``n`` is composite.++.. cpp:function:: int botan_mp_get_bit(botan_mp_t n, size_t bit)++   Returns 0 if the specified bit of ``n`` is not set, 1 if it is set.++.. cpp:function:: int botan_mp_set_bit(botan_mp_t n, size_t bit)++   Set the specified bit of ``n``++.. cpp:function:: int botan_mp_clear_bit(botan_mp_t n, size_t bit)++   Clears the specified bit of ``n``+++Password Hashing+----------------------------------------++.. cpp:function:: int botan_bcrypt_generate(uint8_t* out, size_t* out_len, \+                                    const char* password, \+                                    botan_rng_t rng, \+                                    size_t work_factor, \+                                    uint32_t flags)++   Create a password hash using Bcrypt.+   The output buffer *out* should be of length 64 bytes.+   The output is formatted bcrypt $2a$...++.. cpp:function:: int botan_bcrypt_is_valid(const char* pass, const char* hash)++   Check a previously created password hash.  Returns+   :cpp:enumerator:`BOTAN_SUCCESS` if if this password/hash+   combination is valid, :cpp:enumerator:`BOTAN_FFI_INVALID_VERIFIER`+   if the combination is not valid (but otherwise well formed),+   negative on error.++Public Key Creation, Import and Export+----------------------------------------++.. cpp:type:: opaque* botan_privkey_t++   An opaque data type for a private key. Don't mess with it.++.. cpp:function:: int botan_privkey_create(botan_privkey_t* key, \+                                   const char* algo_name, \+                                   const char* algo_params, \+                                   botan_rng_t rng)++.. cpp:function:: int botan_privkey_create_rsa(botan_privkey_t* key, botan_rng_t rng, size_t n_bits)++   Create an RSA key of the given size++.. cpp:function:: int botan_privkey_create_ecdsa(botan_privkey_t* key, botan_rng_t rng, const char* curve)++   Create a ECDSA key of using a named curve++.. cpp:function:: int botan_privkey_create_ecdh(botan_privkey_t* key, botan_rng_t rng, const char* curve)++   Create a ECDH key of using a named curve++.. cpp:function:: int botan_privkey_create_mceliece(botan_privkey_t* key, botan_rng_t rng, size_t n, size_t t)++   Create a McEliece key using the specified parameters. See+   :ref:`mceliece` for details on choosing parameters.++.. cpp:function:: int botan_privkey_create_dh(botan_privkey_t* key, botan_rng_t rng, const char* params)++   Create a finite field Diffie-Hellman key using the specified named group, for example+   "modp/ietf/3072".++.. cpp:function:: int botan_privkey_load(botan_privkey_t* key, botan_rng_t rng, \+                                 const uint8_t bits[], size_t len, \+                                 const char* password)++   Load a private key. If the key is encrypted, ``password`` will be+   used to attempt decryption.++.. cpp:function:: int botan_privkey_destroy(botan_privkey_t key)++   Destroy the object.++.. cpp:function:: int botan_privkey_export(botan_privkey_t key, \+                                   uint8_t out[], size_t* out_len, \+                                   uint32_t flags)++   Export a public key. If flags is 1 then PEM format is used.++.. cpp:function:: int botan_privkey_export_encrypted(botan_privkey_t key, \+                                             uint8_t out[], size_t* out_len, \+                                             botan_rng_t rng, \+                                             const char* passphrase, \+                                             const char* encryption_algo, \+                                             uint32_t flags)++   Deprecated, use ``botan_privkey_export_encrypted_msec`` or ``botan_privkey_export_encrypted_iter``++.. cpp::function:: int botan_privkey_export_encrypted_pbkdf_msec(botan_privkey_t key,+                                                        uint8_t out[], size_t* out_len, \+                                                        botan_rng_t rng, \+                                                        const char* passphrase, \+                                                        uint32_t pbkdf_msec_runtime, \+                                                        size_t* pbkdf_iterations_out, \+                                                        const char* cipher_algo, \+                                                        const char* pbkdf_algo, \+                                                        uint32_t flags);++    Encrypt a key, running the key derivation function for ``pbkdf_msec_runtime`` milliseconds.+    Returns the number of iterations used in ``pbkdf_iterations_out``.++    ``cipher_algo`` must specify a CBC mode cipher (such as "AES-128/CBC") or as+    a Botan-specific extension a GCM mode may be used.++.. cpp::function:: int botan_privkey_export_encrypted_pbkdf_iter(botan_privkey_t key, \+                                                        uint8_t out[], size_t* out_len, \+                                                        botan_rng_t rng, \+                                                        const char* passphrase, \+                                                        size_t pbkdf_iterations, \+                                                        const char* cipher_algo, \+                                                        const char* pbkdf_algo, \+                                                        uint32_t flags);++   Encrypt a private key. The PBKDF function runs for the specified number of iterations.+   At least 100,000 is recommended.++.. cpp:function:: int botan_privkey_export_pubkey(botan_pubkey_t* out, botan_privkey_t in)++.. cpp:function:: int botan_privkey_get_field(botan_mp_t output, \+                                      botan_privkey_t key, \+                                      const char* field_name)++    Read an algorithm specific field from the private key object, placing it into output.+    For example "p" or "q" for RSA keys, or "x" for DSA keys or ECC keys.++.. cpp:type:: opaque* botan_pubkey_t++   An opaque data type for a public key. Don't mess with it.++.. cpp:function:: int botan_pubkey_load(botan_pubkey_t* key, const uint8_t bits[], size_t len)++.. cpp:function:: int botan_pubkey_export(botan_pubkey_t key, uint8_t out[], size_t* out_len, uint32_t flags)++.. cpp:function:: int botan_pubkey_algo_name(botan_pubkey_t key, char out[], size_t* out_len)++.. cpp:function:: int botan_pubkey_estimated_strength(botan_pubkey_t key, size_t* estimate)++.. cpp:function:: int botan_pubkey_fingerprint(botan_pubkey_t key, const char* hash, \+                                       uint8_t out[], size_t* out_len)++.. cpp:function:: int botan_pubkey_destroy(botan_pubkey_t key)++.. cpp:function:: int botan_pubkey_get_field(botan_mp_t output, \+                                     botan_pubkey_t key, \+                                     const char* field_name)++    Read an algorithm specific field from the public key object, placing it into output.+    For example "n" or "e" for RSA keys or "p", "q", "g", and "y" for DSA keys.++RSA specific functions+----------------------------------------++.. cpp:function:: int botan_privkey_rsa_get_p(botan_mp_t p, botan_privkey_t rsa_key)++   Set ``p`` to the first RSA prime.++.. cpp:function:: int botan_privkey_rsa_get_q(botan_mp_t q, botan_privkey_t rsa_key)++   Set ``q`` to the second RSA prime.++.. cpp:function:: int botan_privkey_rsa_get_d(botan_mp_t d, botan_privkey_t rsa_key)++   Set ``d`` to the RSA private exponent.++.. cpp:function:: int botan_privkey_rsa_get_n(botan_mp_t n, botan_privkey_t rsa_key)++   Set ``n`` to the RSA modulus.++.. cpp:function:: int botan_privkey_rsa_get_e(botan_mp_t e, botan_privkey_t rsa_key)++   Set ``e`` to the RSA public exponent.++.. cpp:function:: int botan_pubkey_rsa_get_e(botan_mp_t e, botan_pubkey_t rsa_key)++   Set ``e`` to the RSA public exponent.++.. cpp:function:: int botan_pubkey_rsa_get_n(botan_mp_t n, botan_pubkey_t rsa_key)++   Set ``n`` to the RSA modulus.++.. cpp:function:: int botan_privkey_load_rsa(botan_privkey_t* key, \+                                     botan_mp_t p, botan_mp_t q, botan_mp_t e)++   Initialize a private RSA key using parameters p, q, and e.++.. cpp:function:: int botan_pubkey_load_rsa(botan_pubkey_t* key, \+                                    botan_mp_t n, botan_mp_t e)++   Initialize a public RSA key using parameters n and e.++DSA specific functions+----------------------------------------++.. cpp:function:: int botan_privkey_load_dsa(botan_privkey_t* key, \+                                     botan_mp_t p, botan_mp_t q, botan_mp_t g, botan_mp_t x)++   Initialize a private DSA key using group parameters p, q, and g and private key x.++.. cpp:function:: int botan_pubkey_load_dsa(botan_pubkey_t* key, \+                                     botan_mp_t p, botan_mp_t q, botan_mp_t g, botan_mp_t y)++   Initialize a private DSA key using group parameters p, q, and g and public key y.++ElGamal specific functions+----------------------------------------++.. cpp:function:: int botan_privkey_load_elgamal(botan_privkey_t* key, \+                                     botan_mp_t p, botan_mp_t g, botan_mp_t x)++   Initialize a private ElGamal key using group parameters p and g and private key x.++.. cpp:function:: int botan_pubkey_load_elgamal(botan_pubkey_t* key, \+                                     botan_mp_t p, botan_mp_t g, botan_mp_t y)++   Initialize a public ElGamal key using group parameters p and g and public key y.++Diffie-Hellman specific functions+----------------------------------------++.. cpp:function:: int botan_privkey_load_dh(botan_privkey_t* key, \+                                     botan_mp_t p, botan_mp_t g, botan_mp_t x)++   Initialize a private Diffie-Hellman key using group parameters p and g and private key x.++.. cpp:function:: int botan_pubkey_load_dh(botan_pubkey_t* key, \+                                     botan_mp_t p, botan_mp_t g, botan_mp_t y)++   Initialize a public Diffie-Hellman key using group parameters p and g and public key y.++Public Key Encryption/Decryption+----------------------------------------++.. cpp:type:: opaque* botan_pk_op_encrypt_t++   An opaque data type for an encryption operation. Don't mess with it.++.. cpp:function:: int botan_pk_op_encrypt_create(botan_pk_op_encrypt_t* op, \+                                         botan_pubkey_t key, \+                                         const char* padding, \+                                         uint32_t flags)++   Create a new operation object which can be used to encrypt using the provided+   key and the specified padding scheme (such as "OAEP(SHA-256)" for use with+   RSA). Flags should be 0 in this version.++.. cpp:function:: int botan_pk_op_encrypt_destroy(botan_pk_op_encrypt_t op)++   Destroy the object.++.. cpp:function:: int botan_pk_op_encrypt_output_length(botan_pk_op_encrypt_t op, \+                  size_t ptext_len, size_t* ctext_len)++   Returns an upper bound on the output length if a plaintext of length ``ptext_len``+   is encrypted with this key/parameter setting. This allows correctly sizing the+   buffer that is passed to :cpp:func:`botan_pk_op_encrypt`.++.. cpp:function:: int botan_pk_op_encrypt(botan_pk_op_encrypt_t op, \+                                  botan_rng_t rng, \+                                  uint8_t out[], size_t* out_len, \+                                  const uint8_t plaintext[], size_t plaintext_len)++   Encrypt the provided data using the key, placing the output in `out`.  If+   `out` is NULL, writes the length of what the ciphertext would have been to+   `*out_len`. However this is computationally expensive (the encryption+   actually occurs, then the result is discarded), so it is better to use+   :cpp:func:`botan_pk_op_encrypt_output_length` to correctly size the buffer.++.. cpp:type:: opaque* botan_pk_op_decrypt_t++   An opaque data type for a decryption operation. Don't mess with it.++.. cpp:function:: int botan_pk_op_decrypt_create(botan_pk_op_decrypt_t* op, \+                                         botan_privkey_t key, \+                                         const char* padding, \+                                         uint32_t flags)++.. cpp:function:: int botan_pk_op_decrypt_destroy(botan_pk_op_decrypt_t op)++.. cpp:function:: int botan_pk_op_decrypt_output_length(botan_pk_op_decrypt_t op, \+                  size_t ctext_len, size_t* ptext_len)++   For a given ciphertext length, returns the upper bound on the size of the+   plaintext that might be enclosed. This allows properly sizing the output+   buffer passed to :cpp:func:`botan_pk_op_decrypt`.++.. cpp:function:: int botan_pk_op_decrypt(botan_pk_op_decrypt_t op, \+                                  uint8_t out[], size_t* out_len, \+                                  uint8_t ciphertext[], size_t ciphertext_len)++Signature Generation+----------------------------------------++.. cpp:type:: opaque* botan_pk_op_sign_t++   An opaque data type for a signature generation operation. Don't mess with it.++.. cpp:function:: int botan_pk_op_sign_create(botan_pk_op_sign_t* op, \+                                      botan_privkey_t key, \+                                      const char* hash_and_padding, \+                                      uint32_t flags)++   Create a signature operator for the provided key. The padding string+   specifies what hash function and padding should be used, for example+   "PKCS1v15(SHA-256)" or "EMSA1(SHA-384)".++.. cpp:function:: int botan_pk_op_sign_destroy(botan_pk_op_sign_t op)++   Destroy an object created by :cpp:func:`botan_pk_op_sign_create`.++.. cpp:function:: int botan_pk_op_sign_output_length(botan_pk_op_sign_t op, size_t* sig_len)++   Writes the length of the signatures that this signer will produce. This+   allows properly sizing the buffer passed to+   :cpp:func:`botan_pk_op_sign_finish`.++.. cpp:function:: int botan_pk_op_sign_update(botan_pk_op_sign_t op, \+                                      const uint8_t in[], size_t in_len)++   Add bytes of the message to be signed.++.. cpp:function:: int botan_pk_op_sign_finish(botan_pk_op_sign_t op, botan_rng_t rng, \+                                      uint8_t sig[], size_t* sig_len)++   Produce a signature over all of the bytes passed to :cpp:func:`botan_pk_op_sign_update`.+   Afterwards, the sign operator is reset and may be used to sign a new message.++Signature Verification+----------------------------------------++.. cpp:type:: opaque* botan_pk_op_verify_t++   An opaque data type for a signature verification operation. Don't mess with it.++.. cpp:function:: int botan_pk_op_verify_create(botan_pk_op_verify_t* op, \+                                        botan_pubkey_t key, \+                                        const char* hash_and_padding, \+                                        uint32_t flags)++.. cpp:function:: int botan_pk_op_verify_destroy(botan_pk_op_verify_t op)++.. cpp:function:: int botan_pk_op_verify_update(botan_pk_op_verify_t op, \+                                        const uint8_t in[], size_t in_len)++   Add bytes of the message to be verified++.. cpp:function:: int botan_pk_op_verify_finish(botan_pk_op_verify_t op, \+                                        const uint8_t sig[], size_t sig_len)++   Verify if the signature provided matches with the message provided as calls+   to :cpp:func:`botan_pk_op_verify_update`.++Key Agreement+----------------------------------------++.. cpp:type:: opaque* botan_pk_op_ka_t++   An opaque data type for a key agreement operation. Don't mess with it.++.. cpp:function:: int botan_pk_op_key_agreement_create(botan_pk_op_ka_t* op, \+                                               botan_privkey_t key, \+                                               const char* kdf, \+                                               uint32_t flags)++.. cpp:function:: int botan_pk_op_key_agreement_destroy(botan_pk_op_ka_t op)++.. cpp:function:: int botan_pk_op_key_agreement_export_public(botan_privkey_t key, \+                                                      uint8_t out[], size_t* out_len)++.. cpp:function:: int botan_pk_op_key_agreement(botan_pk_op_ka_t op, \+                                        uint8_t out[], size_t* out_len, \+                                        const uint8_t other_key[], size_t other_key_len, \+                                        const uint8_t salt[], size_t salt_len)++.. cpp:function:: int botan_mceies_encrypt(botan_pubkey_t mce_key, \+                                   botan_rng_t rng, \+                                   const char* aead, \+                                   const uint8_t pt[], size_t pt_len, \+                                   const uint8_t ad[], size_t ad_len, \+                                   uint8_t ct[], size_t* ct_len)++.. cpp:function:: int botan_mceies_decrypt(botan_privkey_t mce_key, \+                                   const char* aead, \+                                   const uint8_t ct[], size_t ct_len, \+                                   const uint8_t ad[], size_t ad_len, \+                                   uint8_t pt[], size_t* pt_len)++X.509 Certificates+----------------------------------------++.. cpp:type:: opaque* botan_x509_cert_t++   An opaque data type for an X.509 certificate. Don't mess with it.++.. cpp:function:: int botan_x509_cert_load(botan_x509_cert_t* cert_obj, \+                                        const uint8_t cert[], size_t cert_len)++   Load a certificate from the DER or PEM representation++.. cpp:function:: int botan_x509_cert_load_file(botan_x509_cert_t* cert_obj, const char* filename)++   Load a certificate from a file.++.. cpp:function:: int botan_x509_cert_dup(botan_x509_cert_t* cert_obj, botan_x509_cert_t cert)++   Create a new object that refers to the same certificate.++.. cpp:function:: int botan_x509_cert_destroy(botan_x509_cert_t cert)++   Destroy the certificate object++.. cpp:function:: int botan_x509_cert_gen_selfsigned(botan_x509_cert_t* cert, \+                                             botan_privkey_t key, \+                                             botan_rng_t rng, \+                                             const char* common_name, \+                                             const char* org_name)++.. cpp:function:: int botan_x509_cert_get_time_starts(botan_x509_cert_t cert, char out[], size_t* out_len)++   Return the time the certificate becomes valid, as a string in form+   "YYYYMMDDHHMMSSZ" where Z is a literal character reflecting that this time is+   relative to UTC. Prefer :cpp:func:`botan_x509_cert_not_before`.++.. cpp:function:: int botan_x509_cert_get_time_expires(botan_x509_cert_t cert, char out[], size_t* out_len)++   Return the time the certificate expires, as a string in form+   "YYYYMMDDHHMMSSZ" where Z is a literal character reflecting that this time is+   relative to UTC. Prefer :cpp:func:`botan_x509_cert_not_after`.++.. cpp:function:: int botan_x509_cert_not_before(botan_x509_cert_t cert, uint64_t* time_since_epoch)++   Return the time the certificate becomes valid, as seconds since epoch.++.. cpp:function:: int botan_x509_cert_not_after(botan_x509_cert_t cert, uint64_t* time_since_epoch)++   Return the time the certificate expires, as seconds since epoch.++.. cpp:function:: int botan_x509_cert_get_fingerprint(botan_x509_cert_t cert, const char* hash, uint8_t out[], size_t* out_len)++.. cpp:function:: int botan_x509_cert_get_serial_number(botan_x509_cert_t cert, uint8_t out[], size_t* out_len)++   Return the serial number of the certificate.++.. cpp:function:: int botan_x509_cert_get_authority_key_id(botan_x509_cert_t cert, uint8_t out[], size_t* out_len)++   Return the authority key ID set in the certificate, which may be empty.++.. cpp:function:: int botan_x509_cert_get_subject_key_id(botan_x509_cert_t cert, uint8_t out[], size_t* out_len)++   Return the subject key ID set in the certificate, which may be empty.++.. cpp:function:: int botan_x509_cert_get_public_key_bits(botan_x509_cert_t cert, \+                                                  uint8_t out[], size_t* out_len)++   Get the serialized representation of the public key included in this certificate++.. cpp:function:: int botan_x509_cert_get_public_key(botan_x509_cert_t cert, botan_pubkey_t* key)++   Get the public key included in this certificate as a newly allocated object++.. cpp:function:: int botan_x509_cert_get_issuer_dn(botan_x509_cert_t cert, \+                                            const char* key, size_t index, \+                                            uint8_t out[], size_t* out_len)++   Get a value from the issuer DN field.++.. cpp:function:: int botan_x509_cert_get_subject_dn(botan_x509_cert_t cert, \+                                             const char* key, size_t index, \+                                             uint8_t out[], size_t* out_len)++   Get a value from the subject DN field.++.. cpp:function:: int botan_x509_cert_to_string(botan_x509_cert_t cert, char out[], size_t* out_len)++   Format the certificate as a free-form string.++.. cpp:enum:: botan_x509_cert_key_constraints++   Certificate key usage constraints. Allowed values: `NO_CONSTRAINTS`,+   `DIGITAL_SIGNATURE`, `NON_REPUDIATION`, `KEY_ENCIPHERMENT`,+   `DATA_ENCIPHERMENT`, `KEY_AGREEMENT`, `KEY_CERT_SIGN`,+   `CRL_SIGN`, `ENCIPHER_ONLY`, `DECIPHER_ONLY`.++.. cpp:function:: int botan_x509_cert_allowed_usage(botan_x509_cert_t cert, unsigned int key_usage)+++.. cpp:function:: int botan_x509_cert_verify(int* validation_result, \+                  botan_x509_cert_t cert, \+                  const botan_x509_cert_t* intermediates, \+                  size_t intermediates_len, \+                  const botan_x509_cert_t* trusted, \+                  size_t trusted_len, \+                  const char* trusted_path, \+                  size_t required_strength, \+                  const char* hostname, \+                  uint64_t reference_time)++    Verify a certificate. Returns 0 if validation was successful, 1 if+    unsuccessful, or negative on error.++    Sets ``validation_result`` to a code that provides more information.++    If not needed, set ``intermediates`` to NULL and ``intermediates_len`` to+    zero.++    If not needed, set ``trusted`` to NULL and ``trusted_len`` to zero.++    The ``trusted_path`` refers to a directory where one or more trusted CA+    certificates are stored. It may be NULL if not needed.++    Set ``required_strength`` to indicate the minimum key and hash strength+    that is allowed. For instance setting to 80 allows 1024-bit RSA and SHA-1.+    Setting to 110 requires 2048-bit RSA and SHA-256 or higher. Set to zero+    to accept a default.++    Set ``reference_time`` to be the time which the certificate chain is+    validated against. Use zero to use the current system clock.++.. cpp:function:: int botan_x509_cert_verify_with_crl(int* validation_result, \+                  botan_x509_cert_t cert, \+                  const botan_x509_cert_t* intermediates, \+                  size_t intermediates_len, \+                  const botan_x509_cert_t* trusted, \+                  size_t trusted_len, \+                  const botan_x509_crl_t* crls, \+                  size_t crls_len, \+                  const char* trusted_path, \+                  size_t required_strength, \+                  const char* hostname, \+                  uint64_t reference_time)++   Certificate path validation supporting Certificate Revocation Lists.++   Works the same as ``botan_x509_cert_cerify``.++   ``crls`` is an array of ``botan_x509_crl_t`` objects, ``crls_len`` is its length.++.. cpp:function:: const char* botan_x509_cert_validation_status(int code)++   Return a (statically allocated) string associated with the verification+   result.++X.509 Certificate Revocation Lists+----------------------------------------++.. cpp:type:: opaque* botan_x509_crl_t++   An opaque data type for an X.509 CRL.++.. cpp:function:: int botan_x509_crl_load(botan_x509_crl_t* crl_obj, \+                                        const uint8_t crl[], size_t crl_len)++   Load a CRL from the DER or PEM representation.++.. cpp:function:: int botan_x509_crl_load_file(botan_x509_crl_t* crl_obj, const char* filename)++   Load a CRL from a file.++.. cpp:function:: int botan_x509_crl_destroy(botan_x509_crl_t crl)++   Destroy the CRL object.++.. cpp:function:: int botan_x509_is_revoked(botan_x509_crl_t crl, botan_x509_cert_t cert)++   Check whether a given ``crl`` contains a given ``cert``.+   Return ``0`` when the certificate is revoked, ``-1`` otherwise.

@@ -0,0 +1,733 @@++Pipe/Filter Message Processing+========================================++.. note::++    The system described below provides a message processing system with a+    straightforward API. However it makes many extra memory copies and+    allocations than would otherwise be required, and also tends to make+    applications using it somewhat opaque because it is not obvious what this or+    that Pipe& object actually does (type of operation, number of messages+    output (if any!), and so on), whereas using say a HashFunction or AEAD_Mode+    provides a much better idea in the code of what operation is occurring.++    This filter interface is no longer used within the library itself+    (outside a few dusty corners) and will likely not see any further major+    development. However it will remain included because the API is often+    convenient and many applications use it.++Many common uses of cryptography involve processing one or more+streams of data. Botan provides services that make setting up data+flows through various operations, such as compression, encryption, and+base64 encoding. Each of these operations is implemented in what are+called *filters* in Botan. A set of filters are created and placed into+a *pipe*, and information "flows" through the pipe until it reaches+the end, where the output is collected for retrieval. If you're+familiar with the Unix shell environment, this design will sound quite+familiar.++Here is an example that uses a pipe to base64 encode some strings::++  Pipe pipe(new Base64_Encoder); // pipe owns the pointer+  pipe.start_msg();+  pipe.write("message 1");+  pipe.end_msg(); // flushes buffers, increments message number++  // process_msg(x) is start_msg() && write(x) && end_msg()+  pipe.process_msg("message2");++  std::string m1 = pipe.read_all_as_string(0); // "message1"+  std::string m2 = pipe.read_all_as_string(1); // "message2"++Byte streams in the pipe are grouped into messages; blocks of data that+are processed in an identical fashion (ie, with the same sequence of+filter operations). Messages are delimited by calls to ``start_msg``+and ``end_msg``. Each message in a pipe has its own identifier, which+currently is an integer that increments up from zero.++The ``Base64_Encoder`` was allocated using ``new``; but where was it+deallocated?  When a filter object is passed to a ``Pipe``, the pipe+takes ownership of the object, and will deallocate it when it is no+longer needed.++There are two different ways to make use of messages. One is to send+several messages through a ``Pipe`` without changing the ``Pipe``+configuration, so you end up with a sequence of messages; one use of+this would be to send a sequence of identically encrypted UDP packets,+for example (note that the *data* need not be identical; it is just+that each is encrypted, encoded, signed, etc in an identical+fashion). Another is to change the filters that are used in the+``Pipe`` between each message, by adding or removing filters;+functions that let you do this are documented in the Pipe API section.++Botan has about 40 filters that perform different operations on data.+Here's code that uses one of them to encrypt a string with AES::++  AutoSeeded_RNG rng,+  SymmetricKey key(rng, 16); // a random 128-bit key+  InitializationVector iv(rng, 16); // a random 128-bit IV++  // The algorithm we want is specified by a string+  Pipe pipe(get_cipher("AES-128/CBC", key, iv, ENCRYPTION));++  pipe.process_msg("secrets");+  pipe.process_msg("more secrets");++  secure_vector<uint8_t> c1 = pipe.read_all(0);++  uint8_t c2[4096] = { 0 };+  size_t got_out = pipe.read(c2, sizeof(c2), 1);+  // use c2[0...got_out]++Note the use of ``AutoSeeded_RNG``, which is a random number+generator. If you want to, you can explicitly set up the random number+generators and entropy sources you want to, however for 99% of cases+``AutoSeeded_RNG`` is preferable.++``Pipe`` also has convenience methods for dealing with ``std::iostream``.+Here is an example of this, using the bzip2 compression filter::++  std::ifstream in("data.bin", std::ios::binary)+  std::ofstream out("data.bin.bz2", std::ios::binary)++  Pipe pipe(new Compression_Filter("bzip2", 9));++  pipe.start_msg();+  in >> pipe;+  pipe.end_msg();+  out << pipe;++However there is a hitch to the code above; the complete contents of+the compressed data will be held in memory until the entire message+has been compressed, at which time the statement ``out << pipe`` is+executed, and the data is freed as it is read from the pipe and+written to the file. But if the file is very large, we might not have+enough physical memory (or even enough virtual memory!) for that to be+practical. So instead of storing the compressed data in the pipe for+reading it out later, we divert it directly to the file::++  std::ifstream in("data.bin", std::ios::binary)+  std::ofstream out("data.bin.bz2", std::ios::binary)++  Pipe pipe(new Compression_Filter("bzip2", 9), new DataSink_Stream(out));++  pipe.start_msg();+  in >> pipe;+  pipe.end_msg();++This is the first code we've seen so far that uses more than one+filter in a pipe. The output of the compressor is sent to the+``DataSink_Stream``. Anything written to a ``DataSink_Stream`` is+written to a file; the filter produces no output. As soon as the+compression algorithm finishes up a block of data, it will send it+along to the sink filter, which will immediately write it to the+stream; if you were to call ``pipe.read_all()`` after+``pipe.end_msg()``, you'd get an empty vector out. This is+particularly useful for cases where you are processing a large amount+of data, as it means you don't have to store everything in memory at+once.++Here's an example using two computational filters::++   AutoSeeded_RNG rng,+   SymmetricKey key(rng, 32);+   InitializationVector iv(rng, 16);++   Pipe encryptor(get_cipher("AES/CBC/PKCS7", key, iv, ENCRYPTION),+                  new Base64_Encoder);++   encryptor.start_msg();+   file >> encryptor;+   encryptor.end_msg(); // flush buffers, complete computations+   std::cout << encryptor;++You can read from a pipe while you are still writing to it, which+allows you to bound the amount of memory that is in use at any one+time. A common idiom for this is::++   pipe.start_msg();+   std::vector<uint8_t> buffer(4096); // arbitrary size+   while(infile.good())+      {+      infile.read((char*)&buffer[0], buffer.size());+      const size_t got_from_infile = infile.gcount();+      pipe.write(buffer, got_from_infile);++      if(infile.eof())+         pipe.end_msg();++      while(pipe.remaining() > 0)+         {+         const size_t buffered = pipe.read(buffer, buffer.size());+         outfile.write((const char*)&buffer[0], buffered);+         }+      }+   if(infile.bad() || (infile.fail() && !infile.eof()))+      throw Some_Exception();++Fork+---------------------------------++It is common that you might receive some data and want to perform more+than one operation on it (ie, encrypt it with Serpent and calculate+the SHA-256 hash of the plaintext at the same time). That's where+``Fork`` comes in. ``Fork`` is a filter that takes input and passes it+on to *one or more* filters that are attached to it. ``Fork`` changes+the nature of the pipe system completely: instead of being a linked+list, it becomes a tree or acyclic graph.++Each filter in the fork is given its own output buffer, and thus its+own message. For example, if you had previously written two messages+into a pipe, then you start a new one with a fork that has three+paths of filter's inside it, you add three new messages to the+pipe. The data you put into the pipe is duplicated and sent+into each set of filter and the eventual output is placed into a+dedicated message slot in the pipe.++Messages in the pipe are allocated in a depth-first manner. This is only+interesting if you are using more than one fork in a single pipe.+As an example, consider the following::++   Pipe pipe(new Fork(+                new Fork(+                   new Base64_Encoder,+                   new Fork(+                      NULL,+                      new Base64_Encoder+                      )+                   ),+                new Hex_Encoder+                )+      );++In this case, message 0 will be the output of the first+``Base64_Encoder``, message 1 will be a copy of the input (see below+for how fork interprets NULL pointers), message 2 will be the output+of the second ``Base64_Encoder``, and message 3 will be the output of+the ``Hex_Encoder``. This results in message numbers being allocated+in a top to bottom fashion, when looked at on the screen. However,+note that there could be potential for bugs if this is not+anticipated. For example, if your code is passed a filter, and you+assume it is a "normal" one that only uses one message, your message+offsets would be wrong, leading to some confusion during output.++If Fork's first argument is a null pointer, but a later argument is+not, then Fork will feed a copy of its input directly through. Here's+a case where that is useful::++   // have std::string ciphertext, auth_code, key, iv, mac_key;++   Pipe pipe(new Base64_Decoder,+             get_cipher("AES-128", key, iv, DECRYPTION),+             new Fork(+                0, // this message gets plaintext+                new MAC_Filter("HMAC(SHA-1)", mac_key)+             )+      );++   pipe.process_msg(ciphertext);+   std::string plaintext = pipe.read_all_as_string(0);+   secure_vector<uint8_t> mac = pipe.read_all(1);++   if(mac != auth_code)+      error();++Here we wanted to not only decrypt the message, but send the decrypted+text through an additional computation, in order to compute the+authentication code.++Any filters that are attached to the pipe after the fork are+implicitly attached onto the first branch created by the fork. For+example, let's say you created this pipe::++  Pipe pipe(new Fork(new Hash_Filter("SHA-256"),+                     new Hash_Filter("SHA-512")),+            new Hex_Encoder);++And then called ``start_msg``, inserted some data, then+``end_msg``. Then ``pipe`` would contain two messages. The first one+(message number 0) would contain the SHA-256 sum of the input in hex+encoded form, and the other would contain the SHA-512 sum of the input+in raw binary. In many situations you'll want to perform a sequence of+operations on multiple branches of the fork; in which case, use+the filter described in :ref:`chain`.++There is also a ``Threaded_Fork`` which acts the same as ``Fork``,+except it runs each of the filters in its own thread.++.. _chain:++Chain+---------------------------------++A ``Chain`` filter creates a chain of filters and encapsulates them+inside a single filter (itself). This allows a sequence of filters to+become a single filter, to be passed into or out of a function, or to+a ``Fork`` constructor.++You can call ``Chain``'s constructor with up to four ``Filter``+pointers (they will be added in order), or with an array of filter+pointers and a ``size_t`` that tells ``Chain`` how many filters are in+the array (again, they will be attached in order). Here's the example+from the last section, using chain instead of relying on the implicit+pass through the other version used::++  Pipe pipe(new Fork(+                new Chain(new Hash_Filter("SHA-256"), new Hex_Encoder),+                new Hash_Filter("SHA-512")+                )+           );++Sources and Sinks+----------------------------------------++Data Sources+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++A ``DataSource`` is a simple abstraction for a thing that stores+bytes. This type is used heavily in the areas of the API related to+ASN.1 encoding/decoding. The following types are ``DataSource``:+``Pipe``, ``SecureQueue``, and a couple of special purpose ones:+``DataSource_Memory`` and ``DataSource_Stream``.++You can create a ``DataSource_Memory`` with an array of bytes and a+length field. The object will make a copy of the data, so you don't+have to worry about keeping that memory allocated. This is mostly for+internal use, but if it comes in handy, feel free to use it.++A ``DataSource_Stream`` is probably more useful than the memory based+one. Its constructors take either a ``std::istream`` or a+``std::string``. If it's a stream, the data source will use the+``istream`` to satisfy read requests (this is particularly useful to+use with ``std::cin``). If the string version is used, it will attempt+to open up a file with that name and read from it.++Data Sinks+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++A ``DataSink`` (in ``data_snk.h``) is a ``Filter`` that takes+arbitrary amounts of input, and produces no output. This means it's+doing something with the data outside the realm of what+``Filter``/``Pipe`` can handle, for example, writing it to a file+(which is what the ``DataSink_Stream`` does). There is no need for+``DataSink``s that write to a ``std::string`` or memory buffer,+because ``Pipe`` can handle that by itself.++Here's a quick example of using a ``DataSink``, which encrypts+``in.txt`` and sends the output to ``out.txt``. There is+no explicit output operation; the writing of ``out.txt`` is+implicit::++   DataSource_Stream in("in.txt");+   Pipe pipe(get_cipher("AES-128/CTR-BE", key, iv),+             new DataSink_Stream("out.txt"));+   pipe.process_msg(in);++A real advantage of this is that even if "in.txt" is large, only as+much memory is needed for internal I/O buffers will be used.++The Pipe API+---------------------------------++Initializing Pipe+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++By default, ``Pipe`` will do nothing at all; any input placed into the+``Pipe`` will be read back unchanged. Obviously, this has limited+utility, and presumably you want to use one or more filters to somehow+process the data. First, you can choose a set of filters to initialize+the ``Pipe`` via the constructor. You can pass it either a set of up+to four filter pointers, or a pre-defined array and a length::++   Pipe pipe1(new Filter1(/*args*/), new Filter2(/*args*/),+              new Filter3(/*args*/), new Filter4(/*args*/));+   Pipe pipe2(new Filter1(/*args*/), new Filter2(/*args*/));++   Filter* filters[5] = {+     new Filter1(/*args*/), new Filter2(/*args*/), new Filter3(/*args*/),+     new Filter4(/*args*/), new Filter5(/*args*/) /* more if desired... */+   };+   Pipe pipe3(filters, 5);++This is by far the most common way to initialize a ``Pipe``. However,+occasionally a more flexible initialization strategy is necessary;+this is supported by 4 member functions. These functions may only be+used while the pipe in question is not in use; that is, either before+calling ``start_msg``, or after ``end_msg`` has been called (and no+new calls to ``start_msg`` have been made yet).++.. cpp:function:: void Pipe::prepend(Filter* filter)++  Calling ``prepend`` will put the passed filter first in the list of+  transformations. For example, if you prepend a filter implementing+  encryption, and the pipe already had a filter that hex encoded the+  input, then the next message processed would be first encrypted,+  and *then* hex encoded.++.. cpp:function:: void Pipe::append(Filter* filter)++  Like ``prepend``, but places the filter at the end of the message+  flow. This doesn't always do what you expect if there is a fork.++.. cpp:function:: void Pipe::pop()++  Removes the first filter in the flow.++.. cpp:function:: void Pipe::reset()++  Removes all the filters that the pipe currently holds - it is reset+  to an empty/no-op state.  Any data that is being retained by the+  pipe is retained after a ``reset``, and ``reset`` does not affect+  message numbers (discussed later).++Giving Data to a Pipe+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Input to a ``Pipe`` is delimited into messages, which can be read from+independently (ie, you can read 5 bytes from one message, and then all of+another message, without either read affecting any other messages).++.. cpp:function:: void Pipe::start_msg()++  Starts a new message; if a message was already running, an exception is+  thrown. After this function returns, you can call ``write``.++.. cpp:function:: void Pipe::write(const uint8_t* input, size_t length)++.. cpp:function:: void Pipe::write(const std::vector<uint8_t>& input)++.. cpp:function:: void Pipe::write(const std::string& input)++.. cpp:function:: void Pipe::write(DataSource& input)++.. cpp:function:: void Pipe::write(uint8_t input)++  All versions of ``write`` write the input into the filter sequence.+  If a message is not currently active, an exception is thrown.++.. cpp:function:: void Pipe::end_msg()++  End the currently active message++Sometimes, you may want to do only a single write per message. In this+case, you can use the ``process_msg`` series of functions, which start+a message, write their argument into the pipe, and then end the+message. In this case you would not make any explicit calls to+``start_msg``/``end_msg``.++Pipes can also be used with the ``>>`` operator, and will accept a+``std::istream``, or on Unix systems with the ``fd_unix`` module, a+Unix file descriptor. In either case, the entire contents of the file+will be read into the pipe.++Getting Output from a Pipe+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Retrieving the processed data from a pipe is a bit more complicated,+for various reasons. The pipe will separate each message into a+separate buffer, and you have to retrieve data from each message+independently. Each of the reader functions has a final parameter that+specifies what message to read from. If this parameter is set to+``Pipe::DEFAULT_MESSAGE``, it will read the current default message+(``DEFAULT_MESSAGE`` is also the default value of this parameter).++Functions in ``Pipe`` related to reading include:++.. cpp:function:: size_t Pipe::read(uint8_t* out, size_t len)++  Reads up to ``len`` bytes into ``out``, and returns the number of+  bytes actually read.++.. cpp:function:: size_t Pipe::peek(uint8_t* out, size_t len)++  Acts exactly like `read`, except the data is not actually read; the+  next read will return the same data.++.. cpp:function:: secure_vector<uint8_t> Pipe::read_all()++  Reads the entire message into a buffer and returns it++.. cpp:function:: std::string Pipe::read_all_as_string()++  Like ``read_all``, but it returns the data as a ``std::string``.+  No encoding is done; if the message contains raw binary, so will+  the string.++.. cpp:function:: size_t Pipe::remaining()++  Returns how many bytes are left in the message++.. cpp:function:: Pipe::message_id Pipe::default_msg()++  Returns the current default message number++.. cpp:function:: Pipe::message_id Pipe::message_count()++  Returns the total number of messages currently in the pipe++.. cpp:function:: Pipe::set_default_msg(Pipe::message_id msgno)++  Sets the default message number (which must be a valid message+  number for that pipe). The ability to set the default message number+  is particularly important in the case of using the file output+  operations (``<<`` with a ``std::ostream`` or Unix file descriptor),+  because there is no way to specify the message explicitly when using+  the output operator.++Pipe I/O for Unix File Descriptors+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++This is a minor feature, but it comes in handy sometimes. In all+installations of the library, Botan's ``Pipe`` object overloads the+``<<`` and ``>>`` operators for C++ iostream objects,+which is usually more than sufficient for doing I/O.++However, there are cases where the iostream hierarchy does not map well to+local 'file types', so there is also the ability to do I/O directly with Unix+file descriptors. This is most useful when you want to read from or write to+something like a TCP or Unix-domain socket, or a pipe, since for simple file+access it's usually easier to just use C++'s file streams.++If ``BOTAN_EXT_PIPE_UNIXFD_IO`` is defined, then you can use the+overloaded I/O operators with Unix file descriptors. For an example of this,+check out the ``hash_fd`` example, included in the Botan distribution.++Filter Catalog+---------------------------------++This section documents most of the useful filters included in the+library.++Keyed Filters+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++A few sections ago, it was mentioned that ``Pipe`` can process+multiple messages, treating each of them the same. Well, that was a+bit of a lie. There are some algorithms (in particular, block ciphers+not in ECB mode, and all stream ciphers) that change their state as+data is put through them.++Naturally, you might well want to reset the keys or (in the case of+block cipher modes) IVs used by such filters, so multiple messages can+be processed using completely different keys, or new IVs, or new keys+and IVs, or whatever.  And in fact, even for a MAC or an ECB block+cipher, you might well want to change the key used from message to+message.++Enter ``Keyed_Filter``, which acts as an abstract interface for any+filter that is uses keys: block cipher modes, stream ciphers, MACs,+and so on. It has two functions, ``set_key`` and ``set_iv``. Calling+``set_key`` will set (or reset) the key used by the algorithm. Setting+the IV only makes sense in certain algorithms -- a call to ``set_iv``+on an object that doesn't support IVs will cause an exception. You+must call ``set_key`` *before* calling ``set_iv``.++Here's a example::++   Keyed_Filter *aes, *hmac;+   Pipe pipe(new Base64_Decoder,+             // Note the assignments to the cast and hmac variables+             aes = get_cipher("AES-128/CBC", aes_key, iv),+             new Fork(+                0, // Read the section 'Fork' to understand this+                new Chain(+                   hmac = new MAC_Filter("HMAC(SHA-1)", mac_key, 12),+                   new Base64_Encoder+                   )+                )+      );+   pipe.start_msg();+   // use pipe for a while, decrypt some stuff, derive new keys and IVs+   pipe.end_msg();++   aes->set_key(aes_key2);+   aes->set_iv(iv2);+   hmac->set_key(mac_key2);++   pipe.start_msg();+   // use pipe for some other things+   pipe.end_msg();++There are some requirements to using ``Keyed_Filter`` that you must+follow. If you call ``set_key`` or ``set_iv`` on a filter that is+owned by a ``Pipe``, you must do so while the ``Pipe`` is+"unlocked". This refers to the times when no messages are being+processed by ``Pipe`` -- either before ``Pipe``'s ``start_msg`` is+called, or after ``end_msg`` is called (and no new call to+``start_msg`` has happened yet). Doing otherwise will result in+undefined behavior, probably silently getting invalid output.++And remember: if you're resetting both values, reset the key *first*.++Cipher Filters+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Getting a hold of a ``Filter`` implementing a cipher is very+easy. Make sure you're including the header ``lookup.h``, and+then call ``get_cipher``. You will pass the return value+directly into a ``Pipe``. There are a couple different functions+which do varying levels of initialization:++.. cpp:function:: Keyed_Filter* get_cipher(std::string cipher_spec, \+   SymmetricKey key, InitializationVector iv, Cipher_Dir dir)++.. cpp:function:: Keyed_Filter* get_cipher(std::string cipher_spec, \+   SymmetricKey key, Cipher_Dir dir)++The version that doesn't take an IV is useful for things that don't+use them, like block ciphers in ECB mode, or most stream ciphers. If+you specify a cipher spec that does want a IV, and you use the version+that doesn't take one, an exception will be thrown. The ``dir``+argument can be either ``ENCRYPTION`` or ``DECRYPTION``.++The cipher_spec is a string that specifies what cipher is to be+used. The general syntax for "cipher_spec" is "STREAM_CIPHER",+"BLOCK_CIPHER/MODE", or "BLOCK_CIPHER/MODE/PADDING". In the case of+stream ciphers, no mode is necessary, so just the name is+sufficient. A block cipher requires a mode of some sort, which can be+"ECB", "CBC", "CFB(n)", "OFB", "CTR-BE", or "EAX(n)". The argument to+CFB mode is how many bits of feedback should be used. If you just use+"CFB" with no argument, it will default to using a feedback equal to+the block size of the cipher. EAX mode also takes an optional bit+argument, which tells EAX how large a tag size to use~--~generally+this is the size of the block size of the cipher, which is the default+if you don't specify any argument.++In the case of the ECB and CBC modes, a padding method can also be+specified. If it is not supplied, ECB defaults to not padding, and CBC+defaults to using PKCS #5/#7 compatible padding. The padding methods+currently available are "NoPadding", "PKCS7", "OneAndZeros", and+"CTS". CTS padding is currently only available for CBC mode, but the+others can also be used in ECB mode.++Some example "cipher_spec arguments are: "AES-128/CBC",+"Blowfish/CTR-BE", "Serpent/XTS", and "AES-256/EAX".++"CTR-BE" refers to counter mode where the counter is incremented as if+it were a big-endian encoded integer. This is compatible with most+other implementations, but it is possible some will use the+incompatible little endian convention. This version would be denoted+as "CTR-LE" if it were supported.++"EAX" is a new cipher mode designed by Wagner, Rogaway, and+Bellare. It is an authenticated cipher mode (that is, no separate+authentication is needed), has provable security, and is free from+patent entanglements. It runs about half as fast as most of the other+cipher modes (like CBC, OFB, or CTR), which is not bad considering you+don't need to use an authentication code.++Hashes and MACs+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Hash functions and MACs don't need anything special when it comes to+filters. Both just take their input and produce no output until+``end_msg`` is called, at which time they complete the hash or MAC and+send that as output.++These filters take a string naming the type to be used. If for some+reason you name something that doesn't exist, an exception will be thrown.++.. cpp:function:: Hash_Filter::Hash_Filter(std::string hash, size_t outlen = 0)++  This constructor creates a filter that hashes its input with+  ``hash``. When ``end_msg`` is called on the owning pipe, the hash is+  completed and the digest is sent on to the next filter in the+  pipeline. The parameter ``outlen`` specifies how many bytes of the+  hash output will be passed along to the next filter when ``end_msg``+  is called. By default, it will pass the entire hash.++  Examples of names for ``Hash_Filter`` are "SHA-1" and "Whirlpool".++.. cpp:function:: MAC_Filter::MAC_Filter(std::string mac, SymmetricKey key, size_t outlen = 0)++  This constructor takes a name for a mac, such as "HMAC(SHA-1)" or+  "CMAC(AES-128)", along with a key to use. The optional ``outlen``+  works the same as in ``Hash_Filter``.++Encoders+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Often you want your data to be in some form of text (for sending over+channels that aren't 8-bit clean, printing it, etc). The filters+``Hex_Encoder`` and ``Base64_Encoder`` will convert arbitrary binary+data into hex or base64 formats. Not surprisingly, you can use+``Hex_Decoder`` and ``Base64_Decoder`` to convert it back into its+original form.++Both of the encoders can take a few options about how the data should+be formatted (all of which have defaults). The first is a ``bool``+which says if the encoder should insert line breaks. This defaults to+false. Line breaks don't matter either way to the decoder, but it+makes the output a bit more appealing to the human eye, and a few+transport mechanisms (notably some email systems) limit the maximum+line length.++The second encoder option is an integer specifying how long such lines+will be (obviously this will be ignored if line-breaking isn't being+used). The default tends to be in the range of 60-80 characters, but+is not specified. If you want a specific value, set it. Otherwise the+default should be fine.++Lastly, ``Hex_Encoder`` takes an argument of type ``Case``, which can+be ``Uppercase`` or ``Lowercase`` (default is ``Uppercase``). This+specifies what case the characters A-F should be output as. The base64+encoder has no such option, because it uses both upper and lower case+letters for its output.++You can find the declarations for these types in ``hex_filt.h`` and+``b64_filt.h``.++Writing New Filters+---------------------------------++The system of filters and pipes was designed in an attempt to make it+as simple as possible to write new filter types. There are four+functions that need to be implemented by a class deriving from+``Filter``:++.. cpp:function:: std::string Filter::name() const++  This should just return a useful decription of the filter object.++.. cpp:function:: void Filter::write(const uint8_t* input, size_t length)++  This function is what is called when a filter receives input for it+  to process. The filter is not required to process the data right+  away; many filters buffer their input before producing any output. A+  filter will usually have ``write`` called many times during its+  lifetime.++.. cpp:function:: void Filter::send(uint8_t* output, size_t length)++  Eventually, a filter will want to produce some output to send along+  to the next filter in the pipeline. It does so by calling ``send``+  with whatever it wants to send along to the next filter. There is+  also a version of ``send`` taking a single byte argument, as a+  convenience.++  .. note::++     Normally a filter does not need to override ``send``, though it+     can for special handling. It does however need to call this+     function whenever it wants to produce output.++.. cpp:function:: void Filter::start_msg()++  Implementing this function is optional. Implement it if your filter+  would like to do some processing or setup at the start of each+  message, such as allocating a data structure.++.. cpp:function:: void Filter::end_msg()++  Implementing this function is optional. It is called when it has+  been requested that filters finish up their computations. The filter+  should finish up with whatever computation it is working on (for+  example, a compressing filter would flush the compressor and+  ``send`` the final block), and empty any buffers in preparation for+  processing a fresh new set of input.++Additionally, if necessary, filters can define a constructor that+takes any needed arguments, and a destructor to deal with deallocating+memory, closing files, etc.+

@@ -0,0 +1,98 @@+Format Preserving Encryption+========================================++Format preserving encryption (FPE) refers to a set of techniques for+encrypting data such that the ciphertext has the same format as the+plaintext. For instance, you can use FPE to encrypt credit card+numbers with valid checksums such that the ciphertext is also an+credit card number with a valid checksum, or similarly for bank+account numbers, US Social Security numbers, or even more general+mappings like English words onto other English words.++The scheme currently implemented in botan is called FE1, and described+in the paper `Format Preserving Encryption+<https://eprint.iacr.org/2009/251>`_ by Mihir Bellare, Thomas+Ristenpart, Phillip Rogaway, and Till Stegers. FPE is an area of+ongoing standardization and it is likely that other schemes will be+included in the future.++To encrypt an arbitrary value using FE1, you need to use a ranking+method. Basically, the idea is to assign an integer to every value you+might encrypt. For instance, a 16 digit credit card number consists of+a 15 digit code plus a 1 digit checksum. So to encrypt a credit card+number, you first remove the checksum, encrypt the 15 digit value+modulo 10\ :sup:`15`, and then calculate what the checksum is for the+new (ciphertext) number. Or, if you were encrypting words in a+dictionary, you could rank the words by their lexicographical order,+and choose the modulus to be the number of words in the dictionary.++The interfaces for FE1 are defined in the header ``fpe_fe1.h``:++.. versionadded:: 2.5.0++.. cpp:class:: FPE_FE1++   .. cpp:function:: FPE_FE1(const BigInt& n, size_t rounds = 5, \+                             bool compat_mode = false,           \+                             std::string mac_algo = "HMAC(SHA-256)")++      Initialize an FPE operation to encrypt/decrypt integers less+      than *n*. It is expected that *n* is trivially factorable into+      small integers. Common usage would be n to be a power of 10.++      Note that the default parameters to this constructor are+      **incompatible** with the ``fe1_encrypt`` and ``fe1_decrypt``+      function originally added in 1.9.17. For compatibility, use+      3 rounds and set ``compat_mode`` to true.++   .. cpp:function:: BigInt encrypt(const BigInt& x, const uint8_t tweak[], size_t tweak_len) const++      Encrypts the value *x* modulo the value *n* using the *key* and *tweak*+      specified. Returns an integer less than *n*. The *tweak* is a value that+      does not need to be secret that parameterizes the encryption function. For+      instance, if you were encrypting a database column with a single key, you+      could use a per-row-unique integer index value as the tweak. The same+      tweak value must be used during decryption.++   .. cpp:function:: BigInt decrypt(const BigInt& x, const uint8_t tweak[], size_t tweak_len) const++      Decrypts an FE1 ciphertext. The *tweak* must be the same as that provided+      to the encryption function. Returns the plaintext integer.++      Note that there is not any implicit authentication or checking of data in+      FE1, so if you provide an incorrect key or tweak the result is simply a+      random integer.++   .. cpp:function:: BigInt encrypt(const BigInt& x, uint64_t tweak)++      Convenience version of encrypt taking an integer tweak.++   .. cpp:function:: BigInt decrypt(const BigInt& x, uint64_t tweak)++      Convenience version of decrypt taking an integer tweak.++There are two functions that handle the entire FE1 encrypt/decrypt operation.+These are the original interface to FE1, first added in 1.9.17. However because+they do the entire setup cost for each operation, they are significantly slower+than the class-based API presented above.++.. warning:: These functions are hardcoded to use 3 rounds, which may be+             insufficient depending on the chosen modulus.++.. cpp:function:: BigInt FPE::fe1_encrypt(const BigInt& n, const BigInt& X, \+             const SymmetricKey& key, const std::vector<uint8_t>& tweak)++    This creates an FPE_FE1 object, sets the key, and encrypts *X* using+    the provided tweak.++.. cpp:function:: BigInt FPE::fe1_decrypt(const BigInt& n, const BigInt& X, \+             const SymmetricKey& key, const std::vector<uint8_t>& tweak)++    This creates an FPE_FE1 object, sets the key, and decrypts *X* using+    the provided tweak.++This example encrypts a credit card number with a valid `Luhn checksum+<https://en.wikipedia.org/wiki/Luhn_algorithm>`_ to another number with the same+format, including a correct checksum.++.. literalinclude:: ../../src/cli/cc_enc.cpp

@@ -0,0 +1,348 @@+Hash Functions and Checksums+=============================++Hash functions are one-way functions, which map data of arbitrary size to a+fixed output length. Most of the hash functions in Botan are designed to be+cryptographically secure, which means that it is computationally infeasible to+create a collision (finding two inputs with the same hash) or preimages (given a+hash output, generating an arbitrary input with the same hash). But note that+not all such hash functions meet their goals, in particular MD4 and MD5 are+trivially broken. However they are still included due to their wide adoption in+various protocols.++The class :cpp:class:`HashFunction` is defined in `botan/hash.h`.++Using a hash function is typically split into three stages: initialization,+update, and finalization (often referred to as a IUF interface). The+initialization stage is implicit: after creating a hash function object, it is+ready to process data. Then update is called one or more times. Calling update+several times is equivalent to calling it once with all of the arguments+concatenated. After completing a hash computation (eg using ``final``), the+internal state is reset to begin hashing a new message.++.. cpp:class:: HashFunction++  .. cpp:function:: static std::unique_ptr<HashFunction> create(const std::string& name)++    Return a newly allocated hash function object, or nullptr if the+    name is not recognized.++  .. cpp:function:: static std::unique_ptr<HashFunction> create_or_throw(const std::string& name)++    Like ``create`` except that it will throw an exception instead of+    returning nullptr.++  .. cpp:function:: size_t output_length()++    Return the size (in *bytes*) of the output of this function.++  .. cpp:function:: void update(const uint8_t* input, size_t length)++    Updates the computation with *input*.++  .. cpp:function:: void update(uint8_t input)++    Updates the computation with *input*.++  .. cpp:function:: void update(const std::vector<uint8_t>& input)++    Updates the computation with *input*.++  .. cpp:function:: void update(const std::string& input)++    Updates the computation with *input*.++  .. cpp:function:: void final(uint8_t* out)++    Finalize the calculation and place the result into ``out``.+    For the argument taking an array, exactly ``output_length`` bytes will+    be written. After you call ``final``, the algorithm is reset to+    its initial state, so it may be reused immediately.++  .. cpp:function:: secure_vector<uint8_t> final()++    Similar to the other function of the same name, except it returns+    the result in a newly allocated vector.++  .. cpp:function:: secure_vector<uint8_t> process(const uint8_t in[], size_t length)++     Equivalent to calling ``update`` followed by ``final``.++  .. cpp:function:: secure_vector<uint8_t> process(const std::string& in)++     Equivalent to calling ``update`` followed by ``final``.++Code Example+------------++Assume we want to calculate the SHA-256, SHA-384, and SHA-3 hash digests of the STDIN stream using the Botan library.++.. code-block:: cpp++    #include <botan/hash.h>+    #include <botan/hex.h>+    #include <iostream>+    int main ()+       {+       std::unique_ptr<Botan::HashFunction> hash1(Botan::HashFunction::create("SHA-256"));+       std::unique_ptr<Botan::HashFunction> hash2(Botan::HashFunction::create("SHA-384"));+       std::unique_ptr<Botan::HashFunction> hash3(Botan::HashFunction::create("SHA-3"));+       std::vector<uint8_t> buf(2048);++       while(std::cin.good())+          {+          //read STDIN to buffer+          std::cin.read(reinterpret_cast<char*>(buf.data()), buf.size());+          size_t readcount = std::cin.gcount();+          //update hash computations with read data+          hash1->update(buf.data(),readcount);+          hash2->update(buf.data(),readcount);+          hash3->update(buf.data(),readcount);+          }+       std::cout << "SHA-256: " << Botan::hex_encode(hash1->final()) << std::endl;+       std::cout << "SHA-384: " << Botan::hex_encode(hash2->final()) << std::endl;+       std::cout << "SHA-3: " << Botan::hex_encode(hash3->final()) << std::endl;+       return 0;+       }++Available Hash Functions+------------------------------++The following cryptographic hash functions are implemented. If in doubt,+any of SHA-384, SHA-3, or BLAKE2b are fine choices.++BLAKE2b+^^^^^^^^^++Available if ``BOTAN_HAS_BLAKE2B`` is defined.++A recently designed hash function. Very fast on 64-bit processors. Can output a+hash of any length between 1 and 64 bytes, this is specified by passing a value+to the constructor with the desired length.++Named like "Blake2b" which selects default 512-bit output, or as+"Blake2b(256)" to select 256 bits of output.++GOST-34.11+^^^^^^^^^^^^^^^++.. deprecated:: 2.11++Available if ``BOTAN_HAS_GOST_34_11`` is defined.++Russian national standard hash. It is old, slow, and has some weaknesses. Avoid+it unless you must.++.. warning::+   As this hash function is no longer approved by the latest Russian standards,+   support for GOST 34.11 hash is deprecated and will be removed in a future+   major release.++Keccak-1600+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_KECCAK`` is defined.++An older (and incompatible) variant of SHA-3, but sometimes used. Prefer SHA-3 in+new code.++MD4+^^^^^^^^^++Available if ``BOTAN_HAS_MD4`` is defined.++An old hash function that is now known to be trivially breakable. It is very+fast, and may still be suitable as a (non-cryptographic) checksum.++MD5+^^^^^^^^^++Available if ``BOTAN_HAS_MD5`` is defined.++Widely used, now known to be broken.++RIPEMD-160+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_RIPEMD160`` is defined.++A 160 bit hash function, quite old but still thought to be secure (up to the+limit of 2**80 computation required for a collision which is possible with any+160 bit hash function). Somewhat deprecated these days.++SHA-1+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SHA1`` is defined.++Widely adopted NSA designed hash function. Starting to show significant signs of+weakness, and collisions can now be generated. Avoid in new designs.++SHA-256+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SHA2_32`` is defined.++Relatively fast 256 bit hash function, thought to be secure.++Also includes the variant SHA-224. There is no real reason to use SHA-224.++SHA-512+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SHA2_64`` is defined.++SHA-512 is faster than SHA-256 on 64-bit processors. Also includes the+truncated variants SHA-384 and SHA-512/256, which have the advantage+of avoiding message extension attacks.++SHA-3+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SHA3`` is defined.++The new NIST standard hash. Fairly slow.++Supports 224, 256, 384 or 512 bit outputs. SHA-3 is faster with+smaller outputs.  Use as "SHA-3(256)" or "SHA-3(512)". Plain "SHA-3"+selects default 512 bit output.++SHAKE (SHAKE-128, SHAKE-256)+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SHAKE`` is defined.++These are actually XOFs (extensible output functions) based on SHA-3, which can+output a value of any byte length. For example "SHAKE-128(1024)" will produce+1024 bits of output. The specified length must be a multiple of 8. Not+specifying an output length, "SHAKE-128" defaults to a 128-bit output and+"SHAKE-256" defaults to a 256-bit output.++.. warning::+    In the case of SHAKE-128, the default output length in insufficient+    to ensure security. The choice of default lengths was a bug which is+    currently retained for compatability; they should have been 256 and+    512 bits resp to match SHAKE's security level. Using the default+    lengths with SHAKE is deprecated and will be removed in a future major+    release. Instead, always specify the desired output length.++SM3+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SM3`` is defined.++Chinese national hash function, 256 bit output. Widely used in industry there.+Fast and seemingly secure, but no reason to prefer it over SHA-2 or SHA-3 unless+required.++Skein-512+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_SKEIN_512`` is defined.++A contender for the NIST SHA-3 competition. Very fast on 64-bit systems.  Can+output a hash of any length between 1 and 64 bytes. It also accepts an optional+"personalization string" which can create variants of the hash. This is useful+for domain separation.++To set a personalization string set the second param to any value,+typically ASCII strings are used. Examples "Skein-512(256)" or+"Skein-512(384,personalization_string)".++Streebog (Streebog-256, Streebog-512)+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_STREEBOG`` is defined.++Newly designed Russian national hash function. Due to use of input-dependent+table lookups, it is vulnerable to side channels. There is no reason to use it+unless compatibility is needed.++.. warning::+   The Streebog Sbox has recently been revealed to have a hidden structure which+   interacts with its linear layer in a way which may provide a backdoor when+   used in certain ways. Avoid Streebog if at all possible.++Tiger+^^^^^^^^^^^^^^^++.. deprecated:: 2.15++Available if ``BOTAN_HAS_TIGER`` is defined.++An older 192-bit hash function, optimized for 64-bit systems. Possibly+vulnerable to side channels due to its use of table lookups.++Tiger supports variable length output (16, 20 or 24 bytes) and+variable rounds (which must be at least 3). Default is 24 byte output+and 3 rounds. Specify with names like "Tiger" or "Tiger(20,5)".++.. warning::+  There are documented (albeit impractical) attacks on the full Tiger+  hash leading to preimage attacks. This indicates possibility of a+  serious weakness in the hash and for this reason it is deprecated+  and will be removed in a future major release of the library.++Whirlpool+^^^^^^^^^^^^^^^++Available if ``BOTAN_HAS_WHIRLPOOL`` is defined.++A 512-bit hash function standardized by ISO and NESSIE. Relatively slow, and due+to the table based implementation it is potentially vulnerable to cache based+side channels.++Hash Function Combiners+---------------------------++These are functions which combine multiple hash functions to create a new hash+function. They are typically only used in specialized applications.++Parallel+^^^^^^^^^^^^^++Available if ``BOTAN_HAS_PARALLEL_HASH`` is defined.++Parallel simply concatenates multiple hash functions. For example+"Parallel(SHA-256,SHA-512)" outputs a 256+512 bit hash created by hashing the+input with both SHA-256 and SHA-512 and concatenating the outputs.++Note that due to the "multicollision attack" it turns out that generating a+collision for multiple parallel hash functions is no harder than generating a+collision for the strongest hash function.++Comp4P+^^^^^^^^^^^^^++Available if ``BOTAN_HAS_COMB4P`` is defined.++This combines two cryptographic hashes in such a way that preimage and collision+attacks are provably at least as hard as a preimage or collision attack on the+strongest hash.++Checksums+----------------++.. note:: Checksums are not suitable for cryptographic use, but can be used for+          error checking purposes.++Adler32+^^^^^^^^^^^++Available if ``BOTAN_HAS_ADLER32`` is defined.++The Adler32 checksum is used in the zlib format. 32 bit output.++CRC24+^^^^^^^^^^^++Available if ``BOTAN_HAS_CRC24`` is defined.++This is the CRC function used in OpenPGP. 24 bit output.++CRC32+^^^^^^^^^^^++Available if ``BOTAN_HAS_CRC32`` is defined.++This is the 32-bit CRC used in protocols such as Ethernet, gzip, PNG, etc.

@@ -0,0 +1,106 @@++.. _key_derivation_function:++Key Derivation Functions+========================================++Key derivation functions are used to turn some amount of shared secret+material into uniform random keys suitable for use with symmetric+algorithms. An example of an input which is useful for a KDF is a+shared secret created using Diffie-Hellman key agreement.++.. cpp:class:: KDF++  .. cpp:function:: secure_vector<uint8_t> derive_key( \+     size_t key_len, const std::vector<uint8_t>& secret, \+     const std::string& salt = "") const++  .. cpp:function:: secure_vector<uint8_t> derive_key( \+     size_t key_len, const std::vector<uint8_t>& secret, \+     const std::vector<uint8_t>& salt) const++  .. cpp:function:: secure_vector<uint8_t> derive_key( \+     size_t key_len, const std::vector<uint8_t>& secret, \+     const uint8_t* salt, size_t salt_len) const++  .. cpp:function:: secure_vector<uint8_t> derive_key( \+     size_t key_len, const uint8_t* secret, size_t secret_len, \+     const std::string& salt) const++   All variations on the same theme. Deterministically creates a+   uniform random value from *secret* and *salt*. Typically *salt* is+   a label or identifier, such as a session id.++You can create a :cpp:class:`KDF` using++.. cpp:function:: KDF* get_kdf(const std::string& algo_spec)+++Available KDFs+-------------------++Botan includes many different KDFs simply because different protocols and+standards have created subtly different approaches to this problem. For new+code, use HKDF which is conservative, well studied, widely implemented and NIST+approved.++HKDF+~~~~~++Defined in RFC 5869, HKDF uses HMAC to process inputs. Also available+are variants HKDF-Extract and HKDF-Expand. HKDF is the combined+Extract+Expand operation. Use the combined HKDF unless you need+compatibility with some other system.++Available if ``BOTAN_HAS_HKDF`` is defined.++KDF2+~~~~~++KDF2 comes from IEEE 1363. It uses a hash function.++Available if ``BOTAN_HAS_KDF2`` is defined.++KDF1-18033+~~~~~~~~~~~~++KDF1 from ISO 18033-2. Very similar to (but incompatible with) KDF2.++Available if ``BOTAN_HAS_KDF1_18033`` is defined.++KDF1+~~~~~~++KDF1 from IEEE 1363. It can only produce an output at most the length+of the hash function used.++Available if ``BOTAN_HAS_KDF1`` is defined.++X9.42 PRF+~~~~~~~~~~++A KDF from ANSI X9.42. Sometimes used for Diffie-Hellman.++Available if ``BOTAN_HAS_X942_PRF`` is defined.++SP800-108+~~~~~~~~~~++KDFs from NIST SP 800-108. Variants include "SP800-108-Counter",+"SP800-108-Feedback" and "SP800-108-Pipeline".++Available if ``BOTAN_HAS_SP800_108`` is defined.++SP800-56A+~~~~~~~~~~++KDF from NIST SP 800-56A.++Available if ``BOTAN_HAS_SP800_56A`` is defined.++SP800-56C+~~~~~~~~~~++KDF from NIST SP 800-56C.++Available if ``BOTAN_HAS_SP800_56C`` is defined.

@@ -0,0 +1,60 @@+AES Key Wrapping+=================================++NIST specifies two mechanisms for wrapping (encrypting) symmetric keys using+another key. The first (and older, more widely supported) method requires the+input be a multiple of 8 bytes long. The other allows any length input, though+only up to 2**32 bytes.++These algorithms are described in NIST SP 800-38F, and RFCs 3394 and 5649.++This API, defined in ``nist_keywrap.h``, first became available in version 2.4.0++These functions take an arbitrary 128-bit block cipher object, which must+already have been keyed with the key encryption key. NIST only allows these+functions with AES, but any 128-bit cipher will do and some other implementations+(such as in OpenSSL) do also allow other ciphers.  Use AES for best interop.++.. cpp:function:: std::vector<uint8_t> nist_key_wrap(const uint8_t input[], \+                  size_t input_len, const BlockCipher& bc)++   This performs KW (key wrap) mode. The input must be a multiple of 8 bytes long.++.. cpp:function:: secure_vector<uint8_t> nist_key_unwrap(const uint8_t input[], \+                  size_t input_len,  const BlockCipher& bc)++   This unwraps the result of nist_key_wrap, or throw Invalid_Authentication_Tag on error.++.. cpp:function:: std::vector<uint8_t> nist_key_wrap_padded(const uint8_t input[], \+                  size_t input_len, const BlockCipher& bc)++   This performs KWP (key wrap with padding) mode. The input can be any length.++.. cpp:function:: secure_vector<uint8_t> nist_key_unwrap_padded(const uint8_t input[], \+                  size_t input_len, const BlockCipher& bc)++   This unwraps the result of nist_key_wrap_padded, or throws Invalid_Authentication_Tag+   on error.++RFC 3394 Interface+-----------------------------++This is an older interface that was first available (with slight changes) in+1.10, and available in its current form since 2.0 release. It uses a 128-bit,+192-bit, or 256-bit key to encrypt an input key. AES is always used. The input+must be a multiple of 8 bytes; if not an exception is thrown.++This interface is defined in ``rfc3394.h``.++.. cpp:function:: secure_vector<uint8_t> rfc3394_keywrap(const secure_vector<uint8_t>& key, \+                                                         const SymmetricKey& kek)++  Wrap the input key using kek (the key encryption key), and return the result. It will+  be 8 bytes longer than the input key.++.. cpp:function:: secure_vector<uint8_t> rfc3394_keyunwrap(const secure_vector<uint8_t>& key, \+                                                           const SymmetricKey& kek)++  Unwrap a key wrapped with rfc3394_keywrap.++

@@ -0,0 +1,268 @@++.. _mac:++Message Authentication Codes (MAC)+===================================++A Message Authentication Code algorithm computes a tag over a message utilizing+a shared secret key. Thus a valid tag confirms the authenticity and integrity of+the message. Only entities in possession of the shared secret key are able to+verify the tag.++.. note::++    When combining a MAC with unauthenticated encryption mode, prefer to first+    encrypt the message and then MAC the ciphertext. The alternative is to MAC+    the plaintext, which depending on exact usage can suffer serious security+    issues. For a detailed discussion of this issue see the paper "The Order of+    Encryption and Authentication for Protecting Communications" by Hugo+    Krawczyk++The Botan MAC computation is split into five stages.++#. Instantiate the MAC algorithm.+#. Set the secret key.+#. Process IV.+#. Process data.+#. Finalize the MAC computation.++.. cpp:class:: MessageAuthenticationCode++  .. cpp:function:: std::string name() const++     Returns a human-readable string of the name of this algorithm.++  .. cpp:function:: void clear()++     Clear the key.++  .. cpp:function:: MessageAuthenticationCode* clone() const++     Return a newly allocated object of the same type as this one.++  .. cpp:function:: void set_key(const uint8_t* key, size_t length)++    Set the shared MAC key for the calculation. This function has to be called before the data is processed.++  .. cpp:function:: bool valid_keylength(size_t length) const++     This function returns true if and only if *length* is a valid+     keylength for the algorithm.++  .. cpp:function:: size_t minimum_keylength() const++     Return the smallest key length (in bytes) that is acceptable for the+     algorithm.++  .. cpp:function:: size_t maximum_keylength() const++     Return the largest key length (in bytes) that is acceptable for the+     algorithm.++  .. cpp:function:: void start(const uint8_t* nonce, size_t nonce_len)++    Set the IV for the MAC calculation. Note that not all MAC algorithms require an IV.+    If an IV is required, the function has to be called before the data is processed.+    For algorithms that don't require it, the call can be omitted, or else called+    with ``nonce_len`` of zero.++  .. cpp:function:: void update(const uint8_t* input, size_t length)++     Process the passed data.++  .. cpp:function:: void update(const secure_vector<uint8_t>& in)++    Process the passed data.++  .. cpp:function:: void update(uint8_t in)++    Process a single byte.++  .. cpp:function:: void final(uint8_t* out)++    Complete the MAC computation and write the calculated tag to the passed byte array.++  .. cpp:function:: secure_vector<uint8_t> final()++    Complete the MAC computation and return the calculated tag.++  .. cpp:function:: bool verify_mac(const uint8_t* mac, size_t length)++    Finalize the current MAC computation and compare the result to the passed+    ``mac``. Returns ``true``, if the verification is successful and false+    otherwise.+++Code Examples+------------------------++The following example computes an HMAC with a random key then verifies the tag.++    #include <botan/mac.h>+    #include <botan/hex.h>+    #include <botan/system_rng.h>+    #include <assert.h>++    std::string compute_mac(const std::string& msg, const Botan::secure_vector<uint8_t>& key)+       {+       auto hmac = Botan::MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");++       hmac->set_key(key);+       hmac->update(msg);++       return Botan::hex_encode(hmac->final());+       }++    int main()+       {+       Botan::System_RNG rng;++       const auto key = rng.random_vec(32); // 256 bit random key++       // "Message" != "Mussage" so tags will also not match+       std::string tag1 = compute_mac("Message", key);+       std::string tag2 = compute_mac("Mussage", key);+       assert(tag1 != tag2);++       // Recomputing with original input message results in identical tag+       std::string tag3 = compute_mac("Message", key);+       assert(tag1 == tag3);+       }+++The following example code computes a AES-256 GMAC and subsequently verifies the+tag.  Unlike most other MACs, GMAC requires a nonce *which must not repeat or+all security is lost*.++.. code-block:: cpp++    #include <botan/mac.h>+    #include <botan/hex.h>+    #include <iostream>++    int main()+       {+       const std::vector<uint8_t> key = Botan::hex_decode("1337133713371337133713371337133713371337133713371337133713371337");+       const std::vector<uint8_t> nonce = Botan::hex_decode("FFFFFFFFFFFFFFFFFFFFFFFF");+       const std::vector<uint8_t> data = Botan::hex_decode("6BC1BEE22E409F96E93D7E117393172A");+       std::unique_ptr<Botan::MessageAuthenticationCode> mac(Botan::MessageAuthenticationCode::create("GMAC(AES-256)"));+       if(!mac)+          return 1;+       mac->set_key(key);+       mac->start(nonce);+       mac->update(data);+       Botan::secure_vector<uint8_t> tag = mac->final();+       std::cout << mac->name() << ": " << Botan::hex_encode(tag) << std::endl;++       //Verify created MAC+       mac->start(nonce);+       mac->update(data);+       std::cout << "Verification: " << (mac->verify_mac(tag) ? "success" : "failure");+       return 0;+       }++The following example code computes a valid AES-128 CMAC tag and modifies the+data to demonstrate a MAC verification failure.++.. code-block:: cpp++  #include <botan/mac.h>+  #include <botan/hex.h>+  #include <iostream>++    int main()+       {+       const std::vector<uint8_t> key = Botan::hex_decode("2B7E151628AED2A6ABF7158809CF4F3C");+       std::vector<uint8_t> data = Botan::hex_decode("6BC1BEE22E409F96E93D7E117393172A");+       std::unique_ptr<Botan::MessageAuthenticationCode> mac(Botan::MessageAuthenticationCode::create("CMAC(AES-128)"));+       if(!mac)+          return 1;+       mac->set_key(key);+       mac->update(data);+       Botan::secure_vector<uint8_t> tag = mac->final();+       //Corrupting data+       data.back()++;+       //Verify with corrupted data+       mac->update(data);+       std::cout << "Verification with malformed data: " << (mac->verify_mac(tag) ? "success" : "failure");+       return 0;+       }++Available MACs+------------------------------------------++Currently the following MAC algorithms are available in Botan. In new code,+default to HMAC with a strong hash like SHA-256 or SHA-384.++CBC-MAC+~~~~~~~~~~~~++An older authentication code based on a block cipher. Serious security problems,+in particular **insecure** if messages of several different lengths are+authenticated. Avoid unless required for compatibility.++Available if ``BOTAN_HAS_CBC_MAC`` is defined.++.. warning::+   CBC-MAC support is deprecated and will be removed in a future major release.++CMAC+~~~~~~~~~~~~++A modern CBC-MAC variant that avoids the security problems of plain CBC-MAC.+Approved by NIST. Also sometimes called OMAC.++Available if ``BOTAN_HAS_CMAC`` is defined.++GMAC+~~~~~~~~~~~~++GMAC is related to the GCM authenticated cipher mode. It is quite slow unless+hardware support for carryless multiplications is available. A new nonce+must be used with **each** message authenticated, or otherwise all security is+lost.++Available if ``BOTAN_HAS_GMAC`` is defined.++.. warning::+   Due to the nonce requirement, GMAC is exceptionally fragile. Avoid it unless+   absolutely required.++HMAC+~~~~~~~~~~~~++A message authentication code based on a hash function. Very commonly used.++Available if ``BOTAN_HAS_HMAC`` is defined.++Poly1305+~~~~~~~~~~~~++A polynomial mac (similar to GMAC). Very fast, but tricky to use safely. Forms+part of the ChaCha20Poly1305 AEAD mode. A new key must be used for **each**+message, or all security is lost.++Available if ``BOTAN_HAS_POLY1305`` is defined.++.. warning::+   Due to the nonce requirement, Poly1305 is exceptionally fragile. Avoid it unless+   absolutely required.++SipHash+~~~~~~~~~~~~++A modern and very fast PRF. Produces only a 64-bit output. Defaults to+"SipHash(2,4)" which is the recommended configuration, using 2 rounds for each+input block and 4 rounds for finalization.++Available if ``BOTAN_HAS_SIPHASH`` is defined.++X9.19-MAC+~~~~~~~~~~~~++A CBC-MAC variant sometimes used in finance. Always uses DES.+Sometimes called the "DES retail MAC", also standardized in ISO 9797-1.++It is slow and has known attacks. Avoid unless required.++Available if ``BOTAN_HAS_X919_MAC`` is defined.

@@ -0,0 +1,98 @@+One Time Passwords+========================++.. versionadded:: 2.2.0++One time password schemes are a user authentication method that relies on a+fixed secret key which is used to derive a sequence of short passwords, each of+which is accepted only once. Commonly this is used to implement two-factor+authentication (2FA), where the user authenticates using both a conventional+password (or a public key signature) and an OTP generated by a small device such+as a mobile phone.++Botan implements the HOTP and TOTP schemes from RFC 4226 and 6238.++Since the range of possible OTPs is quite small, applications must rate limit+OTP authentication attempts to some small number per second. Otherwise an attacker+could quickly try all 1000000 6-digit OTPs in a brief amount of time.++HOTP+^^^^^^++HOTP generates OTPs that are a short numeric sequence, between 6 and 8 digits+(most applications use 6 digits), created using the HMAC of a 64-bit counter+value. If the counter ever repeats the OTP will also repeat, thus both parties+must assure the counter only increments and is never repeated or+decremented. Thus both client and server must keep track of the next counter+expected.++Anyone with access to the client-specific secret key can authenticate as that+client, so it should be treated with the same security consideration as would be+given to any other symmetric key or plaintext password.++.. cpp:class:: HOTP++    Implement counter-based OTP++    .. cpp:function:: HOTP(const SymmetricKey& key, const std::string& hash_algo = "SHA-1", size_t digits = 6)++       Initialize an HOTP instance with a secret key (specific to each client),+       a hash algorithm (must be SHA-1, SHA-256, or SHA-512), and the number of+       digits with each OTP (must be 6, 7, or 8).++       In RFC 4226, HOTP is only defined with SHA-1, but many HOTP+       implementations support SHA-256 as an extension. The collision attacks+       on SHA-1 do not have any known effect on HOTP's security.++    .. cpp:function:: uint32_t generate_hotp(uint64_t counter)++       Return the OTP associated with a specific counter value.++    .. cpp:function:: std::pair<bool,uint64_t> verify_hotp(uint32_t otp, \+                      uint64_t starting_counter, size_t resync_range = 0)++       Check if a provided OTP matches the one that should be generated for+       the specified counter.++       The *starting_counter* should be the counter of the last successful+       authentication plus 1. If *resync_resync* is greater than 0, some number+       of counter values above *starting_counter* will also be checked if+       necessary. This is useful for instance when a client mistypes an OTP on+       entry; the authentication will fail so the server will not update its+       counter, but the client device will subsequently show the OTP for the+       next counter. Depending on the environment a *resync_range* of 3 to 10+       might be appropriate.++       Returns a pair of (is_valid,next_counter_to_use). If the OTP is invalid+       then always returns (false,starting_counter), since the last successful+       authentication counter has not changed.+++TOTP+^^^^^^^^^^++TOTP is based on the same algorithm as HOTP, but instead of a counter a+timestamp is used.++.. cpp:class:: TOTP++   .. cpp:function:: TOTP(const SymmetricKey& key, const std::string& hash_algo = "SHA-1", \+                          size_t digits = 6, size_t time_step = 30)++      Setup to perform TOTP authentication using secret key *key*.++   .. cpp:function:: uint32_t generate_totp(std::chrono::system_clock::time_point time_point)++   .. cpp:function:: uint32_t generate_totp(uint64_t unix_time)++      Generate and return a TOTP code based on a timestamp.++   .. cpp:function:: bool verify_totp(uint32_t otp, std::chrono::system_clock::time_point time, \+                                      size_t clock_drift_accepted = 0)++   .. cpp:function:: bool verify_totp(uint32_t otp, uint64_t unix_time, \+                                      size_t clock_drift_accepted = 0)++      Return true if the provided OTP code is correct for the provided+      timestamp. If required, use *clock_drift_accepted* to deal with+      the client and server having slightly different clocks.

@@ -0,0 +1,219 @@+Password Hashing+========================================++Storing passwords for user authentication purposes in plaintext is the+simplest but least secure method; when an attacker compromises the+database in which the passwords are stored, they immediately gain+access to all of them. Often passwords are reused among multiple+services or machines, meaning once a password to a single service is+known an attacker has a substantial head start on attacking other+machines.++The general approach is to store, instead of the password, the output+of a one way function of the password. Upon receiving an+authentication request, the authenticating party can recompute the one way+function and compare the value just computed with the one that was+stored. If they match, then the authentication request succeeds. But+when an attacker gains access to the database, they only have the+output of the one way function, not the original password.++Common hash functions such as SHA-256 are one way, but used alone they+have problems for this purpose. What an attacker can do, upon gaining+access to such a stored password database, is hash common dictionary+words and other possible passwords, storing them in a list. Then he+can search through his list; if a stored hash and an entry in his list+match, then he has found the password. Even worse, this can happen+*offline*: an attacker can begin hashing common passwords days,+months, or years before ever gaining access to the database. In+addition, if two users choose the same password, the one way function+output will be the same for both of them, which will be visible upon+inspection of the database.++There are two solutions to these problems: salting and+iteration. Salting refers to including, along with the password, a+randomly chosen value which perturbs the one way function. Salting can+reduce the effectiveness of offline dictionary generation, because for+each potential password, an attacker would have to compute the one way+function output for all possible salts. It also prevents the same+password from producing the same output, as long as the salts do not+collide. Choosing n-bit salts randomly, salt collisions become likely+only after about 2\ :sup:\ `(n/2)` salts have been generated. Choosing a+large salt (say 80 to 128 bits) ensures this is very unlikely. Note+that in password hashing salt collisions are unfortunate, but not+fatal - it simply allows the attacker to attack those two passwords in+parallel easier than they would otherwise be able to.++The other approach, iteration, refers to the general technique of+forcing multiple one way function evaluations when computing the+output, to slow down the operation. For instance if hashing a single+password requires running SHA-256 100,000 times instead of just once,+that will slow down user authentication by a factor of 100,000, but+user authentication happens quite rarely, and usually there are more+expensive operations that need to occur anyway (network and database+I/O, etc). On the other hand, an attacker who is attempting to break a+database full of stolen password hashes will be seriously+inconvenienced by a factor of 100,000 slowdown; they will be able to+only test at a rate of .0001% of what they would without iterations+(or, equivalently, will require 100,000 times as many zombie botnet+hosts).++Memory usage while checking a password is also a consideration; if the+computation requires using a certain minimum amount of memory, then an+attacker can become memory-bound, which may in particular make+customized cracking hardware more expensive. Some password hashing+designs, such as scrypt, explicitly attempt to provide this. The+bcrypt approach requires over 4 KiB of RAM (for the Blowfish key+schedule) and may also make some hardware attacks more expensive.++Botan provides three techniques for password hashing: Argon2, bcrypt, and+passhash9 (based on PBKDF2).++Argon2+----------------------------------------++.. versionadded:: 2.11.0++Argon2 is the winner of the PHC (Password Hashing Competition) and provides+a tunable memory hard password hash. It has a standard string encoding, which looks like::++  "$argon2i$v=19$m=8192,t=10,p=3$YWFhYWFhYWE$itkWB9ODqTd85wUsoib7pfpVTNGMOu0ZJan1odl25V8"++Argon2 has three tunable parameters: ``M``, ``p``, and ``t``. ``M`` gives the+total memory consumption of the algorithm in kilobytes. Increasing ``p``+increases the available parallelism of the computation. The ``t`` parameter+gives the number of passes which are made over the data.++.. note::+   Currently Botan does not make use of ``p`` > 1, so it is best to set it to 1+   to minimize any advantage to highly parallel cracking attempts.++There are three variants of Argon2, namely Argon2d, Argon2i and Argon2id.+Argon2d uses data dependent table lookups with may leak information about the+password via side channel attacks, and is **not recommended** for password+hashing. Argon2i uses data independent table lookups and is immune to these+attacks, but at the cost of requiring higher ``t`` for security. Argon2id uses a+hybrid approach which is thought to be highly secure. The algorithm designers+recommend using Argon2id with ``t`` and ``p`` both equal to 1 and ``M`` set to+the largest amount of memory usable in your environment.++.. cpp:function:: std::string argon2_generate_pwhash(const char* password, size_t password_len, \+                          RandomNumberGenerator& rng, \+                          size_t p, size_t M, size_t t, \+                          size_t y = 2, size_t salt_len = 16, size_t output_len = 32)++   Generate an Argon2 hash of the specified password. The ``y`` parameter specifies+   the variant: 0 for Argon2d, 1 for Argon2i, and 2 for Argon2id.++.. cpp:function:: bool argon2_check_pwhash(const char* password, size_t password_len, \+                                           const std::string& hash)++   Verify an Argon2 password hash against the provided password. Returns false if+   the input hash seems malformed or if the computed hash does not match.++Bcrypt+----------------------------------------++`Bcrypt <https://www.usenix.org/legacy/event/usenix99/provos/provos.pdf>`_ is a+password hashing scheme originally designed for use in OpenBSD, but numerous+other implementations exist. It is made available by including ``bcrypt.h``.++It has the advantage that it requires a small amount (4K) of fast RAM+to compute, which can make hardware password cracking somewhat more+expensive.++Bcrypt provides outputs that look like this::++  "$2a$12$7KIYdyv8Bp32WAvc.7YvI.wvRlyVn0HP/EhPmmOyMQA4YKxINO0p2"++.. note::++   Due to the design of bcrypt, the password is effectively truncated at 72+   characters; further characters are ignored and do not change the hash. To+   support longer passwords, one common approach is to pre-hash the password+   with SHA-256, then run bcrypt using the hex or base64 encoding of the hash as+   the password. (Many bcrypt implementations truncate the password at the first+   NULL character, so hashing the raw binary SHA-256 may cause problems. Botan's+   bcrypt implementation will hash whatever values are given in the+   ``std::string`` including any embedded NULLs so this is not an issue, but+   might cause interop problems if another library needs to validate the+   password hashes.)++.. cpp:function:: std::string generate_bcrypt(const std::string& password, \+                    RandomNumberGenerator& rng, \+                    uint16_t work_factor = 12, \+                    char bcrypt_version = "a")++   Takes the password to hash, a rng, and a work factor.+   The resulting password hash is returned as a string.++   Higher work factors increase the amount of time the algorithm runs,+   increasing the cost of cracking attempts. The increase is exponential, so a+   work factor of 12 takes roughly twice as long as work factor 11. The default+   work factor was set to 10 up until the 2.8.0 release.++   It is recommended to set the work factor as high as your system can tolerate+   (from a performance and latency perspective) since higher work factors greatly+   improve the security against GPU-based attacks.  For example, for protecting+   high value administrator passwords, consider using work factor 15 or 16; at+   these work factors each bcrypt computation takes several seconds. Since admin+   logins will be relatively uncommon, it might be acceptable for each login+   attempt to take some time. As of 2018, a good password cracking rig (with 8+   NVIDIA 1080 cards) can attempt about 1 billion bcrypt computations per month+   for work factor 13. For work factor 12, it can do twice as many.  For work+   factor 15, it can do only one quarter as many attempts.++   Due to bugs affecting various implementations of bcrypt, several different+   variants of the algorithm are defined. As of 2.7.0 Botan supports generating+   (or checking) the 2a, 2b, and 2y variants.  Since Botan has never been+   affected by any of the bugs which necessitated these version upgrades, all+   three versions are identical beyond the version identifier. Which variant to+   use is controlled by the ``bcrypt_version`` argument.++   The bcrypt work factor must be at least 4 (though at this work factor bcrypt+   is not very secure). The bcrypt format allows up to 31, but Botan currently+   rejects all work factors greater than 18 since even that work factor requires+   roughly 15 seconds of computation on a fast machine.++.. cpp:function:: bool check_bcrypt(const std::string& password, \+   const std::string& hash)++   Takes a password and a bcrypt output and returns true if the+   password is the same as the one that was used to generate the+   bcrypt hash.++.. _passhash9:++Passhash9+----------------------------------------++Botan also provides a password hashing technique called passhash9, in+``passhash9.h``, which is based on PBKDF2.++Passhash9 hashes look like::++  "$9$AAAKxwMGNPSdPkOKJS07Xutm3+1Cr3ytmbnkjO6LjHzCMcMQXvcT"++This function should be secure with the proper parameters, and will remain in+the library for the foreseeable future, but it is specific to Botan rather than+being a widely used password hash. Prefer bcrypt or Argon2.++.. warning::++   This password format string ("$9$") conflicts with the format used+   for scrypt password hashes on Cisco systems.++.. cpp:function:: std::string generate_passhash9(const std::string& password, \+   RandomNumberGenerator& rng, uint16_t work_factor = 15, uint8_t alg_id = 4)++   Functions much like ``generate_bcrypt``. The last parameter,+   ``alg_id``, specifies which PRF to use. Currently defined values are+   0: HMAC(SHA-1), 1: HMAC(SHA-256), 2: CMAC(Blowfish), 3: HMAC(SHA-384), 4: HMAC(SHA-512)++   The work factor must be greater than zero and less than 512. This performs+   10000 * ``work_factor`` PBKDF2 iterations, using 96 bits of salt taken from+   ``rng``. Using work factor of 10 or more is recommended.++.. cpp:function:: bool check_passhash9(const std::string& password, \+   const std::string& hash)++   Functions much like ``check_bcrypt``

@@ -0,0 +1,190 @@++.. _pbkdf:++Password Based Key Derivation+========================================++Often one needs to convert a human readable password into a cryptographic+key. It is useful to slow down the computation of these computations in order to+reduce the speed of brute force search, thus they are parameterized in some+way which allows their required computation to be tuned.++PBKDF+---------++:cpp:class:`PBKDF` is the older API for this functionality, presented in header+``pbkdf.h``. It does not support Scrypt, nor will it be able to support other+future hashes (such as Argon2) that may be added in the future. In addition,+this API requires the passphrase be entered as a ``std::string``, which means+the secret will be stored in memory that will not be zeroed.++.. cpp:class:: PBKDF++   .. cpp:function:: void pbkdf_iterations(uint8_t out[], size_t out_len, \+                            const std::string& passphrase, \+                            const uint8_t salt[], size_t salt_len, \+                            size_t iterations) const++      Run the PBKDF algorithm for the specified number of iterations,+      with the given salt, and write output to the buffer.++   .. cpp:function:: void pbkdf_timed(uint8_t out[], size_t out_len, \+                         const std::string& passphrase, \+                         const uint8_t salt[], size_t salt_len, \+                         std::chrono::milliseconds msec, \+                         size_t& iterations) const++      Choose (via short run-time benchmark) how many iterations to perform+      in order to run for roughly msec milliseconds. Writes the number+      of iterations used to reference argument.++   .. cpp:function:: OctetString derive_key( \+               size_t output_len, const std::string& passphrase, \+               const uint8_t* salt, size_t salt_len, \+               size_t iterations) const++   Computes a key from *passphrase* and the *salt* (of length+   *salt_len* bytes) using an algorithm-specific interpretation of+   *iterations*, producing a key of length *output_len*.++   Use an iteration count of at least 10000. The salt should be+   randomly chosen by a good random number generator (see+   :ref:`random_number_generators` for how), or at the very least+   unique to this usage of the passphrase.++   If you call this function again with the same parameters, you will+   get the same key.++PasswordHash+--------------++.. versionadded:: 2.8.0++This API has two classes, one representing the algorithm (such as+"PBKDF2(SHA-256)", or "Scrypt") and the other representing a specific instance+of the problem which is fully specified (say "Scrypt" with N=8192,r=64,p=8).++.. cpp:class:: PasswordHash++   .. cpp:function:: void derive_key(uint8_t out[], size_t out_len, \+                     const char* password, const size_t password_len, \+                     const uint8_t salt[], size_t salt_len) const++      Derive a key, placing it into output++   .. cpp:function:: std::string to_string() const++      Return a descriptive string including the parameters (iteration count, etc)++The ``PasswordHashFamily`` creates specific instances of ``PasswordHash``:++.. cpp:class:: PasswordHashFamily++   .. cpp:function:: static std::unique_ptr<PasswordHashFamily> create(const std::string& what)++      For example "PBKDF2(SHA-256)", "Scrypt", "OpenPGP-S2K(SHA-384)". Returns+      null if not available.++   .. cpp:function:: std::unique_ptr<PasswordHash> default_params() const++      Create a default instance of the password hashing algorithm. Be warned the+      value returned here may change from release to release.++   .. cpp:function:: std::unique_ptr<PasswordHash> tune(size_t output_len, std::chrono::milliseconds msec) const++      Return a password hash instance tuned to run for approximately ``msec``+      milliseconds when producing an output of length ``output_len``. (Accuracy+      may vary, use the command line utility ``botan pbkdf_tune`` to check.)++   .. cpp:function:: std::unique_ptr<PasswordHash> from_params( \+         size_t i1, size_t i2 = 0, size_t i3 = 0) const+         +      Create a password hash using some scheme specific format.+      Eg PBKDF2 and PGP-S2K set iterations in i1+      Scrypt uses N,r,p in i{1-3}+      Bcrypt-PBKDF just has iterations+      Argon2{i,d,id} would use iterations, memory, parallelism for i{1-3}, and Argon2 type is part of the family.+      +      Values not needed should be set to 0.++Available Schemes+----------------------++PBKDF2+^^^^^^^^^^^^++PBKDF2 is the "standard" password derivation scheme, widely implemented in many+different libraries. It uses HMAC internally.++Scrypt+^^^^^^^^^^++Scrypt is a relatively newer design which is "memory hard" - in+addition to requiring large amounts of CPU power it uses a large block+of memory to compute the hash. This makes brute force attacks using+ASICs substantially more expensive.++Scrypt is not supported through :cpp:class:`PBKDF`, only :cpp:class:`PasswordHash`,+starting in 2.8.0. In addition, starting in version 2.7.0, scrypt is available+with this function:++.. cpp:function:: void scrypt(uint8_t output[], size_t output_len, \+                              const std::string& password, \+                              const uint8_t salt[], size_t salt_len, \+                              size_t N, size_t r, size_t p)++   Computes the Scrypt using the password and salt, and produces an output+   of arbitrary length.++   The N, r, p parameters control how much work and memory Scrypt+   uses.  N is the primary control of the workfactor, and must be a+   power of 2. For interactive logins use 32768, for protection of+   secret keys or backups use 1048576.++   The r parameter controls how 'wide' the internal hashing operation+   is. It also increases the amount of memory that is used. Values+   from 1 to 8 are reasonable.++   Setting p parameter to greater than one splits up the work in a way+   that up to p processors can work in parallel.++   As a general recommendation, use N=32768, r=8, p=1++Argon2+^^^^^^^^^^++.. versionadded:: 2.11.0++Argon2 is the winner of the PHC (Password Hashing Competition) and+provides a tunable memory hard PBKDF.++OpenPGP S2K+^^^^^^^^^^^^++.. warning::++   The OpenPGP algorithm is weak and strange, and should be avoided unless+   implementing OpenPGP.++There are some oddities about OpenPGP's S2K algorithms that are documented+here. For one thing, it uses the iteration count in a strange manner; instead of+specifying how many times to iterate the hash, it tells how many *bytes* should+be hashed in total (including the salt). So the exact iteration count will+depend on the size of the salt (which is fixed at 8 bytes by the OpenPGP+standard, though the implementation will allow any salt size) and the size of+the passphrase.++To get what OpenPGP calls "Simple S2K", set iterations to 0, and do not specify+a salt. To get "Salted S2K", again leave the iteration count at 0, but give an+8-byte salt. "Salted and Iterated S2K" requires an 8-byte salt and some+iteration count (this should be significantly larger than the size of the+longest passphrase that might reasonably be used; somewhere from 1024 to 65536+would probably be about right). Using both a reasonably sized salt and a large+iteration count is highly recommended to prevent password guessing attempts.++PBKDF1+^^^^^^^^^^^^++PBKDF1 is an old scheme that can only produce an output length at most+as long as the hash function. It is deprecated and will be removed in+a future release. It is not supported through :cpp:class:`PasswordHash`.

@@ -0,0 +1,1419 @@+.. _pkcs11:++PKCS#11+========================================++.. versionadded:: 1.11.31++|++PKCS#11 is a platform-independent interface for accessing smart cards and+hardware security modules (HSM). Vendors of PKCS#11 compatible devices usually+provide a so called middleware or "PKCS#11 module" which implements the PKCS#11+standard. This middleware translates calls from the platform-independent PKCS#11+API to device specific calls. So application developers don't have to write smart card+or HSM specific code for each device they want to support.++   .. note::++     The Botan PKCS#11 interface is implemented against version v2.40 of the standard.++Botan wraps the C PKCS#11 API to provide a C++ PKCS#11 interface. This is done+in two levels of abstraction: a low level API (see :ref:`pkcs11_low_level`) and+a high level API (see :ref:`pkcs11_high_level`). The low level API provides+access to all functions that are specified by the standard. The high level API+represents an object oriented approach to use PKCS#11 compatible devices but+only provides a subset of the functions described in the standard.++To use the PKCS#11 implementation the ``pkcs11`` module has to be enabled.++   .. note::++      Both PKCS#11 APIs live in the namespace ``Botan::PKCS11``++.. _pkcs11_low_level:++Low Level API+----------------------------------------++The PKCS#11 standards committee provides header files (``pkcs11.h``, ``pkcs11f.h`` and+``pkcs11t.h``) which define the PKCS#11 API in the C programming language. These+header files could be used directly to access PKCS#11 compatible smart cards or+HSMs. The external header files are shipped with Botan in version v2.4 of the standard. The PKCS#11 low+level API wraps the original PKCS#11 API, but still allows to access all functions described in the+standard and has the advantage that it is a C++ interface with features like RAII, exceptions+and automatic memory management.++The low level API is implemented by the :cpp:class:`LowLevel` class and can be accessed by+including the header ``botan/p11.h``.++Preface+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++All constants that belong together in the PKCS#11 standard are grouped into C+++enum classes. For example the different user types are grouped in the+:cpp:enum:`UserType` enumeration:++.. cpp:enum-class:: UserType : CK_USER_TYPE++   .. cpp:enumerator:: UserType::SO = CKU_SO+   .. cpp:enumerator:: UserType::User = CKU_USER+   .. cpp:enumerator:: UserType::ContextSpecific = CKU_CONTEXT_SPECIFIC++Additionally, all types that are used by the low or high level API are mapped by+type aliases to more C++ like names. For instance:++.. cpp:type:: FunctionListPtr = CK_FUNCTION_LIST_PTR++.. rubric:: C-API Wrapping++There is at least one method in the :cpp:class:`LowLevel` class that corresponds to a PKCS#11+function. For example the :cpp:func:`C_GetSlotList` method in the :cpp:class:`LowLevel` class is defined as follows:++.. cpp:class:: LowLevel++   .. cpp:function:: bool C_GetSlotList(Bbool token_present, SlotId* slot_list_ptr, Ulong* count_ptr, ReturnValue* return_value = ThrowException) const++The :cpp:class:`LowLevel` class calls the PKCS#11 function from the function list of the PKCS#11 module:++   .. code-block:: c++      CK_DEFINE_FUNCTION(CK_RV, C_GetSlotList)( CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList,+                                                CK_ULONG_PTR pulCount )++Where it makes sense there is also an overload of the :cpp:class:`LowLevel` method to make usage easier and safer:++   .. cpp:function:: bool C_GetSlotList( bool token_present, std::vector<SlotId>& slot_ids, ReturnValue* return_value = ThrowException ) const++With this overload the user of this API just has to pass a vector of :cpp:type:`SlotId` instead of pointers+to preallocated memory for the slot list and the number of elements. Additionally, there is no need+to call the method twice in order to determine the number of elements first.++Another example is the :cpp:func:`C_InitPIN` overload:++   .. cpp:function:: template<typename Talloc> bool C_InitPIN( SessionHandle session, const std::vector<uint8_t, TAlloc>& pin, ReturnValue* return_value = ThrowException ) const++The templated ``pin`` parameter allows to pass the PIN as a ``std::vector<uint8_t>`` or a ``secure_vector<uint8_t>``.+If used with a ``secure_vector`` it is assured that the memory is securely erased when the ``pin`` object is no longer needed.++Error Handling+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~++All possible PKCS#11 return values are represented by the enum class:++.. cpp:enum-class:: ReturnValue : CK_RV++All methods of the :cpp:class:`LowLevel` class have a default parameter ``ReturnValue* return_value = ThrowException``.+This parameter controls the error handling of all :cpp:class:`LowLevel` methods. The default+behavior ``return_value = ThrowException`` is to throw an exception if the method does+not complete successfully. If a non-``NULL`` pointer is passed, ``return_value`` receives the+return value of the PKCS#11 function and no exception is thrown. In case ``nullptr`` is+passed as ``return_value``, the exact return value is ignored and the method just returns+``true`` if the function succeeds and ``false`` otherwise.++Getting started+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++An object of this class can be instantiated by providing a :cpp:type:`FunctionListPtr` to the :cpp:class:`LowLevel` constructor:++   .. cpp:function:: explicit LowLevel(FunctionListPtr ptr)++The :cpp:class:`LowLevel` class provides a static method to retrieve a :cpp:type:`FunctionListPtr`+from a PKCS#11 module file:++   .. cpp:function:: static bool C_GetFunctionList(Dynamically_Loaded_Library& pkcs11_module, FunctionListPtr* function_list_ptr_ptr, ReturnValue* return_value = ThrowException)++----------++Code Example: Object Instantiation++   .. code-block:: cpp++      Botan::Dynamically_Loaded_Library pkcs11_module( "C:\\pkcs11-middleware\\library.dll" );+      Botan::PKCS11::FunctionListPtr func_list = nullptr;+      Botan::PKCS11::LowLevel::C_GetFunctionList( pkcs11_module, &func_list );+      Botan::PKCS11::LowLevel p11_low_level( func_list );++----------++Code Example: PKCS#11 Module Initialization++   .. code-block:: cpp++      Botan::PKCS11::LowLevel p11_low_level(func_list);++      Botan::PKCS11::C_InitializeArgs init_args = { nullptr, nullptr, nullptr, nullptr,+              static_cast<CK_FLAGS>(Botan::PKCS11::Flag::OsLockingOk), nullptr };++      p11_low_level.C_Initialize(&init_args);++      // work with the token++      p11_low_level.C_Finalize(nullptr);++More code examples can be found in the test suite in the ``test_pkcs11_low_level.cpp`` file.++.. _pkcs11_high_level:++High Level API+----------------------------------------++The high level API provides access to the most commonly used PKCS#11 functionality in an+object oriented manner. Functionality of the high level API includes:++* Loading/unloading of PKCS#11 modules+* Initialization of tokens+* Change of PIN/SO-PIN+* Session management+* Random number generation+* Enumeration of objects on the token (certificates, public keys, private keys)+* Import/export/deletion of certificates+* Generation/import/export/deletion of RSA and EC public and private keys+* Encryption/decryption using RSA with support for OAEP and PKCS1-v1_5 (and raw)+* Signature generation/verification using RSA with support for PSS and PKCS1-v1_5 (and raw)+* Signature generation/verification using ECDSA+* Key derivation using ECDH++Module+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The :cpp:class:`Module` class represents a PKCS#11 shared library (module) and is defined in+``botan/p11_module.h``.++It is constructed from a a file path to a PKCS#11 module and optional :cpp:type:`C_InitializeArgs`:++.. cpp:class:: Module++   .. code-block:: cpp++      Module(const std::string& file_path, C_InitializeArgs init_args =+         { nullptr, nullptr, nullptr, nullptr, static_cast<CK_FLAGS>(Flag::OsLockingOk), nullptr })++   It loads the shared library and calls :cpp:func:`C_Initialize` with the provided :cpp:type:`C_InitializeArgs`.+   On destruction of the object :cpp:func:`C_Finalize` is called.++There are two more methods in this class. One is for reloading the shared library+and reinitializing the PKCS#11 module:++   .. code-block:: cpp++      void reload(C_InitializeArgs init_args =+         { nullptr, nullptr, nullptr, nullptr, static_cast< CK_FLAGS >(Flag::OsLockingOk), nullptr });++The other one is for getting general information about the PKCS#11 module:++   .. cpp:function:: Info get_info() const++      This function calls :cpp:func:`C_GetInfo` internally.++----------++Code example:++   .. code-block:: cpp++      Botan::PKCS11::Module module( "C:\\pkcs11-middleware\\library.dll" );++      // Sometimes useful if a newly connected token is not detected by the PKCS#11 module+      module.reload();++      Botan::PKCS11::Info info = module.get_info();++      // print library version+      std::cout << std::to_string( info.libraryVersion.major ) << "."+         << std::to_string( info.libraryVersion.minor ) << std::endl;++Slot+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The :cpp:class:`Slot` class represents a PKCS#11 slot and is defined in+``botan/p11_slot.h``.++A PKCS#11 slot is usually a smart card reader that potentially contains a token.++.. cpp:class:: Slot++   .. cpp:function:: Slot(Module& module, SlotId slot_id)++      To instantiate this class a reference to a :cpp:class:`Module` object and a ``slot_id`` have to be passed+      to the constructor.++   .. cpp:function:: static std::vector<SlotId> get_available_slots(Module& module, bool token_present)++      Retrieve available slot ids by calling this static method.++      The parameter ``token_present`` controls whether all slots or only slots with a+      token attached are returned by this method. This method calls :cpp:func:`C_GetSlotList()`.++   .. cpp:function:: SlotInfo get_slot_info() const++      Returns information about the slot. Calls :cpp:func:`C_GetSlotInfo`.++   .. cpp:function:: TokenInfo get_token_info() const++      Obtains information about a particular token in the system. Calls :cpp:func:`C_GetTokenInfo`.++   .. cpp:function:: std::vector<MechanismType> get_mechanism_list() const++      Obtains a list of mechanism types supported by the slot. Calls :cpp:func:`C_GetMechanismList`.++   .. cpp:function:: MechanismInfo get_mechanism_info(MechanismType mechanism_type) const++      Obtains information about a particular mechanism possibly supported by a slot.+      Calls :cpp:func:`C_GetMechanismInfo`.++   .. cpp:function:: void initialize(const std::string& label, const secure_string& so_pin) const++      Calls :cpp:func:`C_InitToken` to initialize the token. The ``label`` must not exceed 32 bytes.+      The current PIN of the security officer must be passed in ``so_pin`` if the token+      is reinitialized or if it's a factory new token, the ``so_pin`` that is passed will initially be set.++----------++Code example:++   .. code-block:: cpp++      // only slots with connected token+      std::vector<Botan::PKCS11::SlotId> slots = Botan::PKCS11::Slot::get_available_slots( module, true );++      // use first slot+      Botan::PKCS11::Slot slot( module, slots.at( 0 ) );++      // print firmware version of the slot+      Botan::PKCS11::SlotInfo slot_info = slot.get_slot_info();+      std::cout << std::to_string( slot_info.firmwareVersion.major ) << "."+         << std::to_string( slot_info.firmwareVersion.minor ) << std::endl;++      // print firmware version of the token+      Botan::PKCS11::TokenInfo token_info = slot.get_token_info();+      std::cout << std::to_string( token_info.firmwareVersion.major ) << "."+         << std::to_string( token_info.firmwareVersion.minor ) << std::endl;++      // retrieve all mechanisms supported by the token+      std::vector<Botan::PKCS11::MechanismType> mechanisms = slot.get_mechanism_list();++      // retrieve information about a particular mechanism+      Botan::PKCS11::MechanismInfo mech_info =+         slot.get_mechanism_info( Botan::PKCS11::MechanismType::RsaPkcsOaep );++      // maximum RSA key length supported:+      std::cout << mech_info.ulMaxKeySize << std::endl;++      // initialize the token+      Botan::PKCS11::secure_string so_pin( 8, '0' );+      slot.initialize( "Botan PKCS11 documentation test label", so_pin );++Session+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The :cpp:class:`Session` class represents a PKCS#11 session and is defined in ``botan/p11_session.h``.++A session is a logical connection between an application and a token.++.. cpp:class:: Session++   There are two constructors to create a new session and one constructor to+   take ownership of an existing session. The destructor calls+   :cpp:func:`C_Logout` if a user is logged in to this session and always+   :cpp:func:`C_CloseSession`.++   .. cpp:function:: Session(Slot& slot, bool read_only)++      To initialize a session object a :cpp:class:`Slot` has to be specified on which the session+      should operate. ``read_only`` specifies whether the session should be read only or read write.+      Calls :cpp:func:`C_OpenSession`.++   .. cpp:function:: Session(Slot& slot, Flags flags, VoidPtr callback_data, Notify notify_callback)++      Creates a new session by passing a :cpp:class:`Slot`, session ``flags``, ``callback_data`` and a+      ``notify_callback``. Calls :cpp:func:`C_OpenSession`.++   .. cpp:function:: Session(Slot& slot, SessionHandle handle)++      Takes ownership of an existing session by passing :cpp:class:`Slot` and a session ``handle``.++   .. cpp:function:: SessionHandle release()++      Returns the released :cpp:type:`SessionHandle`++   .. cpp:function:: void login(UserType userType, const secure_string& pin)++      Login to this session by passing :cpp:enum:`UserType` and ``pin``. Calls :cpp:func:`C_Login`.++   .. cpp:function:: void logoff()++      Logout from this session. Not mandatory because on destruction of the :cpp:class:`Session` object+      this is done automatically.++   .. cpp:function:: SessionInfo get_info() const++      Returns information about this session. Calls :cpp:func:`C_GetSessionInfo`.++   .. cpp:function:: void set_pin(const secure_string& old_pin, const secure_string& new_pin) const++      Calls :cpp:func:`C_SetPIN` to change the PIN of the logged in user using the ``old_pin``.++   .. cpp:function:: void init_pin(const secure_string& new_pin)++      Calls :cpp:func:`C_InitPIN` to change or initialize the PIN using the SO_PIN (requires a logged in session).++----------++Code example:++   .. code-block:: cpp++      // open read only session+      {+      Botan::PKCS11::Session read_only_session( slot, true );+      }++      // open read write session+      {+      Botan::PKCS11::Session read_write_session( slot, false );+      }++      // open read write session by passing flags+      {+      Botan::PKCS11::Flags flags =+         Botan::PKCS11::flags( Botan::PKCS11::Flag::SerialSession | Botan::PKCS11::Flag::RwSession );++      Botan::PKCS11::Session read_write_session( slot, flags, nullptr, nullptr );+      }++      // move ownership of a session+      {+      Botan::PKCS11::Session session( slot, false );+      Botan::PKCS11::SessionHandle handle = session.release();++      Botan::PKCS11::Session session2( slot, handle );+      }++      Botan::PKCS11::Session session( slot, false );++      // get session info+      Botan::PKCS11::SessionInfo info = session.get_info();+      std::cout << info.slotID << std::endl;++      // login+      Botan::PKCS11::secure_string pin = { '1', '2', '3', '4', '5', '6' };+      session.login( Botan::PKCS11::UserType::User, pin );++      // set pin+      Botan::PKCS11::secure_string new_pin = { '6', '5', '4', '3', '2', '1' };+      session.set_pin( pin, new_pin );++      // logoff+      session.logoff();++      // log in as security officer+      Botan::PKCS11::secure_string so_pin = { '0', '0', '0', '0', '0', '0', '0', '0' };+      session.login( Botan::PKCS11::UserType::SO, so_pin );++      // change pin to old pin+      session.init_pin( pin );++Objects+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++PKCS#11 objects consist of various attributes (:c:type:`CK_ATTRIBUTE`). For example :c:macro:`CKA_TOKEN`+describes if a PKCS#11 object is a session object or a token object. The helper class :cpp:class:`AttributeContainer`+helps with storing these attributes. The class is defined in ``botan/p11_object.h``.++.. cpp:class:: AttributeContainer++Attributes can be set in an :cpp:class:`AttributeContainer` by various ``add_`` methods:++   .. cpp:function:: void add_class(ObjectClass object_class)++      Add a class attribute (:c:macro:`CKA_CLASS` / :cpp:enumerator:`AttributeType::Class`)++   .. cpp:function:: void add_string(AttributeType attribute, const std::string& value)++      Add a string attribute (e.g. :c:macro:`CKA_LABEL` / :cpp:enumerator:`AttributeType::Label`).++   .. cpp:function:: void AttributeContainer::add_binary(AttributeType attribute, const uint8_t* value, size_t length)++      Add a binary attribute (e.g. :c:macro:`CKA_ID` / :cpp:enumerator:`AttributeType::Id`).++   .. cpp:function:: template<typename TAlloc> void AttributeContainer::add_binary(AttributeType attribute, const std::vector<uint8_t, TAlloc>& binary)++      Add a binary attribute by passing a ``vector``/``secure_vector`` (e.g. :c:macro:`CKA_ID` / :cpp:enumerator:`AttributeType::Id`).++   .. cpp:function:: void AttributeContainer::add_bool(AttributeType attribute, bool value)++      Add a bool attribute (e.g. :c:macro:`CKA_SENSITIVE` / :cpp:enumerator:`AttributeType::Sensitive`).++   .. cpp:function:: template<typename T> void AttributeContainer::add_numeric(AttributeType attribute, T value)++       Add a numeric attribute (e.g. :c:macro:`CKA_MODULUS_BITS` / :cpp:enumerator:`AttributeType::ModulusBits`).++.. rubric:: Object Properties++The PKCS#11 standard defines the mandatory and optional attributes for each object class.+The mandatory and optional attribute requirements are mapped in so called property classes.+Mandatory attributes are set in the constructor, optional attributes can be set via ``set_`` methods.++In the top hierarchy is the :cpp:class:`ObjectProperties` class which inherits from the :cpp:class:`AttributeContainer`.+This class represents the common attributes of all PKCS#11 objects.++.. cpp:class:: ObjectProperties : public AttributeContainer++The constructor is defined as follows:++   .. cpp:function:: ObjectProperties(ObjectClass object_class)++      Every PKCS#11 object needs an object class attribute.++The next level defines the :cpp:class:`StorageObjectProperties` class which inherits from+:cpp:class:`ObjectProperties`.++.. cpp:class:: StorageObjectProperties : public ObjectProperties++The only mandatory attribute is the object class, so the constructor is+defined as follows:++   .. cpp:function:: StorageObjectProperties(ObjectClass object_class)++But in contrast to the :cpp:class:`ObjectProperties` class there are various setter methods. For example to+set the :cpp:enumerator:`AttributeType::Label`:++   .. cpp:function:: void set_label(const std::string& label)++      Sets the label description of the object (RFC2279 string).++The remaining hierarchy is defined as follows:++* :cpp:class:`DataObjectProperties` inherits from :cpp:class:`StorageObjectProperties`+* :cpp:class:`CertificateProperties` inherits from :cpp:class:`StorageObjectProperties`+* :cpp:class:`DomainParameterProperties` inherits from :cpp:class:`StorageObjectProperties`+* :cpp:class:`KeyProperties` inherits from :cpp:class:`StorageObjectProperties`+* :cpp:class:`PublicKeyProperties` inherits from :cpp:class:`KeyProperties`+* :cpp:class:`PrivateKeyProperties` inherits from :cpp:class:`KeyProperties`+* :cpp:class:`SecretKeyProperties` inherits from :cpp:class:`KeyProperties`++PKCS#11 objects themselves are represented by the :cpp:class:`Object` class.++.. cpp:class:: Object++Following constructors are defined:++   .. cpp:function:: Object(Session& session, ObjectHandle handle)++      Takes ownership over an existing object.++   .. cpp:function:: Object(Session& session, const ObjectProperties& obj_props)++      Creates a new object with the :cpp:class:`ObjectProperties` provided in ``obj_props``.++The other methods are:++   .. cpp:function:: secure_vector<uint8_t> get_attribute_value(AttributeType attribute) const++      Returns the value of the given attribute (using :cpp:func:`C_GetAttributeValue`)++   .. cpp:function:: void set_attribute_value(AttributeType attribute, const secure_vector<uint8_t>& value) const++      Sets the given value for the attribute (using :cpp:func:`C_SetAttributeValue`)++   .. cpp:function:: void destroy() const++      Destroys the object.++   .. cpp:function:: ObjectHandle copy(const AttributeContainer& modified_attributes) const++      Allows to copy the object with modified attributes.++And static methods to search for objects:++   .. cpp:function:: template<typename T> static std::vector<T> search(Session& session, const std::vector<Attribute>& search_template)++      Searches for all objects of the given type that match ``search_template``.++   .. cpp:function:: template<typename T> static std::vector<T> search(Session& session, const std::string& label)++      Searches for all objects of the given type using the label (:c:macro:`CKA_LABEL`).++   .. cpp:function:: template<typename T> static std::vector<T> search(Session& session, const std::vector<uint8_t>& id)++      Searches for all objects of the given type using the id (:c:macro:`CKA_ID`).++   .. cpp:function:: template<typename T> static std::vector<T> search(Session& session, const std::string& label, const std::vector<uint8_t>& id)++      Searches for all objects of the given type using the label (:c:macro:`CKA_LABEL`) and id (:c:macro:`CKA_ID`).++   .. cpp:function:: template<typename T> static std::vector<T> search(Session& session)++      Searches for all objects of the given type.++.. rubric:: The ObjectFinder++Another way for searching objects is to use the :cpp:class:`ObjectFinder` class. This class+manages calls to the ``C_FindObjects*`` functions: :cpp:func:`C_FindObjectsInit`, :cpp:func:`C_FindObjects`+and :cpp:func:`C_FindObjectsFinal`.++.. cpp:class:: ObjectFinder++The constructor has the following signature:++   .. cpp:function:: ObjectFinder(Session& session, const std::vector<Attribute>& search_template)++      A search can be prepared with an :cpp:class:`ObjectSearcher` by passing a :cpp:class:`Session` and a ``search_template``.++The actual search operation is started by calling the :cpp:func:`find` method:++   .. cpp:function:: std::vector<ObjectHandle> find(std::uint32_t max_count = 100) const++      Starts or continues a search for token and session objects that match a template. ``max_count``+      specifies the maximum number of search results (object handles) that are returned.++   .. cpp:function:: void finish()++      Finishes the search operation manually to allow a new :cpp:class:`ObjectFinder` to exist.+      Otherwise the search is finished by the destructor.++----------++Code example:++   .. code-block:: cpp++      // create an simple data object+      Botan::secure_vector<uint8_t> value = { 0x00, 0x01 ,0x02, 0x03 };+      std::size_t id = 1337;+      std::string label = "test data object";++      // set properties of the new object+      Botan::PKCS11::DataObjectProperties data_obj_props;+      data_obj_props.set_label( label );+      data_obj_props.set_value( value );+      data_obj_props.set_token( true );+      data_obj_props.set_modifiable( true );+      data_obj_props.set_object_id( Botan::DER_Encoder().encode( id ).get_contents_unlocked() );++      // create the object+      Botan::PKCS11::Object data_obj( session, data_obj_props );++      // get label of this object+      Botan::PKCS11::secure_string retrieved_label =+         data_obj.get_attribute_value( Botan::PKCS11::AttributeType::Label );++      // set a new label+      Botan::PKCS11::secure_string new_label = { 'B', 'o', 't', 'a', 'n' };+      data_obj.set_attribute_value( Botan::PKCS11::AttributeType::Label, new_label );++      // copy the object+      Botan::PKCS11::AttributeContainer copy_attributes;+      copy_attributes.add_string( Botan::PKCS11::AttributeType::Label, "copied object" );+      Botan::PKCS11::ObjectHandle copied_obj_handle = data_obj.copy( copy_attributes );++      // search for an object+      Botan::PKCS11::AttributeContainer search_template;+      search_template.add_string( Botan::PKCS11::AttributeType::Label, "Botan" );+      auto found_objs =+         Botan::PKCS11::Object::search<Botan::PKCS11::Object>( session, search_template.attributes() );++      // destroy the object+      data_obj.destroy();++RSA+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++PKCS#11 RSA support is implemented in ``<botan/p11_rsa.h>``.++.. rubric:: RSA Public Keys++PKCS#11 RSA public keys are provided by the class :cpp:class:`PKCS11_RSA_PublicKey`. This class+inherits from :cpp:class:`RSA_PublicKey` and :cpp:class:`Object`. Furthermore there are two property classes defined+to generate and import RSA public keys analogous to the other property classes described+before: :cpp:class:`RSA_PublicKeyGenerationProperties` and :cpp:class:`RSA_PublicKeyImportProperties`.++.. cpp:class:: PKCS11_RSA_PublicKey : public RSA_PublicKey, public Object++   .. cpp:function:: PKCS11_RSA_PublicKey(Session& session, ObjectHandle handle)++      Existing PKCS#11 RSA public keys can be used by providing an :cpp:type:`ObjectHandle` to the+      constructor.++   .. cpp:function:: PKCS11_RSA_PublicKey(Session& session, const RSA_PublicKeyImportProperties& pubkey_props)++      This constructor can be used to import an existing RSA public key with the :cpp:class:`RSA_PublicKeyImportProperties`+      passed in ``pubkey_props`` to the token.++.. rubric:: RSA Private Keys++The support for PKCS#11 RSA private keys is implemented in a similar way. There are two property+classes: :cpp:class:`RSA_PrivateKeyGenerationProperties` and :cpp:class:`RSA_PrivateKeyImportProperties`. The :cpp:class:`PKCS11_RSA_PrivateKey`+class implements the actual support for PKCS#11 RSA private keys. This class inherits from :cpp:class:`Private_Key`,+:cpp:class:`RSA_PublicKey` and :cpp:class:`Object`. In contrast to the public key class there is a third constructor+to generate private keys directly on the token or in the session and one method to export private keys.++.. cpp:class:: PKCS11_RSA_PrivateKey : public Private_Key, public RSA_PublicKey, public Object++   .. cpp:function:: PKCS11_RSA_PrivateKey(Session& session, ObjectHandle handle)++      Existing PKCS#11 RSA private keys can be used by providing an :cpp:type:`ObjectHandle` to the+      constructor.++   .. cpp:function:: PKCS11_RSA_PrivateKey(Session& session, const RSA_PrivateKeyImportProperties& priv_key_props)++      This constructor can be used to import an existing RSA private key with the :cpp:class:`RSA_PrivateKeyImportProperties`+      passed in ``priv_key_props`` to the token.++   .. cpp:function:: PKCS11_RSA_PrivateKey(Session& session, uint32_t bits, const RSA_PrivateKeyGenerationProperties& priv_key_props)++      Generates a new PKCS#11 RSA private key with bit length provided in ``bits`` and the :cpp:class:`RSA_PrivateKeyGenerationProperties`+      passed in ``priv_key_props``.++   .. cpp:function:: RSA_PrivateKey export_key() const++      Returns the exported :cpp:class:`RSA_PrivateKey`.++PKCS#11 RSA key pairs can be generated with the following free function:++   .. cpp:function:: PKCS11_RSA_KeyPair PKCS11::generate_rsa_keypair(Session& session, const RSA_PublicKeyGenerationProperties& pub_props, const RSA_PrivateKeyGenerationProperties& priv_props)++----------++Code example:++   .. code-block:: cpp++      Botan::PKCS11::secure_string pin = { '1', '2', '3', '4', '5', '6' };+      session.login( Botan::PKCS11::UserType::User, pin );++      /************ import RSA private key *************/++      // create private key in software+      Botan::AutoSeeded_RNG rng;+      Botan::RSA_PrivateKey priv_key_sw( rng, 2048 );++      // set the private key import properties+      Botan::PKCS11::RSA_PrivateKeyImportProperties+         priv_import_props( priv_key_sw.get_n(), priv_key_sw.get_d() );++      priv_import_props.set_pub_exponent( priv_key_sw.get_e() );+      priv_import_props.set_prime_1( priv_key_sw.get_p() );+      priv_import_props.set_prime_2( priv_key_sw.get_q() );+      priv_import_props.set_coefficient( priv_key_sw.get_c() );+      priv_import_props.set_exponent_1( priv_key_sw.get_d1() );+      priv_import_props.set_exponent_2( priv_key_sw.get_d2() );++      priv_import_props.set_token( true );+      priv_import_props.set_private( true );+      priv_import_props.set_decrypt( true );+      priv_import_props.set_sign( true );++      // import+      Botan::PKCS11::PKCS11_RSA_PrivateKey priv_key( session, priv_import_props );++      /************ export PKCS#11 RSA private key *************/+      Botan::RSA_PrivateKey exported = priv_key.export_key();++      /************ import RSA public key *************/++      // set the public key import properties+      Botan::PKCS11::RSA_PublicKeyImportProperties pub_import_props( priv_key.get_n(), priv_key.get_e() );+      pub_import_props.set_token( true );+      pub_import_props.set_encrypt( true );+      pub_import_props.set_private( false );++      // import+      Botan::PKCS11::PKCS11_RSA_PublicKey public_key( session, pub_import_props );++      /************ generate RSA private key *************/++      Botan::PKCS11::RSA_PrivateKeyGenerationProperties priv_generate_props;+      priv_generate_props.set_token( true );+      priv_generate_props.set_private( true );+      priv_generate_props.set_sign( true );+      priv_generate_props.set_decrypt( true );+      priv_generate_props.set_label( "BOTAN_TEST_RSA_PRIV_KEY" );++      Botan::PKCS11::PKCS11_RSA_PrivateKey private_key2( session, 2048, priv_generate_props );++      /************ generate RSA key pair *************/++      Botan::PKCS11::RSA_PublicKeyGenerationProperties pub_generate_props( 2048UL );+      pub_generate_props.set_pub_exponent();+      pub_generate_props.set_label( "BOTAN_TEST_RSA_PUB_KEY" );+      pub_generate_props.set_token( true );+      pub_generate_props.set_encrypt( true );+      pub_generate_props.set_verify( true );+      pub_generate_props.set_private( false );++      Botan::PKCS11::PKCS11_RSA_KeyPair rsa_keypair =+         Botan::PKCS11::generate_rsa_keypair( session, pub_generate_props, priv_generate_props );++      /************ RSA encrypt *************/++      Botan::secure_vector<uint8_t> plaintext = { 0x00, 0x01, 0x02, 0x03 };+      Botan::PK_Encryptor_EME encryptor( rsa_keypair.first, rng, "Raw" );+      auto ciphertext = encryptor.encrypt( plaintext, rng );++      /************ RSA decrypt *************/++      Botan::PK_Decryptor_EME decryptor( rsa_keypair.second, rng, "Raw" );+      plaintext = decryptor.decrypt( ciphertext );++      /************ RSA sign *************/++      Botan::PK_Signer signer( rsa_keypair.second, rng, "EMSA4(SHA-256)", Botan::IEEE_1363 );+      auto signature = signer.sign_message( plaintext, rng );++      /************ RSA verify *************/++      Botan::PK_Verifier verifier( rsa_keypair.first, "EMSA4(SHA-256)", Botan::IEEE_1363 );+      auto ok = verifier.verify_message( plaintext, signature );++ECDSA+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++PKCS#11 ECDSA support is implemented in ``<botan/p11_ecdsa.h>``.++.. rubric:: ECDSA Public Keys++PKCS#11 ECDSA public keys are provided by the class :cpp:class:`PKCS11_ECDSA_PublicKey`. This class+inherits from :cpp:class:`PKCS11_EC_PublicKey` and :cpp:class:`ECDSA_PublicKey`. The necessary property classes+are defined in ``<botan/p11_ecc_key.h>``. For public keys there are :cpp:class:`EC_PublicKeyGenerationProperties`+and :cpp:class:`EC_PublicKeyImportProperties`.++.. cpp:class:: PKCS11_ECDSA_PublicKey : public PKCS11_EC_PublicKey, public virtual ECDSA_PublicKey++   .. cpp:function:: PKCS11_ECDSA_PublicKey(Session& session, ObjectHandle handle)++      Existing PKCS#11 ECDSA private keys can be used by providing an :cpp:type:`ObjectHandle` to the+      constructor.++   .. cpp:function:: PKCS11_ECDSA_PublicKey(Session& session, const EC_PublicKeyImportProperties& props)++      This constructor can be used to import an existing ECDSA public key with the :cpp:class:`EC_PublicKeyImportProperties`+      passed in ``props`` to the token.++   .. cpp:function:: ECDSA_PublicKey PKCS11_ECDSA_PublicKey::export_key() const++      Returns the exported :cpp:class:`ECDSA_PublicKey`.++.. rubric:: ECDSA Private Keys++The class :cpp:class:`PKCS11_ECDSA_PrivateKey` inherits from :cpp:class:`PKCS11_EC_PrivateKey` and implements support+for PKCS#11 ECDSA private keys. There are two property classes for key generation+and import: :cpp:class:`EC_PrivateKeyGenerationProperties` and :cpp:class:`EC_PrivateKeyImportProperties`.++.. cpp:class:: PKCS11_ECDSA_PrivateKey : public PKCS11_EC_PrivateKey++   .. cpp:function:: PKCS11_ECDSA_PrivateKey(Session& session, ObjectHandle handle)++      Existing PKCS#11 ECDSA private keys can be used by providing an :cpp:type:`ObjectHandle` to the+      constructor.++   .. cpp:function:: PKCS11_ECDSA_PrivateKey(Session& session, const EC_PrivateKeyImportProperties& props)++      This constructor can be used to import an existing ECDSA private key with the :cpp:class:`EC_PrivateKeyImportProperties`+      passed in ``props`` to the token.++   .. cpp:function:: PKCS11_ECDSA_PrivateKey(Session& session, const std::vector<uint8_t>& ec_params, const EC_PrivateKeyGenerationProperties& props)++      This constructor can be used to generate a new ECDSA private key with the :cpp:class:`EC_PrivateKeyGenerationProperties`+      passed in ``props`` on the token. The ``ec_params`` parameter is the DER-encoding of an+      ANSI X9.62 Parameters value.++   .. cpp:function:: ECDSA_PrivateKey export_key() const++      Returns the exported :cpp:class:`ECDSA_PrivateKey`.++PKCS#11 ECDSA key pairs can be generated with the following free function:++   .. cpp:function:: PKCS11_ECDSA_KeyPair PKCS11::generate_ecdsa_keypair(Session& session, const EC_PublicKeyGenerationProperties& pub_props, const EC_PrivateKeyGenerationProperties& priv_props)++----------++Code example:++   .. code-block:: cpp++      Botan::PKCS11::secure_string pin = { '1', '2', '3', '4', '5', '6' };+      session.login( Botan::PKCS11::UserType::User, pin );++      /************ import ECDSA private key *************/++      // create private key in software+      Botan::AutoSeeded_RNG rng;++      Botan::ECDSA_PrivateKey priv_key_sw( rng, Botan::EC_Group( "secp256r1" ) );+      priv_key_sw.set_parameter_encoding( Botan::EC_Group_Encoding::EC_DOMPAR_ENC_OID );++      // set the private key import properties+      Botan::PKCS11::EC_PrivateKeyImportProperties priv_import_props(+         priv_key_sw.DER_domain(), priv_key_sw.private_value() );++      priv_import_props.set_token( true );+      priv_import_props.set_private( true );+      priv_import_props.set_sign( true );+      priv_import_props.set_extractable( true );++      // label+      std::string label = "test ECDSA key";+      priv_import_props.set_label( label );++      // import to card+      Botan::PKCS11::PKCS11_ECDSA_PrivateKey priv_key( session, priv_import_props );++      /************ export PKCS#11 ECDSA private key *************/+      Botan::ECDSA_PrivateKey priv_exported = priv_key.export_key();++      /************ import ECDSA public key *************/++      // import to card+      Botan::PKCS11::EC_PublicKeyImportProperties pub_import_props( priv_key_sw.DER_domain(),+         Botan::DER_Encoder().encode( EC2OSP( priv_key_sw.public_point(), Botan::PointGFp::UNCOMPRESSED ),+         Botan::OCTET_STRING ).get_contents_unlocked() );++      pub_import_props.set_token( true );+      pub_import_props.set_verify( true );+      pub_import_props.set_private( false );++      // label+      label = "test ECDSA pub key";+      pub_import_props.set_label( label );++      Botan::PKCS11::PKCS11_ECDSA_PublicKey public_key( session, pub_import_props );++      /************ export PKCS#11 ECDSA public key *************/+      Botan::ECDSA_PublicKey pub_exported = public_key.export_key();++      /************ generate PKCS#11 ECDSA private key *************/+      Botan::PKCS11::EC_PrivateKeyGenerationProperties priv_generate_props;+      priv_generate_props.set_token( true );+      priv_generate_props.set_private( true );+      priv_generate_props.set_sign( true );++      Botan::PKCS11::PKCS11_ECDSA_PrivateKey pk( session,+         Botan::EC_Group( "secp256r1" ).DER_encode( Botan::EC_Group_Encoding::EC_DOMPAR_ENC_OID ),+         priv_generate_props );++      /************ generate PKCS#11 ECDSA key pair *************/++      Botan::PKCS11::EC_PublicKeyGenerationProperties pub_generate_props(+         Botan::EC_Group( "secp256r1" ).DER_encode(Botan::EC_Group_Encoding::EC_DOMPAR_ENC_OID ) );++      pub_generate_props.set_label( "BOTAN_TEST_ECDSA_PUB_KEY" );+      pub_generate_props.set_token( true );+      pub_generate_props.set_verify( true );+      pub_generate_props.set_private( false );+      pub_generate_props.set_modifiable( true );++      Botan::PKCS11::PKCS11_ECDSA_KeyPair key_pair = Botan::PKCS11::generate_ecdsa_keypair( session,+         pub_generate_props, priv_generate_props );++      /************ PKCS#11 ECDSA sign and verify *************/++      std::vector<uint8_t> plaintext( 20, 0x01 );++      Botan::PK_Signer signer( key_pair.second, rng, "Raw", Botan::IEEE_1363, "pkcs11" );+      auto signature = signer.sign_message( plaintext, rng );++      Botan::PK_Verifier token_verifier( key_pair.first, "Raw", Botan::IEEE_1363, "pkcs11" );+      bool ecdsa_ok = token_verifier.verify_message( plaintext, signature );++ECDH+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++PKCS#11 ECDH support is implemented in ``<botan/p11_ecdh.h>``.++.. rubric:: ECDH Public Keys++PKCS#11 ECDH public keys are provided by the class :cpp:class:`PKCS11_ECDH_PublicKey`. This class+inherits from :cpp:class:`PKCS11_EC_PublicKey`. The necessary property classes+are defined in ``<botan/p11_ecc_key.h>``. For public keys there are :cpp:class:`EC_PublicKeyGenerationProperties`+and :cpp:class:`EC_PublicKeyImportProperties`.++.. cpp:class:: PKCS11_ECDH_PublicKey : public PKCS11_EC_PublicKey++   .. cpp:function:: PKCS11_ECDH_PublicKey(Session& session, ObjectHandle handle)++      Existing PKCS#11 ECDH private keys can be used by providing an :cpp:type:`ObjectHandle` to the+      constructor.++   .. cpp:function:: PKCS11_ECDH_PublicKey(Session& session, const EC_PublicKeyImportProperties& props)++      This constructor can be used to import an existing ECDH public key with the :cpp:class:`EC_PublicKeyImportProperties`+      passed in ``props`` to the token.++   .. cpp:function:: ECDH_PublicKey export_key() const++      Returns the exported :cpp:class:`ECDH_PublicKey`.++.. rubric:: ECDH Private Keys++The class :cpp:class:`PKCS11_ECDH_PrivateKey` inherits from :cpp:class:`PKCS11_EC_PrivateKey` and :cpp:class:`PK_Key_Agreement_Key`+and implements support for PKCS#11 ECDH private keys. There are two+property classes. One for key generation and one for import: :cpp:class:`EC_PrivateKeyGenerationProperties` and+:cpp:class:`EC_PrivateKeyImportProperties`.++.. cpp:class:: PKCS11_ECDH_PrivateKey : public virtual PKCS11_EC_PrivateKey, public virtual PK_Key_Agreement_Key++   .. cpp:function:: PKCS11_ECDH_PrivateKey(Session& session, ObjectHandle handle)++      Existing PKCS#11 ECDH private keys can be used by providing an :cpp:type:`ObjectHandle` to the+      constructor.++   .. cpp:function:: PKCS11_ECDH_PrivateKey(Session& session, const EC_PrivateKeyImportProperties& props)++      This constructor can be used to import an existing ECDH private key with the :cpp:class:`EC_PrivateKeyImportProperties`+      passed in ``props`` to the token.++   .. cpp:function:: PKCS11_ECDH_PrivateKey(Session& session, const std::vector<uint8_t>& ec_params, const EC_PrivateKeyGenerationProperties& props)++      This constructor can be used to generate a new ECDH private key with the :cpp:class:`EC_PrivateKeyGenerationProperties`+      passed in ``props`` on the token. The ``ec_params`` parameter is the DER-encoding of an+      ANSI X9.62 Parameters value.++   .. cpp:function:: ECDH_PrivateKey export_key() const++      Returns the exported :cpp:class:`ECDH_PrivateKey`.++PKCS#11 ECDH key pairs can be generated with the following free function:++.. cpp:function:: PKCS11_ECDH_KeyPair PKCS11::generate_ecdh_keypair(Session& session, const EC_PublicKeyGenerationProperties& pub_props, const EC_PrivateKeyGenerationProperties& priv_props)++----------++Code example:++   .. code-block:: cpp++      Botan::PKCS11::secure_string pin = { '1', '2', '3', '4', '5', '6' };+      session.login( Botan::PKCS11::UserType::User, pin );++      /************ import ECDH private key *************/++      Botan::AutoSeeded_RNG rng;++      // create private key in software+      Botan::ECDH_PrivateKey priv_key_sw( rng, Botan::EC_Group( "secp256r1" ) );+      priv_key_sw.set_parameter_encoding( Botan::EC_Group_Encoding::EC_DOMPAR_ENC_OID );++      // set import properties+      Botan::PKCS11::EC_PrivateKeyImportProperties priv_import_props(+         priv_key_sw.DER_domain(), priv_key_sw.private_value() );++      priv_import_props.set_token( true );+      priv_import_props.set_private( true );+      priv_import_props.set_derive( true );+      priv_import_props.set_extractable( true );++      // label+      std::string label = "test ECDH key";+      priv_import_props.set_label( label );++      // import to card+      Botan::PKCS11::PKCS11_ECDH_PrivateKey priv_key( session, priv_import_props );++      /************ export ECDH private key *************/+      Botan::ECDH_PrivateKey exported = priv_key.export_key();++      /************ import ECDH public key *************/++      // set import properties+      Botan::PKCS11::EC_PublicKeyImportProperties pub_import_props( priv_key_sw.DER_domain(),+         Botan::DER_Encoder().encode( EC2OSP( priv_key_sw.public_point(), Botan::PointGFp::UNCOMPRESSED ),+         Botan::OCTET_STRING ).get_contents_unlocked() );++      pub_import_props.set_token( true );+      pub_import_props.set_private( false );+      pub_import_props.set_derive( true );++      // label+      label = "test ECDH pub key";+      pub_import_props.set_label( label );++      // import+      Botan::PKCS11::PKCS11_ECDH_PublicKey pub_key( session, pub_import_props );++      /************ export ECDH private key *************/+      Botan::ECDH_PublicKey exported_pub = pub_key.export_key();++      /************ generate ECDH private key *************/++      Botan::PKCS11::EC_PrivateKeyGenerationProperties priv_generate_props;+      priv_generate_props.set_token( true );+      priv_generate_props.set_private( true );+      priv_generate_props.set_derive( true );++      Botan::PKCS11::PKCS11_ECDH_PrivateKey priv_key2( session,+         Botan::EC_Group( "secp256r1" ).DER_encode( Botan::EC_Group_Encoding::EC_DOMPAR_ENC_OID ),+         priv_generate_props );++      /************ generate ECDH key pair *************/++      Botan::PKCS11::EC_PublicKeyGenerationProperties pub_generate_props(+         Botan::EC_Group( "secp256r1" ).DER_encode( Botan::EC_Group_Encoding::EC_DOMPAR_ENC_OID ) );++      pub_generate_props.set_label( label + "_PUB_KEY" );+      pub_generate_props.set_token( true );+      pub_generate_props.set_derive( true );+      pub_generate_props.set_private( false );+      pub_generate_props.set_modifiable( true );++      Botan::PKCS11::PKCS11_ECDH_KeyPair key_pair = Botan::PKCS11::generate_ecdh_keypair(+         session, pub_generate_props, priv_generate_props );++      /************ ECDH derive *************/++      Botan::PKCS11::PKCS11_ECDH_KeyPair key_pair_other = Botan::PKCS11::generate_ecdh_keypair(+         session, pub_generate_props, priv_generate_props );++      Botan::PK_Key_Agreement ka( key_pair.second, rng, "Raw", "pkcs11" );+      Botan::PK_Key_Agreement kb( key_pair_other.second, rng, "Raw", "pkcs11" );++      Botan::SymmetricKey alice_key = ka.derive_key( 32,+         Botan::unlock( Botan::EC2OSP( key_pair_other.first.public_point(),+         Botan::PointGFp::UNCOMPRESSED ) ) );++      Botan::SymmetricKey bob_key = kb.derive_key( 32,+         Botan::unlock( Botan::EC2OSP( key_pair.first.public_point(),+         Botan::PointGFp::UNCOMPRESSED ) ) );++      bool eq = alice_key == bob_key;++RNG+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The PKCS#11 RNG is defined in ``<botan/p11_randomgenerator.h>``. The class :cpp:class:`PKCS11_RNG`+implements the :cpp:class:`Hardware_RNG` interface.++.. cpp:class:: PKCS11_RNG : public Hardware_RNG++   .. cpp:function:: PKCS11_RNG(Session& session)++      A PKCS#11 :cpp:class:`Session` must be passed to instantiate a ``PKCS11_RNG``.++   .. cpp:function:: void randomize(uint8_t output[], std::size_t length) override++      Calls :cpp:func:`C_GenerateRandom` to generate random data.++   .. cpp:function:: void add_entropy(const uint8_t in[], std::size_t length) override++      Calls :cpp:func:`C_SeedRandom` to add entropy to the random generation function of the token/middleware.++----------++Code example:++   .. code-block:: cpp++      Botan::PKCS11::PKCS11_RNG p11_rng( session );++      /************ generate random data *************/+      std::vector<uint8_t> random( 20 );+      p11_rng.randomize( random.data(), random.size() );++      /************ add entropy *************/+      Botan::AutoSeeded_RNG auto_rng;+      auto auto_rng_random = auto_rng.random_vec( 20 );+      p11_rng.add_entropy( auto_rng_random.data(), auto_rng_random.size() );++      /************ use PKCS#11 RNG to seed HMAC_DRBG *************/+      Botan::HMAC_DRBG drbg( Botan::MessageAuthenticationCode::create( "HMAC(SHA-512)" ), p11_rng );+      drbg.randomize( random.data(), random.size() );++Token Management Functions+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The header file ``<botan/p11.h>`` also defines some free functions for token management:++   .. cpp:function:: void initialize_token(Slot& slot, const std::string& label, const secure_string& so_pin, const secure_string& pin)++      Initializes a token by passing a :cpp:class:`Slot`, a ``label`` and the ``so_pin`` of the security officer.++   .. cpp:function:: void change_pin(Slot& slot, const secure_string& old_pin, const secure_string& new_pin)++      Change PIN with ``old_pin`` to ``new_pin``.++   .. cpp:function:: void change_so_pin(Slot& slot, const secure_string& old_so_pin, const secure_string& new_so_pin)++      Change SO_PIN with ``old_so_pin`` to new ``new_so_pin``.++   .. cpp:function:: void set_pin(Slot& slot, const secure_string& so_pin, const secure_string& pin)++      Sets user ``pin`` with ``so_pin``.++----------++Code example:++   .. code-block:: cpp++      /************ set pin *************/++      Botan::PKCS11::Module module( Middleware_path );++      // only slots with connected token+      std::vector<Botan::PKCS11::SlotId> slots = Botan::PKCS11::Slot::get_available_slots( module, true );++      // use first slot+      Botan::PKCS11::Slot slot( module, slots.at( 0 ) );++      Botan::PKCS11::secure_string so_pin = { '1', '2', '3', '4', '5', '6', '7', '8' };+      Botan::PKCS11::secure_string pin = { '1', '2', '3', '4', '5', '6' };+      Botan::PKCS11::secure_string test_pin = { '6', '5', '4', '3', '2', '1' };++      // set pin+      Botan::PKCS11::set_pin( slot, so_pin, test_pin );++      // change back+      Botan::PKCS11::set_pin( slot, so_pin, pin );++      /************ initialize *************/+      Botan::PKCS11::initialize_token( slot, "Botan handbook example", so_pin, pin );++      /************ change pin *************/+      Botan::PKCS11::change_pin( slot, pin, test_pin );++      // change back+      Botan::PKCS11::change_pin( slot, test_pin, pin );++      /************ change security officer pin *************/+      Botan::PKCS11::change_so_pin( slot, so_pin, test_pin );++      // change back+      Botan::PKCS11::change_so_pin( slot, test_pin, so_pin );++X.509+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The header file ``<botan/p11_x509.h>`` defines the property class :cpp:class:`X509_CertificateProperties`+and the class :cpp:class:`PKCS11_X509_Certificate`.++.. cpp:class:: PKCS11_X509_Certificate : public Object, public X509_Certificate++   .. cpp:function:: PKCS11_X509_Certificate(Session& session, ObjectHandle handle)++      Allows to use existing certificates on the token by passing a valid :cpp:type:`ObjectHandle`.++   .. cpp:function:: PKCS11_X509_Certificate(Session& session, const X509_CertificateProperties& props)++      Allows to import an existing X.509 certificate to the token with the :cpp:class:`X509_CertificateProperties`+      passed in ``props``.++----------++Code example:++   .. code-block:: cpp++      // load existing certificate+      Botan::X509_Certificate root( "test.crt" );++      // set props+      Botan::PKCS11::X509_CertificateProperties props(+         Botan::DER_Encoder().encode( root.subject_dn() ).get_contents_unlocked(), root.BER_encode() );++      props.set_label( "Botan PKCS#11 test certificate" );+      props.set_private( false );+      props.set_token( true );++      // import+      Botan::PKCS11::PKCS11_X509_Certificate pkcs11_cert( session, props );++      // load by handle+      Botan::PKCS11::PKCS11_X509_Certificate pkcs11_cert2( session, pkcs11_cert.handle() );++Tests+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++The PKCS#11 tests are not executed automatically because the depend on an external+PKCS#11 module/middleware. The test tool has to be executed with ``--pkcs11-lib=``+followed with the path of the PKCS#11 module and a second argument which controls the+PKCS#11 tests that are executed. Passing ``pkcs11`` will execute all PKCS#11 tests but it's+also possible to execute only a subset with the following arguments:++- pkcs11-ecdh+- pkcs11-ecdsa+- pkcs11-lowlevel+- pkcs11-manage+- pkcs11-module+- pkcs11-object+- pkcs11-rng+- pkcs11-rsa+- pkcs11-session+- pkcs11-slot+- pkcs11-x509++The following PIN and SO-PIN/PUK values are used in tests:++- PIN 123456+- SO-PIN/PUK 12345678++ .. warning::++   Unlike the CardOS (4.4, 5.0, 5.3), the aforementioned SO-PIN/PUK is+   inappropriate for Gemalto (IDPrime MD 3840) cards, as it must be a byte array+   of length 24. For this reason some of the tests for Gemalto card involving+   SO-PIN will fail.  You run into a risk of exceding login attempts and as a+   result locking your card!  Currently, specifying pin via command-line option+   is not implemented, and therefore the desired PIN must be modified in the+   header src/tests/test_pkcs11.h:++   .. code-block:: cpp++      // SO PIN is expected to be set to "12345678" prior to running the tests+      const std::string SO_PIN = "12345678";+      const auto SO_PIN_SECVEC = Botan::PKCS11::secure_string(SO_PIN.begin(), SO_PIN.end());+++Tested/Supported Smartcards+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^++You are very welcome to contribute your own test results for other testing environments or other cards.+++Test results+++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++|  Smartcard                          | Status                                    | OS                                                | Midleware                                         |   Botan                                           | Errors                                            |++=====================================+===========================================+===================================================+===================================================+===================================================+===================================================++| CardOS 4.4                          | mostly works                              | Windows 10, 64-bit, version 1709                  | API Version 5.4.9.77 (Cryptoki v2.11)             |  2.4.0, Cryptoki v2.40                            | [50]_                                             |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++| CardOS 5.0                          | mostly works                              | Windows 10, 64-bit, version 1709                  | API Version 5.4.9.77 (Cryptoki v2.11)             |  2.4.0, Cryptoki v2.40                            | [51]_                                             |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++| CardOS 5.3                          | mostly works                              | Windows 10, 64-bit, version 1709                  | API Version 5.4.9.77 (Cryptoki v2.11)             |  2.4.0, Cryptoki v2.40                            | [52]_                                             |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++| CardOS 5.3                          | mostly works                              | Windows 10, 64-bit, version 1903                  | API Version 5.5.1 (Cryptoki v2.11)                |  2.12.0 unreleased, Cryptoki v2.40                | [53]_                                             |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++| Gemalto IDPrime MD 3840             | mostly works                              | Windows 10, 64-bit, version 1709                  | IDGo 800, v1.2.4 (Cryptoki v2.20)                 |  2.4.0, Cryptoki v2.40                            | [54]_                                             |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++| SoftHSM 2.3.0 (OpenSSL 1.0.2g)      | works                                     | Windows 10, 64-bit, version 1709                  | Cryptoki v2.40                                    |  2.4.0, Cryptoki v2.40                            |                                                   |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------++| SoftHSM 2.5.0 (OpenSSL 1.1.1)       | works                                     | Windows 10, 64-bit, version 1803                  | Cryptoki v2.40                                    |  2.11.0, Cryptoki v2.40                           |                                                   |++-------------------------------------+-------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+---------------------------------------------------+++.. [50] Failing operations for CardOS 4.4:++ - object_copy [20]_++ - rsa_privkey_export [21]_+ - rsa_generate_private_key [22]_+ - rsa_sign_verify [23]_++ - ecdh_privkey_import [3]_+ - ecdh_privkey_export [2]_+ - ecdh_pubkey_import [4]_+ - ecdh_pubkey_export [4]_+ - ecdh_generate_private_key [3]_+ - ecdh_generate_keypair [3]_+ - ecdh_derive [3]_++ - ecdsa_privkey_import [3]_+ - ecdsa_privkey_export [2]_+ - ecdsa_pubkey_import [4]_+ - ecdsa_pubkey_export [4]_+ - ecdsa_generate_private_key  [3]_+ - ecdsa_generate_keypair  [3]_+ - ecdsa_sign_verify  [3]_++ - rng_add_entropy [5]_+++.. [51] Failing operations for CardOS 5.0++ - object_copy [20]_++ - rsa_privkey_export [21]_+ - rsa_generate_private_key [22]_+ - rsa_sign_verify [23]_++ - ecdh_privkey_export [2]_+ - ecdh_pubkey_import [4]_+ - ecdh_generate_private_key [32]_+ - ecdh_generate_keypair [3]_+ - ecdh_derive [33]_++ - ecdsa_privkey_export [2]_+ - ecdsa_generate_private_key  [30]_+ - ecdsa_generate_keypair  [30]_+ - ecdsa_sign_verify  [30]_++ - rng_add_entropy [5]_++.. [52] Failing operations for CardOS 5.3++ - object_copy [20]_++ - rsa_privkey_export [21]_+ - rsa_generate_private_key [22]_+ - rsa_sign_verify [23]_++ - ecdh_privkey_export [2]_+ - ecdh_pubkey_import [6]_+ - ecdh_pubkey_export [6]_+ - ecdh_generate_private_key [30]_+ - ecdh_generate_keypair [31]_+ - ecdh_derive [30]_++ - ecdsa_privkey_export [2]_+ - ecdsa_pubkey_import [6]_+ - ecdsa_pubkey_export [6]_+ - ecdsa_generate_private_key  [31]_+ - ecdsa_generate_keypair  [31]_+ - ecdsa_sign_verify  [34]_++ - rng_add_entropy [5]_++.. [53] Failing operations for CardOS 5.3 (middelware 5.5.1)++ - ecdh_privkey_export [2]_+ - ecdh_generate_private_key [35]_+ - ecdsa_privkey_export [2]_+ - ecdsa_generate_private_key [36]_+ - c_copy_object [4]_++ - object_copy [4]_++ - rng_add_entropy [5]_++ - rsa_sign_verify [3]_+ - rsa_privkey_export [2]_+ - rsa_generate_private_key [9]_++.. [54] Failing operations for Gemalto IDPrime MD 3840++ - session_login_logout [2]_+ - session_info [2]_+ - set_pin [2]_+ - initialize [2]_+ - change_so_pin [2]_++ - object_copy [20]_++ - rsa_generate_private_key [7]_+ - rsa_encrypt_decrypt [8]_+ - rsa_sign_verify [2]_++ - rng_add_entropy [5]_++Error descriptions++.. [2] CKR_ARGUMENTS_BAD (0x7=7)+.. [3] CKR_MECHANISM_INVALID (0x70=112)+.. [4] CKR_FUNCTION_NOT_SUPPORTED (0x54=84)+.. [5] CKR_RANDOM_SEED_NOT_SUPPORTED (0x120=288)+.. [6] CKM_X9_42_DH_KEY_PAIR_GEN | CKR_DEVICE_ERROR (0x30=48)+.. [7] CKR_TEMPLATE_INCONSISTENT (0xD1=209)+.. [8] CKR_ENCRYPTED_DATA_INVALID | CKM_SHA256_RSA_PKCS (0x40=64)+.. [9] CKR_TEMPLATE_INCOMPLETE (0xD0=208)++.. [20] Test fails due to unsupported copy function (CKR_FUNCTION_NOT_SUPPORTED)+.. [21] Generating private key for extraction with property extractable fails (CKR_ARGUMENTS_BAD)+.. [22] Generate rsa private key operation fails (CKR_TEMPLATE_INCOMPLETE)+.. [23] Raw RSA sign-verify fails (CKR_MECHANISM_INVALID)++.. [30] Invalid argument Decoding error: BER: Value truncated+.. [31] Invalid argument Decoding error: BER: Length field is to large+.. [32] Invalid argument OS2ECP: Unknown format type 155+.. [33] Invalid argument OS2ECP: Unknown format type 92+.. [34] Invalid argument OS2ECP: Unknown format type 57+.. [35] Invalid argument OS2ECP: Unknown format type 82+.. [36] Invalid argument OS2ECP: Unknown format type 102