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", "1234")

    // 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 MemoryX509CertificateStore
  • func (mX509cs *MemoryX509CertificateStore) Certificates() ([]*x509.Certificate, error)
• type MemoryX509KeyStore
  • func (ks *MemoryX509KeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
• type SignatureAlgorithm
• type SigningContext
  • func NewDefaultSigningContext(ks X509KeyStore) *SigningContext
  • 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"
)

Tags

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

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

Variables

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

Well-known errors

Types

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 SignatureAlgorithm

type SignatureAlgorithm string

const (
	// NOTE(russell_h): I guess 1.0 is "exclusive" and 1.1 isn't
	CanonicalXML10AlgorithmId SignatureAlgorithm = "http://www.w3.org/2001/10/xml-exc-c14n#"
	CanonicalXML11AlgorithmId                    = "http://www.w3.org/2006/12/xml-c14n11"
)

Well-known signature algorithms

type SigningContext

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

func NewDefaultSigningContext

func NewDefaultSigningContext(ks X509KeyStore) *SigningContext

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
}

func NewDefaultValidationContext

func NewDefaultValidationContext(certificateStore X509CertificateStore) *ValidationContext

func (*ValidationContext) Validate

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

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