Credentials

This module provides a common interface for operating on your shared credentials.

Usage

To use the library, make sure you have met the following prerequisites:

• You have a master key in KMS. You can create this under Identity and Access Management > Encryption Keys, in the AWS developer console.
• Your AWS access credentials are available where amazonka can find them. This will be automatic if you are running on an EC2 host, otherwise the ~/.aws/credentials file, as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables need to be configured.

Since all of the credentials operations are constrained by a MonadAWS context, running them is identical to that of amazonka, which you will also need to add to your build-depends section of your project's cabal file.

{-# LANGUAGE OverloadedStrings #-}

import Credentials
import Control.Lens
import Data.ByteString (ByteString)
import Network.AWS
import System.IO

example :: IO (ByteString, Revision)
example = do
    -- A new 'Logger' to replace the default noop logger is created,
    -- which will print AWS debug information and errors to stdout.
    lgr <- newLogger Debug stdout

    -- A new amazonka 'Env' is created, which auto-discovers the
    -- underlying host credentials.
    env <- newEnv Frankfurt Discover

    let table = "dynamo-table-name"
        key   = "kms-key-alias"
        name  = "credential-name"

    -- We now run the 'AWS' computation with the overriden logger,
    -- performing the sequence of credentials operations.
    runResourceT . runAWS (env & envLogger .~ lgr) $ do
        -- Firstly, we create the DynamoDB table.
        -- This is an idempotent operation but since it makes remote API calls,
        -- it's recommended you only run this once via the CLI.
        Credentials.setup table

        -- Then we insert a credential\'s value, for a given name.
        -- Encryption is handled transparently and the resulting revision
        -- is returned.
        _ <- Credentials.insert key mempty name "a-super-secret-value" table

        -- Selecting the credential by name, and specifying 'Nothing' for the
        -- revision results in the latest credential revision being returned.
        Credentials.select mempty name Nothing table

Operations

insert

Arguments

:: (MonadMask m, MonadAWS m, Typeable m)

=> KeyId

The KMS master key ARN or alias.

-> Context

The KMS encryption context.

-> Name

The credential name.

-> ByteString

The unencrypted plaintext.

-> DynamoTable

The DynamoDB table.

-> m Revision

Encrypt and insert a new credential revision with the specified name.

The newly inserted revision is returned.

select

Arguments

:: MonadAWS m

=> Context

The KMS encryption context that was used during insertion.

-> Name

The credential name.

-> Maybe Revision

A revision. If Nothing, the latest will be selected.

-> DynamoTable

The DynamoDB table.

-> m (ByteString, Revision)

Select an existing credential, optionally specifying the revision.

The decrypted plaintext and selected revision are returned.

delete

Arguments

:: MonadAWS m

=> Name

The credential name.

-> Revision

The revision to delete.

-> DynamoTable

The DynamoDB table.

-> m ()

Delete the specific credential revision.

truncate

Arguments

:: MonadAWS m

=> Name

The credential name.

-> DynamoTable

The DynamoDB table.

-> m ()

Truncate all of a credential's revisions, so that only the latest revision remains.

revisions

Arguments

:: MonadAWS m

=> DynamoTable

The DynamoDB table.

-> Source m (Name, NonEmpty Revision)

Scan the entire credential database, grouping pages of results into unique credential names and their corresponding revisions.

setup

Arguments

:: MonadAWS m

=> DynamoTable

The DynamoDB table.

-> m Setup

Create the credentials database table.

The returned idempotency flag can be used to notify configuration management tools such as ansible whether about system state.

teardown :: MonadAWS m => DynamoTable -> m ()

Delete the credentials database table and all data.

Note: Unless you have DynamoDB backups running, this is a completely irrevocable action.

KMS

newtype KeyId

The KMS master key identifier.

Constructors

KeyId Text

Instances

Eq KeyId

Methods

(==) :: KeyId -> KeyId -> Bool

(/=) :: KeyId -> KeyId -> Bool

Ord KeyId

Methods

compare :: KeyId -> KeyId -> Ordering

(<) :: KeyId -> KeyId -> Bool

(<=) :: KeyId -> KeyId -> Bool

(>) :: KeyId -> KeyId -> Bool

(>=) :: KeyId -> KeyId -> Bool

max :: KeyId -> KeyId -> KeyId

min :: KeyId -> KeyId -> KeyId

Show KeyId

Methods

showsPrec :: Int -> KeyId -> ShowS

show :: KeyId -> String

showList :: [KeyId] -> ShowS

ToText KeyId

Methods

toText :: KeyId -> Text

FromText KeyId

Methods

parser :: Parser KeyId

ToByteString KeyId

Methods

toBS :: KeyId -> ByteString

ToLog KeyId

Methods

build :: KeyId -> Builder

defaultKeyId :: KeyId

The default KMS master key alias.

Value: alias/credentials

DynamoDB

newtype DynamoTable

A DynamoDB table reference.

Constructors

DynamoTable

Fields

• tableName :: Text

Instances

Eq DynamoTable

Methods

(==) :: DynamoTable -> DynamoTable -> Bool

(/=) :: DynamoTable -> DynamoTable -> Bool

Ord DynamoTable

Methods

compare :: DynamoTable -> DynamoTable -> Ordering

(<) :: DynamoTable -> DynamoTable -> Bool

(<=) :: DynamoTable -> DynamoTable -> Bool

(>) :: DynamoTable -> DynamoTable -> Bool

(>=) :: DynamoTable -> DynamoTable -> Bool

max :: DynamoTable -> DynamoTable -> DynamoTable

min :: DynamoTable -> DynamoTable -> DynamoTable

Show DynamoTable

Methods

showsPrec :: Int -> DynamoTable -> ShowS

show :: DynamoTable -> String

showList :: [DynamoTable] -> ShowS

ToText DynamoTable

Methods

toText :: DynamoTable -> Text

FromText DynamoTable

Methods

parser :: Parser DynamoTable

ToByteString DynamoTable

Methods

toBS :: DynamoTable -> ByteString

ToLog DynamoTable

Methods

build :: DynamoTable -> Builder

defaultTable :: DynamoTable

The default DynamoDB table used to store credentials.

Value: credentials

Errors

data CredentialError

Constructors

MasterKeyMissing KeyId (Maybe Text)

The specified master key id doesn't exist.

IntegrityFailure Name ByteString ByteString

The computed HMAC doesn't matched the stored HMAC.

EncryptFailure Context Name Text

Failure occured during local encryption.

DecryptFailure Context Name Text

Failure occured during local decryption.

StorageMissing Text

Storage doesn't exist, or has gone on holiday.

StorageFailure Text

Some storage pre-condition wasn't met. For example: DynamoDB column size exceeded.

FieldMissing Text [Text]

Missing field from the storage engine.

FieldInvalid Text String

Unable to parse field from the storage engine.

SecretMissing Name (Maybe Revision) Text

Secret with the specified name cannot found.

OptimisticLockFailure Name Revision Text

Attempting to insert a revision that already exists.

Instances

Eq CredentialError

Methods

(==) :: CredentialError -> CredentialError -> Bool

(/=) :: CredentialError -> CredentialError -> Bool

Show CredentialError

Methods

showsPrec :: Int -> CredentialError -> ShowS

show :: CredentialError -> String

showList :: [CredentialError] -> ShowS

Exception CredentialError

Methods

toException :: CredentialError -> SomeException

fromException :: SomeException -> Maybe CredentialError

displayException :: CredentialError -> String

AsCredentialError CredentialError

Methods

_CredentialError :: Prism' CredentialError CredentialError

_MasterKeyMissing :: Prism' CredentialError (KeyId, Maybe Text)

_IntegrityFailure :: Prism' CredentialError (Name, ByteString, ByteString)

_EncryptFailure :: Prism' CredentialError (Context, Name, Text)

_DecryptFailure :: Prism' CredentialError (Context, Name, Text)

_StorageMissing :: Prism' CredentialError Text

_StorageFailure :: Prism' CredentialError Text

_FieldMissing :: Prism' CredentialError (Text, [Text])

_FieldInvalid :: Prism' CredentialError (Text, String)

_SecretMissing :: Prism' CredentialError (Name, Maybe Revision, Text)

_OptimisticLockFailure :: Prism' CredentialError (Name, Revision, Text)

class AsCredentialError a where

Methods

_CredentialError :: Prism' a CredentialError

_MasterKeyMissing :: Prism' a (KeyId, Maybe Text)

_IntegrityFailure :: Prism' a (Name, ByteString, ByteString)

_EncryptFailure :: Prism' a (Context, Name, Text)

_DecryptFailure :: Prism' a (Context, Name, Text)

_StorageMissing :: Prism' a Text

_StorageFailure :: Prism' a Text

_FieldMissing :: Prism' a (Text, [Text])

_FieldInvalid :: Prism' a (Text, String)

_SecretMissing :: Prism' a (Name, Maybe Revision, Text)

_OptimisticLockFailure :: Prism' a (Name, Revision, Text)

Instances

AsCredentialError SomeException

Methods

_CredentialError :: Prism' SomeException CredentialError

_MasterKeyMissing :: Prism' SomeException (KeyId, Maybe Text)

_IntegrityFailure :: Prism' SomeException (Name, ByteString, ByteString)

_EncryptFailure :: Prism' SomeException (Context, Name, Text)

_DecryptFailure :: Prism' SomeException (Context, Name, Text)

_StorageMissing :: Prism' SomeException Text

_StorageFailure :: Prism' SomeException Text

_FieldMissing :: Prism' SomeException (Text, [Text])

_FieldInvalid :: Prism' SomeException (Text, String)

_SecretMissing :: Prism' SomeException (Name, Maybe Revision, Text)

_OptimisticLockFailure :: Prism' SomeException (Name, Revision, Text)

AsCredentialError CredentialError

Methods

_CredentialError :: Prism' CredentialError CredentialError

_MasterKeyMissing :: Prism' CredentialError (KeyId, Maybe Text)

_IntegrityFailure :: Prism' CredentialError (Name, ByteString, ByteString)

_EncryptFailure :: Prism' CredentialError (Context, Name, Text)

_DecryptFailure :: Prism' CredentialError (Context, Name, Text)

_StorageMissing :: Prism' CredentialError Text

_StorageFailure :: Prism' CredentialError Text

_FieldMissing :: Prism' CredentialError (Text, [Text])

_FieldInvalid :: Prism' CredentialError (Text, String)

_SecretMissing :: Prism' CredentialError (Name, Maybe Revision, Text)

_OptimisticLockFailure :: Prism' CredentialError (Name, Revision, Text)

Types

newtype Name

A shared/readable name for a secret.

Constructors

Name Text

Instances

Eq Name

Methods

(==) :: Name -> Name -> Bool

(/=) :: Name -> Name -> Bool

Ord Name

Methods

compare :: Name -> Name -> Ordering

(<) :: Name -> Name -> Bool

(<=) :: Name -> Name -> Bool

(>) :: Name -> Name -> Bool

(>=) :: Name -> Name -> Bool

max :: Name -> Name -> Name

min :: Name -> Name -> Name

Show Name

Methods

showsPrec :: Int -> Name -> ShowS

show :: Name -> String

showList :: [Name] -> ShowS

ToText Name

Methods

toText :: Name -> Text

FromText Name

Methods

parser :: Parser Name

ToByteString Name

Methods

toBS :: Name -> ByteString

ToLog Name

Methods

build :: Name -> Builder

Attribute Name

Methods

toAttr :: Name -> AttributeValue

parseAttr :: AttributeValue -> Maybe Name

Item Name

Methods

toItem :: Name -> HashMap Text AttributeValue

parseItem :: HashMap Text AttributeValue -> Either CredentialError Name

newtype Revision

An opaque, non-monotonic revision number.

Constructors

Revision ByteString

Instances

Eq Revision

Methods

(==) :: Revision -> Revision -> Bool

(/=) :: Revision -> Revision -> Bool

Ord Revision

Methods

compare :: Revision -> Revision -> Ordering

(<) :: Revision -> Revision -> Bool

(<=) :: Revision -> Revision -> Bool

(>) :: Revision -> Revision -> Bool

(>=) :: Revision -> Revision -> Bool

max :: Revision -> Revision -> Revision

min :: Revision -> Revision -> Revision

Show Revision

Methods

showsPrec :: Int -> Revision -> ShowS

show :: Revision -> String

showList :: [Revision] -> ShowS

ToText Revision

Methods

toText :: Revision -> Text

FromText Revision

Methods

parser :: Parser Revision

ToByteString Revision

Methods

toBS :: Revision -> ByteString

ToLog Revision

Methods

build :: Revision -> Builder

Attribute Revision

Methods

toAttr :: Revision -> AttributeValue

parseAttr :: AttributeValue -> Maybe Revision

Item Revision

Methods

toItem :: Revision -> HashMap Text AttributeValue

parseItem :: HashMap Text AttributeValue -> Either CredentialError Revision

newtype Context

A KMS encryption context.

See: KMS Encryption Context documentation for more information.

Constructors

Context

Fields

• fromContext :: HashMap Text Text

Instances

Eq Context

Methods

(==) :: Context -> Context -> Bool

(/=) :: Context -> Context -> Bool

Show Context

Methods

showsPrec :: Int -> Context -> ShowS

show :: Context -> String

showList :: [Context] -> ShowS

Monoid Context

Methods

mempty :: Context

mappend :: Context -> Context -> Context

mconcat :: [Context] -> Context

data Setup

Denotes idempotency of an action. That is, whether an action resulted in any setup being performed.

Constructors

Created

Exists

Instances

Eq Setup

Methods

(==) :: Setup -> Setup -> Bool

(/=) :: Setup -> Setup -> Bool

Show Setup

Methods

showsPrec :: Int -> Setup -> ShowS

show :: Setup -> String

showList :: [Setup] -> ShowS

ToText Setup

Methods

toText :: Setup -> Text

ToLog Setup

Methods

build :: Setup -> Builder