cms

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package cms writes and reads the signatures of the Cryptographic Message Syntax (RFC 5652): SignedData with one signer or more, as the signatures of BDF documents (package sign) and of PDF files (PAdES, vector/pdfbdf) are, and the time-stamp tokens of RFC 3161, which are SignedData too.

It is the part of CMS that those need: a signer identified by the issuer and serial number of its certificate (or, read, by its key identifier), signed attributes (the content type, the digest of the content, the signing time and the signing certificate of ESS), and unsigned ones (a time-stamp token), with ECDSA or RSA keys and SHA-2 digests. What it reads is untrusted: lengths, counts and nesting are bounded.

Index

Constants

View Source
const (
	// MaxSize bounds the DER of a SignedData.
	MaxSize = 4 << 20
)

Limits of what is read.

Variables

View Source
var (
	OIDData                 = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 7, 1}
	OIDSignedData           = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 7, 2}
	OIDContentType          = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 3}
	OIDMessageDigest        = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 4}
	OIDSigningTime          = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 5}
	OIDSigningCertificateV2 = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 16, 2, 47}
	OIDTimeStampToken       = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 16, 2, 14}
	OIDTSTInfo              = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 16, 1, 4}
)

Object identifiers.

Functions

func AddUnsigned

func AddUnsigned(der []byte, a Attribute) ([]byte, error)

AddUnsigned adds an unsigned attribute to the first signer of the DER of a SignedData, and returns the new DER. The signature stays valid: the unsigned attributes are not signed.

func ParseTimeStampRequest

func ParseTimeStampRequest(der []byte) (digest []byte, h crypto.Hash, nonce *big.Int, err error)

