pkcs7

README

pkcs7

This is a fork of an excellent pkcs7 package. Copyright (c) 2015 Andrew Smith.

Notable additions to the original library are stream verifying and signing functions. To verify signed message from reader src while writing contents to some writer dest use:

p7 := pkcs7.NewDecoder(r)
if err := p7.VerifyTo(dest); err != nil {
    // handle error
}
// use p7 fields and methods

To sign file src with known size to writer dest:

p7 := pkcs7.NewEncoder(dest)
if err := p7.AddSigner(cert.Certificate, cert.PrivateKey, SignerInfoConfig{}); err != nil {
    // handle add signer error
}
if err = p7.SignFrom(r, size); err != nil {
    // handle write error
}

Original README

pkcs7 implements parsing and creating signed and enveloped messages.

• Documentation on GoDoc

Documentation

Overview

Package pkcs7 implements parsing and generation of some PKCS#7 structures.

Index

• Constants
• Variables
• func DegenerateCertificate(cert []byte) ([]byte, error)
• func Encrypt(content []byte, recipients []*x509.Certificate) ([]byte, error)
• func ParseCertificate(der []byte) (*x509.Certificate, error)
• func ParseCertificates(der []byte) ([]*x509.Certificate, error)
• type Attribute
• type MessageDigestMismatchError
  • func (err *MessageDigestMismatchError) Error() string
• type PKCS7
  • func NewDecoder(r io.Reader) *PKCS7
  • func Parse(data []byte) (p7 *PKCS7, err error)
  • func (p7 *PKCS7) Decrypt(cert *x509.Certificate, pk crypto.PrivateKey) ([]byte, error)
  • func (p7 *PKCS7) GetOnlySigner() *x509.Certificate
  • func (p7 *PKCS7) UnmarshalSignedAttribute(attributeType asn1.ObjectIdentifier, out interface{}) error
  • func (p7 *PKCS7) Verify() (err error)
  • func (p7 *PKCS7) VerifyTo(dest io.Writer) error
• type SignedData
  • func NewEncoder(w io.Writer) *SignedData
  • func NewSignedData(data []byte) (*SignedData, error)
  • func (sd *SignedData) AddCertificate(cert *x509.Certificate)
  • func (sd *SignedData) AddSigner(cert *x509.Certificate, pkey crypto.PrivateKey, config SignerInfoConfig) error
  • func (sd *SignedData) Detach()
  • func (sd *SignedData) Finish() ([]byte, error)
  • func (sd *SignedData) SignFrom(r io.Reader, size int) (err error)
• type SignerInfoConfig

Examples

• SignedData

Constants

const (
	EncryptionAlgorithmDESCBC = iota
	EncryptionAlgorithmAES128GCM
)

const (
	NumericString = cryptobyte_asn1.Tag(18)
)

The following is a list of standard tag and class combinations.

Variables

var ContentEncryptionAlgorithm = EncryptionAlgorithmDESCBC

ContentEncryptionAlgorithm determines the algorithm used to encrypt the plaintext message. Change the value of this variable to change which algorithm is used in the Encrypt() function.

var ErrNotEncryptedContent = xerrors.New("pkcs7: content data is a decryptable data type")

ErrNotEncryptedContent is returned when attempting to Decrypt data that is not encrypted data

var ErrUnsupportedAlgorithm = xerrors.New("pkcs7: cannot decrypt data: only RSA, DES, DES-EDE3, AES-256-CBC and AES-128-GCM supported")

ErrUnsupportedAlgorithm tells you when our quick dev assumptions have failed

var ErrUnsupportedContentType = xerrors.New("pkcs7: cannot parse data: unimplemented content type")

ErrUnsupportedContentType is returned when a PKCS7 content is not supported. Currently only Data (1.2.840.113549.1.7.1), Signed Data (1.2.840.113549.1.7.2), and Enveloped Data are supported (1.2.840.113549.1.7.3)

var ErrUnsupportedEncryptionAlgorithm = xerrors.New("pkcs7: cannot encrypt content: only DES-CBC and AES-128-GCM supported")

ErrUnsupportedEncryptionAlgorithm is returned when attempting to encrypt content with an unsupported algorithm.

Functions

func DegenerateCertificate

func DegenerateCertificate(cert []byte) ([]byte, error)

DegenerateCertificate creates a signed data structure containing only the provided certificate or certificate chain.

func Encrypt

func Encrypt(content []byte, recipients []*x509.Certificate) ([]byte, error)

Encrypt creates and returns an envelope data PKCS7 structure with encrypted recipient keys for each recipient public key.

The algorithm used to perform encryption is determined by the current value of the global ContentEncryptionAlgorithm package variable. By default, the value is EncryptionAlgorithmDESCBC. To use a different algorithm, change the value before calling Encrypt(). For example:

