Add initial version of composite signatures

.github/workflows/build-docs.yml

@@ -11,6 +11,13 @@ on:
     paths:
       - 'working/doc/spec/**'
 
+  workflow_dispatch:
+    inputs:
+      branch_name:
+        description: 'The branch name to run the workflow on'
+        required: true
+        default: 'main'
+
 jobs:
   build:
     name: Automatic Docs build

working/doc/spec/comp_sig.md

@@ -0,0 +1,213 @@
+## Composite Signature
+
+Composite Signatures are mechanisms for signatures and verification, following
+the digital signature algorithm defined in [COMP_SIG]
+
+
++--------------------------------------+---------------------------------------------------+
+|                                      |Functions                                          |
+|                                      +-----+-----+------+-----+-------+-----+-----+------+
+| Mechanism                            | ENC | SIG | SIGR |     | GENK  | WRP |     | ENCS |
+|                                      |  &  |  &  |  &   | DIG |   &   |  &  | DRV |  &   |
+|                                      | DEC | VER | VERR |     | GENKP | UWRP|     | DECS |
++======================================+:===:+:===:+:====:+:===:+:=====:+:===:+:===:+:====:+
+| CKM_COMP_SIG_KEY_PAIR_GEN             |     |    |      |     |   ✓   |     |     |      |
+| CKM_COMP_SIG                          |     | ✓  |     |     |        |     |     |      |
+| CKM_COMP_SIG_EXTERNAL_HASH            |     | ✓  |     |     |        |     |     |      |
++--------------------------------------+-----+-----+------+-----+-------+-----+-----+------+
+table: Composite Signature Mechanisms vs. Functions
+
+
+### Definitions
+
+This section defines the key type **CKK_COMP_SIG** for type **CK_KEY_TYPE**, as used in the **CKA_KEY_TYPE** attribute of all Composite key objects.
+
+Mechanisms:
+
+- CKM_COMP_SIG_KEY_PAIR_GEN
+- CKM_COMP_SIG
+- CKM_COMP_SIG_EXTERNAL_HASH
+
+
+**CK_COMP_SIG_PARAMETER_SET_TYPE** is used to indicate which Composite Signature parameter set the keys belong to.
+
+~~~{.c}
+typedef CK_ULONG CK_COMP_SIG_PARAMETER_SET_TYPE;
+~~~
+
+Parameter set types:
+
+- CKP_COMP_SIG_MLDSA44_RSA2048_PSS_SHA256
+- CKP_COMP_SIG_MLDSA44_RSA2048_PKCS15_SHA256
+- CKP_COMP_SIG_MLDSA44_ED25519_SHA512
+- CKP_COMP_SIG_MLDSA44_ECDSA_P256_SHA256
+- CKP_COMP_SIG_MLDSA65_RSA3072_PSS_SHA512
+- CKP_COMP_SIG_MLDSA65_RSA3072_PKCS15_SHA512
+- CKP_COMP_SIG_MLDSA65_RSA4096_PSS_SHA512
+- CKP_COMP_SIG_MLDSA65_RSA4096_PKCS15_SHA512
+- CKP_COMP_SIG_MLDSA65_ECDSA_P256_SHA512
+- CKP_COMP_SIG_MLDSA65_ECDSA_P384_SHA512
+- CKP_COMP_SIG_MLDSA65_ECDSA_BRAINPOOLP256R1_SHA512
+- CKP_COMP_SIG_MLDSA65_ED25519_SHA512
+- CKP_COMP_SIG_MLDSA87_ECDSA_P384_SHA512
+- CKP_COMP_SIG_MLDSA87_ECDSA_BRAINPOOLP384R1_SHA512
+- CKP_COMP_SIG_MLDSA87_ED448_SHAKE256
+- CKP_COMP_SIG_MLDSA87_RSA3072_PSS_SHA512
+- CKP_COMP_SIG_MLDSA87_RSA4096_PSS_SHA512
+- CKP_COMP_SIG_MLDSA87_ECDSA_P521_SHA512
+
+
+**CK_SIGN_ADDITIONAL_CONTEXT** is used in the mechanism parameters to supply a NIST-defined context string.  It is
+defined in the ML-DSA section of this specification.
+
+
+
+### Composite Signature public key objects
+
+Composite Signature public key objects (object class **CKO_PUBLIC_KEY**, key type **CKK_COMP_SIG**) hold Composite Signature public keys.
+
+The following table defines the Composite Signature public key object attributes, in addition
+to the common attributes defined for this object class:
+
+| Attribute               | Data Type                       | Meaning                               |
+| ----------------------- | --------------------------------| ------------------------------------- |
+| CKA_PARAMETER_SET ^1,3^ | CK_COMP_SIG_PARAMETER_SET_TYPE  | Composite Signature parameter set     |
+| CKA_VALUE ^1,4^         | Byte array                      | Public key as defined in [COMP_SIG]   |
+table: Composite Signature Public Key Object Attributes
+
+- Refer to Table 13 for footnotes
+
+The **CKA_PARAMETER_SET** attribute value selects a predefined set of parameters
+specified by [COMP_SIG].
+The parameter set will select the security level and public key sizes. Tokens may
+ support a subset of the defined parameter sets.
+
+The following is a sample template for creating an Composite Signature public key object:
+
+~~~{.c}
+CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
+CK_KEY_TYPE keyType = CKK_COMP_SIG;
+CK_UTF8CHAR label[] = "A Composite Signature public key object";
+CK_COMP_SIG_PARAMETER_SET_TYPE param_set = CKP_COMP_SIG_MLDSA65_ECDSA_P256_SHA512;
+CK_BYTE value[] = {...};
+CK_BBOOL true = CK_TRUE;
+CK_ATTRIBUTE template[] = {
+  {CKA_CLASS, &class, sizeof(class)},
+  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
+  {CKA_TOKEN, &true, sizeof(true)},
+  {CKA_LABEL, label, sizeof(label)-1},
+  {CKA_PARAMETER_SET, &param_set, sizeof(param_set)},
+  {CKA_VALUE, value, sizeof(value)}
+};
+~~~
+
+### Composite Signature private key objects
+
+Composite Signature private key objects (object class **CKO_PRIVATE_KEY**, key type
+**CKK_COMP_SIG**) hold Composite Signature private keys.
+
+The following table defines the Composite Signature private key object attributes, in
+addition to the common attributes defined for this object class:
+
+| Attribute                | Data Type                      | Meaning                                     |
+| ------------------------ | ------------------------------ | ------------------------------------------- |
+| CKA_PARAMETER_SET^1,4,6^ | CK_COMP_SIG_PARAMETER_SET_TYPE | Composite Signature parameter set           |
+| CKA_VALUE^1,4,6,7^       | Byte array                     | Private key as defined in [COMP_SIG]        |
+table: Composite Signature Private Key Object Attributes
+
+- Refer to Table 13 for footnotes
+
+**CKA_VALUE** must be provided during **C_CreateObject**.
+
+The **CKA_PARAMETER_SET** attribute value selects a predefined set of parameters
+specified in [COMP_SIG].  The parameter set will select the composite label, the
+component algorithms and any associated parameters for the component algorithms
+as well as the pre-hash algorithm.
+
+Note that when generating a Composite Signature private key, the parameter set is not
+specified in the key’s template. This is because Composite Signature private keys are
+only generated as part of a Composite Signature key pair, and the parameter set for
+the pair is specified in the template for the Composite Signature public key.
+
+The following is a sample template for creating a Composite Signature private key object:
+
+
+~~~{.c}
+CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
+CK_KEY_TYPE keyType = CKK_COMP_SIG;
+CK_UTF8CHAR label[] = "A Composite Signature private key object";
+CK_BYTE subject[] = {...};
+CK_BYTE id[] = {123};
+CK_BYTE value[] = {...};
+CK_BBOOL true = CK_TRUE;
+
+CK_ATTRIBUTE template[] = {
+  {CKA_CLASS, &class, sizeof(class)},
+  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
+  {CKA_TOKEN, &true, sizeof(true)},
+  {CKA_LABEL, label, sizeof(label)-1},
+  {CKA_SUBJECT, subject, sizeof(subject)},
+  {CKA_ID, id, sizeof(id)},
+  {CKA_SENSITIVE, &true, sizeof(true)},
+  {CKA_SIGN, &true, sizeof(true)},
+  {CKA_VALUE, value, sizeof(value)}
+};
+~~~
+
+
+## Composite Signature key pair generation
+
+The Composite Signature key pair generation mechanism, denoted **CKM_COMP_SIG_KEY_PAIR_GEN**,
+is a key pair generation mechanism using KeyGen() as defined in section 4.1 of [COMP_SIG]
+
+It takes **CK_COMP_SIG_PARAMETER_SET_TYPE** to denote the composite component algorithms, 
+the composite label and the hash function. 
+
+The mechanism generates Composite Signature public and private key pairs with a parameter set,
+as specified in the **CKA_PARAMETER_SET** attribute of the template for the public key.  
+This parameter set references the object identifiers defined in [COMP_SIG] which fully specify
+the composite label, component algorithms and the hash function used for pre-hashing.
+
+The mechanism contributes the **CKA_CLASS**, **CKA_KEY_TYPE**, and **CKA_VALUE** attributes
+to the new public key and the **CKA_CLASS**, **CKA_KEY_TYPE**, **CKA_PARAMETER_SET**, and
+**CKA_VALUE** attributes to the new private key; other attributes required by the Composite
+Signature public and private key types must be specified in the templates.
+
+For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the **CK_MECHANISM_INFO**
+structure specify the supported range of Composite Signature public key in bytes.
+
+
+### Composite Signature
+
+The composite signature mechanism, denoted **CKM_COMP_SIG**, is a mechanism for generating
+and verifying Composite Signatures as defined in sections 4.2 and 4.3 of [COMP_SIG], 
+Algorithm 4.2 Sign and Algorithm 4.3 Verify, using SHA256, SHA512 or SHAKE256 as the hash
+function. The data passed in is the message M.
+
+The composite signature mechanism, denoted **CKM_COMP_SIG_EXTERNAL_HASH**, is a mechanism
+for generating and verifying Composite Signatures as defined in sections 4.2 and 4.3 of 
+[COMP_SIG] using SHA256, SHA512 or SHAKE256 as the hash function. The data passed in is
+the pre-hash of the message PH(M).  The hash algorithm used is the hash algorithm
+specified in the **CK_COMP_SIG_PARAMETER_SET_TYPE** for the specific composite.
+For example, a **CKM_COMP_SIG_EXTERNAL_HASH** with a **CK_COMP_SIG_PARAMETER_SET_TYPE**
+of **CKP_COMP_SIG_MLDSA65_ECDSA_P256_SHA512** MUST require PH(M) to be 64 bytes long
+because PH(M) is calculated by computing the value of SHA512(M). 
+
+Both signing mechanisms have an optional parameter **CK_SIGN_ADDITIONAL_CONTEXT**. If
+no parameter is supplied ulContextLen will be zero and pContext will be NULL.  Constraints
+on key types and the length of the data are summarized in the following table. In the
+table, k is the length in bytes of the Composite Signature.
+
+
+| Function          | Key Type                        | Input Length | Output Length |
+| ----------------- | ------------------------------- | ------------ | ------------- |
+| C_Sign            | Composite Signature Private Key | any          | k             |
+| C_Verify ^1^      | Composite Signature Public Key  | any, k       | N/A           |
+| C_VerifySignature | Composite Signature Public Key  | any, k       | N/A           |
+table: Composite Signature: Key and Data Length
+
+^1^ Single-part operations only.
+
+For these mechanisms, the _ulMinKeySize_ and _ulMaxKeySize_ fields of the
+**CK_MECHANISM_INFO** structure specify the supported range of Composite Signature
+public keys in bytes.

working/doc/spec/references.md

@@ -68,6 +68,12 @@ Johnson, D.B. “The Commercial Data Masking Facility (CDMF) data privacy algori
 
 URL: <http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=5389557>
 
+**[COMP_SIG]**
+
+M. Ounsworth, J. Gray, M. Pala, J. Klaußner, S. Fluher. "Composite ML-DSA for use in X.509 Public Key Infrastructure", January 2026
+
+URL: <https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/14/>
+
 **[CHACHA]**
 
 D. Bernstein, “ChaCha, a variant of Salsa20”, January 2008.

working/doc/spec/spec_files.txt

@@ -98,6 +98,7 @@ xmss_and_xmss-mt.md
 ml_dsa.md
 ml-kem.md
 slh-dsa.md
+comp_sig.md
 kmac.md
 references.md
 security_and_privacy_considerations.md