class Ansible::Vault
The top level class for interacting with Vault
files.
Constants
- FILE_HEADER
The standard header for Ansible’s current vault format
- VERSION
Public Class Methods
Build a new Vault
@param path [String, Pathname] The path to the file to read @param password [String] The password for the file @param options [Hash] Additional options @param plaintext [String] The plaintext of the file to be written when
encrypting
@option options [Boolean] :allow_blank_password Allow nil and empty string
passwords, defaults to false.
# File lib/ansible/vault.rb, line 59 def initialize(path:, password:, plaintext: :none, **options) @path = path.to_s @path = path @password = validate_password(password, options).shred_later @plaintext = plaintext @plaintext.shred_later if String === @plaintext end
Read and decrypt, if necessary, the contents of a vault
If the file does not appear to be encrypted the file is simply read.
@param path [String, Pathname] The path to the file to read @param password [String] The password for the file @param options [Hash] Additional options, see {#initialize} for details @return [String] The plaintext contents of the vault, this is marked for
zeroing before the GC reaps the object. Any data extracted/parsed from this string should be similarly wiped from memory when no longer used.
# File lib/ansible/vault.rb, line 34 def self.read(path:, password:, **options) new(path: path, password: password, **options).read end
Encrypt plaintext using the supplied and write it to the specified location
@param path [String, Pathname] The path to the file to write, truncated
before writing
@param password [String] The password for the file @param plaintext [String] The secrets to be protected @param options [Hash] Additional options, see {#initialize} for details @return [File] The closed file handle the vault was written to
# File lib/ansible/vault.rb, line 46 def self.write(path:, password:, plaintext:, **options) new(path: path, password: password, plaintext: plaintext, **options).write end
Public Instance Methods
Inspect this vault
Overridden from the default implementation to prevent passwords from being leaked into logs.
@return [String]
# File lib/ansible/vault.rb, line 73 def inspect %Q{#<Ansible::Vault:#{"0x00%x" % (object_id << 1)} @path="#{@path}", @password="#{@password[0,4]}...">} end
Extract the plaintext from a previously written vault file
If the file does not appear to be encrypted the raw contents will be returned.
@return [String] The plaintext contents of the vault, this is marked for
zeroing before the GC reaps the object. Any data extracted/parsed from this string should be similarly wiped from memory when no longer used.
# File lib/ansible/vault.rb, line 95 def read file = FileReader.new(@path) return File.read(@path) unless file.encrypted? decryptor = Decryptor.new(password: @password, file: file) decryptor.plaintext end
Write the plaintext to the file specified
@return [File] The closed file handle the vault was written to
# File lib/ansible/vault.rb, line 80 def write file = FileWriter.new(@path) encryptor = Encryptor.new(password: @password, file: file) encryptor.encrypt(@plaintext) file.write end
Private Instance Methods
# File lib/ansible/vault.rb, line 104 def validate_password(password, options) if !options[:allow_blank_password] && (password.nil? || password.strip.empty?) raise BlankPassword, 'A nil or empty string password was supplied!' \ 'If this is expected set the allow_blank_password option.' end password or '' end