Why does DecodeChain support only one key bag?

[marsskop]

Hello folks.

Discussion topic: why does pfxData in DecodeChain support only one key bag?

• PKCS#12 v1.1. standard (https://datatracker.ietf.org/doc/html/rfc7292) supports multiple key bags
• Java's keytool (https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html) supports multiple key bags for PKCS12 format
• but openssl CLI supports only one private key (https://en.wikipedia.org/wiki/PKCS_12#:~:text=PKCS%20#12%20files%20are%20usually%20created%20using%20OpenSSL,%20which%20only%20supports%20a%20single%20private%20key%20from%20the%20command%20line%20interface)

Having multiple key bags is a crucial feature for me personally. Extending pfxData and DecodeChain to be able to support multiple key bags shouldn't be too hard. What do you think?

[AGWA]

What's your use case for having multiple keys in a single PKCS#12 file? What API do you propose for parsing such files?

[marsskop]

Use case: an application uses a PKCS#12 keystore to connect to two other apps in the cluster, one asks for one key, another for another (we have mTLS). During the deployment of our application, we are meant to read, generate and spread out required keystores;
CLI tool keytool is not available.

Proposition:

• each bag has an Attributes field, in which friendlyName (aka alias in JKS) can be used to differentiate between entries (each entry is private key + cert chain)
• supported types of bags in PKCS#12 file are: keyBag, pkcs8ShroudedKeyBag, certBag (from PKCS#12 v1.1. standard (https://datatracker.ietf.org/doc/html/rfc7292))
• in a way similar to original DecodeChain function, we loop through all the bags, 1) identifying attributes, 2) identifying type of the bag using object identifier, 3) parsing keys/certs appropriately, and 4) creating structs KeyBag (a struct consisting of a map of Attributes and an interface PrivateKey) and CertBag (a struct consisting of a map of Attributes and an x509 certificate X509Certificate)
• we remove the assumption that the first certificate is a leaf certificate; let the end user decide (resolves DecodeChain assumes the certificate chain order is from the leaf to root #54)
• by returning attributes we resolve Provide access to friendlyName for every object #49

Here's an example of the func:

type KeyBag struct {
	Attributes map[string]string
	PrivateKey interface{}
}

type CertBag struct {
	Attributes      map[string]string
	X509Certificate *x509.Certificate
}


func DecodeChainToBags(pfxData []byte, password string) (keyBags []KeyBag, certBags []CertBag, err error) {
	encodedPassword, err := bmpStringZeroTerminated(password)
	if err != nil {
		return nil, nil, err
	}

	bags, encodedPassword, err := getSafeContents(pfxData, encodedPassword, 1, 2)
	if err != nil {
		return nil, nil, err
	}

	for _, bag := range bags {
		attributes := make(map[string]string)
		for _, attribute := range bag.Attributes {
			k, v, err := convertAttribute(&attribute)
			if err != nil {
				return nil, nil, err
			}
			attributes[k] = v
		}
		switch {
		case bag.Id.Equal(oidCertBag):
			certsData, err := decodeCertBag(bag.Value.Bytes)
			if err != nil {
				return nil, nil, err
			}
			certs, err := x509.ParseCertificates(certsData)
			if err != nil {
				return nil, nil, err
			}
			if len(certs) != 1 {
				err = errors.New("pkcs12: expected exactly one certificate in the certBag")
				return nil, nil, err
			}

			certBags = append(certBags, CertBag{
				Attributes:      attributes,
				X509Certificate: certs[0],
			})

		case bag.Id.Equal(oidKeyBag):
			privateKey, err := x509.ParsePKCS8PrivateKey(bag.Value.Bytes)
			if err != nil {
				return nil, nil, err
			}
			keyBags = append(keyBags, KeyBag{
				Attributes: attributes,
				PrivateKey: privateKey,
			})
		case bag.Id.Equal(oidPKCS8ShroundedKeyBag):
			privateKey, err := decodePkcs8ShroudedKeyBag(bag.Value.Bytes, encodedPassword)
			if err != nil {
				return nil, nil, err
			}
			keyBags = append(keyBags, KeyBag{
				Attributes: attributes,
				PrivateKey: privateKey,
			})
		}
	}

	if len(certBags) == 0 {
		return nil, nil, errors.New("pkcs12: certificate missing")
	}
	if len(keyBags) == 0 {
		return nil, nil, errors.New("pkcs12: private key missing")
	}
	return
}

[AGWA]

I'm concerned that this API is too difficult to use correctly. Presumably, the desired end state for this use case is to get a []tls.Certificate which is used to set the Certificates field of tls.Config. With the proposed API, developers would have to assemble chains and match them up to private keys themselves.

I'd prefer an API like the following, which automatically matches certificates to private keys:

type Chain struct {
        FriendlyName string
        PrivateKey   crypto.PrivateKey
        Leaf         *x509.Certificate
        CACerts      []*x509.Certificate
}

func DecodeChains(pfxData []byte, password string) ([]Chain, error)

For every private key, it would find the corresponding certificate for that key, and then build a chain by recursively finding the issuer certificate.

This would resolve #54 but not #49; however I'm not sure that detailed inspection of PKCS#12 files is a use case worth supporting.

[marsskop]

I see, I understand your concerns. The API you offer works in my use case perfectly. I'd like to work on a PR if this proposition gets accepted.

[marsskop]

Linked #62