-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Secure Credentials Storage and Distribution
--   
--   This library provides a unified interface for managing secure, shared
--   credentials. It uses Amazon Key Management Service (KMS) for master
--   key management, locally encrypts and decrypts secrets, which are then
--   stored in any of the supported storage backends. (Currently DynamoDB.)
--   
--   The use-case is to avoid storing sensitive information such as
--   passwords and connection strings in plaintext in places such as source
--   control or on developers' machines. Instead you can securely
--   administer and distribute secrets, leveraging Amazon's IAM policies
--   for access control and permissions to ensure limited read-only
--   permissions from production/deployed hosts. You can embed this library
--   into projects such as web applications to securely retrieve sensitive
--   information such as database passwords or private keys on startup.
--   
--   A complementary CLI for management of credentials can be installed via
--   <a>credentials-cli</a>.
--   
--   You can read more about other use-cases and prerequisites <a>here</a>.
@package credentials
@version 0.0.2


module Credentials.Types

-- | The KMS master key identifier.
newtype KeyId
KeyId :: Text -> KeyId

-- | The default KMS master key alias.
--   
--   <i>Value:</i> <tt>alias/credentials</tt>
defaultKeyId :: KeyId

-- | A shared/readable name for a secret.
newtype Name
Name :: Text -> Name

-- | An opaque, non-monotonic revision number.
newtype Revision
Revision :: ByteString -> Revision

-- | A KMS encryption context.
--   
--   <i>See:</i> KMS <a>Encryption Context</a> documentation for more
--   information.
newtype Context
Context :: HashMap Text Text -> Context
[fromContext] :: Context -> HashMap Text Text

-- | The encryption parameters required to perform decryption.
data Encrypted
Encrypted :: !ByteString -> !ByteString -> !(HMAC SHA256) -> Encrypted

-- | The wrapped (encrypted) data encryption key.
[wrappedKey] :: Encrypted -> !ByteString

-- | The encrypted ciphertext.
[ciphertext] :: Encrypted -> !ByteString

-- | HMAC SHA256 digest of the ciphertext.
[digest] :: Encrypted -> !(HMAC SHA256)

-- | Denotes idempotency of an action. That is, whether an action resulted
--   in any setup being performed.
data Setup
Created :: Setup
Exists :: Setup
data CredentialError

-- | The specified master key id doesn't exist.
MasterKeyMissing :: KeyId -> (Maybe Text) -> CredentialError

-- | The computed HMAC doesn't matched the stored HMAC.
IntegrityFailure :: Name -> ByteString -> ByteString -> CredentialError

-- | Failure occured during local encryption.
EncryptFailure :: Context -> Name -> Text -> CredentialError

-- | Failure occured during local decryption.
DecryptFailure :: Context -> Name -> Text -> CredentialError

-- | Storage doesn't exist, or has gone on holiday.
StorageMissing :: Text -> CredentialError

-- | Some storage pre-condition wasn't met. For example: DynamoDB column
--   size exceeded.
StorageFailure :: Text -> CredentialError

-- | Missing field from the storage engine.
FieldMissing :: Text -> [Text] -> CredentialError

-- | Unable to parse field from the storage engine.
FieldInvalid :: Text -> String -> CredentialError

-- | Secret with the specified name cannot found.
SecretMissing :: Name -> (Maybe Revision) -> Text -> CredentialError

