ATMI C Function Reference
tpkey_getinfo(3c)
Name
tpkey_getinfo()—Gets information associated with a key handle.
Synopsis
#include <atmi.h>
int tpkey_getinfo(TPKEY hKey, char *attribute_name, void *value, long *value_len, long flags)
Description
tpkey_getinfo() reports information about a key handle. A key handle represents a specific principal's key and the information associated with it.
The key under examination is identified by the hKey input parameter. The attribute for which information is desired is identified by the attribute_name input parameter. 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_name parameter will be stored in the memory location indicated by value. The maximum amount of data that can be stored at this location is specified by the caller in value_len.
After tpkey_getinfo() completes, value_len is set to the size of the data actually returned (including a terminating NULL value for string values). If the number of bytes that need to be returned exceeds value_len, tpkey_getinfo() fails (with the TPELIMIT error code) and sets value_len to the required amount of space.
The flags argument is reserved for future use and must be set to 0.
Return Values
On failure, this function returns -1 and sets tperrno to indicate the error condition.
Errors
[TPEINVAL]
Invalid arguments were given. For example, hKey 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
tpkey_close(3c), tpkey_open(3c), tpkey_setinfo(3c)
