Parameters

Edit online

The parameters for CSNDPIM.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of elements in the rule_array variable. The value must be 1, 2, 3 or 4.
rule_array
Direction: Input
Type: String array
A pointer to a string variable containing an array of keywords. The keywords are 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords are described in Table 1.
Table 1. Keywords for CSNDPIM control information

Keywords for CSNDPIM control information
Keyword Description
Requested action (One, required)
RNW-CERT Specifies to load the input certificate in place of a previously imported certificate. The new certificate must have the same public key, subject name, and subject key identifier as the old certificate to be a valid replacement. This operation is expected for expiration updates or other operations that change certificate parameters without changing the subject public key.

Input:

label
64-byte label
certificate
X.509 certificate, binary DER encoded, or in PEM format
rule array
Hashing method keyword (optional). For available methods (keywords) see section Hashing method later in this table. If not passed, then no hash is returned.

Output:

  • A status indication is returned.
  • If a hashing method had been specified, on success, the hash of the certificate is returned for verification with a tool. The size of the hash is determined by the hashing method.
CHGLABEL Specifies to change the label for a previously imported certificate. This might be used after RNW-CERT to update the label in some matching updated certificate characteristics. This command does not change any security aspects for the referenced certificate or the certificates that depend on it.

Input:

label
current 64-byte label
input_data
new 64-byte label

As output, a status indication is returned.
VAL-CERT Specifies to validate the input certificate against the public key infrastructure stored in the HSM. This is a method of testing the certificate to see if an operational request with the certificate will succeed.

Input:

certificate
X.509 certificate, binary DER encoded or PEM format

Output:

status indication
Either a success indication is returned or an informational error about why the certificate validation failed (for example, issuer not found). The returned status indicates only one error, while there may be more than one issues with a particular certificate.
output_data
The 64-byte label is returned for the certificate in the adapter that is used to validate the input operational certificate. This returned label may be used as input with the LSTISSUR keyword to obtain the issuer of the validating certificate. It can also be used with GET-CERT to obtain the full certificate for the validating certificate. This allows the user to re-construct the validation certificate chain used for their operational certificate. This is necessary if a user needs to pass a certification chain to a partner.
Note: This keyword does not require a signature on a Connectivity Programming Request/Reply Block (CPRB) of type T2 (T2 CPRB).
GET-CERT Given an input 64-byte label for a particular certificate, this keword returns the full X.509 certificate for that certificate and the HSM-internal state of the certificate. Optionally the HSM-computed hash of the certificate is also returned.

Input:

label
64-byte label
rule array
Hashing method keyword (optional). For available methods (keywords) see section Hashing method later in this table. If not passed, then no hash is returned.

Output:

On success, the following output is returned. On failure, only an error indication is returned.

output_data
X.509 certificate, binary DER encoded, or in PEM format, matching the input 64-byte label
  • See the SIZEDATA keyword definition for alternate output.
  • See the Output format indicator section later in this table.
hash
If a hashing method had been specified, the hash of the certificate referred to by the input label is returned.
rule array
State of the certificate, specified as a single 8-byte rule-array keyword, to be interpreted as follows:
  1. The first left-most byte X’BBxxxxxxxxxxxxxx’ is reserved.
  2. The second left-most byte X’xxBBxxxxxxxxxxxx’ indicates the activity status of a certificate. Valid values are:
    • X’xx30xxxxxxxxxxxx’: The certificate is not active.
      • For a root certificate this could mean that the certificate has only been loaded, but not activated.
      • For any certificates (root or non-root) this could mean the certificate has expired (check other bytes).
    • X’xx31xxxxxxxxxxxx’: The certificate is active.
      • An active installed certificate is used by the HSM to validate other certificates.
  3. The third left-most byte X’xxxxBBxxxxxxxxxx’ indicates the expiration status of a certificate. Valid values are:
    • X’xxxx30xxxxxxxxxx’: The certificate is not expired.
    • X’xxxx31xxxxxxxxxx’: The certificate is expired.
  4. The fourth left-most byte X’xxxxxxBBxxxxxxxx’ is reserved.
  5. The fifth left-most byte X’xxxxxxxxBBxxxxxx’indicates the hash method specified when a certificate was loaded. Valid values are:
    • X’xxxxxxxx32xxxxxx’: The SHA-256 method was used to load the certificate.
    • X’xxxxxxxx34xxxxxx’: The SHA-384 method was used to load the certificate.
    • X’xxxxxxxx38xxxxxx’: The SHA-512 method was used to load the certificate.
