pwss 0.5.1 → 0.6.0

data/README.textile

@@ -1,190 +0,0 @@
-h1. Pwss
-
-A password manager in the spirit of "pws":https://github.com/janlelis/pws.
-
-Features:
-
-* PWSS manages password *files*:
-** A password file can store different entries (password and other sensitive information)
-** The user can manage different password files (e.g., work, personal)
-* Entries in a password file can be any of Entry, CreditCard, BankAccount, SoftwareLicense.  Each type stores a different set of infos:
-** *Entry:* title, username, password, url, description
-** *CreditCard:* title, issuer, name_on_card, card_number, valid_from, valid_till, verification_number, pin, url, notes
-** *BankAccount:* title, name, iban, url, description
-** *SoftwareLicense: title, version, license_number, licensed_to, email, purchased_on
-* Password files can be encrypted
-* Encrypted password files can be decrypted, for instance, to batch process entries, to migrate to another tool, or to manually edit entries
-* Entries are human-readable (and editable), when the password file is not encrypted
-
-h2. Installation
-
-Type from the command line:
-
-bc. $ gem install pwss
-
-h2. Quick Start
-
-Try the following:
-
-bc. $ pwss init
-$ pwss add First Entry
-$ pwss get First
-
-For some more information:
-
-bc. $ pwss man # get information from the command line
-$ pwss -h   # command syntax
-
-h2. Detailed Instructions
-
-*Getting started.* @pwss@ stores passwords in a YAML file (also called "safe" or "password file" in the following), possibly encrypted.
-
-A typical usage scenario is the following:
-
-# @pwss init@ will create a new encrypted password safe in @~/.pwss.yaml.enc@. If you specify a filename without the @.enc@ extension, the password safe will be stored in plain text (see below).
-# @pwss add@ will add a new entry to the file
-# @pwss get string@ will retrieve all entries whose *title* contains @string@, let the user choose an entry, and make the password of the chosen entry available in the clipboard for a given period (the default is 30 seconds; the option @-w@ controls the amount of time the password is available)
-
-*Using multiple safes.* If you want to create multiple password files or store a password file in a non-standard location, use the @-f@ (@--filename@) option:
-
-# @pwss init -f MYFILE@
-# @pwss add -f MYFILE@
-# @pwss get -f MYFILE@
-
-*Do not forget to use the extension @.enc@, if your password file to be encrypted.* (See "Encrypted and Plain files", below.)
-
-*Controlling how long passwords are made available for* Use the @-w@ option to determine how long the password is made available in the clipboard.  For instance:
-
-bc. $ pwss get my_email -w 3
-
-will retrieve a user selected entry whose title is @my_email@ and make the password available in the clipboard for @3@ seconds.
-
-Use @0@ to keep the password in the clipboard till a key is pressed.
-
-*Automatically Generated Password* pwss can automatically generate passwords for entries which are added or updated.
-
-The generated passwords are random sequences of chars and symbols.  No attempt is made to make them readable or simpler to remember.  You can use the @-a@ option to limit the generator to use only digits and letters ([0-9a-zA-Z]): this is useful, for instance, for websites which do accept certain classes of characters.
-
-Use the @-g LENGTH@ option to determine the password length.
-
-*The automatically generated password is made available in the clipboard, so that it can be used as needed*.
-
-For instance:
-
-bc. $ pwss update my_email -g 10 -a -w 20
-
-will update the @my_email@ entry, by replacing the existing password with one of length @10@ automatically generated by @pwss@; the password contains only alphabetic characters and digits.  The new password will be made available in the clipboard for @20@ seconds.
-
-*Encrypted and Plain Files.* @pwss@ works equally well with encrypted and plain files.  More in details, the file extension determines whether @pwss@ tries to decrypt/encrypt the file or not.  Use @.enc@ extension to tell @pwss@ the file is encrypted; any other extension will tell @pwss@ to treat the file as plain text.
-
-For instance:
-
-bc. $ pwss init -f a.yaml.enc
-
-will initialize an encrypted safe @a.yaml.enc@.
-
-By contrast,
-
-bc. $ pwss init -f a.yaml
-
-Encrypting sensitive information is a good idea. (Just in case you were expecting a witty statement.)  However, if you use @pwss@ to store non-critical infomation, prefer to edit the password safe with a text editor, or use another application for managing encryption and decryption, using @pwss@ with the file in plain format might be more convenient.
-
-*Moving from plain to encrypted.* You can use the @encrypt@ and @decrypt@ commands at any time to move from the plain to the encrypted format.
-
-bc. $ pwss -f YOURFILE encrypt 
-
-will encrypt @YOURFILE@, while @decrypt@ will perform the opposite operation.
-
-*Starting from an Existing File.*  You can also start from an existing file, as long as it is an array of YAML records, each containing, at least, a @title@ and a @password@ field.  (See next section, for the file structure.)
-
-In this scenario, you can use the following commands to get started:
-
-# @pwss -f YOURFILE encrypt@ will encrypt your existing password file
-# @mv YOURFILE.enc ~/.pwss.yaml.enc@ moves the encrypted file to the default location (not necessary, but it simplifies the workflow)
-
-To add entries to the password safe, use the @add@ command.  If you prefer to operate on the file using a text editor, you can also use the @decrypt@ and @encrypt@ commands.
-
-*Defining your entries.*  @pwss@ requires entries to have only a @title@ and a @password@ field.  If you want you can define and store your own records in the yaml files.
-
-*Getting Help.*
-
-bc. $ pwss
-
-will show all command options.
-
-h2. Under the Hood
-
-@pwss@ adopts a human-readable format for storing passwords, when the file is not encrypted, of course! (Unless you have mathematical super-powers and can read encrypted text.)
-
-The password files is a YAML file containing an array of entries.  By default, entries have the following records:
-
-* title
-* username
-* password
-* url
-* description
-
-Example
-
-<pre>
-- title: A webservice
-  username: username@example.com
-  password: 1234567890
-  url: http://www.example.com
-  description: >
-    with a password like the one above, who needs a password safe
-
-- title: My email
-  username: username@example.com
-  password: 1234567890
-  url: http://www.example.com
-  description: >
-    Also available via email client, with the following connection parameters
-    smtp.example.com
-    imap.example.com
-</pre>
-
-Notice that only @title@ and @password@ are required.
-
-h2. Changelog
-
-* *Release 0.5.1* fixes a bug of the "add" command, which threw an error if the title was not supplied on the command line.  When adding an entry, now it is possible to specify the title on the command line or just wait for the title prompt
-* *Release 0.5.0* This is a release mainly focused on improving interaction. It includes small changes to the command syntax and improved exit conditions. In details:
-** *add* now accepts the title in the command line.  For instance @pwss add New Entry@
-** *new* is now an alias for the *add* command
-** *update* now requires to specify the field: use @-p@, @--password@, or @--field password@, if you want to update the password
-** show the usage summary, if no arguments are given 
-** *C-c* is now trapped and properly managed (clearing the clipboard)
-** decryption errors are now properly managed
-** the content of the clipboard is now restored after the waiting period
-
-* *Release 0.4.0*
-** New @--stdout@ option will output password to standard output (useful for integration with other applications)
-** New @--select N@ option will automatically select the @N@th entry (rather than asking the user to select an entry).
-
-* *Release 0.3.0*
-** internal refactoring: CLI parsing is now based on "Slop":https://github.com/leejarvis/slop.  The documentation has been revised and should now be simpler to understand.
-** added some controls to avoid overwriting existing files (in particular: init, encrypt, and decrypt).  The command is now less Unix-like, but I hope you will appreciate a bit more safety.
-
-* *Release 0.2.0* (never really made it to the public -- use version 0.3.0)
-** it is now possible to add entries of various types (= with different fields).  The supported types include: CreditCard, BankAccount, SoftwareLicense.  Use the -e (--entry) option to specify the type of entry to add
-** an empty string can now be used to exit (instead of -1) when multiple matches are found
-
-* *Release 0.1.0*
-** the update command now allows one to update the password or any other field of existing entries
-** a simple password generator allows pwss to generate a random password
-** most commands make the password of the selected entry available in the clipboard (useful, for instance, if you automatically generate a password)
-** a destroy command allows one to delete an entry from a safe.  Similar to get, all entries matching a query are shown.  The user is then asked to select which entry has to be deleted or stop.  User confirmation is required even in case of a single match.
-
-h2. License
-
-Licensed under the terms of the MIT License.
-
-
-h2. Contributing
-
-1. Fork it (http://github.com/<my-github-username>/pwss/fork )
-2. Create your feature branch (@git checkout -b my-new-feature@)
-3. Commit your changes (@git commit -am 'Add some feature'@)
-4. Push to the branch (@git push origin my-new-feature@)
-5. Create new Pull Request

data/bin/pwss

@@ -1,445 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'fileutils'
-require 'slop'
-require 'date'
-
-require "pwss"
-require "pwss/version"
-require "pwss/cipher"
-require "pwss/entry"
-require "pwss/credit_card"
-require "pwss/bank_account"
-require "pwss/software_license"
-require "pwss/fileops"
-
-# load filename and decrypt, if necessary
-# return the filename as string and the password (in case you need to save)
-def file2string filename
-  string = FileOps::load filename
-  if FileOps::encrypted? filename then
-    password = Cipher::ask_password
-    string = Cipher::decrypt string, password
-  end
-  [string, password]
-end
-
-# add and new are command aliases.  Unfortunately slop does not seem to support aliases.
-# hence this function, which is called by both commands.
-def add opts, args
-  filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-  waiting  = opts.to_hash[:wait]     || DEFAULT_SECS
-  length   = opts.to_hash[:generate] || 0
-  type     = opts.to_hash[:type]     || "Entry"
-  alnum    = opts.to_hash[:alnum]
-
-  default_title = args.join(" ")
-  string, password = file2string filename
-
-  puts "Adding #{default_title != "" ? "entry '" + default_title + "'" : "an entry"} of type '#{type}' to #{filename}"
-  # ask for a new entry
-  if default_title != "" then
-    overrides = {"title" => ["Readline.readline('title (leave empty for \"#{default_title}\"): ')", "'#{default_title}'"]}
-  else
-    overrides = Hash.new
-  end
-  pe = eval("Pwss::" + type).new
-  pe.ask length, alnum, overrides
-
-  # add the entry to the safe
-  entries = YAML::load(string) || Array.new
-  entries << pe.entry
-
-  # check status of input file and encrypt if necessary
-  if FileOps::encrypted? filename then
-    new_string = Cipher::encrypt entries.to_yaml, password
-  else
-    new_string = entries.to_yaml
-  end
-
-  FileOps::backup filename
-  FileOps::save filename, new_string
-
-  puts "Entry added."
-  
-  # make password available in the clipboard, if there is a password to make available
-  if pe.entry["password"] 
-    Cipher.password_to_clipboard pe.entry["password"], waiting
-  end
-end
-
-version = Pwss::VERSION
-man = <<EOS
-NAME
-  pwss -- A command-line password manager
-
-SYNOPSYS
-  pwss [-h|-v]
-  pwss command [options] [args]
-
-DESCRIPTION
-  PWSS is a password manager, in the spirit of pws.
-
-  Features:
-
-  * PWSS manages password *files*:
-    - A password file can store different entries (password and other
-      sensitive information)
-    - The user can manage different password files (e.g., work, personal)
-
-  * Entries in a password file can be any of Entry, CreditCard, BankAccount, 
-    SoftwareLicense.  Each type stores a different set of infos:
-
-    - Entry:           title, username, password, url, description
-    - CreditCard:      title, issuer, name_on_card, card_number, valid_from, 
-                       valid_till, verification_number, pin, url, notes
-    - BankAccount:     title, name, iban, url, description
-    - SoftwareLicense: title, version, license_number, licensed_to,
-                       email, purchased_on
-
-  * Password files can be encrypted
-
-  * Encrypted password files can be decrypted, for instance, to batch process
-    entries, to migrate to another tool, or to manually edit entries
-
-  * Entries are human-readable (and editable), when the password file is not
-    encrypted
-
-EXAMPLES
-  pwss -h                               # get syntax of each command
-
-  # scenario
-  pwss init -f a.enc                    # generate an encrypted safe a.enc
-  pwss add -f a.enc -g 16 -a            # add an entry (pwss will generate a random 16-char password)
-  pwss get -f a.enc my secret account   # find an entry
-
-VERSION
-  This is version #{version}
-
-LICENSE
-  MIT
-
-SEE ALSO
-  pwss -h
-  pwss man
-  https://github.com/avillafiorita/pwss
-EOS
-
-
-
-#
-# Main App Starts Here!
-#
-cmd = nil
-opts = Slop.parse :help => true, :strict => true do
-  # the default filename
-  DEFAULT_FILENAME = File.join(Dir.home, ".pwss.yaml.enc")
-  # the default number of seconds password is available in the clipboard
-  DEFAULT_SECS = 30
-
-  banner "pwss [-h|-v]\npwss command [options] [args]"
-
-  ##############################################################################
-  on "-v", "--version", 'Print version information' do
-    cmd = "version"
-    puts "pwss version #{version}"
-  end
-
-  ##############################################################################
-  command :man do
-    banner "pwss man"
-    description "Print detailed information about how to use pwss"
-
-    run do |_, _|
-      cmd = "man"
-      puts man
-    end
-  end
-
-  ##############################################################################
-  command :init do
-    banner "pwss init [options]"
-    description "Init a new password file"
-
-    on "-f", "--filename=", "Password file to create. Use extension '.enc' to encrypt it."
-
-    run do |opts, args|
-      cmd = "init"
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-
-      if File.exists?(filename)
-        puts "Error: file #{filename} already exists."
-        exit 1
-      end
-
-      empty_safe = "# safe created on #{Date.today}\n"
-
-      # check status of input file and encrypt if necessary
-      if FileOps::encrypted? filename then
-        password = Cipher::check_password
-        new_string = Cipher::encrypt empty_safe, password
-      else
-        new_string = empty_safe
-      end
-
-      FileOps::backup(filename) if File.exists?(filename)
-      FileOps::save filename, new_string
-
-      puts "New safe created in #{filename}"
-    end
-  end
-
-  ##############################################################################
-  command :list do
-    banner "pwss list [options]"
-    description "List all entries of a file (e.g., to decrypt or batch process)"
-
-    on "-f", "--filename=", "Password file to use."
-
-    run do |opts, args|
-      cmd = "list"
-
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-
-      string, _ = file2string filename
-      entries = YAML::load(string) || Array.new
-
-      Pwss::list entries
-    end
-  end
-
-  ##############################################################################
-  command :get do
-    banner "pwss get [options] string"
-    description "Get password for entry matching <string> in the title field"
-
-    on "-f", "--filename=", "Password file to use"
-    on "-w", "--wait=", "Seconds password is available in the clipboard (0 = interactive)", as: Integer
-    on "--stdout", "Output the password to standard output"
-    on "--select=", "Select the N-th matching entry", as: Integer
-
-    run  do |opts, args|
-      cmd = "get"
-
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-      waiting = opts.to_hash[:wait] || DEFAULT_SECS
-      stdout_opt = opts.to_hash[:stdout]
-      entry_no = opts.to_hash[:select] || nil
-
-      string, _ = file2string filename
-      entries = YAML::load(string) || Array.new
-
-      password = Pwss::get args.join(" "), entries, entry_no
-
-      if password then
-        stdout_opt ? printf("%s", password) : Cipher.password_to_clipboard(password, waiting)
-      end
-
-    end
-  end
-
-
-  ##############################################################################
-  command :add do
-    banner "pwss add [options] [entry title]"
-    description "Add an entry and copy its password in the clipboard"
-
-    on "-f", "--filename=", "Password file to use"
-    on "-w", "--wait=", "Seconds password is available in the clipboard (0 = interactive)", as: Integer
-    
-    on "-e", "--entry=", "Create an entry of type TYPE (Entry, CreditCard, BankAccount, SoftwareLicense).\n                        Default to 'Entry', which is good enough for websites credentials"
-
-    on "-g", "--generate=", "Generate a random password of given length.", as: Integer
-    on "-a", "--alnum", "Use only alphanumeric chars for the randomly generated password"
-
-    run do |opts, args|
-      cmd = "add"
-      add opts, args
-    end
-  end
-
-  command :new do
-    banner "pwss new [options] [entry title]"
-    description "An alias for add"
-
-    on "-f", "--filename=", "Password file to use"
-    on "-w", "--wait=", "Seconds password is available in the clipboard (0 = interactive)", as: Integer
-    
-    on "-e", "--entry=", "Create an entry of type TYPE (Entry, CreditCard, BankAccount, SoftwareLicense).\n                        Default to 'Entry', which is good enough for websites credentials"
-
-    on "-g", "--generate=", "Generate a random password of given length.", as: Integer
-    on "-a", "--alnum", "Use only alphanumeric chars for the randomly generated password"
-
-    run do |opts, args|
-      cmd = "new"
-      add opts, args
-    end
-  end
-
-  ##############################################################################
-  command :update do
-    banner "pwss update [options] string"
-    description "Update given field of user-selected entry matching <string>"
-
-    on "-f", "--filename=", "Password file to use"
-    on "-w", "--wait=", "Seconds password is available in the clipboard (0 = interactive)", as: Integer
-    on "-g", "--generate=", "Generate a random password of given length", as: Integer
-    on "-a", "--alnum", "Use only alphanumeric chars for the randomly generated password"
-    on "--field=", 'Field to update'
-    on "-p", "--password", "an alias for --field password"
-
-    run do |opts, args|
-      cmd = "update"
-
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-      waiting  = opts.to_hash[:wait]     || DEFAULT_SECS
-      length   = opts.to_hash[:generate] || 0
-      alnum    = opts.to_hash[:alnum]
-      field    = opts.to_hash[:password] ? "password" : opts.to_hash[:field]
-
-      if not field then
-        puts "Please specify a field to update (used --field ... or -p)"
-        exit 1
-      end
-
-      string, password = file2string filename
-
-      # load entries and update 
-      entries = YAML::load(string) || Array.new
-
-      if field == "password" then
-        # update password
-        entries, entry_password = Pwss::update args.join(" "), entries, length, alnum
-      else
-        entries, entry_password = Pwss::update_field args.join(" "), entries, field
-      end
-
-      # check status of input file and encrypt if necessary
-      if FileOps::encrypted? filename then
-        new_string = Cipher::encrypt entries.to_yaml, password
-      else
-        new_string = entries.to_yaml
-      end
-
-      FileOps::backup filename
-      FileOps::save filename, new_string
-
-      puts "Entry updated."
-
-      # copy to clipboard the new password
-      if entry_password
-        Cipher.password_to_clipboard entry_password, waiting
-      end
-    end
-  end    
-
-  ##############################################################################
-  # Look for entries matching string, offer the user to select one of the
-  # matching entries, and destroy the entry.  
-  # The command asks for confirmation even if there is only one matching entry.
-  # Destroyed entries cannot be recovered (unless you dig in the backup file).
-  command :destroy do
-    banner "pwss destroy [options] string"
-    description "Destroy a user-selected entry matching <string>, after user confirmation."
-
-    on "-f", "--filename=", "Password file to create. Use extension '.enc' to encrypt it."
-
-    run do |opts, args|
-      cmd = "destroy"
-      
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-
-      string, password = file2string filename
-      entries = YAML::load(string)
-
-      entries = Pwss::destroy args.join(" "), entries
-      
-      # check status of input file and encrypt if necessary
-      if FileOps::encrypted? filename then
-        new_string = Cipher::encrypt entries.to_yaml, password
-      else
-        new_string = entries.to_yaml
-      end
-
-      FileOps::backup filename
-      FileOps::save filename, new_string
-
-      puts "Entry deleted."
-    end
-  end
-
-  ##############################################################################
-  # OPERATIONS ON PASSWORD FILES
-  ##############################################################################
-
-  ##############################################################################
-  command :encrypt do
-    banner "pwss encrypt [options]"
-    description "Encrypt a password safe"
-    
-    on "-f", "--filename=", "Password file to encrypt. Write to <file>.enc."
-
-    run do |opts, _|
-      cmd = "encrypt"
-      
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME.sub(/\.enc$/, "")
-
-      if not File.exists?(filename)
-        puts "Error: file #{filename} does not exist."
-        exit 1
-      end
-
-      password = Cipher::check_password
-      data = FileOps::load filename
-      encrypted = Cipher::encrypt data, password
-
-      enc_filename = filename + ".enc"
-
-      if File.exists?(enc_filename)
-        FileOps::backup enc_filename
-        puts "Warning: existing #{enc_filename} backupped to #{enc_filename}~"
-      end
-      FileOps::save enc_filename, encrypted
-      puts "An encrypted copy now lives in #{enc_filename}"
-      puts "You might want to check everything is ok and delete the plain file: #{filename}"
-    end
-  end
-
-  ##############################################################################
-  command :decrypt do
-    banner "pwss decrypt [options]"
-    description "Decrypt a password safe"
-
-    on "-f", "--filename=", "Password file to decrypt.  Write to <file>, without '.enc'."
-
-    run do |opts, _|
-      cmd = "decrypt"
-
-      filename = opts.to_hash[:filename] || DEFAULT_FILENAME
-
-      if not File.exists?(filename)
-        puts "Error: file #{filename} does not exist."
-        exit 1
-      end
-
-      password = Cipher::ask_password
-      data = FileOps::load filename
-      decrypted = Cipher::decrypt data, password
-
-      dec_filename = filename.sub(/\.enc$/,"")
-      if File.exists?(dec_filename)
-        FileOps::backup dec_filename
-        puts "Warning: existing #{dec_filename} backupped to #{dec_filename}~"
-      end
-      
-      FileOps::save dec_filename, decrypted
-      puts "A decrypted copy now lives in #{dec_filename}"
-      puts "You might want to check everything is ok and delete #{filename}, if you wish."
-    end
-  end
-
-end
-
-if cmd == nil then
-  puts opts
-end