Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPKEYSETINFO(3cbl)

Name

TPKEYSETINFO() - set optional parameters associated with a key handle

Synopsis

01 TPKEYDEF-REC. 
   COPY TPKEYDEF.

01 ATTVALUE-REC.
   COPY user data

01 TPSTATUS-REC.
   COPY TPSTATUS.

CALL "TPKEYSETINFO" USING TPKEYDEF-REC ATTVALUE-REC TPSTATUS-REC.

Description

TPKEYSETINFO() sets an optional attribute parameter for a key handle. A key handle represents a specific principal's key and the information associated with it.

The key for which information is to be modified is identified by KEY-HANDLE in TPKEYDEF-REC. KEY-HANDLE is a key identifier returned by a previous call to TPKEYOPEN().

The attribute for which information is to be modified is identified by ATTRIBUTE-NAME in TPKEYDEF-REC. The attribute name may be padded with SPACES or LOW-VALUES. Some attributes may be specific to a certain cryptographic service provider, but the core set of attributes presented on the TPKEYGETINFO(3cbl) reference page should be supported by all providers.

The information in user-defined ATTVALUE-REC is to be associated with ATTRIBUTE-NAME. Upon successful completion of TPKEYSETINFO(), the information in ATTVALUE-REC is stored or processed in a manner defined by the cryptographic service provider. If the data content of ATTVALUE-REC is self-describing, ATTRIBUTE-VALUE-LEN in TPKEYDEF-REC is ignored (and may be 0). Otherwise, ATTRIBUTE-VALUE-LEN must contain the length of data in ATTVALUE-REC.

Return Values

Upon successful completion, TPKEYSETINFO() sets TP-STATUS in TPSTATUS-REC to [TPOK].

Errors

Upon failure, TPKEYSETINFO() sets TP-STATUS in TPSTATUS-REC to one of the following values:

[TPEINVAL]

Invalid arguments were given. For example, KEY-HANDLE is not set correctly.

[TPESYSTEM]

An error occurred. Consult the system error log file for more details.

[TPELIMIT]

The attribute value provided is too large.

[TPENOENT]

The requested attribute is not recognized by the key's cryptographic service provider.