pkcs9

Documentation

Overview

PKCS#9 is a specification for trusted timestamping. Timestamping services create a timestamp token which includes a known-good timestamp with a signature over it. The token can be attached to a document to prove that it existed at the indicated time. When attached to a PKCS#7 signedData structure, the timestamp proves that the primary signature was created during the valid lifespan of the signing certificate, allowing it to be validated after the certificates have expired.

See RFC 3161

Index

• Constants
• Variables
• func AddStampToSignedAuthenticode(signerInfo *pkcs7.SignerInfo, token pkcs7.ContentInfoSignedData) error
• func AddStampToSignedData(signerInfo *pkcs7.SignerInfo, token pkcs7.ContentInfoSignedData) error
• func NewLegacyRequest(url string, encryptedDigest []byte) (*http.Request, error)
• func ParseLegacyResponse(body []byte) (*pkcs7.ContentInfoSignedData, error)
• type Accuracy
• type CounterSignature
  • func Verify(tst *pkcs7.ContentInfoSignedData, data []byte, certs []*x509.Certificate) (*CounterSignature, error)
  • func VerifyMicrosoftToken(token *pkcs7.ContentInfoSignedData, encryptedDigest []byte) (*CounterSignature, error)
  • func VerifyPkcs7(sig pkcs7.Signature) (*CounterSignature, error)
  • func (cs CounterSignature) VerifyChain(roots *x509.CertPool, extraCerts []*x509.Certificate) error
• type GeneralName
• type MessageImprint
  • func (i MessageImprint) Verify(data []byte) error
• type MicrosoftTimeStampRequest
• type PKIStatusInfo
• type Request
• type TSTInfo
• type TimeStampReq
  • func NewRequest(url string, hash crypto.Hash, hashValue []byte) (msg *TimeStampReq, req *http.Request, err error)
  • func (req *TimeStampReq) ParseResponse(body []byte) (*pkcs7.ContentInfoSignedData, error)
  • func (req *TimeStampReq) SanityCheckToken(psd *pkcs7.ContentInfoSignedData) error
• type TimeStampResp
• type TimestampedSignature
  • func TimestampAndMarshal(ctx context.Context, psd *pkcs7.ContentInfoSignedData, timestamper Timestamper, ...) (*TimestampedSignature, error)
  • func VerifyOptionalTimestamp(sig pkcs7.Signature) (TimestampedSignature, error)
  • func (sig TimestampedSignature) VerifyChain(roots *x509.CertPool, extraCerts []*x509.Certificate, usage x509.ExtKeyUsage) error
• type Timestamper

Constants

const (
	StatusGranted = iota
	StatusGrantedWithMods
	StatusRejection
	StatusWaiting
	StatusRevocationWarning
	StatusRevocationNotification

	FailureBadAlg              = 0
	FailureBadRequest          = 2
	FailureBadDataFormat       = 5
	FailureTimeNotAvailable    = 14
	FailureUnacceptedPolicy    = 15
	FailureUnacceptedExtension = 16
	FailureAddInfoNotAvailable = 17
	SystemFailure              = 25
)

Variables

var (
	OidKeyPurposeTimeStamping  = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 3, 8}
	OidTSTInfo                 = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 16, 1, 4}
	OidAttributeTimeStampToken = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 16, 2, 14}
	OidAttributeCounterSign    = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 9, 6}

	OidSpcTimeStampRequest = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 311, 3, 2, 1}
	// undocumented(?) alternative to OidAttributeTimeStampToken found in Authenticode signatures
	OidSpcTimeStampToken = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 311, 3, 3, 1}
)

Functions

func AddStampToSignedAuthenticode

func AddStampToSignedAuthenticode(signerInfo *pkcs7.SignerInfo, token pkcs7.ContentInfoSignedData) error

Attach a RFC 3161 timestamp to a PKCS#7 SignerInfo using the OID for authenticode signatures

func AddStampToSignedData

func AddStampToSignedData(signerInfo *pkcs7.SignerInfo, token pkcs7.ContentInfoSignedData) error

Attach a RFC 3161 timestamp to a PKCS#7 SignerInfo

func NewLegacyRequest

func NewLegacyRequest(url string, encryptedDigest []byte) (*http.Request, error)

func ParseLegacyResponse

func ParseLegacyResponse(body []byte) (*pkcs7.ContentInfoSignedData, error)

Types

type Accuracy

type Accuracy struct {
	Seconds int `asn1:"optional"`
	Millis  int `asn1:"optional,tag:0"`
	Micros  int `asn1:"optional,tag:1"`
}

type CounterSignature

type CounterSignature struct {
	pkcs7.Signature
	Hash        crypto.Hash
	SigningTime time.Time
}

Validated timestamp token

func Verify

func Verify(tst *pkcs7.ContentInfoSignedData, data []byte, certs []*x509.Certificate) (*CounterSignature, error)

Verify a timestamp token using external data

func VerifyMicrosoftToken

func VerifyMicrosoftToken(token *pkcs7.ContentInfoSignedData, encryptedDigest []byte) (*CounterSignature, error)

