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)