BlitzMax

BlitzMax

  • Downloads
  • Docs
  • API
  • Resources
  • About

›Crypto

BlitzMax API

  • Introduction

BRL

    Audio

    • Introduction
    • TChannel
    • TSound

    AudioSample

    • Introduction
    • TAudioSample
    • TAudioSampleLoader

    Bank

    • Introduction
    • TBank

    BankStream

    • Introduction
    • TBankStream

    Base64

    • Introduction
    • TBase64

    Blitz

    • Introduction
    • TArrayBoundsException
    • TBlitzException
    • TNullFunctionException
    • TNullMethodException
    • TNullObjectException
    • TOutOfDataException
    • TRuntimeException
  • BRL.BMPLoader
  • Clipboard

    • Introduction
    • TClipboard
    • TClipboardOpts
    • TWin32ClipboardOpts
    • TX11ClipboardOpts
  • BRL.D3D7Max2D
  • BRL.D3D9Max2D
  • BRL.DirectSoundAudio
  • BRL.EndianStream
  • Event

    • Introduction
    • TEvent
  • BRL.EventQueue
  • BRL.FileSystem
  • BRL.FreeAudioAudio
  • BRL.GLGraphics
  • BRL.GLMax2D
  • BRL.GNet
  • BRL.Graphics
  • BRL.Hook
  • IO

    • Introduction
    • MaxIO
  • BRL.JPGLoader
  • BRL.KeyCodes
  • LinkedList

    • Introduction
    • TList
    • TListEnum
    • TLink

    Map

    • Introduction
    • TMap
    • TIntMap
    • TIntKey
    • TPtrMap
    • TPtrKey
    • TStringMap
  • BRL.Math
  • Matrix

    • Introduction
    • SMat2D
    • SMat2F
    • SMat2I
    • SMat3D
    • SMat3F
    • SMat3I
    • SMat4D
    • SMat4F
    • SMat4I

    Max2D

    • Introduction
    • TImage

    MaxLua

    • Introduction
    • TLuaClass
    • TLuaObject
  • BRL.OGGLoader
  • BRL.OpenALAudio
  • ObjectList

    • Introduction
    • TObjectList
    • TObjectListEnumerator
    • TObjectListReverseEnumerator

    Pixmap

    • Introduction
    • TPixmap
    • TPixmapLoader
  • BRL.PNGLoader
  • BRL.PolledInput
  • Quaternion

    • Introduction
    • SQuatD
    • SQuatF
    • SQuatI
  • BRL.RamStream
  • Random

    • Introduction
    • TRandom

    Reflection

    • Introduction
    • TTypeId
    • TMember
    • TConstant
    • TField
    • TGlobal
    • TFunction
    • TMethod
  • BRL.Retro
  • BRL.Socket
  • BRL.SocketStream
  • BRL.StandardIO
  • Stream

    • Introduction
    • TCStream
    • TIO
    • TStream
    • TStreamException
    • TStreamFactory
    • TStreamReadException
    • TStreamWrapper
    • TStreamWriteException

    StringBuilder

    • Introduction
    • TStringBuilder
    • TSplitBuffer
  • BRL.System
  • BRL.SystemDefault
  • BRL.TextStream
  • BRL.TGALoader
  • ThreadPool

    • Introduction
    • TRunnable
    • TThreadPoolExecutor

    Threads

    • Introduction
    • TThread
    • TThreadData
    • TMutex
    • TSemaphore
    • TCondVar

    Timer

    • Introduction
    • TChrono
  • BRL.TimerDefault
  • Vector

    • Introduction
    • SVec2D
    • SVec2F
    • SVec2I
    • SVec3D
    • SVec3F
    • SVec3I
    • SVec4D
    • SVec4F
    • SVec4I

    Volumes

    • Introduction
    • TVolume
  • BRL.WAVLoader

Text

    CSV

    • Introduction
    • TCsvParser
    • TCsvHeader
    • TCsvRow
    • TCsvOptions
    • SCsvColumn

    Format

    • Introduction
    • TFormatter

    Ini

    • Introduction
    • TIni
    • TIniProperty
    • TIniSection

    JConv

    • Introduction
    • TJConv
    • TJConvBuilder
    • TJConvSerializer

    Json

    • Introduction
    • TJSON
    • TJSONObject
    • TJSONString
    • TJSONInteger
    • TJSONReal
    • TJSONBool
    • TJSONArray
    • TJSONNull
    • TJSONError
    • TJSONNumber

    Regex

    • Introduction
    • TRegEx
    • TRegExMatch
    • TRegExOptions
    • TRegExException

    TOML

    • Introduction
    • ETomlNodeType
    • TToml
    • ITomlNode
    • STomlDate
    • STomlDateTime
    • STomlTime
    • TTomlArray
    • TTomlInteger
    • TTomlString
    • TTomlTable
    • TTomlBoolean

    Xml

    • Introduction
    • TxmlDoc
    • TxmlNode
    • TxmlAttribute

