Digital Signature Verify (CSNDDSV)

Edit online

Use the Digital Signature Verify callable service to verify a digital signature using a PKA public key.

  • The Digital Signature Verify callable service can use the RSA, ECC, ML-DSA or CRYSTALS-Dilithium public key, depending on the digital signature algorithm used to generate the signature.
  • The Digital Signature Verify callable service can use the RSA public keys that are contained in trusted blocks regardless of whether the block also contains rules to govern its use when generating or exporting keys with the RKX service. If the TPK-ONLY keyword is used in the rule_array parameter, an error will occur if the PKA_public_key_identifier parameter does not contain a trusted block.
  • The Digital Signature Verify callable service can use an X.509 certificate containing an RSA or ECC public key.

This service verifies digital signatures generated with these methods:

  • ANSI X9.62 (ECC using ECDSA: Brainpool, NIST prime, and Koblitz curve secp256k1)
    • Recommended hash methods: SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.
  • ISO/IEC 14888 Schnorr Digital Signature Algorithm (SDSA), (ECC using keyword EC-SDSA)
    • The hash method for P256 keys is SHA-256.
    • The hash method for P521 keys is SHA-512.
  • Edwards-curve digital signature algorithm (ECC using EDDSA)
    • Required hash method for Ed25519: SHA-512.
    • Required hash method for Ed448: SHAKE-256.
  • ANSI X9.31 (RSA)
  • ISO 9796-1 (RSA)
  • RSA DSI PKCS #1 v1.5 and v2.1 (RSA)
  • Padding on the left with zeros (RSA)
  • ML-DSA or CRYSTALS-Dilithium Digital Signature Algorithm (CRDL-DSA)

The input text can be hashed using the One-Way Hash verb, the MDC Generate verb, or the Digital Signature Verify verb.

This verb can also use the public keys that are contained in trusted blocks, regardless of whether the block also contains rules to govern its use when generating or exporting keys with the Remote Key Export verb. The format of the trusted block enables Digital Signature Verify to distinguish it from other RSA key tokens, and therefore no special rule array keyword or other parameters are required in order to indicate that the trusted block is being used. However, if the Digital Signature Generate verb is used with the TPK-ONLY keyword in the rule_array, an error will occur if the PKA_public_key_identifier does not contain a trusted block.

This service accepts either the input message (text) or a hash of the input message. If the input text is specified to be a hash, then it should have been previously hashed. You can use the One-Way Hash verb. See also Formatting hashes and keys in public-key cryptography.

An X.509 certificate couples an identity to a PKA (RSA or ECC) public key. As of CCA 6.0, such an X.509 certificate can be used by the CSNDDSV verb instead of a PKA (RSA or ECC) public key token. Because X.509 certificates require authentication against a PKI, the TKE workstation must be used to install the trust roots that will be used to validate your operational X.509 certificates at run-time.

If the input text is specified to be a message (by the MESSAGE key word), or if PKCS-PSS is specified, then apply a required hashing-method specification keyword. If the PKCS-PSS keyword is specified, optionally specify a signature checking rule to indicate whether the derived salt length is an exact match to the input salt length (the default), or is not an exact match (requires special authorization).

If keyword ECDSA is specified in the rule array, the Elliptic Curve Digital Signature Algorithm is used as the digital-signature hash formatting method.

If keyword EDDSA is specified, the EC Edwards digital signature algorithm and hashing method appropriate for Edwards curves is used (ED-HASH).

If keyword CRDL-DSA is specified, the ML-DSA or CRYSTALS-Dilithium algorithm and an appropriate hashing method is used (CRLDHASH). Otherwise, specify the optional digital-signature hash formatting method keyword in the rule array for the method used to generate the RSA digital signature being verified.

See also Formatting hashes and keys in public-key cryptography.

The Automated Crypto Validation Protocol (ACVP) defines a mechanism to automatically verify the cryptographic implementation of a software or hardware crypto module. ACVP is a network protocol for which NIST provides a server using the protocol which produces test vectors, validates responses and, in the case of successful validation, issues certificates that can be used in support of the Cryptographic Module Validation Program’s (CMVP) FIPS 140-2 conformance validations.

Also refer to the following pages of the NIST:


ACVP
ACVP ML-DSA JSON Specification
Cryptographic Module Validation Program

Notes:

  1. This verb supports PCI-HSM 2016 compliant-tagged key tokens.
  2. The maximum signature length is 256 bytes (2048 bits).

EC signature verification update

Beginning with CCA Release 5.0 of CSNDDSV for the CEX5C, checking of EC signatures is strengthened with new hardware support. For most invalid signatures the typical response of return code 4, reason code 429 is still returned. However, for some cases where the signature value r or value s is mathematically off the curve described by the q value from the EC key, that is, when r > (q-1) or s > (q-1), then return code 12 with reason code 769 is returned, indicating a rejection from the EC hardware layer. The decision to return the different error for the more serious case is reached when the host library loads (at application startup) by the value of a new environment variable: CSU_EC_CHECKCURVE
For appropriate failure cases, if the value of CSU_EC_CHECKCURVE is 1, then the new return/reason code 12/769 is returned. Otherwise, 4/429 is returned. The default value of CSU_EC_CHECKCURVE is 0, to maintain compatibility with prior releases. IBM® recommends that customers prepare their applications and set the new environment variable to 1. Use the following command to set the variable (also to set it in a profile):
 export CSU_EC_CHECKCURVE=1

Some error path test cases with pre-figured values may need to be updated, and the new return/reason code handling may need to be added to your application as a different type of signature verification failure. The adapter is functioning normally and no service action is required. Note that this change does not narrow valid verification cases or add restrictions. All valid signatures when passed to CSNDDSV with the correct key still verify with return code of 0, reason code of 0.

Advantages of the new verification granularity

The new use of return code/reason code 12/769 can help you with problem determination for the following practical cases:

  • Check the bytes of the ECDSA signature. The r value is mathematically determined from the order of G of the curve and a random number. If the value of r or the value of s equals or exceeds the order of G of the curve, then the signature has been corrupted. No value or range of values can be statically ruled out for any bytes of r or s because of the random components. However you may be able to detect a corruption pattern by inspection. The s value is the same byte length as r (which is the same length as the curve order of G). The s value immediately follows r in the signature.
  • Certain types of key corruption may also cause this error - forcing the key to be off the curve. Since public keys are passed in the clear, this is hard to detect until the public key is actually used, but again inspection of the key data may help.
  • While using the wrong key type on the same curve size (example: substituting a P384 key for a BP384 key) will probably not generate 12/769 instead of 4/429, using a key for a smaller curve may generate 12/769 (example: substituting a P224 key for a P256 key).