-- | Attempting to insert a revision that already exists.
OptimisticLockFailure :: Name -> Revision -> Text -> CredentialError
class AsCredentialError a where _MasterKeyMissing = (.) _CredentialError _MasterKeyMissing _IntegrityFailure = (.) _CredentialError _IntegrityFailure _EncryptFailure = (.) _CredentialError _EncryptFailure _DecryptFailure = (.) _CredentialError _DecryptFailure _StorageMissing = (.) _CredentialError _StorageMissing _StorageFailure = (.) _CredentialError _StorageFailure _FieldMissing = (.) _CredentialError _FieldMissing _FieldInvalid = (.) _CredentialError _FieldInvalid _SecretMissing = (.) _CredentialError _SecretMissing _OptimisticLockFailure = (.) _CredentialError _OptimisticLockFailure
_CredentialError :: AsCredentialError a => Prism' a CredentialError
_MasterKeyMissing :: AsCredentialError a => Prism' a (KeyId, Maybe Text)
_IntegrityFailure :: AsCredentialError a => Prism' a (Name, ByteString, ByteString)
_EncryptFailure :: AsCredentialError a => Prism' a (Context, Name, Text)
_DecryptFailure :: AsCredentialError a => Prism' a (Context, Name, Text)
_StorageMissing :: AsCredentialError a => Prism' a Text
_StorageFailure :: AsCredentialError a => Prism' a Text
_FieldMissing :: AsCredentialError a => Prism' a (Text, [Text])
_FieldInvalid :: AsCredentialError a => Prism' a (Text, String)
_SecretMissing :: AsCredentialError a => Prism' a (Name, Maybe Revision, Text)
_OptimisticLockFailure :: AsCredentialError a => Prism' a (Name, Revision, Text)
instance GHC.Show.Show Credentials.Types.CredentialError
instance GHC.Classes.Eq Credentials.Types.CredentialError
instance GHC.Show.Show Credentials.Types.Setup
instance GHC.Classes.Eq Credentials.Types.Setup
instance GHC.Base.Monoid Credentials.Types.Context
instance GHC.Show.Show Credentials.Types.Context
instance GHC.Classes.Eq Credentials.Types.Context
instance Network.AWS.Data.Log.ToLog Credentials.Types.Revision
instance Network.AWS.Data.ByteString.ToByteString Credentials.Types.Revision
instance Network.AWS.Data.Text.ToText Credentials.Types.Revision
instance Network.AWS.Data.Text.FromText Credentials.Types.Revision
instance GHC.Show.Show Credentials.Types.Revision
instance GHC.Classes.Ord Credentials.Types.Revision
instance GHC.Classes.Eq Credentials.Types.Revision
instance Network.AWS.Data.Log.ToLog Credentials.Types.Name
instance Network.AWS.Data.ByteString.ToByteString Credentials.Types.Name
instance Network.AWS.Data.Text.ToText Credentials.Types.Name
instance Network.AWS.Data.Text.FromText Credentials.Types.Name
instance GHC.Show.Show Credentials.Types.Name
instance GHC.Classes.Ord Credentials.Types.Name
instance GHC.Classes.Eq Credentials.Types.Name
instance Network.AWS.Data.Log.ToLog Credentials.Types.KeyId
instance Network.AWS.Data.ByteString.ToByteString Credentials.Types.KeyId
instance Network.AWS.Data.Text.ToText Credentials.Types.KeyId
instance Network.AWS.Data.Text.FromText Credentials.Types.KeyId
instance GHC.Show.Show Credentials.Types.KeyId
instance GHC.Classes.Ord Credentials.Types.KeyId
instance GHC.Classes.Eq Credentials.Types.KeyId
instance Network.AWS.Data.Text.ToText Credentials.Types.Setup
instance Network.AWS.Data.Log.ToLog Credentials.Types.Setup
instance GHC.Exception.Exception Credentials.Types.CredentialError
instance Credentials.Types.AsCredentialError Credentials.Types.CredentialError
instance Credentials.Types.AsCredentialError GHC.Exception.SomeException


-- | Encryption and decryption of local data, by using a wrapped key
--   mechanism and master keys stored in KMS.
--   
--   See the <a>Credentials</a> module for usage information.
module Credentials.KMS

-- | Encrypt a plaintext <a>ByteString</a> with the given master key and
--   encryption context. The <a>Name</a> is used to annotate error
--   messages.
--   
--   The wrapped data encryption key, ciphertext, and HMAC SHA256 are
--   returned if no error occurs.
encrypt :: (MonadAWS m, Typeable m) => KeyId -> Context -> Name -> ByteString -> m Encrypted

-- | Decrypt ciphertext using the given encryption context, and wrapped
--   data encryption key. The HMAC SHA256 is recalculated and compared for
--   message integrity. The <a>Name</a> is used to annotate error messages.
--   
--   The resulting unencrypted plaintext <a>ByteString</a> is returned if
--   no error occurs.
decrypt :: MonadAWS m => Context -> Name -> Encrypted -> m ByteString


-- | This module contains the schema that is used by
--   <a>Credentials.DynamoDB</a> to serialise encryption parameters to
--   DynamoDB items.
module Credentials.DynamoDB.Item
padding :: Text

-- | The DynamoDB field used for optimistic locking.
--   
--   Serialisation of <a>Version</a> handles left-padding to support
--   consistent lexicographic ordering when used as a range in DynamoDB.
newtype Version
Version :: Integer -> Version
equals :: Item a => a -> HashMap Text Condition
nameField :: Text
revisionField :: Text
versionField :: Text
wrappedKeyField :: Text
ciphertextField :: Text
digestField :: Text
class Item a

-- | Encode an item as a set of attributes including their schema.
toItem :: Item a => a -> HashMap Text AttributeValue

-- | Decode an item from a set of attributes.
parseItem :: Item a => HashMap Text AttributeValue -> Either CredentialError a

-- | Decode an item by throwing a <a>CredentialError</a> exception when an
--   error is encountered.
fromItem :: (MonadThrow m, Item a) => HashMap Text AttributeValue -> m a
parse :: Attribute a => Text -> HashMap Text AttributeValue -> Either CredentialError a
class Attribute a

-- | Encode an attribute value.
toAttr :: Attribute a => a -> AttributeValue

