Wrapping and Unwrapping Support

[jonomango]

Hello, we love this library and have been using it extensively for our internal projects. We have implemented wrapping and unwrapping support in a crypto11 fork and would like for this feature to be added upstream. We would like the original authors' input on how the design should look.

We have currently added receivers to the SecretKey struct (WrapKWP() and UnwrapKWP()), but maybe it would be better to make something resembling the BlockModeCloser struct? Something like NewKWPWrapper() and NewKWPUnwrapper()? Can we have some input on this?

[aedlebeck]

I would also like this functionality.

[Nicolas-Peiffer]

Hi @jonomango and @aedlebeck 😃 , TY 🙏 for your interest and the issue. And sorry for the late reply.

In 2026 the big project for crypto11 is to add the support of PKCS#11 v3.2 and the support of the ML-KEM PQC algorithm:

• add support for pkcs11 v3.2 ml-kem #131
• We work on this branch mainly: pkcs11-v3.2-ml-kem.
• It will lead to a crypto11@v2, as there are many changes, including we are using a new PKCS11 implementation eclipse-keypont/pkcs11-go.
• Summary of the changes here: pkcs11-v3.2-ml-kem/CHANGELOG.md

The other big project for 2026 is giving + moving the crypto11 project under the Eclipse Foundation.

Knowing this, how do you think we should discuss your idea and verify if it is feasible to implement it in the future of crypto11@v2? 🤔

[jonomango]

This is how we designed it in our fork and it is easy to use, maybe we can flesh out this implementation a bit more if you have any ideas @Nicolas-Peiffer

func (wrappingKey *SecretKey) WrapSecretKey(key *SecretKey, mechParam any, wrappingMech uint) (wrappedKey []byte, err error) {
	err = wrappingKey.context.withSession(func(session *pkcs11Session) error {
		mech := []*pkcs11.Mechanism{pkcs11.NewMechanism(wrappingMech, mechParam)}

		wrappedKey, err = session.ctx.WrapKey(session.handle, mech, wrappingKey.Handle, key.Handle)
		if err != nil {
			return fmt.Errorf("Failed to WrapKey: %w", err)
		}

		return nil
	})

	return wrappedKey, err
}

func (unwrappingKey *SecretKey) UnwrapSecretKey(wrappedKey []byte, mechParam any, id []byte, wrappingMech uint, cipher *SymmetricCipher) (unwrappedKey *SecretKey, err error) {
	template, err := NewAttributeSetWithID(id)
	if err != nil {
		return nil, err
	}
	return unwrappingKey.UnwrapSecretKeyWithAttributes(wrappedKey, mechParam, template, wrappingMech, cipher)
}

func (unwrappingKey *SecretKey) UnwrapSecretKeyWithLabel(wrappedKey []byte, mechParam any, id, label []byte, wrappingMech uint, cipher *SymmetricCipher) (unwrappedKey *SecretKey, err error) {
	template, err := NewAttributeSetWithIDAndLabel(id, label)
	if err != nil {
		return nil, err
	}
	return unwrappingKey.UnwrapSecretKeyWithAttributes(wrappedKey, mechParam, template, wrappingMech, cipher)
}

func (unwrappingKey *SecretKey) UnwrapSecretKeyWithAttributes(wrappedKey []byte, mechParam any, template AttributeSet, wrappingMech uint, cipher *SymmetricCipher) (unwrappedKey *SecretKey, err error) {
	err = unwrappingKey.context.withSession(func(session *pkcs11Session) error {
		mech := []*pkcs11.Mechanism{pkcs11.NewMechanism(wrappingMech, mechParam)}
		template.AddIfNotPresent([]*pkcs11.Attribute{
			pkcs11.NewAttribute(pkcs11.CKA_CLASS, pkcs11.CKO_SECRET_KEY),
			pkcs11.NewAttribute(pkcs11.CKA_KEY_TYPE, cipher.KeyType),
			pkcs11.NewAttribute(pkcs11.CKA_TOKEN, true),
			pkcs11.NewAttribute(pkcs11.CKA_SIGN, cipher.MAC),
			pkcs11.NewAttribute(pkcs11.CKA_VERIFY, cipher.MAC),
			pkcs11.NewAttribute(pkcs11.CKA_ENCRYPT, cipher.Encrypt), // Not supported on CloudHSM
			pkcs11.NewAttribute(pkcs11.CKA_DECRYPT, cipher.Encrypt), // Not supported on CloudHSM
			pkcs11.NewAttribute(pkcs11.CKA_WRAP, cipher.Wrap),
			pkcs11.NewAttribute(pkcs11.CKA_UNWRAP, cipher.Unwrap),
			pkcs11.NewAttribute(pkcs11.CKA_DERIVE, cipher.Derive),
			pkcs11.NewAttribute(pkcs11.CKA_SENSITIVE, true),
			pkcs11.NewAttribute(pkcs11.CKA_EXTRACTABLE, cipher.Extractable),
		})

		handle, err := session.ctx.UnwrapKey(session.handle, mech, unwrappingKey.Handle, wrappedKey, template.ToSlice())
		if err != nil {
			return fmt.Errorf("Failed to UnwrapKey: %w", err)
		}

		unwrappedKey = &SecretKey{PKCS11Object{Handle: handle, context: unwrappingKey.context}, cipher}
		return nil
	})

	return
}