MaxGUI

  • MaxGUI.MaxGUI
  • MaxGUI.Drivers
  • MaxGUI.Localization
  • MaxGUI.ProxyGadgets
  • MaxGUI.CocoaMaxGUI
  • MaxGUI.Win32MaxGUIEx

PUB

  • Pub.FreeJoy
  • Pub.FreeProcess
  • Pub.Glad
  • Pub.Glew
  • Joystick

    • Introduction
    • TJoystickDriver
  • Pub.Lua
  • Pub.OpenAL
  • Pub.OpenGLES
  • Pub.xmmintrin
  • Pub.ZLib

Crypto

    Digest

    • Introduction
    • TMessageDigest
    • TDigestRegister
    • TNoSuchAlgorithmException

    Cipher

    • Introduction
    • TCipher
    • TCipherMode
    • Crypto.AESCipher
    • Crypto.AnubisCipher
    • Crypto.BlowfishCipher
    • Crypto.CamelliaCipher
    • Crypto.Cast5Cipher
    • Crypto.DESCipher
    • Crypto.IdeaCipher
    • Crypto.KasumiCipher
    • Crypto.KhazadCipher
    • Crypto.KSeedCipher
    • Crypto.NoekeonCipher
    • Crypto.SerpentCipher
    • Crypto.SkipjackCipher
    • Crypto.TwofishCipher
    • Crypto.XTeaCipher

    CBCMode

    • Introduction
    • TCBCCipherMode

    CFBMode

    • Introduction
    • TCFBCipherMode

    CTRMode

    • Introduction
    • TCTRCipherMode

    ECBMode

    • Introduction
    • TECBCipherMode

    F8Mode

    • Introduction
    • TF8CipherMode

    LRWMode

    • Introduction
    • TLRWCipherMode

    OFBMode

    • Introduction
    • TOFBCipherMode

    XTSMode

    • Introduction
    • TXTSCipherMode

    Blake2BDigest

    • Introduction
    • TBlake2B_512
    • TBlake2B_384
    • TBlake2B_256
    • TBlake2B_160

    CRC32

    • Introduction
    • TCRC32

    MD5Digest

    • Introduction
    • TMD5

    Ripemd320Digest

    • Introduction
    • TRipemd320

    Ripemd356Digest

    • Introduction
    • TRipemd256

    Ripemd160Digest

    • Introduction
    • TRipemd160

    Ripemd128Digest

    • Introduction
    • TRipemd128

    SHA1Digest

    • Introduction
    • TSHA1

    SHA256Digest

    • Introduction
    • TSHA256

    SHA512Digest

    • Introduction
    • TSHA512

    SHA3Digest

    • Introduction
    • TSHA3_512
    • TSHA3_384
    • TSHA3_256
    • TSHA3_224

    TigerDigest

    • Introduction
    • TTiger

    WhirlpoolDigest

    • Introduction
    • TWhirlpool

    Crypto

    • Introduction
    • TCryptoRandom
    • TCryptoSecretBox
    • TCryptoHash
    • TCryptoSign
    • TCryptoKeyExchange
    • TCryptoKey
    • TCryptoHashKey
    • TCryptoSecretBoxKey
    • TCryptoSignature
    • TCryptoExchangeKeyPair
    • TCryptoSessionKeyPair
    • TCryptoNPacket
    • TCryptoKK1Packet
    • TCryptoKK2Packet
    • TCryptoXX1Packet
    • TCryptoXX2Packet
    • TCryptoXX3Packet
    • TCryptoExchangeState
    • TCryptoPWHashMasterKey
    • TCryptoPWHashStoredKey
    • TCryptoPasswordHash

SDL

    SDL

    • Introduction
    • TSDLStream

    SDLSystem

    • Introduction
    • TSDLMultiGesture

    SDLVideo

    • Introduction
    • TSDLDisplay
    • TSDLDisplayMode
    • TSDLGLContext
    • TSDLWindow

    SDLRender

    • Introduction
    • TSDLRenderer
    • TSDLTexture

    SDLTimer

    • Introduction
    • TSDLTimer

    SDLHaptic

    • Introduction
    • TSDLHaptic
    • TSDLHapticCondition
    • TSDLHapticConstant
    • TSDLHapticCustom
    • TSDLHapticDirection
    • TSDLHapticEffect
    • TSDLHapticLeftRight
    • TSDLHapticPeriodic
    • TSDLHapticRamp

    SDLSensor

    • Introduction
    • TSDLSensor
  • SDL.SDLFreeAudio
  • SDL.GLSDLMax2D
  • SDL.GL2SDLMax2D
  • SDL.D3D9SDLMax2D
  • SDLVirtualJoystick

    • Introduction
    • TVirtualJoystick

