hibp

README

pwned-passwords

A simple Go client library for checking compromised passwords against HIBP Pwned Passwords.

Upon request, results will be cached (in-memory), keyed by hash. With a two hour expiry window, subsequent requests will use cached data or fetch fresh data accordingly.

Installation

go get -u github.com/mattevans/pwned-passwords

Usage

package main

import (
        "fmt"
	hibp "github.com/mattevans/pwned-passwords"
	"os"
)

func main() {
  // Init a client.
  client := hibp.NewClient()

  // Check to see if your given string is compromised.
  pwned, err := client.Pwned.Compromised("string to check")
  if err != nil {
      fmt.Println("Pwned failed")
      os.Exit(1)
  }

  if pwned {
      // Oh dear!
      // You should avoid using that password
  } else {
     // Woo!
     // All clear!
  }
}

Expire in-memory cache

client.Cache.Expire(HASHED_VALUE)

client.Cache.ExpireAll()

Contributing

If you've found a bug or would like to contribute, please create an issue here on GitHub, or better yet fork the project and submit a pull request!

Documentation

Index

• type CacheService
  • func (s *CacheService) Expire(hash string)
  • func (s *CacheService) ExpireAll()
  • func (s *CacheService) Get(hash string) *PwnedStore
  • func (s *CacheService) IsExpired(hash string) bool
  • func (s *CacheService) Store(hash string, compromised bool)
• type Client
  • func NewClient() *Client
  • func (c *Client) Do(req *http.Request) ([]string, error)
  • func (c *Client) NewRequest(method, urlPath string, body interface{}) (*http.Request, error)
• type PwnedService
  • func (s *PwnedService) Compromised(value string) (bool, error)
• type PwnedStore

Types

type CacheService

type CacheService service

CacheService handles in-memory caching of our hash/compromised pairs.

func (*CacheService) Expire

func (s *CacheService) Expire(hash string)

Expire will expire the cache for a given hash.

func (*CacheService) ExpireAll

func (s *CacheService) ExpireAll()

ExpireAll will expire all cache.

func (*CacheService) Get

func (s *CacheService) Get(hash string) *PwnedStore

Get will return our stored in-memory hash/compromised pairs, if we have them.

func (*CacheService) IsExpired

func (s *CacheService) IsExpired(hash string) bool

IsExpired checks if we have cached hash and that it isn't expired.

func (*CacheService) Store

func (s *CacheService) Store(hash string, compromised bool)

Store will save our hash/compromised pairs to a PwnedStore.

type Client

type Client struct {
	AppID      string
	UserAgent  string
	BackendURL *url.URL

	// Services used for communicating with the API.
	Pwned *PwnedService
	Cache *CacheService
	// contains filtered or unexported fields
}

Client holds a connection to the HIBP API.

func NewClient

func NewClient() *Client

NewClient creates a new Client with the appropriate connection details and services used for communicating with the API.

func (*Client) Do

func (c *Client) Do(req *http.Request) ([]string, error)

Do sends an API request and returns the API response.

func (*Client) NewRequest

func (c *Client) NewRequest(method, urlPath string, body interface{}) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlPath, which will be resolved to the BackendURL of the Client.

type PwnedService

type PwnedService service

PwnedService handles retrieving pwned hashes from in-memory cache or by fetching fresh results.

func (*PwnedService) Compromised

func (s *PwnedService) Compromised(value string) (bool, error)

Compromised will build and execute a request to HIBP to check to see if the passed value is compromised or not.

type PwnedStore

type PwnedStore struct {
	Hash        string     `json:"hash"`
	Compromised bool       `json:"compromised"`
	UpdatedAt   *time.Time `json:"updated_at"`
}

PwnedStore holds our pwned password hashes and compromised status.