xmldsig

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 19, 2021 License: Apache-2.0 Imports: 19 Imported by: 0

README

xmldsig

Build Status PkgGoDev

XML Digital Signatures implemented in pure Go.

Installation

Install go-xmldsig using go get:

$ go get github.com/lafriks/go-xmldsig

Usage

Signing
package main

import (
    "github.com/beevik/etree"
    "github.com/lafriks/go-xmldsig"
)

func main() {
    // Generate a key and self-signed certificate for signing
    randomKeyStore := xmldsig.RandomKeyStoreForTest()
    ctx := xmldsig.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 := xmldsig.NewDefaultValidationContext(&xmldsig.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

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"
	RSASHA384SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384"
	RSASHA512SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"
	ECDSASHA1SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1"
	ECDSASHA256SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"
	ECDSASHA384SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384"
	ECDSASHA512SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-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#"
	CanonicalXML10ExclusiveWithCommentsAlgorithmId AlgorithmID = "http://www.w3.org/2001/10/xml-exc-c14n#WithComments"

	CanonicalXML11AlgorithmId             AlgorithmID = "http://www.w3.org/2006/12/xml-c14n11"
	CanonicalXML11WithCommentsAlgorithmId AlgorithmID = "http://www.w3.org/2006/12/xml-c14n11#WithComments"

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

type CanonicalizationMethod struct {
	XMLName   xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# CanonicalizationMethod"`
	Algorithm string   `xml:"Algorithm,attr"`
}

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 MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList

func MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList(prefixList string) Canonicalizer

MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList 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 MakeC14N10WithCommentsCanonicalizer

func MakeC14N10WithCommentsCanonicalizer() Canonicalizer

MakeC14N10WithCommentsCanonicalizer constructs an inclusive canonicalizer.

func MakeC14N11Canonicalizer

func MakeC14N11Canonicalizer() Canonicalizer

MakeC14N11Canonicalizer constructs an inclusive canonicalizer.

func MakeC14N11WithCommentsCanonicalizer

func MakeC14N11WithCommentsCanonicalizer() Canonicalizer

MakeC14N11WithCommentsCanonicalizer constructs an inclusive canonicalizer.

func MakeNullCanonicalizer

func MakeNullCanonicalizer() Canonicalizer

type Clock

type Clock interface {
	// Now returns the current local time. See time package.
	Now() time.Time
}

Clock represents anything capable of returning the current time stamp.

type DigestMethod

type DigestMethod struct {
	XMLName   xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# DigestMethod"`
	Algorithm string   `xml:"Algorithm,attr"`
}

type InclusiveNamespaces

type InclusiveNamespaces struct {
	XMLName    xml.Name `xml:"http://www.w3.org/2001/10/xml-exc-c14n# InclusiveNamespaces"`
	PrefixList string   `xml:"PrefixList,attr"`
}

type KeyInfo

type KeyInfo struct {
	XMLName  xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# KeyInfo"`
	X509Data X509Data `xml:"X509Data"`
}

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 NullCanonicalizer

type NullCanonicalizer struct {
}

func (*NullCanonicalizer) Algorithm

func (c *NullCanonicalizer) Algorithm() AlgorithmID

func (*NullCanonicalizer) Canonicalize

func (c *NullCanonicalizer) Canonicalize(el *etree.Element) ([]byte, error)

type Reference

type Reference struct {
	XMLName     xml.Name     `xml:"http://www.w3.org/2000/09/xmldsig# Reference"`
	URI         string       `xml:"URI,attr"`
	DigestValue string       `xml:"DigestValue"`
	DigestAlgo  DigestMethod `xml:"DigestMethod"`
	Transforms  Transforms   `xml:"Transforms"`
}

type Signature

type Signature struct {
	XMLName        xml.Name        `xml:"http://www.w3.org/2000/09/xmldsig# Signature"`
	SignedInfo     *SignedInfo     `xml:"SignedInfo"`
	SignatureValue *SignatureValue `xml:"SignatureValue"`
	KeyInfo        *KeyInfo        `xml:"KeyInfo"`
	// contains filtered or unexported fields
}

func (*Signature) SetUnderlyingElement

func (s *Signature) SetUnderlyingElement(el *etree.Element)

SetUnderlyingElement will be called with a reference to the Element this Signature was unmarshaled from.

func (*Signature) UnderlyingElement

func (s *Signature) UnderlyingElement() *etree.Element

UnderlyingElement returns a reference to the Element this signature was unmarshaled from, where applicable.

type SignatureMethod

type SignatureMethod struct {
	XMLName   xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# SignatureMethod"`
	Algorithm string   `xml:"Algorithm,attr"`
}

type SignatureValue

type SignatureValue struct {
	XMLName xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# SignatureValue"`
	Data    string   `xml:",chardata"`
}

type SignedInfo

type SignedInfo struct {
	XMLName                xml.Name               `xml:"http://www.w3.org/2000/09/xmldsig# SignedInfo"`
	CanonicalizationMethod CanonicalizationMethod `xml:"CanonicalizationMethod"`
	SignatureMethod        SignatureMethod        `xml:"SignatureMethod"`
	References             []Reference            `xml:"Reference"`
}

type SigningContext

type SigningContext struct {
	Hash crypto.Hash

	// This field will be nil and unused if the SigningContext is created with
	// NewSigningContext
	KeyStore X509KeyStore

	IdAttribute   string
	Prefix        string
	Canonicalizer Canonicalizer
	// contains filtered or unexported fields
}

func NewDefaultSigningContext

func NewDefaultSigningContext(ks X509KeyStore) *SigningContext

func NewSigningContext

func NewSigningContext(signer crypto.Signer, certs [][]byte) (*SigningContext, error)

NewSigningContext creates a new signing context with the given signer and certificate chain. Note that e.g. rsa.PrivateKey implements the crypto.Signer interface. The certificate chain is a slice of ASN.1 DER-encoded X.509 certificates. A SigningContext created with this function should not use the KeyStore field. It will return error if passed a nil crypto.Signer

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 Transform

type Transform struct {
	XMLName             xml.Name             `xml:"http://www.w3.org/2000/09/xmldsig# Transform"`
	Algorithm           string               `xml:"Algorithm,attr"`
	InclusiveNamespaces *InclusiveNamespaces `xml:"InclusiveNamespaces"`
}

type Transforms

type Transforms struct {
	XMLName    xml.Name    `xml:"http://www.w3.org/2000/09/xmldsig# Transforms"`
	Transforms []Transform `xml:"Transform"`
}

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.

func (*ValidationContext) ValidateWithRootTrust

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

ValidateWithRootTrust does the same as Verify except it actually verifies the root CA is trusted as well

type X509Certificate

type X509Certificate struct {
	XMLName xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# X509Certificate"`
	Data    string   `xml:",chardata"`
}

type X509CertificateStore

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

type X509ChainStore

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

type X509Data

type X509Data struct {
	XMLName          xml.Name          `xml:"http://www.w3.org/2000/09/xmldsig# X509Data"`
	X509Certificates []X509Certificate `xml:"X509Certificate"`
}

type X509KeyStore

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

func RandomKeyStoreForTest

func RandomKeyStoreForTest() X509KeyStore

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL