crypto-api-0.8: A generic interface for cryptographic operations

Portability | portable
Stability | beta
Maintainer | Thomas.DuBuisson@gmail.com

Crypto.Padding

Contents

- PKCS5 (RFC 1423) based [un]padding routines
- ESP (RFC 4303) [un]padding routines

Description

PKCS5 (RFC 1423) and IPSec ESP (RFC 4303) padding methods are implemented both as trivial functions operating on bytestrings and as `Put` routines usable from the Data.Serialize module. These methods do not work for algorithms or pad sizes in excess of 255 bytes (2040 bits, so extremely large as far as cipher needs are concerned).

Synopsis

- padPKCS5 :: ByteLength -> ByteString -> ByteString
- padBlockSize :: BlockCipher k => k -> ByteString -> ByteString
- putPaddedPKCS5 :: ByteLength -> ByteString -> Put
- unpadPKCS5safe :: ByteString -> Maybe ByteString
- unpadPKCS5 :: ByteString -> ByteString
- padESP :: Int -> ByteString -> ByteString
- unpadESP :: ByteString -> Maybe ByteString
- padESPBlockSize :: BlockCipher k => k -> ByteString -> ByteString
- putPadESPBlockSize :: BlockCipher k => k -> ByteString -> Put
- putPadESP :: Int -> ByteString -> Put

# PKCS5 (RFC 1423) based [un]padding routines

padPKCS5 :: ByteLength -> ByteString -> ByteString

PKCS5 (aka RFC1423) padding method. This method will not work properly for pad modulos > 256

padBlockSize :: BlockCipher k => k -> ByteString -> ByteString

PKCS5 (aka RFC1423) padding method using the BlockCipher instance to determine the pad size.

putPaddedPKCS5 :: ByteLength -> ByteString -> Put

Ex:

         putPaddedPKCS5 m bs

Will pad out `bs` to a byte multiple of `m` and put both the bytestring and it's padding via `Put` (this saves on copying if you are already using Cereal).

unpadPKCS5safe :: ByteString -> Maybe ByteString

unpad a strict bytestring padded in the typical PKCS5 manner. This routine verifies all pad bytes and pad length match correctly.

unpadPKCS5 :: ByteString -> ByteString

unpad a strict bytestring without checking the pad bytes and length any more than necessary.

# ESP (RFC 4303) [un]padding routines

padESP :: Int -> ByteString -> ByteString

Pad a bytestring to the IPSEC esp specification

     padESP m payload

is equivilent to:

                   (msg)       (padding)       (length field)
         B.concat [payload, B.pack [1,2,3,4..], B.pack [padLen]]

Where:

- the msg is any payload, including TFC.
- the padding is <= 255
- the length field is one byte.

Notice the result bytesting length remainder `r` equals zero. The lack of a "next header" field means this function is not directly useable for an IPSec implementation (copy/paste the 4 line function and add in a "next header" field if you are making IPSec ESP).

unpadESP :: ByteString -> Maybe ByteString

A static espPad allows reuse of a single B.pack'ed pad for all calls to padESP

unpad and return the padded message (Nothing is returned if the padding is invalid)

padESPBlockSize :: BlockCipher k => k -> ByteString -> ByteString

Like padESP but use the BlockCipher instance to determine padding size

putPadESPBlockSize :: BlockCipher k => k -> ByteString -> Put

Like putPadESP but using the BlockCipher instance to determine padding size

putPadESP :: Int -> ByteString -> Put

Pad a bytestring to the IPSEC ESP specification using `Put`. This can reduce copying if you are already using `Put`.