dsig

README

goxmldsig

XML Digital Signatures implemented in pure Go.

Installation

Install goxmldsig into your $GOPATH using go get:

$ go get github.com/russellhaering/goxmldsig

Usage

Signing

package main

import (
    "github.com/beevik/etree"
    "github.com/russellhaering/goxmldsig"
)

func main() {
    // Generate a key and self-signed certificate for signing
    randomKeyStore := dsig.RandomKeyStoreForTest()
    ctx := dsig.NewDefaultSigningContext(randomKeyStore)
    elementToSign := &etree.Element{
        Tag: "ExampleElement",
    }
    elementToSign.CreateAttr("ID", "id1234")

    // Sign the element
    signedElement, err := ctx.SignEnveloped(elementToSign)
    if err != nil {
        panic(err)
    }

    // Serialize the signed element. It is important not to modify the element
    // after it has been signed - even pretty-printing the XML will invalidate
    // the signature.
    doc := etree.NewDocument()
    doc.SetRoot(signedElement)
    str, err := doc.WriteToString()
    if err != nil {
        panic(err)
    }

    println(str)
}

Signature Validation

// Validate an element against a root certificate
func validate(root *x509.Certificate, el *etree.Element) {
    // Construct a signing context with one or more roots of trust.
    ctx := dsig.NewDefaultValidationContext(&dsig.MemoryX509CertificateStore{
        Roots: []*x509.Certificate{root},
    })

    // It is important to only use the returned validated element.
    // See: https://www.w3.org/TR/xmldsig-bestpractices/#check-what-is-signed
    validated, err := ctx.Validate(el)
    if err != nil {
        panic(err)
    }

    doc := etree.NewDocument()
    doc.SetRoot(validated)
    str, err := doc.WriteToString()
    if err != nil {
        panic(err)
    }

    println(str)
}

Limitations

This library was created in order to implement SAML 2.0 without needing to execute a command line tool to create and validate signatures. It currently only implements the subset of relevant standards needed to support that implementation, but I hope to make it more complete over time. Contributions are welcome.

Documentation

Index

• Constants
• Variables
• type AlgorithmID
  • func (id AlgorithmID) String() string
• type Canonicalizer
  • func MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer
  • func MakeC14N11Canonicalizer() Canonicalizer
• type Clock
  • func NewFakeClock(wrapped clockwork.Clock) *Clock
  • func NewFakeClockAt(t time.Time) *Clock
  • func NewRealClock() *Clock
  • func (c *Clock) After(d time.Duration) <-chan time.Time
  • func (c *Clock) Now() time.Time
  • func (c *Clock) Sleep(d time.Duration)
• type MemoryX509CertificateStore
  • func (mX509cs *MemoryX509CertificateStore) Certificates() ([]*x509.Certificate, error)
