cms

package
v0.2.9 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2023 License: MIT, MIT Imports: 8 Imported by: 0

README

CMS PkgGoDev

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

Examples

Constants

This section is empty.

Variables

This section is empty.

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.

func SignHash

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

SignHash creates a detached CMS SignedData from the informed hash 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()}); err != nil {
	panic(err)
}
Output:

func CreateSignedDataHash added in v0.2.8

func CreateSignedDataHash(digest []byte, chain []*x509.Certificate, signer crypto.Signer) (*SignedData, error)

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) 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) ([][][]*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) ([][][]*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.

Directories

Path Synopsis
Package asn1 implements parsing of DER-encoded ASN.1 data structures, as defined in ITU-T Rec X.690.
Package asn1 implements parsing of DER-encoded ASN.1 data structures, as defined in ITU-T Rec X.690.
Package oid contains OIDs that are used by other packages in this repository.
Package oid contains OIDs that are used by other packages in this repository.
Package protocol implements low level CMS types, parsing and generation.
Package protocol implements low level CMS types, parsing and generation.

Jump to

Keyboard shortcuts

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