-- | Decode an attribute value.
parseAttr :: Attribute a => AttributeValue -> Maybe a
instance Network.AWS.Data.Text.ToText Credentials.DynamoDB.Item.Version
instance Network.AWS.Data.Text.FromText Credentials.DynamoDB.Item.Version
instance GHC.Num.Num Credentials.DynamoDB.Item.Version
instance GHC.Classes.Ord Credentials.DynamoDB.Item.Version
instance GHC.Classes.Eq Credentials.DynamoDB.Item.Version
instance (Credentials.DynamoDB.Item.Item a, Credentials.DynamoDB.Item.Item b) => Credentials.DynamoDB.Item.Item (a, b)
instance Credentials.DynamoDB.Item.Item Credentials.Types.Name
instance Credentials.DynamoDB.Item.Item Credentials.Types.Revision
instance Credentials.DynamoDB.Item.Item Credentials.DynamoDB.Item.Version
instance Credentials.DynamoDB.Item.Item Credentials.Types.Encrypted
instance Credentials.DynamoDB.Item.Attribute Data.Text.Internal.Text
instance Credentials.DynamoDB.Item.Attribute Data.ByteString.Internal.ByteString
instance Credentials.DynamoDB.Item.Attribute Credentials.Types.Name
instance Credentials.DynamoDB.Item.Attribute Credentials.Types.Revision
instance Credentials.DynamoDB.Item.Attribute GHC.Integer.Type.Integer
instance Credentials.DynamoDB.Item.Attribute Credentials.DynamoDB.Item.Version
instance Credentials.DynamoDB.Item.Attribute (Crypto.MAC.HMAC.HMAC Crypto.Hash.SHA256.SHA256)


-- | Provides the implementation for storage and retrieval of encrypted
--   credentials in DynamoDB. The encryption and decryption is handled by
--   <a>Credentials.KMS</a>.
--   
--   See the <a>Credentials</a> module for usage information.
module Credentials.DynamoDB

-- | A DynamoDB table reference.
newtype DynamoTable
DynamoTable :: Text -> DynamoTable
[tableName] :: DynamoTable -> Text

-- | The default DynamoDB table used to store credentials.
--   
--   <i>Value:</i> <tt>credentials</tt>
defaultTable :: DynamoTable

-- | Encrypt and insert a new credential revision with the specified name.
--   
--   The newly inserted revision is returned.
insert :: (MonadMask m, MonadAWS m, Typeable m) => KeyId -> Context -> Name -> ByteString -> DynamoTable -> m Revision

-- | Select an existing credential, optionally specifying the revision.
--   
--   The decrypted plaintext and selected revision are returned.
select :: MonadAWS m => Context -> Name -> Maybe Revision -> DynamoTable -> m (ByteString, Revision)

-- | Delete the specific credential revision.
delete :: MonadAWS m => Name -> Revision -> DynamoTable -> m ()

-- | Truncate all of a credential's revisions, so that only the latest
--   revision remains.
truncate :: MonadAWS m => Name -> DynamoTable -> m ()

-- | Scan the entire credential database, grouping pages of results into
--   unique credential names and their corresponding revisions.
revisions :: MonadAWS m => DynamoTable -> Source m (Name, NonEmpty Revision)

-- | Create the credentials database table.
--   
--   The returned idempotency flag can be used to notify configuration
--   management tools such as ansible whether about system state.
setup :: MonadAWS m => DynamoTable -> m Setup

-- | Delete the credentials database table and all data.
--   
--   <i>Note:</i> Unless you have DynamoDB backups running, this is a
--   completely irrevocable action.
teardown :: MonadAWS m => DynamoTable -> m ()
instance Network.AWS.Data.Log.ToLog Credentials.DynamoDB.DynamoTable
instance Network.AWS.Data.ByteString.ToByteString Credentials.DynamoDB.DynamoTable
instance Network.AWS.Data.Text.ToText Credentials.DynamoDB.DynamoTable
instance Network.AWS.Data.Text.FromText Credentials.DynamoDB.DynamoTable
instance GHC.Show.Show Credentials.DynamoDB.DynamoTable
instance GHC.Classes.Ord Credentials.DynamoDB.DynamoTable
instance GHC.Classes.Eq Credentials.DynamoDB.DynamoTable


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

-- | Encrypt and insert a new credential revision with the specified name.
--   
--   The newly inserted revision is returned.
insert :: (MonadMask m, MonadAWS m, Typeable m) => KeyId -> Context -> Name -> ByteString -> DynamoTable -> m Revision

-- | Select an existing credential, optionally specifying the revision.
--   
--   The decrypted plaintext and selected revision are returned.
select :: MonadAWS m => Context -> Name -> Maybe Revision -> DynamoTable -> m (ByteString, Revision)

