ubiquity

Documentation

Overview

Package ubiquity contains the ubiquity scoring logic for CF-SSL bundling.

Index

• Variables
• func CompareChainCryptoSuite(chain1, chain2 []*x509.Certificate) int
• func CompareChainExpiry(chain1, chain2 []*x509.Certificate) int
• func CompareChainHashPriority(chain1, chain2 []*x509.Certificate) int
• func CompareChainHashUbiquity(chain1, chain2 []*x509.Certificate) int
• func CompareChainKeyAlgoPriority(chain1, chain2 []*x509.Certificate) int
• func CompareChainKeyAlgoUbiquity(chain1, chain2 []*x509.Certificate) int
• func CompareChainLength(chain1, chain2 []*x509.Certificate) int
• func CompareExpiryUbiquity(chain1, chain2 []*x509.Certificate) int
• func ComparePlatformUbiquity(chain1, chain2 []*x509.Certificate) int
• func CrossPlatformUbiquity(chain []*x509.Certificate) int
• func Filter(chains [][]*x509.Certificate, f RankingFunc) [][]*x509.Certificate
• func HashPriority(certs []*x509.Certificate) int
• func KeyAlgoPriority(certs []*x509.Certificate) int
• func LoadPlatforms(filename string)
• func SHA1RawPublicKey(cert *x509.Certificate) string
• func UntrustedPlatforms(root *x509.Certificate) []string
• type CertSet
  • func (s CertSet) Add(cert *x509.Certificate)
  • func (s CertSet) Lookup(cert *x509.Certificate) bool
• type HashUbiquity
  • func ChainHashUbiquity(chain []*x509.Certificate) HashUbiquity
• type KeyAlgoUbiquity
  • func ChainKeyAlgoUbiquity(chain []*x509.Certificate) KeyAlgoUbiquity
• type Platform
  • func (p *Platform) ParseAndLoad() (ok bool)
  • func (p Platform) Trust(root *x509.Certificate) bool
• type RankingFunc

Variables

var Platforms []Platform

Platforms is the list of platforms against which ubiquity bundling will be optimized.

Functions

func CompareChainCryptoSuite

func CompareChainCryptoSuite(chain1, chain2 []*x509.Certificate) int

CompareChainCryptoSuite ranks chains with more current crypto suite higher.

func CompareChainExpiry

func CompareChainExpiry(chain1, chain2 []*x509.Certificate) int

CompareChainExpiry ranks chain that lasts longer higher.

func CompareChainHashPriority

func CompareChainHashPriority(chain1, chain2 []*x509.Certificate) int

CompareChainHashPriority ranks chains with more current hash functions higher.

func CompareChainHashUbiquity

func CompareChainHashUbiquity(chain1, chain2 []*x509.Certificate) int

Return positive value if hash function ubiquity of chain1 is greater than that of chain2, negative value if ubiquity rank of chain1 is lower than that of chain2, 0 if they are ranked equal.

func CompareChainKeyAlgoPriority

func CompareChainKeyAlgoPriority(chain1, chain2 []*x509.Certificate) int

CompareChainKeyAlgoPriority ranks chains with more current key algorithm higher.

func CompareChainKeyAlgoUbiquity

func CompareChainKeyAlgoUbiquity(chain1, chain2 []*x509.Certificate) int

Return positive value if key algorithm ubiquity of chain1 is greater than that of chain2, negative value if ubiquity rank of chain1 is lower than that of chain2, 0 if they are ranked equal.

func CompareChainLength

func CompareChainLength(chain1, chain2 []*x509.Certificate) int

CompareChainLength ranks shorter chain higher.

func CompareExpiryUbiquity

func CompareExpiryUbiquity(chain1, chain2 []*x509.Certificate) int

CompareExpiryUbiquity ranks two certificate chains based on the exiry dates of intermediates and roots. Certs expire later are ranked higher than ones expire earlier. The ranking between chains are determined by the first pair of intermediates, scanned from the root level, that ar ranked differently.

func ComparePlatformUbiquity

func ComparePlatformUbiquity(chain1, chain2 []*x509.Certificate) int

ComparePlatformUbiquity compares the cross-platform ubiquity between chain1 and chain2.

func CrossPlatformUbiquity

func CrossPlatformUbiquity(chain []*x509.Certificate) int