Note: This keyword does not require a signature on a Connectivity Programming Request/Reply Block (CPRB) of type T2 (T2 CPRB).
VAL-TR34 Specifies to validate the certificate using the semantics of TR-34 sample certificates - device vendor certificates.
LSTROOTS Returns a list of 64-byte labels for installed trust parent certificates.

There is no input.

Output:

status indication
A status indication is returned.
output_data
On success, an array of 64 byte labels representing all the loaded root certificates is returned. The returned buffer size indicates the count of certificates (as a multiple of 64).
  • See the SIZEDATA keyword definition for alternate output.
Note: This keyword does not require a signature on a Connectivity Programming Request/Reply Block (CPRB) of type T2 (T2 CPRB).
Action modifier (One, optional)
SIZEDATA Specifies to return only the size of the data returned by the requested action. Used with VAL-CERT, GET-CERT, and LSTROOTS keywords.

The size returned is placed in the output_data_length parameter. It refers to the data that would have been placed in the output_data parameter if the SIZEDATA keyword was not passed.
Certificate validation method (One, required for VAL-CERT)
RFC-2459 Attempt to validate the certificate using the semantics of RFC-2459.
RFC-3280 Attempt to validate the certificate using the semantics of RFC-3280
RFC-5280 Attempt to validate the certificate using the semantics of RFC-5280
RFC-ANY Attempt to validate the certificate using first the semantics of RFC-2459, then RFC-3280, and then RFC-5280. If the certificate is not compliant with any RFC, the first error encountered (from RFC-2459 processing) is returned.
Hashing method (One, optional with RNW-CERT and GET-CERT)
SHA-256 The hash variable (either input or output, depending on the action) is calculated with the SHA-256 hash method. The size of the variable is 32 bytes.
SHA-384 The hash variable (either input or output, depending on the action) is calculated with the SHA-384 hash method. Size of the variable is 48 bytes.
SHA-512 The hash variable (either input or output, depending on the action) is calculated with the SHA-512 hash method. Size of the variable is 64 bytes.
Output format indicator (one, required with GET-CERT and not allowed otherwise) (One, optional with RNW-CERT and GET-CERT)
DER-FMT Specifies that the output data object should be DER encoded
PEM-FMT Specifies that the output data object should be PEM (Base64) encoded.
certificate_length
Direction: Input
Type: Integer
Pointer to an integer variable containing the number of bytes of data in the certificate variable. The maximum length is 3500.
certificate
Direction: Input
Type: String
A pointer to a string variable containing an X.509 certificate. The data must be DER or PEM encoded.
label_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the label variable. This value must be 64 or 0 if no label processing is expected.
label
Direction: Input
Type: String
A pointer to a string variable containing a label for the input certificate specified with the certificate parameter. The label is 64-byte ASCII data buffer, with the following format characteristics:
  • If the label is less than 64 characters, it must be left-justified in the 64 character buffer, and it must be padded on the right with spaces.
  • The first character must be either alphanumeric, or one member from the following set: @, $, or #.
  • All other characters must be either alphanumeric, a period, or one of the set: @, $, or #.
  • The input string is not null-terminated. It is a fixed length string (64 characters) with no special terminators.
hash_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the hash variable. This value depends on the specified hashing method keyword. It must be 32 for SHA-256, 48 for SHA-384, and 64 for SHA-512.
hash
Direction: Input/Output
Type: String
A pointer to a string variable containing a hash of the referenced X.509 certificate. The hash is either input or output, depending on the requested action keyword. The format of the hash data is raw binary data of the size indicated by the hashing method keyword.
input_data_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the input_data variable. The maximum length depends on the usage.
input_data
Direction: Input
Type: String
A pointer to a string variable with contents that depend on the rule array keyword for the requested action:
CHGLABEL
Parameter input_data shall contain the new 64-byte label for the internally stored certificate.
all others
Parameter input_data_length should be zero and this parameter should be NULL.
output_data_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the output_data variable. On input, it must indicate the size of the buffer available. On output, if the size is sufficient, the variable contains the actual length of the data returned by the service. If the SIZEDATA keyword is passed, the size returned refers to the amount of data that is returned if the SIZEDATA keyword is not passed.
output_data
Direction: Output
Type: String
A pointer to a string variable containing the output data from the service, with contents that depends on the rule array keyword for the requested action:
LSTROOTS
Paramter output_data contains the array of 64 byte labels returned.
GET-CERT
Paramter output_data contains the returned X.509 certificate corresponding to the input label.
VAL-CERT
Paramter output_data contains the returned label from the validating certificate for the input certificate.
all others
Paramter output_data_length is zero and this parameter is NULL.
reserved1_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the reserved1 variable. This parameter must be a null pointer or point to a value of 0.
reserved1
Direction: Output
Type: String
A pointer to a string variable reserved for this verb.