Steam

    SteamSDK

    • Introduction
    • TSteamClient
    • TSteamUtils
    • TSteamUserStats
    • TSteamFriends
    • TSteamUGC
    • ISteamFriendsListener
    • ISteamUGCListener
    • ISteamUserStatsListener
    • ISteamUtilsListener
    • EItemPreviewType
    • EPersonaChange
    • EPersonaState
    • ERemoteStoragePublishedFileVisibility
    • EUGCMatchingUGCType
    • EUGCQuery
    • EUserRestriction
    • EUserUGCList
    • EWorkshopFileType
Edit

TCryptoPasswordHash

Password Hashing

Secret keys used to encrypt or sign confidential data have to be chosen from a very large keyspace.

However, passwords are usually short, human-generated strings, making dictionary attacks practical.

Password hashing functions derive a high-entropy secret key of any size from a password.

The generated key will have the size defined by the application, no matter what the password length is.

  • The same password hashed with same parameters will always produce the same output.
  • The function deriving a key from a password is CPU intensive, to mitigate brute-force attacks by requiring a significant effort to verify each password.

Common use cases:

  • Password storage, or rather: storing what it takes to verify a password without having to store the actual password.
  • Deriving a secret key from a password, for example for disk encryption

Example

SuperStrict

Framework brl.standardio
Import Crypto.Crypto

Const OPS_LIMIT:Int = 10000

Local password:String = "Password123"

' generate a master key
Local masterKey:TCryptoPWHashMasterKey = TCryptoPasswordHash.KeyGen()

Print "Master key : " + masterKey.ToString()

Local storedKey:TCryptoPWHashStoredKey

' calculate stored key based on password, master key and parameters
TCryptoPasswordHash.Create(storedKey, password, masterKey, OPS_LIMIT, 0)

Print "Password Hash : " + storedKey.ToString()

' verify the password against the stored key
Verify(storedKey, password, masterKey)

Local wrongPass:String = "password123"

' try to verify the wrong password against the stored key
Verify(storedKey, wrongPass, masterKey)


Function Verify(storedKey:TCryptoPWHashStoredKey, password:String, masterKey:TCryptoPWHashMasterKey)
    If TCryptoPasswordHash.Verify(storedKey, password, masterKey, 50000, 0) Then
        Print "Verified"
    Else
        Print "Invalid"
    End If
End Function

Functions

Function KeyGen:TCryptoPWHashMasterKey()

Generates a key used to encrypt all hashed passwords, along with their parameters.

Hashed passwords and master keys should be stored in different places: hashed passwords are typically stored in a database, whereas the master key can be statically loaded or hardcoded in the application.

If the database ever gets breached, the list of hashed passwords will be completely useless without the master password.

The storage format supports reencryption and algorithm upgrades.


Function Deterministic:Int(h:Byte Ptr, hLen:Size_T, password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)

Derives a deterministic high-entropy key of any length (@hLen bytes) from a password, a context, a master key masterKey and a set of parameters for the hash function.

The resulting key is put into h.

  • opslimit is the number of iterations. The higher the number, the slower the function will be, and the more secure the end result will be against brute-force attacks. This should be adjusted according to the hardware, and to application constraints.
  • memlimit is the maximum amount of memory to use. The current function use a fixed amount of memory, and ignores this parameter. It can be unconditionally set to 0.
  • threads is the number of threads. The current function ignores this parameter. It can be unconditionally set to 1.

This function can be used to derive a key from a password if no other information has been stored. For example, it can be used to encrypt/decrypt a file using nothing but a password.


Function Deterministic:Int(h:Byte[], password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)

Derives a deterministic high-entropy key of any length from a password, a context, a master key masterKey and a set of parameters for the hash function.

The resulting key is put into h.

  • opslimit is the number of iterations. The higher the number, the slower the function will be, and the more secure the end result will be against brute-force attacks. This should be adjusted according to the hardware, and to application constraints.
  • memlimit is the maximum amount of memory to use. The current function use a fixed amount of memory, and ignores this parameter. It can be unconditionally set to 0.
  • threads is the number of threads. The current function ignores this parameter. It can be unconditionally set to 1.

This function can be used to derive a key from a password if no other information has been stored. For example, it can be used to encrypt/decrypt a file using nothing but a password.


Function Create:Int(stored:TCryptoPWHashStoredKey Var, password:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)