CrossPlatformUbiquity returns a ubiquity score (persumably relecting the market share in percentage) based on whether the given chain can be verified with the different platforms' root certificate stores.

func Filter

func Filter(chains [][]*x509.Certificate, f RankingFunc) [][]*x509.Certificate

Filter filters out the chains with highest rank according to the ranking function f.

func HashPriority

func HashPriority(certs []*x509.Certificate) int

HashPriority returns the hash priority of the chain as the average of hash priority of certs in it.

func KeyAlgoPriority

func KeyAlgoPriority(certs []*x509.Certificate) int

KeyAlgoPriority returns the key algorithm priority of the chain as the average of key algorithm priority of certs in it.

func LoadPlatforms

func LoadPlatforms(filename string)

LoadPlatforms reads the file content as a json object array and convert it to Platforms.

func SHA1RawPublicKey

func SHA1RawPublicKey(cert *x509.Certificate) string

SHA1RawPublicKey returns a SHA1 hash of the raw certificate public key

func UntrustedPlatforms

func UntrustedPlatforms(root *x509.Certificate) []string

UntrustedPlatforms returns a list of platforms which don't trust the root certificate.

Types

type CertSet

type CertSet map[string]bool

CertSet is a succint set of x509 certificates which only stores certificates' SHA1 hashes.

func (CertSet) Add

func (s CertSet) Add(cert *x509.Certificate)

Add adds a certificate to the set.

func (CertSet) Lookup

func (s CertSet) Lookup(cert *x509.Certificate) bool

Lookup returns whether a certificate is stored in the set.

type HashUbiquity

type HashUbiquity int

const (
	UnknownHashUbiquity HashUbiquity = 0
	SHA2Ubiquity        HashUbiquity = 70
	SHA1Ubiquity        HashUbiquity = 100
	MD5Ubiquity         HashUbiquity = 0
	MD2Ubiquity         HashUbiquity = 0
)

SHA1 is ubiquitous. SHA2 is not supported on some legacy platforms. We consider MD2/MD5 is harmful and thus assign them lowest ubiquity.

func ChainHashUbiquity

func ChainHashUbiquity(chain []*x509.Certificate) HashUbiquity

Hash ubiquity of a chain is the lowest hash ubiquity among certs in it.

type KeyAlgoUbiquity

type KeyAlgoUbiquity int

const (
	RSAUbiquity         KeyAlgoUbiquity = 100
	DSAUbiquity         KeyAlgoUbiquity = 100
	ECDSA256Ubiquity    KeyAlgoUbiquity = 70
	ECDSA384Ubiquity    KeyAlgoUbiquity = 70
	ECDSA521Ubiquity    KeyAlgoUbiquity = 30
	UnknownAlgoUbiquity KeyAlgoUbiquity = 0
)

RSA and DSA are considered ubiquitous. ECDSA256 and ECDSA384 should be supported by TLS 1.2 and have limited support from TLS 1.0 and 1.1, based on RFC6460. And ECDSA521 are relatively less supported as a standard.

func ChainKeyAlgoUbiquity

func ChainKeyAlgoUbiquity(chain []*x509.Certificate) KeyAlgoUbiquity

Key algorithm ubiquity of a chain is the lowest key algorithm ubiquity among certs in it.

type Platform

type Platform struct {
	Name            string `json:"name"`
	Weight          int    `json:"weight"`
	HashAlgo        string `json:"hash_algo"`
	KeyAlgo         string `json:"key_algo"`
	KeyStoreFile    string `json:"keystore"`
	KeyStore        CertSet
	HashUbiquity    HashUbiquity
	KeyAlgoUbiquity KeyAlgoUbiquity
}

A Platform contains ubiquity information on supported crypto algorithms and root certificate store name.

func (*Platform) ParseAndLoad

func (p *Platform) ParseAndLoad() (ok bool)

ParseAndLoad converts HashAlgo and KeyAlgo to corresponding ubiquity value and load certificates into internal KeyStore from KeyStoreFiles

func (Platform) Trust

func (p Platform) Trust(root *x509.Certificate) bool

Trust returns whether the platform has the root cert in the trusted store.

type RankingFunc

type RankingFunc func(chain1, chain2 []*x509.Certificate) int

RankingFunc returns the relative rank between chain1 and chain2. Return value:

positive integer if rank(chain1) > rank(chain2),
negative integer if rank(chain1) < rank(chain2),
0 if rank(chain1) == (chain2).