HsOpenSSL-0.10.3: (Incomplete) OpenSSL binding for Haskell

Safe HaskellSafe-Infered

OpenSSL.BIO

Contents

Description

A BIO is an I/O abstraction, it hides many of the underlying I/O details from an application, if you are writing a pure C application...

I know, we are hacking on Haskell so BIO components like BIO_s_file are hardly needed. But for filter BIOs, such as BIO_f_base64 and BIO_f_cipher, they should be useful too to us.

Synopsis

Type

data BIO Source

BIO is a ForeignPtr to an opaque BIO object. They are created by newXXX actions.

withBioPtr :: BIO -> (Ptr BIO_ -> IO a) -> IO aSource

withBioPtr' :: Maybe BIO -> (Ptr BIO_ -> IO a) -> IO aSource

BIO chaning

bioPush :: BIO -> BIO -> IO ()Source

Computation of bioPush a b connects b behind a.

Example:

 do b64 <- newBase64 True
    mem <- newMem
    bioPush b64 mem

    -- Encode some text in Base64 and write the result to the
    -- memory buffer.
    bioWrite b64 "Hello, world!"
    bioFlush b64

    -- Then dump the memory buffer.
    bioRead mem >>= putStrLn

(==>) :: BIO -> BIO -> IO ()Source

a ==> b is an alias to bioPush a b.

(<==) :: BIO -> BIO -> IO ()Source

a <== b is an alias to bioPush b a.

bioJoin :: [BIO] -> IO ()Source

bioJoin [bio1, bio2, ..] connects many BIOs at once.

BIO control operations

bioFlush :: BIO -> IO ()Source

bioFlush bio normally writes out any internally buffered data, in some cases it is used to signal EOF and that no more data will be written.

bioReset :: BIO -> IO ()Source

bioReset bio typically resets a BIO to some initial state.

bioEOF :: BIO -> IO BoolSource

bioEOF bio returns 1 if bio has read EOF, the precise meaning of EOF varies according to the BIO type.

BIO I/O functions

bioRead :: BIO -> IO StringSource

bioRead bio lazily reads all data in bio.

bioReadBS :: BIO -> Int -> IO ByteStringSource

bioReadBS bio len attempts to read len bytes from bio, then return a ByteString. The actual length of result may be less than len.

bioReadLBS :: BIO -> IO ByteStringSource

bioReadLBS bio lazily reads all data in bio, then return a LazyByteString.

bioGets :: BIO -> Int -> IO StringSource

bioGets bio len normally attempts to read one line of data from bio of maximum length len. There are exceptions to this however, for example bioGets on a digest BIO will calculate and return the digest and other BIOs may not support bioGets at all.

bioGetsBS :: BIO -> Int -> IO ByteStringSource

bioGetsBS does the same as bioGets but returns ByteString.

bioGetsLBS :: BIO -> Int -> IO ByteStringSource

bioGetsLBS does the same as bioGets but returns LazyByteString.

bioWrite :: BIO -> String -> IO ()Source

bioWrite bio str lazily writes entire str to bio. The string doesn't necessarily have to be finite.

bioWriteBS :: BIO -> ByteString -> IO ()Source

bioWriteBS bio bs writes bs to bio.

bioWriteLBS :: BIO -> ByteString -> IO ()Source

bioWriteLBS bio lbs lazily writes entire lbs to bio. The string doesn't necessarily have to be finite.

Base64 BIO filter

newBase64 :: Bool -> IO BIOSource

newBase64 noNL creates a Base64 BIO filter. This is a filter bio that base64 encodes any data written through it and decodes any data read through it.

If noNL flag is True, the filter encodes the data all on one line or expects the data to be all on one line.

Base64 BIOs do not support bioGets.

bioFlush on a Base64 BIO that is being written through is used to signal that no more data is to be encoded: this is used to flush the final block through the BIO.

Buffering BIO filter

newBufferSource

Arguments

:: Maybe Int

Explicit buffer size (Just n) or the default size (Nothing).

-> IO BIO 

newBuffer mBufSize creates a buffering BIO filter. Data written to a buffering BIO is buffered and periodically written to the next BIO in the chain. Data read from a buffering BIO comes from the next BIO in the chain.

Buffering BIOs support bioGets.

Calling bioReset on a buffering BIO clears any buffered data.

Question: When I created a BIO chain like this and attempted to read from the buf, the buffering BIO weirdly behaved: BIO_read() returned nothing, but both BIO_eof() and BIO_should_retry() returned zero. I tried to examine the source code of crypto/bio/bf_buff.c but it was too complicated to understand. Does anyone know why this happens? The version of OpenSSL was 0.9.7l.

 main = withOpenSSL $
        do mem <- newConstMem "Hello, world!"
           buf <- newBuffer Nothing
           mem ==> buf

           bioRead buf >>= putStrLn -- This fails, but why?

I am being depressed for this unaccountable failure.

Memory BIO sink/source

newMem :: IO BIOSource

newMem creates a memory BIO sink/source. Any data written to a memory BIO can be recalled by reading from it. Unless the memory BIO is read only any data read from it is deleted from the BIO.

Memory BIOs support bioGets.

Calling bioReset on a read write memory BIO clears any data in it. On a read only BIO it restores the BIO to its original state and the read only data can be read again.

bioEOF is true if no data is in the BIO.

Every read from a read write memory BIO will remove the data just read with an internal copy operation, if a BIO contains a lots of data and it is read in small chunks the operation can be very slow. The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a buffering BIO (newBuffer) to the chain will speed up the process.

newConstMem :: String -> IO BIOSource

newConstMem str creates a read-only memory BIO source.

newConstMemBS :: ByteString -> IO BIOSource

newConstMemBS bs is like newConstMem but takes a ByteString.

newConstMemLBS :: ByteString -> IO BIOSource

newConstMemLBS lbs is like newConstMem but takes a LazyByteString.

Null data BIO sink/source

newNullBIO :: IO BIOSource

newNullBIO creates a null BIO sink/source. Data written to the null sink is discarded, reads return EOF.

A null sink is useful if, for example, an application wishes to digest some data by writing through a digest bio but not send the digested data anywhere. Since a BIO chain must normally include a source/sink BIO this can be achieved by adding a null sink BIO to the end of the chain.