-- | Delete the specific credential revision.
delete :: MonadAWS m => Name -> Revision -> DynamoTable -> m ()

-- | Truncate all of a credential's revisions, so that only the latest
--   revision remains.
truncate :: MonadAWS m => Name -> DynamoTable -> m ()

-- | Scan the entire credential database, grouping pages of results into
--   unique credential names and their corresponding revisions.
revisions :: MonadAWS m => DynamoTable -> Source m (Name, NonEmpty Revision)

-- | Create the credentials database table.
--   
--   The returned idempotency flag can be used to notify configuration
--   management tools such as ansible whether about system state.
setup :: MonadAWS m => DynamoTable -> m Setup

-- | Delete the credentials database table and all data.
--   
--   <i>Note:</i> Unless you have DynamoDB backups running, this is a
--   completely irrevocable action.
teardown :: MonadAWS m => DynamoTable -> m ()

-- | The KMS master key identifier.
newtype KeyId
KeyId :: Text -> KeyId

-- | The default KMS master key alias.
--   
--   <i>Value:</i> <tt>alias/credentials</tt>
defaultKeyId :: KeyId

-- | A DynamoDB table reference.
newtype DynamoTable
DynamoTable :: Text -> DynamoTable
[tableName] :: DynamoTable -> Text

-- | The default DynamoDB table used to store credentials.
--   
--   <i>Value:</i> <tt>credentials</tt>
defaultTable :: DynamoTable
data CredentialError

-- | The specified master key id doesn't exist.
MasterKeyMissing :: KeyId -> (Maybe Text) -> CredentialError

-- | The computed HMAC doesn't matched the stored HMAC.
IntegrityFailure :: Name -> ByteString -> ByteString -> CredentialError

-- | Failure occured during local encryption.
EncryptFailure :: Context -> Name -> Text -> CredentialError

-- | Failure occured during local decryption.
DecryptFailure :: Context -> Name -> Text -> CredentialError

-- | Storage doesn't exist, or has gone on holiday.
StorageMissing :: Text -> CredentialError

-- | Some storage pre-condition wasn't met. For example: DynamoDB column
--   size exceeded.
StorageFailure :: Text -> CredentialError

-- | Missing field from the storage engine.
FieldMissing :: Text -> [Text] -> CredentialError

-- | Unable to parse field from the storage engine.
FieldInvalid :: Text -> String -> CredentialError

-- | Secret with the specified name cannot found.
SecretMissing :: Name -> (Maybe Revision) -> Text -> CredentialError

-- | Attempting to insert a revision that already exists.
OptimisticLockFailure :: Name -> Revision -> Text -> CredentialError
class AsCredentialError a where _MasterKeyMissing = (.) _CredentialError _MasterKeyMissing _IntegrityFailure = (.) _CredentialError _IntegrityFailure _EncryptFailure = (.) _CredentialError _EncryptFailure _DecryptFailure = (.) _CredentialError _DecryptFailure _StorageMissing = (.) _CredentialError _StorageMissing _StorageFailure = (.) _CredentialError _StorageFailure _FieldMissing = (.) _CredentialError _FieldMissing _FieldInvalid = (.) _CredentialError _FieldInvalid _SecretMissing = (.) _CredentialError _SecretMissing _OptimisticLockFailure = (.) _CredentialError _OptimisticLockFailure
_CredentialError :: AsCredentialError a => Prism' a CredentialError
_MasterKeyMissing :: AsCredentialError a => Prism' a (KeyId, Maybe Text)
_IntegrityFailure :: AsCredentialError a => Prism' a (Name, ByteString, ByteString)
_EncryptFailure :: AsCredentialError a => Prism' a (Context, Name, Text)
_DecryptFailure :: AsCredentialError a => Prism' a (Context, Name, Text)
_StorageMissing :: AsCredentialError a => Prism' a Text
_StorageFailure :: AsCredentialError a => Prism' a Text
_FieldMissing :: AsCredentialError a => Prism' a (Text, [Text])
_FieldInvalid :: AsCredentialError a => Prism' a (Text, String)
_SecretMissing :: AsCredentialError a => Prism' a (Name, Maybe Revision, Text)
_OptimisticLockFailure :: AsCredentialError a => Prism' a (Name, Revision, Text)

-- | A shared/readable name for a secret.
newtype Name
Name :: Text -> Name

-- | An opaque, non-monotonic revision number.
newtype Revision
Revision :: ByteString -> Revision

-- | A KMS encryption context.
--   
--   <i>See:</i> KMS <a>Encryption Context</a> documentation for more
--   information.
newtype Context
Context :: HashMap Text Text -> Context
[fromContext] :: Context -> HashMap Text Text

-- | Denotes idempotency of an action. That is, whether an action resulted
--   in any setup being performed.
data Setup
Created :: Setup
Exists :: Setup