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 ParseHTTPResponse(msg *TimeStampReq, body []byte) (*pkcs7.ContentInfoSignedData, error)
• func SanityCheckToken(req *TimeStampReq, psd *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 TSTInfo
  • func UnpackTokenInfo(psd *pkcs7.ContentInfoSignedData) (*TSTInfo, error)
• type TimeStampReq
  • func MakeHTTPRequest(url string, hash crypto.Hash, hashValue []byte) (msg *TimeStampReq, req *http.Request, err error)
  • func NewRequest(hash crypto.Hash, hashValue []byte) (*TimeStampReq, error)
• type TimeStampResp
• type TimestampClient
  • func (t TimestampClient) MicrosoftRequest(encryptedDigest []byte) (*pkcs7.ContentInfoSignedData, error)
  • func (t TimestampClient) Request(hash crypto.Hash, hashValue []byte) (*pkcs7.ContentInfoSignedData, error)
• type TimestampedSignature
  • func TimestampAndMarshal(psd *pkcs7.ContentInfoSignedData, timestamper Timestamper, authenticode bool) (*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}
	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 ParseHTTPResponse

func ParseHTTPResponse(msg *TimeStampReq, body []byte) (*pkcs7.ContentInfoSignedData, error)

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

func SanityCheckToken

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

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

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 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"`
}

func UnpackTokenInfo

func UnpackTokenInfo(psd *pkcs7.ContentInfoSignedData) (*TSTInfo, error)

Unpack TSTInfo from a timestamp token

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 MakeHTTPRequest

func MakeHTTPRequest(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 NewRequest

func NewRequest(hash crypto.Hash, hashValue []byte) (*TimeStampReq, error)

Create a timestamp request using the given digest

type TimeStampResp

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

type TimestampClient

type TimestampClient struct {
	URL       string
	Timeout   time.Duration
	UserAgent string
	CaFile    string
}

RFC 3161 HTTP client

func (TimestampClient) MicrosoftRequest

func (t TimestampClient) MicrosoftRequest(encryptedDigest []byte) (*pkcs7.ContentInfoSignedData, error)

func (TimestampClient) Request

func (t TimestampClient) Request(hash crypto.Hash, hashValue []byte) (*pkcs7.ContentInfoSignedData, error)

Request a RFC 3161 timestamp token from the server and return the sanity-checked token

type TimestampedSignature

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

Validated signature containing a optional timestamp token

func TimestampAndMarshal

func TimestampAndMarshal(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 {
	// PKCS#9 timestamp
	Timestamp(data []byte, hash crypto.Hash) (token *pkcs7.ContentInfoSignedData, err error)
	// Old "Microsoft" style counter-signature
	LegacyTimestamp(data []byte) (token *pkcs7.ContentInfoSignedData, err error)
}