cms

README

CMS

This package is forked from github/smimesign with the following changes:

• Adds inclusive checking for cert timestamps in timestamp authorities (https://github.com/github/smimesign/pull/121)
• Fixes tests for MacOS due to regressions in return types in Go 1.18 crypto libraries (https://github.com/golang/go/issues/52010)
• Adds support for separate cert pools for cert validation and TSA validation.

CMS (Cryptographic Message Syntax) is a syntax for signing, digesting, and encrypting arbitrary messages. It evolved from PKCS#7 and is the basis for higher level protocols such as S/MIME. This package implements the SignedData CMS content-type, allowing users to digitally sign data as well as verify data signed by others.

Signing and Verifying Data

High level APIs are provided for signing a message with a certificate and key:

msg := []byte("some data")
cert, _ := x509.ParseCertificate(someCertificateData)
key, _ := x509.ParseECPrivateKey(somePrivateKeyData)

der, _ := cms.Sign(msg, []*x509.Certificate{cert}, key)

////
/// At another time, in another place...
//

sd, _ := ParseSignedData(der)
if err, _ := sd.Verify(x509.VerifyOptions{}); err != nil {
  panic(err)
}

By default, CMS SignedData includes the original message. High level APIs are also available for creating and verifying detached signatures:

msg := []byte("some data")
cert, _ := x509.ParseCertificate(someCertificateData)
key, _ := x509.ParseECPrivateKey(somePrivateKeyData)

der, _ := cms.SignDetached(msg, cert, key)

////
/// At another time, in another place...
//

sd, _ := ParseSignedData(der)
if err, _ := sd.VerifyDetached(msg, x509.VerifyOptions{}); err != nil {
  panic(err)
}

Timestamping

Because certificates expire and can be revoked, it is may be helpful to attach certified timestamps to signatures, proving that they existed at a given time. RFC3161 timestamps can be added to signatures like so:

signedData, _ := NewSignedData([]byte("Hello, world!"))
signedData.Sign(identity.Chain(), identity.PrivateKey)
signedData.AddTimestamps("http://timestamp.digicert.com")

derEncoded, _ := signedData.ToDER()
io.Copy(os.Stdout, bytes.NewReader(derEncoded))

Verification functions implicitly verify timestamps as well. Without a timestamp, verification will fail if the certificate is no longer valid.

Documentation

Index

• func Sign(data []byte, chain []*x509.Certificate, signer crypto.Signer) ([]byte, error)
• func SignDetached(data []byte, chain []*x509.Certificate, signer crypto.Signer) ([]byte, error)
• type SignedData
  • func NewSignedData(data []byte) (*SignedData, error)
  • func ParseSignedData(ber []byte) (*SignedData, error)
  • func (sd *SignedData) AddTimestamps(url string) error
  • func (sd *SignedData) Detached()
  • func (sd *SignedData) GetCertificates() ([]*x509.Certificate, error)
  • func (sd *SignedData) GetData() ([]byte, error)
  • func (sd *SignedData) IsDetached() bool
  • func (sd *SignedData) Raw() *protocol.SignedData
  • func (sd *SignedData) SetCertificates(certs []*x509.Certificate) error
  • func (sd *SignedData) Sign(chain []*x509.Certificate, signer crypto.Signer) error
  • func (sd *SignedData) ToDER() ([]byte, error)
  • func (sd *SignedData) Verify(opts x509.VerifyOptions, tsaOpts x509.VerifyOptions) ([][][]*x509.Certificate, error)
  • func (sd *SignedData) VerifyDetached(message []byte, opts x509.VerifyOptions, tsaOpts x509.VerifyOptions) ([][][]*x509.Certificate, error)

Examples

• SignedData

Functions

func Sign

func Sign(data []byte, chain []*x509.Certificate, signer crypto.Signer) ([]byte, error)

Sign creates a CMS SignedData from the content and signs it with signer. At minimum, chain must contain the leaf certificate associated with the signer. Any additional intermediates will also be added to the SignedData. The DER encoded CMS message is returned.

func SignDetached

func SignDetached(data []byte, chain []*x509.Certificate, signer crypto.Signer) ([]byte, error)

SignDetached creates a detached CMS SignedData from the content and signs it with signer. At minimum, chain must contain the leaf certificate associated with the signer. Any additional intermediates will also be added to the SignedData. The DER encoded CMS message is returned.

Types

type SignedData

type SignedData struct {
	// contains filtered or unexported fields
}

SignedData represents a signed message or detached signature.

Example

data := []byte("hello, world!")

// Wrap the data in a CMS SignedData structure and sign it with our key.
signedDataDER, err := Sign(data, exampleChain, examplePrivateKey)
if err != nil {
	panic(err)
}

// Re-parse the encoded SignedData structure.
signedData, err := ParseSignedData(signedDataDER)
if err != nil {
	panic(err)
}

// Verify the SignedData's signature.
if _, err = signedData.Verify(x509.VerifyOptions{Roots: root.ChainPool()}, x509.VerifyOptions{}); err != nil {
	panic(err)
}

func NewSignedData

func NewSignedData(data []byte) (*SignedData, error)

NewSignedData creates a new SignedData from the given data.

func ParseSignedData

func ParseSignedData(ber []byte) (*SignedData, error)

ParseSignedData parses a SignedData from BER encoded data.

func (*SignedData) AddTimestamps

func (sd *SignedData) AddTimestamps(url string) error

AddTimestamps adds a timestamp to the SignedData using the RFC3161 timestamping service at the given URL. This timestamp proves that the signed message existed the time of generation, allowing verifiers to have more trust in old messages signed with revoked keys.

func (*SignedData) Detached

func (sd *SignedData) Detached()

Detached removes the data content from this SignedData. No more signatures can be added after this method has been called.

func (*SignedData) GetCertificates

func (sd *SignedData) GetCertificates() ([]*x509.Certificate, error)

GetCertificates gets all the certificates stored in the SignedData.

func (*SignedData) GetData

func (sd *SignedData) GetData() ([]byte, error)

GetData gets the encapsulated data from the SignedData. Nil will be returned if this is a detached signature. A protocol.ErrWrongType will be returned if the SignedData encapsulates something other than data (1.2.840.113549.1.7.1).

func (*SignedData) IsDetached

func (sd *SignedData) IsDetached() bool

IsDetached checks if this SignedData has data content.

func (*SignedData) Raw

func (sd *SignedData) Raw() *protocol.SignedData

Raw returns the underlying CMS SignedData struct.

func (*SignedData) SetCertificates

func (sd *SignedData) SetCertificates(certs []*x509.Certificate) error

SetCertificates replaces the certificates stored in the SignedData with new ones.

func (*SignedData) Sign

func (sd *SignedData) Sign(chain []*x509.Certificate, signer crypto.Signer) error

Sign adds a signature to the SignedData.At minimum, chain must contain the leaf certificate associated with the signer. Any additional intermediates will also be added to the SignedData.

func (*SignedData) ToDER

func (sd *SignedData) ToDER() ([]byte, error)

ToDER encodes this SignedData message using DER.

func (*SignedData) Verify

func (sd *SignedData) Verify(opts x509.VerifyOptions, tsaOpts x509.VerifyOptions) ([][][]*x509.Certificate, error)

Verify verifies the SingerInfos' signatures. Each signature's associated certificate is verified using the provided roots. UnsafeNoVerify may be specified to skip this verification. Nil may be provided to use system roots. The full chains for the certificates whose keys made the signatures are returned.

WARNING: this function doesn't do any revocation checking.

func (*SignedData) VerifyDetached

func (sd *SignedData) VerifyDetached(message []byte, opts x509.VerifyOptions, tsaOpts x509.VerifyOptions) ([][][]*x509.Certificate, error)

VerifyDetached verifies the SingerInfos' detached signatures over the provided data message. Each signature's associated certificate is verified using the provided roots. UnsafeNoVerify may be specified to skip this verification. Nil may be provided to use system roots. The full chains for the certificates whose keys made the signatures are returned.

WARNING: this function doesn't do any revocation checking.