Computes a fixed-length (#CRYPTO_PWHASH_STOREDBYTES bytes), hashed, encrypted, authenticated representative of the password, that can be safely stored in a database.

This representative can be used to later check if a user provided password is likely to be the original one, without ever storing the password in the database.

The function encrypts and authenticates the representative and the parameters using the master key masterKey. All passwords can safely be encrypted using the same, long-term master key. Applications can also choose to derive masterKey from a master-master key, and a unique user identifier.

The representative includes opsLimit, memLimit and threads: these do not have to be stored separately.

Note that the representative is not a string: this is binary data, that must be stored as a blob in a database, or encoded as a string (for example as a hex value or using a safe base64 variant).


Function Verify:Int(stored:TCryptoPWHashStoredKey, password:String, masterKey:TCryptoPWHashMasterKey, opsLimitMax:ULong, memLimitMax:Size_T, threadsMax:Int = 1)

Verifies that the password is valid for the stored representative stored, decrypted using masterKey.

opslimitMax, memlimitMax and threadsMax are maximum values, designed to prevent DoS attacks against applications if the input is untrusted. They should be set to the maximum values ever used in the Create() function.

If the encoded parameters in the representative exceed these values, the function returns False.

If the representative cannot be decrypted, the function returns False without even trying to hash the password.

If the password doesn't appear to be valid for the stored representative, the function returns False. If the password passes all the checks, the function returns True.


Function DeriveStaticKey:Int(staticKey:Byte Ptr, staticKeyLen:Size_T, stored:TCryptoPWHashStoredKey, password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)

Fills staticKey with staticKeyLen bytes derived from the representative for password.

Verifies that password is valid for the representative. If this is the case, it fills staticKey with staticKeyLen bytes derived from that representative, and returns True.

If the password doesn't appear to be valid for what was stored, the function returns False.

This function can be used to derive a deterministic, high-entropy key from a password and user-specific data stored in a database.


Function DeriveStaticKey:Int(staticKey:Byte[], stored:TCryptoPWHashStoredKey, password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)

Fills staticKey with bytes derived from the representative for password.

Verifies that password is valid for the representative. If this is the case, it fills staticKey with bytes derived from that representative, and returns True.

If the password doesn't appear to be valid for what was stored, the function returns False.

This function can be used to derive a deterministic, high-entropy key from a password and user-specific data stored in a database.


Function Reencrypt:Int(stored:TCryptoPWHashStoredKey, masterKey:TCryptoPWHashMasterKey, newMasterKey:TCryptoPWHashMasterKey)

Reencrypts a representative stored using the current master key masterKey and a new master key newMasterKey.

It updates stored in-place and returns True on success. If the representative couldn't be decrypted using masterKey, the function returns False.


Function Upgrade:Int(stored:TCryptoPWHashStoredKey, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)

Upgrades in-place a previously computed representative stored encrypted using the master key masterKey, to the new parameters opslimit, memlimit and threads.

If previously passwords become too fast to verify after a hardware upgrade, stored representatives can be upgraded with new parameters without requiring the original passwords.

Note that parameters can only be increased. Trying to reduce the value of an existing parameter will not change the original value.

Returns

True on success, or False if the data couldn't be decrypted using the provided master password.


← TCryptoPWHashStoredKeyIntroduction →
  • Functions
    • Function KeyGen:TCryptoPWHashMasterKey()
    • Function Deterministic:Int(h:Byte Ptr, hLen:Size_T, password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)
    • Function Deterministic:Int(h:Byte[], password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)
    • Function Create:Int(stored:TCryptoPWHashStoredKey Var, password:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)
    • Function Verify:Int(stored:TCryptoPWHashStoredKey, password:String, masterKey:TCryptoPWHashMasterKey, opsLimitMax:ULong, memLimitMax:Size_T, threadsMax:Int = 1)
    • Function DeriveStaticKey:Int(staticKey:Byte Ptr, staticKeyLen:Size_T, stored:TCryptoPWHashStoredKey, password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)
    • Function DeriveStaticKey:Int(staticKey:Byte[], stored:TCryptoPWHashStoredKey, password:String, context:String, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)
    • Function Reencrypt:Int(stored:TCryptoPWHashStoredKey, masterKey:TCryptoPWHashMasterKey, newMasterKey:TCryptoPWHashMasterKey)
    • Function Upgrade:Int(stored:TCryptoPWHashStoredKey, masterKey:TCryptoPWHashMasterKey, opsLimit:ULong, memLimit:Size_T, threads:Int = 1)
BlitzMax
Docs
Getting StartedDownloadsAbout
Community
ResourcesSyntaxBomb Forums
More
GitHubStarChat on Discord
Copyright © 2023 Bruce A Henderson