winvault

README

winvault

Package winvault provides primitives for accessing the undocumented Windows Vault API.

Installation

go get github.com/danieljoos/winvault

Usage

List Web Credentials

The following example prints the credentials stored by Internet Explorer:

package main

import (
	"fmt"

	"github.com/danieljoos/winvault"
)

func main() {
	vault, err := winvault.OpenWebCredentials()
	if err != nil {
		panic(err)
	}
	defer vault.Close()

	items, err := vault.Items()
	if err != nil {
		panic(err)
	}
	for _, item := range items {
		fmt.Println("---")
		fmt.Println("Application:", item.Name)
		fmt.Println("Resource:", item.Resource.AsString())
		fmt.Println("Username:", item.Identity.AsString())
		fmt.Println("Password:", item.Authenticator.AsString())
	}
}

Documentation

Overview

Package winvault provides primitives for accessing the undocumented Windows Vault API. The package uses the functions exposed by the vaulcli.dll library to access Windows credential vaults. For example this includes the web-credentials vault that is used by Internet Explorer and Edge to store login form information.

At the moment, the package provides read-only access to the vault data.

As the Windows Vault API is not officially supported nor documented, the main concepts and function signatures have been taken from the following sources:

• http://www.oxid.it/downloads/vaultdump.txt
• https://github.com/EmpireProject/Empire
• https://github.com/rapid7/meterpreter

Index

• Variables
• func List() ([]uuid.UUID, error)
• type ElementType
• type Vault
  • func Open(vaultID uuid.UUID) (*Vault, error)
  • func OpenWebCredentials() (*Vault, error)
  • func (t *Vault) Close()
  • func (t *Vault) Items() ([]VaultItem, error)
• type VaultItem
• type VaultItemElement
• type VaultItemElementByteArray
  • func (t *VaultItemElementByteArray) AsByteArray() []byte
  • func (t *VaultItemElementByteArray) AsString() string
  • func (t *VaultItemElementByteArray) ID() int32
  • func (t *VaultItemElementByteArray) Type() ElementType
• type VaultItemElementString
  • func (t *VaultItemElementString) AsByteArray() []byte
  • func (t *VaultItemElementString) AsString() string
  • func (t *VaultItemElementString) ID() int32
  • func (t *VaultItemElementString) Type() ElementType

Variables

var (
	// VaultIDWebCredentials holds the fixed UUID of the web-credentials vault.
	// This vault is used by Internet Explorer and Edge (at least on Windows 10)
	// to store login information.
	VaultIDWebCredentials = uuid.Must(uuid.Parse("42c4f44b-8a9b-a041-b380-dd4a704ddb28"))
)

Functions

func List

func List() ([]uuid.UUID, error)

List returns a list of IDs of available vaults. The function does not open any vault.

Types

type ElementType

type ElementType int

ElementType is an enumeration used to distinguish the types of vault-item elements.

const (
	// ElementTypeString corresponds to string elements.
	ElementTypeString ElementType = iota

	// ElementTypeByteArray corresponds to byte-array elements.
	ElementTypeByteArray
)

type Vault

type Vault struct {
	ID   uuid.UUID
	Name string
	Path string
	// contains filtered or unexported fields
}

Vault represents an open credential vault. A vault has a unique ID and a name. The vault's path points to where the credential data is stored on the disk. Open vaults should be closed after use.

func Open

func Open(vaultID uuid.UUID) (*Vault, error)

Open opens the vault with the given ID. The function fetches the name and path property of the vault, as well. On success, the function returns the opened vault. An error is returned otherwise.

func OpenWebCredentials

func OpenWebCredentials() (*Vault, error)

OpenWebCredentials opens the web-credentials vault. The function calls the Open() function with the fixed UUID of the web-credentials vault. On success, the function returns the opened web-credentials vault. It returns an error otherwise.

func (*Vault) Close

func (t *Vault) Close()

Close closes an open vault. Open vaults should always be closed after use to free memory reserved by the Windows Vault API. The function invalidates the vault handle. Subsequent operations on this vault object will fail.

func (*Vault) Items

func (t *Vault) Items() ([]VaultItem, error)

Items returns the credential items of this vault. The function enumerates and fetches all of the vault's items including their secret strings (e.g. the password). If one of the items cannot be fetched it will be silently ignored.

The values inside the returned vault items are copied into the managed golang memory. Therefore they can be used even after closing the vault.

type VaultItem

type VaultItem struct {
	ID            uuid.UUID
	Name          string
	Resource      VaultItemElement
	Identity      VaultItemElement
	Authenticator VaultItemElement
	LastModified  time.Time
}

VaultItem represents a credential item in a vault. A vault item has a unique ID and a friendly name (the latter might contain the name of the application that owns the credentials, e.g. for web-credentials the name is set to "Internet Explorer").

The Resource property contains the name of the resource the credential is used for, e.g. this can be the URL in case of web-credentials. The Identity property holds information about the credential's identity, e.g. the user name in case of web-credentials. The Authenticator property holds the actual credential secret - for web- credentials this would be the password.

type VaultItemElement

type VaultItemElement interface {
	ID() int32
	Type() ElementType
	AsString() string
	AsByteArray() []byte
}

VaultItemElement defines an interface for property-elements of vault items. Such elements can be of different types and therefore this interface defines a method for getting the actual type of the element. The actual values can be fetched using accessor methods for the different types. For now, the element types 'string' and 'byte-array' are supported.

type VaultItemElementByteArray

type VaultItemElementByteArray struct {
	// contains filtered or unexported fields
}

VaultItemElementByteArray implements the VaultItemElement interface for elements of type byte-array.

func (*VaultItemElementByteArray) AsByteArray

func (t *VaultItemElementByteArray) AsByteArray() []byte

AsByteArray returns the element's byte-array value.

func (*VaultItemElementByteArray) AsString

func (t *VaultItemElementByteArray) AsString() string

AsString returns the string representation of the element's byte-array value.

func (*VaultItemElementByteArray) ID

func (t *VaultItemElementByteArray) ID() int32

ID returns the element ID.

func (*VaultItemElementByteArray) Type

func (t *VaultItemElementByteArray) Type() ElementType

Type always returns ElementTypeByteArray.

type VaultItemElementString

type VaultItemElementString struct {
	// contains filtered or unexported fields
}

VaultItemElementString implements the VaultItemElement interface for elements of type string.

func (*VaultItemElementString) AsByteArray

func (t *VaultItemElementString) AsByteArray() []byte

AsByteArray returns the byte representation of the element's string value.

func (*VaultItemElementString) AsString

func (t *VaultItemElementString) AsString() string

AsString returns the element's string value.

func (*VaultItemElementString) ID

func (t *VaultItemElementString) ID() int32

ID returns the element ID.

func (*VaultItemElementString) Type

func (t *VaultItemElementString) Type() ElementType

Type always returns ElementTypeString.