Verify a non-RFC-3161 timestamp token against the given encrypted digest from the primary signature.

func VerifyPkcs7

func VerifyPkcs7(sig pkcs7.Signature) (*CounterSignature, error)

Look for a timestamp (counter-signature or timestamp token) in the UnauthenticatedAttributes of the given already-validated signature and check its integrity. The certificate chain is not checked; call VerifyChain() on the result to validate it fully. Returns nil if no timestamp is present.

func (CounterSignature) VerifyChain

func (cs CounterSignature) VerifyChain(roots *x509.CertPool, extraCerts []*x509.Certificate) error

Verify that the timestamp token has a valid certificate chain

type GeneralName

type GeneralName struct {
	// See RFC 3280
	Value asn1.RawValue
}

type MessageImprint

type MessageImprint struct {
	HashAlgorithm pkix.AlgorithmIdentifier
	HashedMessage []byte
}

func (MessageImprint) Verify

func (i MessageImprint) Verify(data []byte) error

Verify that the digest (imprint) in a timestamp token matches the given data

type MicrosoftTimeStampRequest

type MicrosoftTimeStampRequest struct {
	CounterSignatureType asn1.ObjectIdentifier
	Attributes           struct{} `asn1:"optional"`
	Content              struct {
		ContentType asn1.ObjectIdentifier
		Content     []byte `asn1:"explicit,tag:0"`
	}
}

type PKIStatusInfo

type PKIStatusInfo struct {
	Status       int
	StatusString []string       `asn1:"optional"`
	FailInfo     asn1.BitString `asn1:"optional"`
}

type Request

type Request struct {
	// EncryptedDigest is the raw encrypted signature value
	EncryptedDigest []byte
	// Hash is the desired hash function for the timestamp. Ignored for legacy requests.
	Hash crypto.Hash
	// Legacy indicates a nonstandard microsoft timestamp request, otherwise RFC 3161 is used
	Legacy bool
}

Request holds parameters for a timestamp operation

type TSTInfo

type TSTInfo struct {
	Version        int
	Policy         asn1.ObjectIdentifier
	MessageImprint MessageImprint
	SerialNumber   *big.Int
	GenTime        time.Time
	Accuracy       Accuracy         `asn1:"optional"`
	Ordering       bool             `asn1:"optional,default:false"`
	Nonce          *big.Int         `asn1:"optional"`
	TSA            GeneralName      `asn1:"optional,implicit,tag:0"`
	Extensions     []pkix.Extension `asn1:"optional,implicit,tag:1"`
}

type TimeStampReq

type TimeStampReq struct {
	Version        int
	MessageImprint MessageImprint
	ReqPolicy      asn1.ObjectIdentifier `asn1:"optional"`
	Nonce          *big.Int              `asn1:"optional"`
	CertReq        bool                  `asn1:"default:false"`
	Extensions     []pkix.Extension      `asn1:"optional,implicit,tag:0"`
}

func NewRequest

func NewRequest(url string, hash crypto.Hash, hashValue []byte) (msg *TimeStampReq, req *http.Request, err error)

Create a HTTP request to request a token from the given URL

func (*TimeStampReq) ParseResponse

func (req *TimeStampReq) ParseResponse(body []byte) (*pkcs7.ContentInfoSignedData, error)

Parse a timestamp token from a HTTP response, sanity checking it against the original request nonce

func (*TimeStampReq) SanityCheckToken

func (req *TimeStampReq) SanityCheckToken(psd *pkcs7.ContentInfoSignedData) error

Sanity check a timestamp token against the nonce in the original request

type TimeStampResp

type TimeStampResp struct {
	Status         PKIStatusInfo
	TimeStampToken pkcs7.ContentInfoSignedData `asn1:"optional"`
}

type TimestampedSignature

type TimestampedSignature struct {
	pkcs7.Signature
	CounterSignature *CounterSignature
	Raw              []byte
}

Validated signature containing a optional timestamp token

func TimestampAndMarshal

func TimestampAndMarshal(ctx context.Context, psd *pkcs7.ContentInfoSignedData, timestamper Timestamper, authenticode bool) (*TimestampedSignature, error)

func VerifyOptionalTimestamp

func VerifyOptionalTimestamp(sig pkcs7.Signature) (TimestampedSignature, error)

Look for a timestamp token or counter-signature in the given signature and return a structure that can be used to validate the signature's certificate chain. If no timestamp is present, then the current time will be used when validating the chain.

func (TimestampedSignature) VerifyChain

func (sig TimestampedSignature) VerifyChain(roots *x509.CertPool, extraCerts []*x509.Certificate, usage x509.ExtKeyUsage) error

Verify the certificate chain of a PKCS#7 signature. If the signature has a valid timestamp token attached, then the timestamp is used for validating the primary signature's chain, making the signature valid after the certificates have expired.

type Timestamper

type Timestamper interface {
	Timestamp(ctx context.Context, req *Request) (*pkcs7.ContentInfoSignedData, error)
}

Timestamper is the common interface for the timestamp client and middleware