ContentEncryptionAlgorithm = EncryptionAlgorithmAES128GCM

TODO(fullsailor): Add support for encrypting content with other algorithms

func ParseCertificate

func ParseCertificate(der []byte) (*x509.Certificate, error)

ParseCertificate parses a single certificate from the given ASN.1 DER data.

func ParseCertificates

func ParseCertificates(der []byte) ([]*x509.Certificate, error)

ParseCertificates parses one or more certificates from the given ASN.1 DER data. The certificates must be concatenated with no intermediate padding.

Types

type Attribute

type Attribute struct {
	Type  asn1.ObjectIdentifier
	Value interface{}
}

Attribute represents a key value pair attribute. Value must be marshalable byte `encoding/asn1`

type MessageDigestMismatchError

type MessageDigestMismatchError struct {
	ExpectedDigest []byte
	ActualDigest   []byte
}

MessageDigestMismatchError is returned when the signer data digest does not match the computed digest for the contained content

func (*MessageDigestMismatchError) Error

func (err *MessageDigestMismatchError) Error() string

type PKCS7

type PKCS7 struct {
	Content      []byte
	Certificates []*x509.Certificate
	CRLs         []pkix.CertificateList
	Signers      []signerInfo
	// contains filtered or unexported fields
}

PKCS7 Represents a PKCS7 structure

func NewDecoder

func NewDecoder(r io.Reader) *PKCS7

NewDecoder creates stream PKCS7 decoder

func Parse

func Parse(data []byte) (p7 *PKCS7, err error)

Parse decodes a BER encoded PKCS7 package

func (*PKCS7) Decrypt

func (p7 *PKCS7) Decrypt(cert *x509.Certificate, pk crypto.PrivateKey) ([]byte, error)

Decrypt decrypts encrypted content info for recipient cert and private key

func (*PKCS7) GetOnlySigner

func (p7 *PKCS7) GetOnlySigner() *x509.Certificate

GetOnlySigner returns an x509.Certificate for the first signer of the signed data payload. If there are more or less than one signer, nil is returned

func (*PKCS7) UnmarshalSignedAttribute

func (p7 *PKCS7) UnmarshalSignedAttribute(attributeType asn1.ObjectIdentifier, out interface{}) error

UnmarshalSignedAttribute decodes a single attribute from the signer info

func (*PKCS7) Verify

func (p7 *PKCS7) Verify() (err error)

Verify checks the signatures of a PKCS7 object WARNING: Verify does not check signing time or verify certificate chains at this time.

func (*PKCS7) VerifyTo

func (p7 *PKCS7) VerifyTo(dest io.Writer) error

VerifyTo parses underlying message stream and writes extracted content into writer

type SignedData

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

SignedData is an opaque data structure for creating signed data payloads

Example

// generate a signing cert or load a key pair
cert, err := createTestCertificate()
if err != nil {
	log.Panicf("Cannot create test certificates: %s", err)
}

// Initialize a SignedData struct with content to be signed
signedData, err := NewSignedData([]byte("Example data to be signed"))
if err != nil {
	log.Panicf("Cannot initialize signed data: %s", err)
}

// Add the signing cert and private key
if err := signedData.AddSigner(cert.Certificate, cert.PrivateKey, SignerInfoConfig{}); err != nil {
	log.Panicf("Cannot add signer: %s", err)
}

// Call Detach() is you want to remove content from the signature
// and generate an S/MIME detached signature
signedData.Detach()

// Finish() to obtain the signature bytes
detachedSignature, err := signedData.Finish()
if err != nil {
	log.Panicf("Cannot finish signing data: %s", err)
}
pem.Encode(ioutil.Discard, &pem.Block{Type: "PKCS7", Bytes: detachedSignature})

func NewEncoder

func NewEncoder(w io.Writer) *SignedData

NewEncoder creates stream PKCS signer

func NewSignedData

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

NewSignedData initializes a SignedData with content

func (*SignedData) AddCertificate

func (sd *SignedData) AddCertificate(cert *x509.Certificate)

AddCertificate adds the certificate to the payload. Useful for parent certificates

func (*SignedData) AddSigner

func (sd *SignedData) AddSigner(cert *x509.Certificate, pkey crypto.PrivateKey, config SignerInfoConfig) error

AddSigner signs attributes about the content and adds certificate to payload

func (*SignedData) Detach

func (sd *SignedData) Detach()

Detach removes content from the signed data struct to make it a detached signature. This must be called right before Finish()

func (*SignedData) Finish

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

Finish marshals the content and its signers

func (*SignedData) SignFrom

func (sd *SignedData) SignFrom(r io.Reader, size int) (err error)

type SignerInfoConfig

type SignerInfoConfig struct {
	ExtraSignedAttributes []Attribute
}

SignerInfoConfig are optional values to include when adding a signer