Verify Signature (QC3VFYSG, Qc3VerifySignature) API
Required Parameter Group:
| 1 | Signature | Input | Char(*) |
| 2 | Length of signature | Input | Binary(4) |
| 3 | Input data | Input | Char(*) |
| 4 | Length of input data | Input | Binary(4) |
| 5 | Input data format name | Input | Char(8) |
| 6 | Algorithm description | Input | Char(*) |
| 7 | Algorithm description format name | Input | Char(8) |
| 8 | Key description | Input | Char(*) |
| 9 | Key description format name | Input | Char(8) |
| 10 | Cryptographic service provider | Input | Char(1) |
| 11 | Cryptographic device name | Input | Char(10) |
| 12 | Error code | I/O | Char(*) |
Service Program Name: QC3SIGVR
Default Public Authority: *USE
Threadsafe: Yes
The Verify Signature (OPM, QC3VFYSG; ILE, Qc3VerifySignature) API verifies a digital signature is correctly related to the input data. If the verification fails with a CPF9DEF, the input data has been corrupted. A digital signature is created by hashing data and encrypting the hash value using a public key algorithm (PKA). A digital signature can be created by using the Calculate Signature (OPM, QC3CALSG; ILE, Qc3CalculateSignature) API.
Information on cryptographic standards can be found in Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
Authorities and Locks
- Required device description authority
- *USE
- Required file authority
- *OBJOPR, *READ
Required Parameter Group
- Signature
- INPUT; CHAR(*)
The digital signature to verify.
- Length of signature
- INPUT; BINARY(4)
The length of signature should be equal to the key size (size of the modulus), but expressed in bytes.
- Input data
- INPUT; CHAR(*)
The data to verify.
The format of the input data is specified in the input data format name parameter. - Length of input data
- INPUT; BINARY(4)
For input data format DATA0100, this is the length of the data to verify.
For input data format DATA0200, this is the number of entries in the array. - Input data format name
- INPUT; CHAR(8)
The format of the input data parameter.
The possible format names follow.- DATA0100
- The input data parameter contains the data to verify.
- DATA0200
- The input data parameter contains an array of pointers and lengths to the data to verify.
See Input Data Formats for a description of this format.
- Algorithm description
- INPUT; CHAR(*)
The algorithm and associated parameters for verifying the data.
The format of the algorithm description is specified in the algorithm description format name parameter. - Algorithm description format name
- INPUT; CHAR(8)
The format of the algorithm description.
The possible format names follow.- ALGD0100
- The token for an algorithm context. This format must be used when performing the verify signature operation over multiple calls. After the last call (when the final operation flag is on), the context will reset to its initial state and can be used in another API.
- ALGD0400
- Parameters for a verify signature operation.
- ALGD0600
- Parameters for an elliptic curve sign operation (ECDSA).
See Algorithm Description Formats for a description of these formats.
- Key description
- INPUT; CHAR(*)
The key and associated parameters for verifying the data.
The format of the key description is specified in the key description format name parameter.
If the verify operation extends over multiple calls (see ALGD0100 description above), only the key description from the first call will be used. Therefore, on subsequent calls, you may set the pointer to this parameter to NULL. - Key description format name
- INPUT; CHAR(8)
The format of the key description.
If the pointer to the key description parameter is NULL, this parameter will be ignored.
The possible format names follow.- KEYD0100
- The token for a key context. This format identifies a key context. A key
context is used to store a key value so it need not be recreated or retrieved
every time it is used. To create a key context, use the
Create Key Context (OPM, QC3CRTKX;
ILE, Qc3CreateKeyContext) API.
- KEYD0200
- Key parameters.
- KEYD0400
- Keystore label. This format identifies a key from keystore. For more
information about cryptographic services keystore, see Cryptographic Services Keystore.
- KEYD0600
- PEM certificate. This format uses the PKA key in an ASCII encoded
PEM based certificate.
- KEYD0700
- Certificate label. This format uses the public PKA key identified by a label
into signature verification certificate keystore (*SIGNATUREVERIFICATION).
- KEYD0800
- Distinguished name. This format uses the public PKA key identified by a
distinguished name for a certificate in signature verification certificate
keystore (*SIGNATUREVERIFICATION).
See Key Description Formats for a description of these formats.
- Cryptographic service provider
- INPUT; CHAR(1)
The cryptographic service provider (CSP) that will perform the verify signature operation.
0 Any CSP.
The system will choose an appropriate CSP to perform the verify signature operation.1 Software CSP.
The system will perform the verify signature operation using software. If the requested algorithm is not available in software, an error is returned.2 Hardware CSP.
The system will perform the verify signature operation using cryptographic hardware. If the requested algorithm is not available in hardware, an error is returned. A specific cryptographic device can be specified using the cryptographic device name parameter. If the cryptographic device is not specified, the system will choose an appropriate one.
- Cryptographic device name
- INPUT; CHAR(10)
The name of a cryptographic device description.
This parameter is valid when the cryptographic service provider parameter specifies 2 (hardware CSP). Otherwise, this parameter must be blanks or the pointer to this parameter set to NULL. - Error code
- I/O; CHAR(*)
The structure in which to return error information.
For the format of the structure, see Error code parameter.
Input Data Formats
For detailed descriptions of the table fields, see Input Data Formats Field Descriptions.DATA0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat. | PTR(SPP) | Input data pointer | |
| BINARY(4) | Input data length | ||
| CHAR(12) | Reserved | ||
Input Data Formats Field Descriptions
- Input data length
- The length of data to verify.
- Input data pointer
- A space pointer to the data to verify.
- Reserved
- Must be null (binary 0s).
Algorithm Description Formats
For detailed descriptions of the table fields, see Algorithm Description Formats Field Descriptions.ALGD0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Algorithm context token |
| 8 | 8 | CHAR(1) | Final operation flag |
ALGD0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Public key cipher algorithm |
| 4 | 4 | CHAR(1) | PKA block format |
| 5 | 5 | CHAR(3) | Reserved |
| 8 | 8 | BINARY(4) | Signing hash algorithm |
ALGD0600 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Elliptic curve public key algorithm |
| 4 | 4 | CHAR(4) | Reserved |
| 8 | 8 | BINARY(4) | Signing hash algorithm |
| 12 | C | BINARY(4) | Domain parameters length |
| 16 | 10 | PTR(SPP) | Domain parameters |
Algorithm Description Formats Field Descriptions
- Algorithm context token
- A token for an algorithm context. The algorithm context is created by using the Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
- Final operation flag
- The final processing indicator.
0 Continue.
The system will not perform final processing and the algorithm context will maintain the state of the operation. The algorithm context can be used on future calls to this API to continue the verify signature operation. The result of the signature verification will not be returned until the final operation flag is set on. The pointer to the signature parameter may be set to NULL because the signature is not used until the final operation flag is set on.1 Final.
The system will perform final processing. The signature will be verified and the algorithm context will reset to its initial state. The algorithm context can then be used to begin a new cryptographic operation. When performing a final operation, the pointer to the input data parameter may be set to NULL.
- PKA block format
- The public key algorithm block format. Following are the valid values.
0 PKCS #1 block type 00 1 PKCS #1 block type 01 3 ISO 9796-1 5 ANSI X9.31
This format is only valid with signing hash algorithm 2 (SHA-1).
- Public key cipher algorithm
- The encryption algorithm. Following are the valid public key cipher algorithms.
50 RSA
- Elliptic curve public key algorithm
- Following are the valid elliptic curve public key algorithms:
55
ECDSA
Documented in Digital Signature Standard (DSS), FIPS PUB 186-3.
- Reserved
- Must be null (binary 0s).
- Signing hash algorithm
- The hash algorithm. Following are the valid values for the signing hash algorithm.
1 MD5 2 SHA-1 3 SHA-256 4 SHA-384 5 SHA-512 7 SHA-224 - Domain parameters length
- The length of elliptic curve ASN.1, BER encoded domain parameters. If no domain parameters are being supplied independently of the keys, this field should be zero and domain parameters pointer should be NULL.
- Domain parameters
- The elliptic curve ASN.1 BER encoded domain parameters to be used in the event that the ECC key does not already contain domain parameters. If domain parameters are already associated with the key when performing an ECC operation such as ECDSA (See Calculate Signature (OPM, QC3CALSG; ILE, Qc3CalculateSignature) API and Verify Signature (OPM, QC3VFYSG; ILE, Qc3VerifySignature) API) these supplied domain parameters (which will be associated with the Algorithm Context token), will be ignored.
Key Description Formats
For detailed descriptions of the table fields, see Key Description Formats Field Descriptions.KEYD0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Key context token |
KEYD0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Key type |
| 4 | 4 | BINARY(4) | Key string length |
| 8 | 8 | CHAR(1) | Key format |
| 9 | 9 | CHAR(3) | Reserved |
| 12 | C | CHAR(*) | Key string |
KEYD0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(20) | Qualified keystore file name |
| 20 | 14 | CHAR(32) | Record label |
| 52 | 34 | CHAR(4) | Reserved |
KEYD0600 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | PEM certificate length |
| 4 | 4 | CHAR(4) | Reserved |
| 8 | 8 | CHAR(*) | PEM certificate |
KEYD0700 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Certificate label length |
| 4 | 4 | CHAR(4) | Reserved |
| 8 | 8 | CHAR(*) | Certificate label |
KEYD0800 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Distinguished name length |
| 4 | 4 | CHAR(4) | Reserved |
| 8 | 8 | CHAR(*) | Distinguished name |
Key Description Formats Field Descriptions
- Certificate label
- The label of the certificate in signature verification certificate keystore
(*SIGNATUREVERIFICATION).
- Certificate label length
- The length of the certificate label.
- Distinguished name
- The distinguished name of the certificate in signature verification
certificate keystore (*SIGNATUREVERIFICATION).
- Distinguished name length
- The length of the distinguished name.
- File name
- The name of a keystore file. Keystore files are created by using the Create Keystore (OPM, QC3CRTKS; ILE, Qc3CreateKeyStore) API.
- Key context token
- A token for a key context. The key context is created by using the Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext) API.
- Key format
- The format of the key string field. Following are the valid values.
1 BER string
The key is specified in BER encoded PKCS #8 format. For specifications of this format, refer to RSA Security Inc. Public-Key Cryptography Standards. To generate a PKA key pair in this format, use the Generate PKA Key Pair (OPM, QC3GENPK; ILE, Qc3GenPKAKeyPair) API. For details related to the ECC public and private key syntax, see also SEC1 and ANSI X9.62. To generate an elliptic curve PKA key pair, use the Generate ECC Key Pair (OPM, QC3GENECC; ILE, Qc3GenECCKeyPair) API.
- Key string
- The key to use in the verify signature operation.
- Key string length
- Length of the key string specified in the key string field. The format of the key string is specified in the key format field.
- Key type
- The type of key. Following are the valid values.
50 RSA public 56 ECC public
- PEM certificate
- An ASCII encoded PEM formated certificate.
- PEM certificate length
- The length of the PEM certificate.
- Qualified keystore file name
- The keystore file where the key is stored. Keystore files are created
by using the Create Keystore (OPM, QC3CRTKS;
ILE, Qc3CreateKeyStore) API. The first 10 characters contain the file name.
The second 10 characters contain the name of the library
where the keystore file is located. You can use the following special values
for the library name.
*CURLIB The job's current library is used to locate the keystore file. If no library is specified as the current library for the job, the QGPL library is used. *LIBL The job's library list is searched for the first occurence of the specified file name.
- Record label
- The label of a key record in a keystore file. The label will be converted from the job CCSID, or if 65535, the job default CCSID (DFTCCSID) job attribute to CCSID 1200 (Unicode UTF-16). The key record may contain either an RSA public or private key. If a private key, the public key is extracted to use in the verify operation. Key records are created by using the Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord) API or the Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API.
- Reserved
- Must be null (binary 0s).
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9D82 E | No domain parameters specified for the ECC operation. |
| CPF9D83 E | Elliptic curve public key algorithm not valid. |
| CPF9D84 E | Domain parameters not valid. |
| CPF9D85 E | Domain parameters length not valid. |
| CPF9D99 E | Error openning certificate store. |
| CPF9D9F E | Not authorized to keystore file. |
| CPF9DA0 E | Error occured opening keystore file. |
| CPF9DA1 E | Key record not found. |
| CPF9DA2 E | Option 34 is not installed. |
| CPF9DA3 E | Not authorized to use APPIDs. |
| CPF9DA4 E | RSA key identifier was not found in system certificate store. |
| CPF9DA5 E | Keystore file not found. |
| CPF9DA6 E | The keystore file is not available. |
| CPF9DA7 E | File is corrupt or not a valid keystore file. |
| CPF9DA9 D | The PEM certificate contains invalid formatting. |
| CPF9DAA D | A key requires translation. |
| CPF9DAB E | A key can not be decrypted. |
| CPF9DB3 E | Qualified keystore file name not valid. |
| CPF9DB6 E | Record label not valid. |
| CPF9DB8 E | Error occured retrieving key from keystore. |
| CPF9DBE E | PEM certificate length not valid. |
| CPF9DBF E | Certificate label length not valid. |
| CPF9DC0 E | Distinguished name length not valid. |
| CPF9DC2 E | Key-encrypting algorithm context not compatible with key-encrypting key context. |
| CPF9DC6 E | Algorithm not valid for encrypting or decrypting a key. |
| CPF9DC8 E | The input data parameter specifies a NULL pointer. |
| CPF9DC9 E | The total length of data in the input data array is not valid. |
| CPF9DCC E | The length of area provided for signature is not valid. |
| CPF9DCE E | A data length is not valid. |
| CPF9DCF E | A data pointer is not valid. |
| CPF9DD0 E | Clear data format name not valid. |
| CPF9DD2 E | Algorithm description format name not valid. |
| CPF9DD3 E | Key description format name not valid. |
| CPF9DD5 E | Length of input data not valid. |
| CPF9DD6 E | Length of area provided for output data is too small. |
| CPF9DD7 E | The key-encrypting key context for the specified key is not valid or was previously destroyed. |
| CPF9DD8 E | The key-encrypting algorithm context for the specified key is not valid or was previously destroyed. |
| CPF9DDA E | Unexpected return code &1. |
| CPF9DDB E | The key string or Diffie-Hellman parameter string is not valid. |
| CPF9DDD E | The key string length is not valid. |
| CPF9DE0 E | Hash algorithm not valid. |
| CPF9DE3 E | Mode not valid. |
| CPF9DE5 E | PKA (public key algorithm) block format not valid. |
| CPF9DE6 E | Public key algorithm not valid. |
| CPF9DE7 E | Key type not valid. |
| CPF9DE9 E | Key format not valid. |
| CPF9DEC E | Cryptographic service provider not valid. |
| CPF9DED E | Final operation flag not valid. |
| CPF9DEE E | Reserved field not null. |
| CPF9DEF E | The signature verification failed. |
| CPF9DF0 E | Operation, algorithm, or mode not available on the requested CSP (cryptographic service provider). |
| CPF9DF1 E | The algorithm context token does not reference a valid algorithm context. |
| CPF9DF2 E | The algorithm context is not found or was previously destroyed. |
| CPF9DF3 E | Algorithm in algorithm context not valid for requested operation. |
| CPF9DF4 E | The key context token does not reference a valid key context. |
| CPF9DF5 E | The key context is not found or was previously destroyed. |
| CPF9DF7 E | Algorithm context not compatible with key context. |
| CPF9DF8 E | Cryptographic device name not valid. |
| CPF9DF9 E | Cryptographic device not found. |
| CPF9DFB E | Cryptographic service provider (CSP) conflicts with the key context CSP. |
| CPF9DFD E | Not authorized to device. |
| CPF9DFE E | Cryptographic device not available. |
API introduced: V5R3
[ Back to top | Cryptographic Services APIs | APIs by category ]