1=pod 2 3=head1 NAME 4 5EVP_SIGNATURE-SLH-DSA, 6EVP_SIGNATURE-SLH-DSA-SHA2-128s, EVP_SIGNATURE-SLH-DSA-SHA2-128f, 7EVP_SIGNATURE-SLH-DSA-SHA2-192s, EVP_SIGNATURE-SLH-DSA-SHA2-192f, 8EVP_SIGNATURE-SLH-DSA-SHA2-256s, EVP_SIGNATURE-SLH-DSA-SHA2-256f, 9EVP_SIGNATURE-SLH-DSA-SHAKE-128s, EVP_SIGNATURE-SLH-DSA-SHAKE-128f, 10EVP_SIGNATURE-SLH-DSA-SHAKE-192s, EVP_SIGNATURE-SLH-DSA-SHAKE-192f, 11EVP_SIGNATURE-SLH-DSA-SHAKE-256s, EVP_SIGNATURE-SLH-DSA-SHAKE-256f 12- EVP_PKEY SLH-DSA support 13 14=head1 DESCRIPTION 15 16The B<SLH-DSA-SHA2-128s>, B<EVP_PKEY-SLH-DSA-SHA2-128f>, 17B<SLH-DSA-SHA2-192s>, B<EVP_PKEY-SLH-DSA-SHA2-192f>, 18B<SLH-DSA-SHA2-256s>, B<EVP_PKEY-SLH-DSA-SHA2-256f>, 19B<SLH-DSA-SHAKE-128s>, B<EVP_PKEY-SLH-DSA-SHAKE-128f>, 20B<SLH-DSA-SHAKE-192s>, B<EVP_PKEY-SLH-DSA-SHAKE-192f>, 21B<SLH-DSA-SHAKE-256s> and B<EVP_PKEY-SLH-DSA-SHAKE-256f> EVP_PKEY implementations 22supports key generation, one-shot sign and verify using the SLH-DSA 23signature schemes described in FIPS 205. 24 25The different algorithms names correspond to the parameter sets defined in 26FIPS 205 Section 11 Table 2. 27C<s> types have smaller signature sizes, and the C<f> variants are faster, 28(The signatures range from ~8K to ~50K depending on the type chosen). There are 293 different security categories also depending on the type. 30 31L<EVP_SIGNATURE_fetch(3)> can be used to explicitely fetch one of the 12 32algorithms which can then be used with L<EVP_PKEY_sign_message_init(3)>, 33L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify_message_init(3)>, and 34L<EVP_PKEY_verify(3)> to perform one-shot message signing or verification. 35 36The normal signing process (called Pure SLH-DSA Signature Generation) 37encodes the message internally as 0x00 || len(ctx) || ctx || message. 38where B<ctx> is some optional value of size 0x00..0xFF. 39OpenSSL also allows the message to not be encoded which is required for 40testing. OpenSSL does not support Pre Hash SLH-DSA Signature Generation, but this 41may be done by the user by doing Pre hash encoding externally and then chosing 42the option to not encode the message. 43 44=head2 SLH-DSA Signature Parameters 45 46The C<context-string> parameter, described below, can be used for both signing 47and verification. 48It may be set by passing an OSSL_PARAM array to L<EVP_PKEY_sign_init_ex2(3)> or 49L<EVP_PKEY_verify_init_ex2(3)> 50 51=over 4 52 53=item "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string> 54 55A string of octets with length at most 255. By default it is the empty string. 56 57=back 58 59The following parameters can be used when signing: 60They can be set by passing an OSSL_PARAM array to L<EVP_PKEY_sign_init_ex2(3)>. 61 62=over 4 63 64=item "message-encoding" (B<OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING>) <integer> 65 66The default value of 1 uses 'Pure SLH-DSA Signature Generation' as described 67above. Setting it to 0 does not encode the message, which is used for testing, 68but can also be used for 'Pre Hash SLH-DSA Signature Generation'. 69 70=item "test-entropy" (B<OSSL_SIGNATURE_PARAM_TEST_ENTROPY <octet string> 71 72Used for testing to pass a optional random value. 73 74=item "deterministic" (B<OSSL_SIGNATURE_PARAM_DETERMINISTIC>) <integer> 75 76The default value of 0 generates a random value (using a DRBG) this is used when 77processing the message. Setting this to 1 causes the private key seed to be used 78instead. This value is ignored if "test-entropy" is set. 79 80=back 81 82See L<EVP_PKEY-SLH-DSA(7)> for information related to B<SLH-DSA> keys. 83 84=head1 NOTES 85 86For backwards compatibility reasons EVP_DigestSignInit_ex(), EVP_DigestSign(), 87EVP_DigestVerifyInit_ex() and EVP_DigestVerify() may also be used, but the digest 88passed in I<mdname> must be NULL. 89 90=head1 EXAMPLES 91 92To sign a message using an SLH-DSA EVP_PKEY structure: 93 94 void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len) 95 { 96 size_t sig_len; 97 unsigned char *sig = NULL; 98 const OSSL_PARAM params[] = { 99 OSSL_PARAM_octet_string("context-string", (unsigned char *)"A context string", 33), 100 OSSL_PARAM_END 101 }; 102 EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL); 103 EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "SLH-DSA-SHA2-128s", NULL); 104 105 EVP_PKEY_sign_message_init(sctx, sig_alg, params); 106 /* Calculate the required size for the signature by passing a NULL buffer. */ 107 EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len); 108 sig = OPENSSL_zalloc(sig_len); 109 EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len); 110 ... 111 OPENSSL_free(sig); 112 EVP_SIGNATURE(sig_alg); 113 EVP_PKEY_CTX_free(sctx); 114 } 115 116=head1 SEE ALSO 117 118L<EVP_PKEY-SLH-DSA(7)> 119L<provider-signature(7)>, 120L<EVP_PKEY_sign(3)>, 121L<EVP_PKEY_verify(3)>, 122 123=head1 HISTORY 124 125This functionality was added in OpenSSL 3.5. 126 127=head1 COPYRIGHT 128 129Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 130 131Licensed under the Apache License 2.0 (the "License"). You may not use 132this file except in compliance with the License. You can obtain a copy 133in the file LICENSE in the source distribution or at 134L<https://www.openssl.org/source/license.html>. 135 136=cut 137