ParseTimeStampRequest reads a request of a time-stamp: its digest and nonce (for a TSA of one's own).

func Sign

func Sign(content []byte, key crypto.Signer, chain []*x509.Certificate, o *SignOptions) ([]byte, error)

Sign signs content with a key whose certificate is the first of chain; the other certificates of chain go with it (the intermediate ones). It returns the DER of a ContentInfo of SignedData.

func TimeStampRequest

func TimeStampRequest(digest []byte, h crypto.Hash) (req []byte, nonce *big.Int, err error)

TimeStampRequest makes the DER of a request of a time-stamp of a digest, with a nonce that the token must hold.

func TimeStampResponse

func TimeStampResponse(token []byte) ([]byte, error)

TimeStampResponse wraps a token in a granted TimeStampResp.

func TimeStampToken

func TimeStampToken(digest []byte, h crypto.Hash, at time.Time, serial, nonce *big.Int, policy asn1.ObjectIdentifier, key crypto.Signer, chain []*x509.Certificate) ([]byte, error)

TimeStampToken makes a token of a TSA (for tests, and for a TSA of one's own): the TSTInfo of a digest at a time, signed with the key of the TSA.

Types

type Attribute

type Attribute struct {
	Type   asn1.ObjectIdentifier
	Values []byte
}

Attribute is an attribute of a signer: its type, and the DER of its values (the content of their SET).

type SignOptions

type SignOptions struct {
	// Hash is the digest of the content and of the attributes (SHA-256
	// when 0; SHA-384 and SHA-512 also).
	Hash crypto.Hash
	// Detached leaves the content out: who verifies has it.
	Detached bool
	// ContentType is the type of the content (id-data when nil).
	ContentType asn1.ObjectIdentifier
	// SigningTime is written as the signing-time attribute, unless it is
	// zero (PAdES puts the time in the signature dictionary instead).
	SigningTime time.Time
	// NoSigningCertificate leaves out the signing-certificate-v2 attribute
	// of ESS (which CAdES and PAdES require).
	NoSigningCertificate bool
	// Attributes are more signed attributes.
	Attributes []Attribute
}

SignOptions are the options of Sign.

type SignedData

type SignedData struct {
	// ContentType is the type of the content, and Content the content
	// that it holds (nil when it is detached).
	ContentType asn1.ObjectIdentifier
	Content     []byte
	// Certificates are the certificates that it carries.
	Certificates []*x509.Certificate
	Signers      []*Signer
}

SignedData is a SignedData that was read.

func Parse

func Parse(der []byte) (*SignedData, error)

Parse reads the DER of a ContentInfo of SignedData.

func (*SignedData) Verify

func (sd *SignedData) Verify(s *Signer, content []byte) error

Verify checks the signature of the signer over content (that of the SignedData, or the detached content), with the certificate of the signer: the digest of the content in its attributes, the content type, and the signing certificate of ESS when there is one. It does not check the certificate itself (VerifyChain).

func (*SignedData) VerifyChain

func (sd *SignedData) VerifyChain(s *Signer, roots *x509.CertPool, at time.Time, usage ...x509.ExtKeyUsage) ([][]*x509.Certificate, error)

VerifyChain checks the certificate of a signer against roots (nil: the roots of the system), at a time (that of a time-stamp, or now), with the intermediate certificates of the SignedData. It returns the chain.

type Signer

type Signer struct {
	// Certificate is the certificate of the signer among those of the
	// SignedData (nil when it is not among them).
	Certificate *x509.Certificate
	// Hash is the digest of the signer.
	Hash crypto.Hash
	// SignedAttributes and UnsignedAttributes are its attributes.
	SignedAttributes   []Attribute
	UnsignedAttributes []Attribute
	// Signature is the value of its signature.
	Signature []byte
	// contains filtered or unexported fields
}

Signer is a signer of a SignedData.

func (*Signer) Attribute

func (s *Signer) Attribute(t asn1.ObjectIdentifier) []byte

Attribute returns the first value of a signed attribute (nil when the signer has none of the type).

func (*Signer) SignatureDigest

func (s *Signer) SignatureDigest(h crypto.Hash) []byte

SignatureDigest is the digest of the value of the signature of a signer: what a time-stamp token for it stamps.

func (*Signer) SigningTime

func (s *Signer) SigningTime() time.Time

SigningTime is the time of the signing-time attribute (zero without one).

func (*Signer) TimeStampOf

func (s *Signer) TimeStampOf() (*TimeStamp, error)

TimeStampOf returns the time-stamp token of a signer (its unsigned signature-time-stamp attribute), checked against the signature: nil without one.

func (*Signer) Unsigned

func (s *Signer) Unsigned(t asn1.ObjectIdentifier) []byte

Unsigned returns the first value of an unsigned attribute.

type TimeStamp

type TimeStamp struct {
	// Time is when the TSA stamped the digest, Digest the digest, Hash
	// its algorithm, and Serial the number of the token.
	Time   time.Time
	Digest []byte
	Hash   crypto.Hash
	Serial *big.Int
	// Token is the token: a SignedData of the TSA.
	Token *SignedData
	// DER is the DER of the token.
	DER []byte
}

TimeStamp is a time-stamp token that was read.

func ReadTimeStamp

func ReadTimeStamp(der []byte) (*TimeStamp, error)

ReadTimeStamp reads and checks a time-stamp token: that its TSA signed it (the certificate of the TSA is not checked here: VerifyChain of the token with x509.ExtKeyUsageTimeStamping).

func ReadTimeStampResponse

func ReadTimeStampResponse(der []byte) (*TimeStamp, error)

ReadTimeStampResponse reads the DER of a TimeStampResp: the token, when the TSA granted it.

func RequestTimeStamp

func RequestTimeStamp(ctx context.Context, client *http.Client, url string, digest []byte, h crypto.Hash) (*TimeStamp, error)

RequestTimeStamp asks a TSA at a URL (HTTP, RFC 3161 §3.4) for a time-stamp token of a digest, and checks it (ReadTimeStamp): the digest it stamps and the nonce of the request. client nil is http.DefaultClient.

Directories

Path Synopsis
Package cmstest makes what tests of signatures need: a certificate authority of its own, certificates of keys that it issues, and a time-stamp authority (RFC 3161) over HTTP.
Package cmstest makes what tests of signatures need: a certificate authority of its own, certificates of keys that it issues, and a time-stamp authority (RFC 3161) over HTTP.

Jump to

Keyboard shortcuts

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