ATMI COBOL Function Reference
TPKEYGETINFO(3cbl)
Name
TPKEYGETINFO() - get information associated with a key handle
Synopsis
01 TPKEYDEF-REC.
COPY TPKEYDEF.
01 ATTVALUE-REC.
COPY user data
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPKEYGETINFO" USING TPKEYDEF-REC ATTVALUE-REC TPSTATUS-REC.
Description
TPKEYGETINFO() reports information about a key handle. A key handle represents a specific principal's key and the information associated with it.
The calling process must supply KEY-HANDLE in TPKEYDEF-REC, which is a key identifier returned by a previous call to TPKEYOPEN().
The attribute for which information is desired is identified by ATTRIBUTE-NAME in TPKEYDEF-REC. The attribute name may be padded with SPACES or LOW-VALUES. Some attributes are specific to a cryptographic service provider, but the following core set of attributes should be supported by all providers.
|
Attribute
|
Value
|
|
PRINCIPAL
|
The name identifying the principal associated with the key (key handle), represented as a NULL-terminated character string.
|
|
PKENCRYPT_ALG
|
An ASN.1 Distinguished Encoding Rules (DER) object identifier of the public key algorithm used by the key for public key encryption.
The object identifier for RSA is identified in the following table.
|
|
PKENCRYPT_BITS
|
The key length of the public key algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive.
|
|
SIGNATURE_ALG
|
An ASN.1 DER object identifier of the digital signature algorithm used by the key for digital signature.
The object identifiers for RSA and DSA are identified in the following table.
|
|
SIGNATURE_BITS
|
The key length of the digital signature algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive.
|
|
ENCRYPT_ALG
|
An ASN.1 DER object identifier of the symmetric key algorithm used by the key for bulk data encryption.
The object identifiers for DES, 3DES, and RC2 are identified in the following table.
|
|
ENCRYPT_BITS
|
The key length of the symmetric key algorithm. The value must be within the range of 40 to 128 bits, inclusive.
When an algorithm with a fixed key length is set in ENCRYPT_ALG, the ENCRYPT_BITS value is automatically set to the fixed key length. For example, if ENCRYPT_ALG is set to DES, the ENCRYPT_BITS value is automatically set to 56.
|
|
DIGEST_ALG
|
An ASN.1 DER object identifier of the message digest algorithm used by the key for digital signature.
The object identifiers for MD5 and SHA-1 are identified in the following table.
|
|
PROVIDER
|
The name of the cryptographic service provider.
|
|
VERSION
|
The version number of the cryptographic service provider's software.
|
The ASN.1 DER algorithm object identifiers supported by the default public key implementation are given in the following table.
|
ASN.1 DER Algorithm Object Identifier
|
Algorithm
|
|
{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x02, 0x05 }
|
MD5
|
|
{ 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x1a }
|
SHA1
|
|
{ 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01 }
|
RSA
|
|
{ 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x0c }
|
DSA
|
|
{ 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x07 }
|
DES
|
|
{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x03, 0x07 }
|
3DES
|
|
{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x03, 0x02 }
|
RC2
|
The information associated with the specified attribute will be stored in user-defined ATTVALUE-REC, padded at the end with SPACES. The maximum amount of data that can be stored at this location is specified by the caller in ATTRIBUTE-VALUE-LEN in TPKEYDEF-REC.
After TPKEYGETINFO() completes, ATTRIBUTE-VALUE-LEN is set to the size of the data actually returned (not including padding values). If the number of bytes that need to be returned exceeds ATTRIBUTE-VALUE-LEN, TPKEYGETINFO() fails (with the TPELIMIT error code) and sets ATTRIBUTE-VALUE-LEN to the required amount of space.
Return Values
Upon successful completion, TPKEYGETINFO() sets TP-STATUS in TPSTATUS-REC to [TPOK].
Errors
Upon failure, TPKEYGETINFO() sets TP-STATUS in TPSTATUS-REC to one of the following values:
[TPEINVAL]
Invalid arguments were given. For example, KEY-HANDLE is not a valid key.
[TPESYSTEM]
An error occurred. Consult the system error log file for details.
[TPELIMIT]
Insufficient space was provided to hold the requested attribute value.
[TPENOENT]
The requested attribute is not associated with this key.
See Also
TPKEYCLOSE(3cbl), TPKEYOPEN(3cbl), TPKEYSETINFO(3cbl)
