1 Passlib 1.8.0.Dev0 Documentation3 1.1 Welcome
Total Page:16
File Type:pdf, Size:1020Kb
Passlib Documentation Release 1.8.0.dev0 Assurance Technologies, LLC Oct 08, 2020 Contents 1 Passlib 1.8.0.dev0 documentation3 1.1 Welcome.................................................3 1.2 Getting Started..............................................4 1.3 Online Resources.............................................4 1.4 Hosting..................................................4 2 Walkthrough & Tutorials 5 2.1 Installation................................................5 2.1.1 Supported Platforms......................................5 2.1.2 Optional Libraries........................................5 2.1.3 Installation Instructions.....................................6 2.1.4 Testing.............................................6 2.1.5 Building the Documentation..................................7 2.2 Library Overview............................................7 2.2.1 Password Hashes........................................7 2.2.2 Password Contexts.......................................8 2.2.3 Two-Factor Authentication...................................8 2.2.4 Application Helpers.......................................8 2.3 New Application Quickstart Guide...................................9 2.3.1 Choosing a Hash........................................9 2.3.1.1 The Options......................................9 2.3.1.2 Detailed Comparison of Choices...........................9 2.3.1.3 Making a Decision................................... 11 2.3.2 Creating and Using a CryptContext.............................. 11 2.4 PasswordHash Tutorial........................................ 12 2.4.1 Overview............................................ 12 2.4.2 Hashing & Verifying...................................... 13 2.4.2.1 Hashing........................................ 13 2.4.2.2 Verifying........................................ 14 2.4.2.3 Unicode & non-ASCII Characters........................... 14 2.4.3 Customizing the Configuration................................. 14 2.4.3.1 The using() Method.................................. 14 2.4.3.2 Usage Example.................................... 14 2.4.3.3 Other Keywords.................................... 15 2.4.4 Context Keywords....................................... 15 2.4.5 Identifying Hashes....................................... 16 i 2.4.6 Choosing the right rounds value................................ 17 2.5 CryptContext Tutorial........................................ 17 2.5.1 Overview............................................ 17 2.5.2 Walkthrough Outline...................................... 18 2.5.3 Basic Usage........................................... 18 2.5.4 Using Default Settings..................................... 19 2.5.5 Loading & Saving a CryptContext............................... 20 2.5.6 Deprecation & Hash Migration................................. 21 2.5.6.1 Deprecating Algorithms................................ 21 2.5.6.2 Integrating Hash Migration.............................. 22 2.5.6.3 Settings Rounds Limitations.............................. 22 2.5.7 Undocumented Features.................................... 23 2.5.8 Full Integration Example.................................... 23 2.5.8.1 Policy Configuration File............................... 23 2.5.8.2 Initializing the CryptContext............................. 24 2.5.8.3 Encrypting New Passwords.............................. 25 2.5.8.4 Verifying & Migrating Existing Passwords...................... 26 2.6 TOTP Tutorial.............................................. 26 2.6.1 Overview............................................ 26 2.6.2 Walkthrough.......................................... 27 2.6.2.1 1. Generate an Application Secret........................... 27 2.6.2.2 2. TOTP Factory Initialization............................ 27 2.6.2.3 3. Rate-Limiting & Cache Initialization........................ 28 2.6.2.4 4. Setting up TOTP for a User............................. 28 2.6.2.5 5. Storing the TOTP object.............................. 28 2.6.2.6 6. Verifying a Token.................................. 29 2.6.2.7 7. Reserializing Existing Objects........................... 30 2.6.3 Creating TOTP Instances.................................... 31 2.6.3.1 Direct Creation.................................... 31 2.6.3.2 Using a Factory.................................... 32 2.6.4 Configuring Clients....................................... 32 2.6.4.1 Rendering URIs.................................... 33 2.6.4.2 Rendering QR Codes................................. 33 2.6.4.3 Parsing URIs...................................... 33 2.6.5 Storing TOTP instances..................................... 34 2.6.5.1 JSON Serialization.................................. 34 2.6.5.2 Application Secrets.................................. 34 2.6.5.3 Encrypting Keys.................................... 35 2.6.6 Generating Tokens (Client-Side Only)............................. 36 2.6.7 Verifying Tokens........................................ 36 2.6.7.1 Match & Verify.................................... 36 2.6.7.2 Preventing Token Reuse................................ 37 2.6.7.3 Why Rate-Limiting is Critical............................. 38 3 API Reference 39 3.1 passlib.apache - Apache Password Files............................. 40 3.1.1 Htpasswd Files......................................... 40 3.1.1.1 Loading & Saving................................... 42 3.1.1.2 Inspection....................................... 42 3.1.1.3 Modification...................................... 43 3.1.1.4 Alternate Constructors................................. 43 3.1.1.5 Attributes....................................... 43 3.1.1.6 Errors......................................... 43 3.1.2 Htdigest Files.......................................... 44 ii 3.1.2.1 Loading & Saving................................... 44 3.1.2.2 Inspection....................................... 45 3.1.2.3 Modification...................................... 45 3.1.2.4 Alternate Constructors................................. 46 3.1.2.5 Attributes....................................... 46 3.1.2.6 Errors......................................... 46 3.2 passlib.apps - Helpers for various applications.......................... 46 3.2.1 Usage Example......................................... 47 3.2.2 Django............................................. 47 3.2.3 LDAP.............................................. 48 3.2.4 MySQL............................................. 48 3.2.5 PHPass............................................. 48 3.2.6 PostgreSQL........................................... 49 3.2.7 Roundup............................................ 49 3.2.8 Custom Applications...................................... 49 3.3 passlib.context - CryptContext Hash Manager.......................... 50 3.3.1 The CryptContext Class.................................... 50 3.3.1.1 Constructor Keywords................................. 50 3.3.1.2 Primary Methods................................... 55 3.3.1.3 Hash Migration.................................... 57 3.3.1.4 Disabled Hash Managment.............................. 59 3.3.1.5 Alternate Constructors................................. 59 3.3.1.6 Changing the Configuration.............................. 60 3.3.1.7 Examining the Configuration............................. 62 3.3.1.8 Saving the Configuration............................... 63 3.3.1.9 Configuration Errors.................................. 64 3.3.2 Other Helpers.......................................... 64 3.4 passlib.crypto - Cryptographic Helper Functions........................ 65 3.4.1 passlib.crypto.digest - Hash & Related Helpers.................. 65 3.4.1.1 Hash Functions.................................... 65 3.4.1.2 PKCS#5 Key Derivation Functions.......................... 66 3.4.2 passlib.crypto.des - DES routines........................... 67 3.5 passlib.exc - Exceptions and warnings............................... 68 3.5.1 Exceptions........................................... 69 3.5.1.1 TOTP Exceptions................................... 70 3.5.2 Warnings............................................ 70 3.5.2.1 Minor Warnings.................................... 70 3.5.2.2 Critical Warnings................................... 71 3.6 passlib.ext.django - Django Password Hashing Plugin..................... 71 3.6.1 Installation........................................... 72 3.6.2 Configuration.......................................... 72 3.6.3 Module Contents........................................ 73 3.7 passlib.hash - Password Hashing Schemes............................ 74 3.7.1 Overview............................................ 74 3.7.2 Unix Hashes........................................... 74 3.7.2.1 Active Unix Hashes.................................. 75 3.7.2.2 Deprecated Unix Hashes............................... 83 3.7.2.3 Archaic Unix Hashes................................. 92 3.7.3 Other “Modular Crypt” Hashes................................. 101 3.7.3.1 Active Hashes..................................... 101 3.7.3.2 Deprecated Hashes.................................. 115 3.7.4 LDAP / RFC2307 Hashes.................................... 119 3.7.4.1 Standard LDAP Schemes............................... 119 3.7.4.2 Non-Standard LDAP Schemes............................ 124 iii 3.7.5 SQL Database Hashes..................................... 128 3.7.5.1 passlib.hash.mssql2000 - MS SQL 2000 password hash.......... 129 3.7.5.2 passlib.hash.mssql2005 - MS SQL 2005 password hash.......... 130 3.7.5.3 passlib.hash.mysql323