README

goxmldsig

Build Status GoDoc

XML Digital Signatures implemented in pure Go.

Installation

Install goxmldsig 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.

Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const (
	DefaultPrefix = "ds"
	Namespace     = "http://www.w3.org/2000/09/xmldsig#"
)
View Source
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

    View Source
    const (
    	AlgorithmAttr  = "Algorithm"
    	URIAttr        = "URI"
    	DefaultIdAttr  = "ID"
    	PrefixListAttr = "PrefixList"
    )
    View Source
    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

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

      Well-known errors

      View Source
      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")
      	ErrInvalidSignature = errors.New("Invalid Signature")
      )

      Functions

      This section is empty.

      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"
      
      	CanonicalXML10RecAlgorithmId     AlgorithmID = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
      	CanonicalXML10CommentAlgorithmId AlgorithmID = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"
      
      	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 MakeC14N10CommentCanonicalizer

          func MakeC14N10CommentCanonicalizer() Canonicalizer

            MakeC14N10CommentCanonicalizer constructs an inclusive canonicalizer.

            func MakeC14N10ExclusiveCanonicalizerWithPrefixList

            func MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer

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

              func MakeC14N10RecCanonicalizer

              func MakeC14N10RecCanonicalizer() Canonicalizer

                MakeC14N10RecCanonicalizer constructs an inclusive canonicalizer.

                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) GetDigestAlgorithmIdentifier

                    func (ctx *SigningContext) GetDigestAlgorithmIdentifier() string

                    func (*SigningContext) GetSignatureMethodIdentifier

                    func (ctx *SigningContext) GetSignatureMethodIdentifier() string

                    func (*SigningContext) SetSignatureMethod

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

                    func (*SigningContext) SignEnveloped

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

                    func (*SigningContext) SignString

                    func (ctx *SigningContext) SignString(content string) ([]byte, error)

                      Useful for signing query string (including DEFLATED AuthnRequest) when using HTTP-Redirect to make a signed request. See 3.4.4.1 DEFLATE Encoding of https://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf

                      type TLSCertKeyStore

                      type TLSCertKeyStore tls.Certificate

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

                        func (TLSCertKeyStore) GetChain

                        func (d TLSCertKeyStore) GetChain() ([][]byte, error)

                          GetChain impliments X509ChainStore using the underlying tls.Certificate

                          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 X509ChainStore

                              type X509ChainStore interface {
                              	GetChain() (certs [][]byte, err error)
                              }

                              type X509KeyStore

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

                              func RandomKeyStoreForTest

                              func RandomKeyStoreForTest() X509KeyStore

                              Directories

                              Path Synopsis