• type MemoryX509KeyStore
  • func (ks *MemoryX509KeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
• type SigningContext
  • func NewDefaultSigningContext(ks X509KeyStore) *SigningContext
  • func (ctx *SigningContext) ConstructSignature(el *etree.Element, enveloped bool) (*etree.Element, error)
  • func (ctx *SigningContext) SetSignatureMethod(algorithmID string) error
  • func (ctx *SigningContext) SignEnveloped(el *etree.Element) (*etree.Element, error)
• type TLSCertKeyStore
  • func (d TLSCertKeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
• type ValidationContext
  • func NewDefaultValidationContext(certificateStore X509CertificateStore) *ValidationContext
  • func (ctx *ValidationContext) Validate(el *etree.Element) (*etree.Element, error)
• type X509CertificateStore
• type X509KeyStore
  • func RandomKeyStoreForTest() X509KeyStore

Constants

const (
	DefaultPrefix = "ds"
	Namespace     = "http://www.w3.org/2000/09/xmldsig#"
)

const (
	SignatureTag              = "Signature"
	SignedInfoTag             = "SignedInfo"
	CanonicalizationMethodTag = "CanonicalizationMethod"
	SignatureMethodTag        = "SignatureMethod"
	ReferenceTag              = "Reference"
	TransformsTag             = "Transforms"
	TransformTag              = "Transform"
	DigestMethodTag           = "DigestMethod"
	DigestValueTag            = "DigestValue"
	SignatureValueTag         = "SignatureValue"
	KeyInfoTag                = "KeyInfo"
	X509DataTag               = "X509Data"
	X509CertificateTag        = "X509Certificate"
	InclusiveNamespacesTag    = "InclusiveNamespaces"
)

Tags

const (
	AlgorithmAttr  = "Algorithm"
	URIAttr        = "URI"
	DefaultIdAttr  = "ID"
	PrefixListAttr = "PrefixList"
)

const (
	RSASHA1SignatureMethod   = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
	RSASHA256SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
	RSASHA512SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"
)

Variables

var (
	ErrNonRSAKey           = fmt.Errorf("Private key was not RSA")
	ErrMissingCertificates = fmt.Errorf("No public certificates provided")
)

Well-known errors

var (
	// ErrMissingSignature indicates that no enveloped signature was found referencing
	// the top level element passed for signature verification.
	ErrMissingSignature = errors.New("Missing signature referencing the top-level element")
)

Types

type AlgorithmID

type AlgorithmID string

const (
	// Supported canonicalization algorithms
	CanonicalXML10ExclusiveAlgorithmId AlgorithmID = "http://www.w3.org/2001/10/xml-exc-c14n#"
	CanonicalXML11AlgorithmId          AlgorithmID = "http://www.w3.org/2006/12/xml-c14n11"

	EnvelopedSignatureAltorithmId AlgorithmID = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
)

Well-known signature algorithms

func (AlgorithmID) String

func (id AlgorithmID) String() string

type Canonicalizer

type Canonicalizer interface {
	Canonicalize(el *etree.Element) ([]byte, error)
	Algorithm() AlgorithmID
}

Canonicalizer is an implementation of a canonicalization algorithm.

func MakeC14N10ExclusiveCanonicalizerWithPrefixList

func MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer

MakeC14N10ExclusiveCanonicalizerWithPrefixList constructs an exclusive Canonicalizer from a PrefixList in NMTOKENS format (a white space separated list).

func MakeC14N11Canonicalizer

func MakeC14N11Canonicalizer() Canonicalizer

MakeC14N11Canonicalizer constructs an inclusive canonicalizer.

type Clock

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

Clock wraps a clockwork.Clock (which could be real or fake) in order to default to a real clock when a nil *Clock is used. In other words, if you attempt to use a nil *Clock it will defer to the real system clock. This allows Clock to be easily added to structs with methods that currently reference the time package, without requiring every instantiation of that struct to be updated.

func NewFakeClock

func NewFakeClock(wrapped clockwork.Clock) *Clock

func NewFakeClockAt

func NewFakeClockAt(t time.Time) *Clock

func NewRealClock

func NewRealClock() *Clock

func (*Clock) After

func (c *Clock) After(d time.Duration) <-chan time.Time

func (*Clock) Now

func (c *Clock) Now() time.Time

func (*Clock) Sleep

func (c *Clock) Sleep(d time.Duration)

type MemoryX509CertificateStore

type MemoryX509CertificateStore struct {
	Roots []*x509.Certificate
}

func (*MemoryX509CertificateStore) Certificates

func (mX509cs *MemoryX509CertificateStore) Certificates() ([]*x509.Certificate, error)

type MemoryX509KeyStore

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

func (*MemoryX509KeyStore) GetKeyPair

func (ks *MemoryX509KeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)

type SigningContext

type SigningContext struct {
	Hash          crypto.Hash
	KeyStore      X509KeyStore
	IdAttribute   string
	Prefix        string
	Canonicalizer Canonicalizer
}

func NewDefaultSigningContext

func NewDefaultSigningContext(ks X509KeyStore) *SigningContext

func (*SigningContext) ConstructSignature

func (ctx *SigningContext) ConstructSignature(el *etree.Element, enveloped bool) (*etree.Element, error)

func (*SigningContext) SetSignatureMethod

func (ctx *SigningContext) SetSignatureMethod(algorithmID string) error

func (*SigningContext) SignEnveloped

func (ctx *SigningContext) SignEnveloped(el *etree.Element) (*etree.Element, error)

type TLSCertKeyStore

type TLSCertKeyStore tls.Certificate

TLSCertKeyStore wraps the stdlib tls.Certificate to return its contained key and certs.

func (TLSCertKeyStore) GetKeyPair

func (d TLSCertKeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)

GetKeyPair implements X509KeyStore using the underlying tls.Certificate

type ValidationContext

type ValidationContext struct {
	CertificateStore X509CertificateStore
	IdAttribute      string
	Clock            *Clock
}

func NewDefaultValidationContext

func NewDefaultValidationContext(certificateStore X509CertificateStore) *ValidationContext

func (*ValidationContext) Validate

func (ctx *ValidationContext) Validate(el *etree.Element) (*etree.Element, error)

Validate verifies that the passed element contains a valid enveloped signature matching a currently-valid certificate in the context's CertificateStore.

type X509CertificateStore

type X509CertificateStore interface {
	Certificates() (roots []*x509.Certificate, err error)
}

type X509KeyStore

type X509KeyStore interface {
	GetKeyPair() (privateKey *rsa.PrivateKey, cert []byte, err error)
}

func RandomKeyStoreForTest

func RandomKeyStoreForTest() X509KeyStore