gi-glib-2.0.29: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.GLib.Structs.Hmac

Contents

- Exported types
- Methods
  - copy
  - getDigest
  - getString
  - new
  - ref
  - unref
  - update

Description

HMACs should be used when producing a cookie or hash based on data and a key. Simple mechanisms for using SHA1 and other algorithms to digest a key and data together are vulnerable to various security issues. HMAC uses algorithms like SHA1 in a secure way to produce a digest of a key and data.

Both the key and data are arbitrary byte arrays of bytes or characters.

Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 in GLib 2.42. Support for SHA-384 was added in GLib 2.52.

To create a new `GHmac`, use `hmacNew`. To free a `GHmac`, use `hmacUnref`.

Since: 2.30

Synopsis

- newtype Hmac = Hmac (ManagedPtr Hmac)
- hmacCopy :: (HasCallStack, MonadIO m) => Hmac -> m Hmac
- hmacGetDigest :: (HasCallStack, MonadIO m) => Hmac -> ByteString -> m ()
- hmacGetString :: (HasCallStack, MonadIO m) => Hmac -> m Text
- hmacNew :: (HasCallStack, MonadIO m) => ChecksumType -> ByteString -> m (Maybe Hmac)
- hmacRef :: (HasCallStack, MonadIO m) => Hmac -> m Hmac
- hmacUnref :: (HasCallStack, MonadIO m) => Hmac -> m ()
- hmacUpdate :: (HasCallStack, MonadIO m) => Hmac -> ByteString -> m ()

# Exported types

newtype Hmac Source #

Memory-managed wrapper type.

Constructors

Hmac (ManagedPtr Hmac) |

#### Instances

Instances details

Eq Hmac Source # |
Instance details Defined in GI.GLib.Structs.Hmac Methods (==) :: Hmac -> Hmac -> Bool Source # (/=) :: Hmac -> Hmac -> Bool Source #
GBoxed Hmac Source # |
Instance details Defined in GI.GLib.Structs.Hmac
ManagedPtrNewtype Hmac Source # |
Instance details Defined in GI.GLib.Structs.Hmac Methods toManagedPtr :: Hmac -> ManagedPtr Hmac Source #
TypedObject Hmac Source # |
Instance details Defined in GI.GLib.Structs.Hmac Methods glibType :: IO GType Source #
HasParentTypes Hmac Source # |
Instance details Defined in GI.GLib.Structs.Hmac
IsGValue (Maybe Hmac) Source # | Convert `Hmac` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.GLib.Structs.Hmac Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Hmac -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Hmac) Source #
type ParentTypes Hmac Source # |
Instance details Defined in GI.GLib.Structs.Hmac type ParentTypes Hmac = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

copy, ref, unref, update.

#### Getters

getDigest, getString.

#### Setters

None.

## copy

hmacCopy Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Hmac | `hmac`: the `Hmac` to copy
-> m Hmac | Returns: the copy of the passed `Hmac`. Use `hmacUnref` when finished using it.

Copies a `Hmac`. If `hmac` has been closed, by calling `hmacGetString` or `hmacGetDigest`, the copied HMAC will be closed as well.

Since: 2.30

## getDigest

hmacGetDigest Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Hmac | `hmac`: a `Hmac`
-> ByteString | `buffer`: output buffer
-> m () |

Gets the digest from `checksum` as a raw binary array and places it into `buffer`. The size of the digest depends on the type of checksum.

Once this function has been called, the `Hmac` is closed and can no longer be updated with `checksumUpdate`.

Since: 2.30

## getString

hmacGetString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Hmac | `hmac`: a `Hmac`
-> m Text | Returns: the hexadecimal representation of the HMAC. The returned string is owned by the HMAC and should not be modified or freed.

Gets the HMAC as a hexadecimal string.

Once this function has been called the `Hmac` can no longer be updated with `hmacUpdate`.

The hexadecimal characters will be lower case.

Since: 2.30

## new

hmacNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> ChecksumType | `digestType`: the desired type of digest
-> ByteString | `key`: the key for the HMAC
-> m (Maybe Hmac) | Returns: the newly created `Hmac`, or `Nothing`. Use `hmacUnref` to free the memory allocated by it.

Creates a new `Hmac`, using the digest algorithm `digestType`. If the `digestType` is not known, `Nothing` is returned. A `Hmac` can be used to compute the HMAC of a key and an arbitrary binary blob, using different hashing algorithms.

A `Hmac` works by feeding a binary blob through `hmacUpdate` until the data is complete; the digest can then be extracted using `hmacGetString`, which will return the checksum as a hexadecimal string; or `hmacGetDigest`, which will return a array of raw bytes. Once either `hmacGetString` or `hmacGetDigest` have been called on a `Hmac`, the HMAC will be closed and it won't be possible to call `hmacUpdate` on it anymore.

Support for digests of type `ChecksumTypeSha512` has been added in GLib 2.42. Support for `ChecksumTypeSha384` was added in GLib 2.52.

Since: 2.30

## ref

hmacRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Hmac | `hmac`: a valid `Hmac`
-> m Hmac | Returns: the passed in `Hmac`.

Atomically increments the reference count of `hmac` by one.

This function is MT-safe and may be called from any thread.

Since: 2.30

## unref

hmacUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Hmac | `hmac`: a `Hmac`
-> m () |

Atomically decrements the reference count of `hmac` by one.

If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. Frees the memory allocated for `hmac`.

Since: 2.30

## update

hmacUpdate Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Hmac | `hmac`: a `Hmac`
-> ByteString | `data`: buffer used to compute the checksum
-> m () |

Feeds `data` into an existing `Hmac`.

The HMAC must still be open, that is `hmacGetString` or `hmacGetDigest` must not have been called on `hmac`.

Since: 2.30