Documentation
¶
Overview ¶
Package xmldsig helps generate XML files with digital signatures.
Index ¶
- Constants
- Variables
- func NakedPEM(cert *x509.Certificate) string
- func PEMCertificate(cert *x509.Certificate) []byte
- func PEMPrivateECDSAKey(key *ecdsa.PrivateKey) []byte
- func PEMPrivateRSAKey(key *rsa.PrivateKey) []byte
- type AlgorithmMethod
- type Cert
- type CertDigest
- type Certificate
- func (cert *Certificate) Fingerprint(hash crypto.Hash) (string, error)
- func (cert *Certificate) Issuer() string
- func (cert *Certificate) NakedPEM() string
- func (cert *Certificate) PEM() []byte
- func (cert *Certificate) PrivateKey() []byte
- func (cert *Certificate) PrivateKeyInfo() *PrivateKeyInfo
- func (cert *Certificate) PublicKeyAlgorithm() x509.PublicKeyAlgorithm
- func (cert *Certificate) SerialNumber() string
- func (cert *Certificate) Sign(data string, hash crypto.Hash, ecdsaFormatDER bool) (string, error)
- func (cert *Certificate) SubjectSerialNumber() string
- func (cert *Certificate) TLSAuthConfig() (*tls.Config, error)
- type ClaimedRoles
- type DataObjectFormat
- type ECKeyValue
- type Identifier
- type IssuerSerial
- type KeyAlgorithm
- type KeyInfo
- type KeyValue
- type NamedCurve
- type Namespaces
- type Object
- type ObjectIdentifier
- type Option
- func WithCertificate(cert *Certificate) Option
- func WithCurrentTime(fn func() time.Time) Option
- func WithDocID(id string) Option
- func WithNamespace(name, url string) Option
- func WithTimestamp(url string) Option
- func WithXAdESConfig(opts XAdESConfig) Option
- func WithXMLDSigConfig(opts XMLDSigConfig) Option
- type PolicyIdentifier
- type PolicySigPolicyHash
- type PolicySigPolicyID
- type PolicySignaturePolicyID
- type PrivateKeyInfo
- type QualifyingProperties
- type RSAKeyValue
- type Reference
- type SigPolicyQualifier
- type SigPolicyQualifiers
- type Signature
- type SignedDataObjectProperties
- type SignedInfo
- type SignedProperties
- type SignedSignatureProperties
- type SignerRole
- type SigningCertificate
- type Timestamp
- type TimestampSignatureValue
- type Transforms
- type UnsignedProperties
- type Value
- type X509Data
- type XAdESConfig
- type XAdESPolicyConfig
- type XAdESSignerRole
- type XMLDSigConfig
Constants ¶
const ( NamespaceXAdES = "http://uri.etsi.org/01903/v1.3.2#" NamespaceDSig = "http://www.w3.org/2000/09/xmldsig#" NamespaceDSig11 = "http://www.w3.org/2009/xmldsig11#" )
Namespaces used in XML-DSig and XAdES.
const ( XMLNS = "xmlns" XAdES = "xades" DSig = "ds" )
XML namespace prefixes.
const ( ReferenceTypeObject = "http://www.w3.org/2000/09/xmldsig#Object" XpathFilterAlgorithm = "http://www.w3.org/TR/1999/REC-xpath-19991116" )
Reference type URIs.
const ( AlgDSigRSASHA224 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha224" AlgDSigRSASHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" AlgDSigRSASHA384 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384" AlgDSigRSASHA512 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512" AlgDSigRSASHA512_224 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512/224" AlgDSigRSASHA512_256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512/256" AlgDSigECDSASHA224 = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224" AlgDSigECDSASHA256 = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" AlgDSigECDSASHA384 = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384" AlgDSigECDSASHA512 = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512" )
Supported signing algorithms URIs.
const (
TimestampFreeTSA = "https://freetsa.org/tsr"
)
List of free TSA servers: https://gist.github.com/Manouchehri/fd754e402d98430243455713efada710
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound is returned when a matching certificate was not found.
Functions ¶
func NakedPEM ¶
func NakedPEM(cert *x509.Certificate) string
NakedPEM converts a x509 formated certificate to the PEM format without the headers, useful for including in the XML document.
func PEMCertificate ¶
func PEMCertificate(cert *x509.Certificate) []byte
PEMCertificate provides the complete PEM version of the certificate.
func PEMPrivateECDSAKey ¶ added in v0.13.0
func PEMPrivateECDSAKey(key *ecdsa.PrivateKey) []byte
PEMPrivateECDSAKey issues a PEM string with the ECDSA Key.
func PEMPrivateRSAKey ¶
func PEMPrivateRSAKey(key *rsa.PrivateKey) []byte
PEMPrivateRSAKey issues a PEM string with the RSA Key.
Types ¶
type AlgorithmMethod ¶
type AlgorithmMethod struct {
Algorithm string `xml:"Algorithm,attr"`
XPath string `xml:"ds:XPath,omitempty"`
}
AlgorithmMethod contains URL identifier of the signing algorithm (e.g. RSA-SHA256)
type Cert ¶ added in v0.12.0
type Cert struct {
CertDigest *CertDigest `xml:"xades:CertDigest"`
IssuerSerial *IssuerSerial `xml:"xades:IssuerSerial"`
}
Cert encapsulates digest and issuer information for the signing certificate.
type CertDigest ¶ added in v0.12.0
type CertDigest struct {
DigestMethod *AlgorithmMethod `xml:"ds:DigestMethod"`
DigestValue string `xml:"ds:DigestValue"`
}
CertDigest contains the digest method and value for the signing certificate.
type Certificate ¶
type Certificate struct {
CaChain []*x509.Certificate
// contains filtered or unexported fields
}
Certificate stores information about a signing Certificate which can be used to sign a facturae XML
func LoadCertificate ¶
func LoadCertificate(path, password string) (*Certificate, error)
LoadCertificate creates a new Certificate instance from a PKCS12 file at the given path with the given password
func LoadCertificateFromBytes ¶ added in v0.12.0
func LoadCertificateFromBytes(data []byte, password string) (*Certificate, error)
LoadCertificateFromBytes creates a new Certificate instance from a PKCS12 certificate given as bytes, with the given password
func NewCertificate ¶ added in v0.15.0
func NewCertificate(cert *x509.Certificate, key crypto.Signer) (*Certificate, error)
NewCertificate creates a Certificate from a parsed x509.Certificate and a crypto.Signer
func (*Certificate) Fingerprint ¶
func (cert *Certificate) Fingerprint(hash crypto.Hash) (string, error)
Fingerprint returns the requested hash of the certificate's DER bytes.
func (*Certificate) Issuer ¶
func (cert *Certificate) Issuer() string
Issuer returns a description of the certificate issuer
func (*Certificate) NakedPEM ¶
func (cert *Certificate) NakedPEM() string
NakedPEM will return the public certificate encoded in base64 PEM (without markers like "-----BEGIN CERTIFICATE-----")
func (*Certificate) PEM ¶
func (cert *Certificate) PEM() []byte
PEM provides the PEM representation of the certificate.
func (*Certificate) PrivateKey ¶
func (cert *Certificate) PrivateKey() []byte
PrivateKey provides the private key in PEM format for both RSA and ECDSA keys.
func (*Certificate) PrivateKeyInfo ¶
func (cert *Certificate) PrivateKeyInfo() *PrivateKeyInfo
PrivateKeyInfo exposes public components of the configured private key that may be embedded in ds:KeyInfo blocks for interoperability.
func (*Certificate) PublicKeyAlgorithm ¶ added in v0.12.0
func (cert *Certificate) PublicKeyAlgorithm() x509.PublicKeyAlgorithm
PublicKeyAlgorithm exposes the public key algorithm of the certificate.
func (*Certificate) SerialNumber ¶
func (cert *Certificate) SerialNumber() string
SerialNumber returns the serial number of the certificate
func (*Certificate) Sign ¶
Sign hashes the provided data with the requested hash algorithm and signs the digest using the configured private key. For ECDSA keys, ecdsaFormat controls whether the signature is returned in concatenated r||s format (W3C XML DSig standard) or raw DER encoding (required by ZATCA).
func (*Certificate) SubjectSerialNumber ¶ added in v0.13.0
func (cert *Certificate) SubjectSerialNumber() string
SubjectSerialNumber returns the serialNumber attribute from the certificate's Subject Distinguished Name (OID 2.5.4.5). This is typically used to carry national identifiers such as "TINPL-…", "PNOPL-…", "PESEL-…", or "NIP-…" in Polish qualified certificates.
func (*Certificate) TLSAuthConfig ¶
func (cert *Certificate) TLSAuthConfig() (*tls.Config, error)
TLSAuthConfig prepares TLS authentication connection details ready to use with HTTP servers that require them in addition to the signatures of the XML-DSig signed payload.
type ClaimedRoles ¶ added in v0.12.0
type ClaimedRoles struct {
ClaimedRole []string `xml:"xades:ClaimedRole"`
}
ClaimedRoles holds one or more claimed role declarations.
type DataObjectFormat ¶
type DataObjectFormat struct {
ObjectReference string `xml:"ObjectReference,attr"`
Description string `xml:"xades:Description,omitempty"`
ObjectIdentifier *ObjectIdentifier `xml:"xades:ObjectIdentifier,omitempty"`
MimeType string `xml:"xades:MimeType,omitempty"`
Encoding string `xml:"xades:Encoding,omitempty"`
}
DataObjectFormat describes the xades:DataObjectFormat element.
type ECKeyValue ¶ added in v0.12.0
type ECKeyValue struct {
XMLName xml.Name `xml:"dsig11:ECKeyValue"`
NamedCurve NamedCurve `xml:"dsig11:NamedCurve"`
PublicKey string `xml:"dsig11:PublicKey"`
}
type Identifier ¶
type Identifier struct {
Qualifier string `xml:"Qualifier,attr,omitempty"`
Value string `xml:",chardata"`
}
Identifier is reused by multiple elements to represent string content with an optional qualifier attribute.
type IssuerSerial ¶
type IssuerSerial struct {
X509IssuerName string `xml:"ds:X509IssuerName"`
X509SerialNumber string `xml:"ds:X509SerialNumber"`
}
IssuerSerial wraps issuer and serial number statements for a certificate.
type KeyAlgorithm ¶ added in v0.12.0
type KeyAlgorithm string
KeyAlgorithm describes the public key algorithm exposed via PrivateKeyInfo.
const ( KeyAlgorithmUnknown KeyAlgorithm = "" KeyAlgorithmRSA KeyAlgorithm = "RSA" KeyAlgorithmECDSA KeyAlgorithm = "ECDSA" )
type KeyInfo ¶
type KeyInfo struct {
XMLName xml.Name `xml:"ds:KeyInfo"`
ID string `xml:"Id,attr"`
DSig11Namespace string `xml:"xmlns:dsig11,attr,omitempty"`
X509Data *X509Data `xml:"ds:X509Data,omitempty"`
KeyValue *KeyValue `xml:"ds:KeyValue,omitempty"` // optional, some APIs require it
}
KeyInfo contains the public key and certificate information
type KeyValue ¶
type KeyValue struct {
// RSA (XMLDSIG 1.0)
RSA *RSAKeyValue `xml:"ds:RSAKeyValue,omitempty"`
// EC (XMLDSIG 1.1)
EC *ECKeyValue `xml:"dsig11:ECKeyValue,omitempty"`
}
KeyValue contains the public key (optional, only specific APIs require it)
type NamedCurve ¶ added in v0.12.0
type NamedCurve struct {
URI string `xml:"URI,attr"`
}
type Namespaces ¶
Namespaces defines special functionality for dealing with namespaces
func (Namespaces) Add ¶
func (ns Namespaces) Add(name, url string) Namespaces
Add will add the namespace and return a new instance of the map without modifying the original.
type Object ¶
type Object struct {
QualifyingProperties *QualifyingProperties `xml:"xades:QualifyingProperties"`
}
Object wraps the XAdES qualifying properties
type ObjectIdentifier ¶
type ObjectIdentifier struct {
Identifier Identifier `xml:"xades:Identifier"`
Description string `xml:"xades:Description,omitempty"`
}
ObjectIdentifier configures xades:ObjectIdentifier element content.
type Option ¶
type Option func(o *options) error
Option function to be used for defining startup options
func WithCertificate ¶
func WithCertificate(cert *Certificate) Option
WithCertificate expects a path to a file containing a PKCS12 (.p12 or .pfx) certificate file, and a password used to open it.
func WithCurrentTime ¶
WithCurrentTime allows a callback to be provided in order to using a different signing time method. This is especially useful for testing. Default is to provide `time.Now().UTC()`.
func WithNamespace ¶
WithNamespace is used to define all the namespaces that must be included in canonicalization processes. DSig requires each segment that is used in a hash to reference all previously defined namespaces, even if they are not used inside the current segment.
func WithTimestamp ¶
WithTimestamp will add an official timestamp to the signature.
func WithXAdESConfig ¶ added in v0.13.0
func WithXAdESConfig(opts XAdESConfig) Option
WithXAdESConfig enables XAdES support with the given config. Pass a zero-value XAdESConfig to use default XAdES settings.
func WithXMLDSigConfig ¶ added in v0.12.0
func WithXMLDSigConfig(opts XMLDSigConfig) Option
WithXMLDSigConfig allows passing custom options overriding default XMLDSig settings.
type PolicyIdentifier ¶
type PolicyIdentifier struct {
SignaturePolicyID *PolicySignaturePolicyID `xml:"xades:SignaturePolicyId"`
}
PolicyIdentifier represents xades:SignaturePolicyIdentifier > xades:SignaturePolicyId.
type PolicySigPolicyHash ¶ added in v0.12.0
type PolicySigPolicyHash struct {
DigestMethod *AlgorithmMethod `xml:"ds:DigestMethod,omitempty"`
DigestValue string `xml:"ds:DigestValue,omitempty"`
}
PolicySigPolicyHash carries information about the policy hash.
type PolicySigPolicyID ¶ added in v0.12.0
type PolicySigPolicyID struct {
Identifier Identifier `xml:"xades:Identifier"`
Description string `xml:"xades:Description,omitempty"`
}
PolicySigPolicyID wraps identifier and description fields.
type PolicySignaturePolicyID ¶ added in v0.12.0
type PolicySignaturePolicyID struct {
SigPolicyID PolicySigPolicyID `xml:"xades:SigPolicyId"`
SigPolicyHash *PolicySigPolicyHash `xml:"xades:SigPolicyHash,omitempty"`
SigPolicyQualifiers *SigPolicyQualifiers `xml:"xades:SigPolicyQualifiers,omitempty"`
}
PolicySignaturePolicyID contains the policy identifier and optional hash data.
type PrivateKeyInfo ¶
type PrivateKeyInfo struct {
Algorithm KeyAlgorithm
// RSA fields
Modulus string
Exponent string
// ECDSA fields
CurveURI string
PublicKey string
}
PrivateKeyInfo contains public information extracted from the private key. Values are base64-encoded to match XML-DSig expectations when embedding ds:KeyInfo payloads.
type QualifyingProperties ¶
type QualifyingProperties struct {
XAdESNamespace string `xml:"xmlns:xades,attr,omitempty"`
ID string `xml:"Id,attr"`
Target string `xml:"Target,attr"`
SignedProperties *SignedProperties `xml:"xades:SignedProperties"`
UnsignedProperties *UnsignedProperties `xml:"xades:UnsignedProperties,omitempty"`
}
QualifyingProperties contains XAdES-specific signature data. XAdES-specific namespace is required, so we use `xades` prefix.
type RSAKeyValue ¶ added in v0.12.0
type Reference ¶
type Reference struct {
ID string `xml:"Id,attr,omitempty"`
Type string `xml:"Type,attr,omitempty"`
URI string `xml:"URI,attr"`
Transforms *Transforms `xml:"ds:Transforms,omitempty"`
DigestMethod *AlgorithmMethod `xml:"ds:DigestMethod"`
DigestValue string `xml:"ds:DigestValue"`
}
Reference contains information about the document part that is signed Note that there may be multiple references in a signature - in XAdES, one reference is for the outermost XML element, and another reference is for XAdES-specific data (xades:SignedProperties)
type SigPolicyQualifier ¶ added in v0.14.0
type SigPolicyQualifier struct {
SPURI string `xml:"xades:SPURI"`
}
SigPolicyQualifier contains a single policy qualifier (e.g. SPURI).
type SigPolicyQualifiers ¶ added in v0.14.0
type SigPolicyQualifiers struct {
SigPolicyQualifier []SigPolicyQualifier `xml:"xades:SigPolicyQualifier"`
}
SigPolicyQualifiers holds policy qualifier elements such as SPURI.
type Signature ¶
type Signature struct {
DSigNamespace string `xml:"xmlns:ds,attr,omitempty"`
ID string `xml:"Id,attr"`
XMLName xml.Name `xml:"ds:Signature"`
SignedInfo *SignedInfo `xml:"ds:SignedInfo"`
Value *Value `xml:"ds:SignatureValue"`
KeyInfo *KeyInfo `xml:"ds:KeyInfo"`
Object *Object `xml:"ds:Object,omitempty"`
// contains filtered or unexported fields
}
Signature contains the complete signature to be added to the document.
type SignedDataObjectProperties ¶ added in v0.12.0
type SignedDataObjectProperties struct {
DataObjectFormat *DataObjectFormat `xml:"xades:DataObjectFormat"`
}
SignedDataObjectProperties describes signed objects such as the main document body.
type SignedInfo ¶
type SignedInfo struct {
XMLName xml.Name `xml:"ds:SignedInfo"`
ID string `xml:"Id,attr,omitempty"`
CanonicalizationMethod *AlgorithmMethod `xml:"ds:CanonicalizationMethod"`
SignatureMethod *AlgorithmMethod `xml:"ds:SignatureMethod"`
Reference []*Reference `xml:"ds:Reference"`
}
SignedInfo contains the info that will be signed by the certificate.
type SignedProperties ¶
type SignedProperties struct {
XMLName xml.Name `xml:"xades:SignedProperties"`
ID string `xml:"Id,attr"`
SignedSignatureProperties *SignedSignatureProperties `xml:"xades:SignedSignatureProperties"`
SignedDataObjectProperties *SignedDataObjectProperties `xml:"xades:SignedDataObjectProperties,omitempty"`
}
SignedProperties represents the root xades:SignedProperties element.
type SignedSignatureProperties ¶
type SignedSignatureProperties struct {
SigningTime string `xml:"xades:SigningTime"`
SigningCertificate *SigningCertificate `xml:"xades:SigningCertificate"`
SignaturePolicyIdentifier *PolicyIdentifier `xml:"xades:SignaturePolicyIdentifier,omitempty"`
SignerRole *SignerRole `xml:"xades:SignerRole,omitempty"`
}
SignedSignatureProperties contains signer-specific statements such as SigningTime and SigningCertificate.
type SignerRole ¶
type SignerRole struct {
ClaimedRoles *ClaimedRoles `xml:"xades:ClaimedRoles"`
}
SignerRole enumerates claimed signer roles.
type SigningCertificate ¶
type SigningCertificate struct {
Cert []*Cert `xml:"xades:Cert"`
}
SigningCertificate encloses certificate details required by XAdES.
type Timestamp ¶
type Timestamp struct {
CanonicalizationMethod *AlgorithmMethod `xml:"ds:CanonicalizationMethod"`
EncapsulatedTimeStamp string `xml:"xades:EncapsulatedTimeStamp"`
}
Timestamp contains authentication data for a timestamp.
type TimestampSignatureValue ¶
type TimestampSignatureValue struct {
XMLName xml.Name
Namespace string `xml:"xmlns:ds,attr"`
ID string `xml:"Id,attr"`
Value string `xml:",chardata"`
}
TimestampSignatureValue is the value of the signature timestamp.
type Transforms ¶
type Transforms struct {
Transform []*AlgorithmMethod `xml:"ds:Transform"`
}
Transforms contains a list of transforms to apply to the document before signing, as URL identifiers - usually includes canonicalization and hash algorithms.
type UnsignedProperties ¶
type UnsignedProperties struct {
SignatureTimestamp *Timestamp `xml:"xades:UnsignedSignatureProperties>xades:SignatureTimestamp"`
}
UnsignedProperties contains signature data not included in the SignedInfo (e.g. verified timestamp)
type X509Data ¶
type X509Data struct {
X509Certificate []string `xml:"ds:X509Certificate"`
}
X509Data contains the certificate chain
type XAdESConfig ¶
type XAdESConfig struct {
// Configuration for XAdES always present fields
TimestampFormatter func(time.Time) string
IssuerSerializer func(pkix.RDNSequence) string
SigningCertificateHash crypto.Hash
SignedPropertiesCanonicalizer dsig.Canonicalizer
SignedPropertiesHash crypto.Hash
// XAdES-specific optional XML fields
Role XAdESSignerRole
Description string
DataObjectFormat *DataObjectFormat
Policy *XAdESPolicyConfig
IncludeCaChain bool
// When true, digests in XAdES elements are hex-encoded
// before base64: base64(hex(hash)) instead of base64(hash).
HexEncodeDigests bool
// When true, the signing certificate digest is computed
// over the base64 PEM text instead of the raw DER bytes.
HashPEMText bool
// SignedPropertiesSerializer, when set, produces the exact bytes of
// <xades:SignedProperties> that are hashed, replacing the default
// canonicalization.
SignedPropertiesSerializer func([]byte) ([]byte, error)
}
XAdESConfig configures the XAdES-specific properties.
type XAdESPolicyConfig ¶
type XAdESPolicyConfig struct {
URL string `json:"url"` // URL to the policy definition; also used as SPURI qualifier when Identifier is set
Identifier string `json:"identifier,omitempty"` // OID/URN identifier (when set, used as the policy identifier instead of URL)
Description string `json:"description,omitempty"` // Optional human description
Algorithm string `json:"algorithm"` // eg. SHA1 or SHA256
Hash string `json:"hash"` // Base64 encoded hash (usually provided with policy)
}
XAdESPolicyConfig provides a convenient way to specify what policy details to add to the XAdES signature.
type XAdESSignerRole ¶
type XAdESSignerRole string
XAdESSignerRole defines the accepted signer roles for XAdES signatures.
func (XAdESSignerRole) String ¶
func (r XAdESSignerRole) String() string
String converts the XAdES role into a string.
type XMLDSigConfig ¶ added in v0.12.0
type XMLDSigConfig struct {
DataCanonicalizer dsig.Canonicalizer
DataHash crypto.Hash
IncludeKeyValue bool
ReferenceKeyInfoInSignedInfo bool
KeyInfoHash crypto.Hash
KeyInfoCanonicalizer dsig.Canonicalizer
SignedInfoCanonicalizer dsig.Canonicalizer
SignedInfoHash crypto.Hash
// ECDSAFormatDER returns ECDSA signatures as raw DER (ZATCA) instead of the W3C-standard r||s form.
ECDSAFormatDER bool
OmitDocumentReferenceType bool
OmitDataCanonicalizationTransform bool
DocumentTransforms []*AlgorithmMethod
PreHashTransforms func([]byte) ([]byte, error)
}
XMLDSigConfig configures canonicalization, hashing, and KeyInfo handling for raw XML DSig signatures.