cryptcheck

README

cryptcheck

Go wrapper for Imirhil/cryptcheck API. Currently v1 of the API is supported, v2 is not released or documented yet.

API v1 is now at 201809, added missing Error field in Host.

Requirements

• Go >= 1.10

Installation

You need to install my proxy module before if you are using Go 1.10.x or earlier.

go get github.com/keltia/proxy

With Go 1.11+ and its modules support, it should work out of the box with

go get github.com/keltia/cryptcheck/cmd/...

if you have the GO111MODULE environment variable set on on.

USAGE

There is a small example program included in cmd/cryptcheck to either show the grade of a given site or JSON dump of the detailed report.

You can just get the grade like this:

$ cryptcheck www.ssllabs.com
cryptcheck Wrapper: 1.4.0 API version 201809

Grade for 'www.ssllabs.com' is B (Date: 2018-07-30 23:52:52.494 +0200 CEST)

You can get a more detail report with -d:

$ cryptcheck -d www.ssllabs.com
cryptcheck Wrapper: 1.4.0 API version 201809

{"Hosts":[{"host":{"Name":"www.ssllabs.com","ip":"64.41.200.100","Port":443},"handshake":{"Key":{"type":"rsa","size":20
[...]

You can use jq to display the output of cryptcheck -d <site> in a colorised way (use -raw to remove the banner display):

cryptcheck -raw tls.imirhil.fr | jq .

There is also a debug mode with -D.

By default, Cryptcheck returns the last run cached by the site, if you want to refresh, use -R.

API Usage

As with many API wrappers, you will need to first create a client with some optional configuration, then there are two main functions:

    // Simplest way
    c := cryptcheck.NewClient()
    grade, err := c.GetScore("example.com")
    if err != nil {
        log.Fatalf("error: %v", err)
    }
    
    
    // With some options, timeout at 15s and debug-like verbosity
    cnf := cryptcheck.Config{
        Timeout:15, 
        Log:2,
    }
    c := cryptcheck.NewClient(cnf)
    report, err := c.GetDetailedReport("foo.xxx")
    if err != nil {
        log.Fatalf("error: %v", err)
    }

OPTIONS

Option	Type	Description
Timeout	int	time for connections (default: 10s )
Log	int	1: verbose, 2: debug (default: 0)
Refresh	bool	Force refresh of the sites (default: false)

Using behind a web Proxy

Dependency: proxy support is provided by my github.com/keltia/proxy module.

UNIX/Linux:

    export HTTP_PROXY=[http://]host[:port] (sh/bash/zsh)
    setenv HTTP_PROXY [http://]host[:port] (csh/tcsh)

Windows:

    set HTTP_PROXY=[http://]host[:port]

The rules of Go's ProxyFromEnvironment apply (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, lowercase variants allowed).

If your proxy requires you to authenticate, please create a file named .netrc in your HOME directory with permissions either 0400 or 0600 with the following data:

machine proxy user <username> password <password>

and it should be picked up. On Windows, the file will be located at

%LOCALAPPDATA%\cryptcheck\netrc

License

The BSD 2-Clause license.

Contributing

This project is an open Open Source project, please read CONTRIBUTING.md.

Feedback

We welcome pull requests, bug fixes and issue reports.

Before proposing a large change, first please discuss your change by raising an issue.

Documentation

Overview

File location: $HOME/.netrc

Index

• Constants
• func Version() string
• type Cipher
• type Client
  • func NewClient(cnf ...Config) *Client
  • func (c *Client) GetDetailedReport(site string) (report Report, err error)
  • func (c *Client) GetScore(site string) (score string, err error)
• type Config
• type Grade
• type Handshake
• type Host
• type Key
• type Report
• type Result
• type Site

Constants

const (

	// DefaultWait is the timeout
	DefaultWait = 10 * time.Second

	// APIVersion is the cryptcheck API v1 as observed
	APIVersion = "201909"

	// MyVersion is the API version
	MyVersion = "1.6.0"

	// MyName is the name used for the configuration
	MyName = "cryptcheck"

	// DefaultRetry is the number of times we try hard to get an answer
	DefaultRetry = 5
)

Functions

func Version

func Version() string

Version returns our internal API version

Types

type Cipher

type Cipher struct {
	Protocol string
	Name     string
	Size     int
	DH       Key `json:"dh"`
}

Cipher describes a single cipher

type Client

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

Client is used to store proxyauth & other internal state

func NewClient

func NewClient(cnf ...Config) *Client

NewClient setups proxy authentication

func (*Client) GetDetailedReport

func (c *Client) GetDetailedReport(site string) (report Report, err error)

GetDetailedReport retrieve the full data

func (*Client) GetScore

func (c *Client) GetScore(site string) (score string, err error)

GetScore retrieves the current score from tls.imirhil.fr

type Config

type Config struct {
	BaseURL string
	Timeout int
	Refresh bool
	Log     int
}

Config is for giving options to NewClient

type Grade

type Grade struct {
	Rank    string
	Details struct {
		Score           float64 `json:"score"`
		Protocol        int     `json:"protocol"`
		KeyExchange     int     `json:"key_exchange"`
		CipherStrengths int     `json:"cipher_strengths"`
	} `json:"details"`
	Error   []string
	Danger  []string
	Warning []string
	Success []string
}

Grade aka score of the site

type Handshake

type Handshake struct {
	Key       Key
	DH        []Key `json:"dh"`
	Protocols []string
	Ciphers   []Cipher
	HSTS      int `json:"hsts"`
}

Handshake contains crypto parameters

type Host

type Host struct {
	Host      Site      `json:"host"`
	Handshake Handshake `json:"handshake"`
	Grade     Grade
	Error     string
}

Host describe a single host

type Key

type Key struct {
	Type    string `json:"type"`
	Size    int    `json:"size"`
	RSASize int    `json:"rsa_size"`
}

Key describes a single key

type Report

type Report struct {
	ID struct {
		Oid string `json:"$oid"`
	} `json:"_id"`
	Service   string
	Host      string
	Port      int
	Pending   bool
	Result    Result
	CreateAt  time.Time `json:"create_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Report describes the details for the crypto

type Result

type Result struct {
	Date  time.Time `json:"date"`
	Hosts []Host
}

Result holds the actual results, host-per-host

type Site

type Site struct {
	Name string
	IP   string `json:"ip"`
	Port int
}

Site contains DNS site data