Sign Buffer (QYDOSGNB, QydoSignBuffer)

The Sign Buffer (OPM, QYDOSGNB; ILE, QydoSignBuffer) API allows the local system to certify that the series of bytes being signed is trustworthy. It does this by generating a digital signature for those bytes and returning this signature to the caller.

The application identifier will be used to find the certificate needed to sign this object. The certificate will be used later to verify the contents of this object have not changed and this certificate will be reported as having signed this object.

Authorities and Locks

API Public Authority

*USE.

Authority Required

To use this API, you must be authorized to the object signing applications function associated with your application identifier through iSeries Navigator's application administration support. The Change Function Usage Information(QSYCHFUI) API, with a function ID of the same name as the application identifier, also can be used to change the list of users that are allowed to use this application identifier.

Required Parameter Group

Buffer to sign

INPUT; CHAR(*)

The buffer of data to be signed. Only the part of the object described in the Description of buffer to sign will be signed.

Description of buffer to sign

INPUT; CHAR(*)

Array of offsets and lengths to the data to be signed. The API will treat these bytes as if they were a contiguous stream of bytes. The offset is from the start of the buffer.

The format of the description of the data to sign is in the following table. For detailed descriptions of the fields in this table, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	Binary(4)	Offset to start of first series of bytes to sign
4	4	Binary(4)	Length of first series of bytes to sign
n	n	Binary(4)	Offset to start of next series of bytes to sign
n+4	n+10	Binary(4)	Length of next series of bytes to sign

Number of descriptions of buffer to sign

INPUT; BINARY(4)

Number of offsets and lengths needed to describe what parts of the buffer should be signed.

Application identifier

INPUT; CHAR(*)

The user-supplied application ID to sign objects with. The application type must be 4 (object signing) and it must be assigned to a valid certificate label.

Length of application identifier

INPUT; BINARY(4)

The length of the specified application identifier. This length must be a value from 1 to 30.

Resulting signature

OUTPUT; CHAR(*)

Area to contain the signature to be returned by the API. See Resulting signature formats for details on the format of this parameter. This field may be NULL if the length of resulting signature provided is 0.

Length of resulting signature provided

INPUT; BINARY(4)

The length of the area provided to contain the returned signature.

Format of resulting signature

INPUT; CHAR(8)

The format of the results of the signing operation.

SGNB0100	Just the signature itself is returned. The signature will be in PKCS #1 block type 01 format.
SGNB0200	The signature itself and the certificate label needed to verify the signature are returned. The signature will be in PKCS #1 block type 01 format.
SGNB0300	The signature itself and the ASN.1 encoded certificate itself needed to verify the signature are returned. The signature will be in PKCS #1 block type 01 format.
SGNB0400	The signature itself and the distinguished name of the certificate needed to verify the signature are returned. The signature will be in PKCS #1 block type 01 format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Field Descriptions

Length of first series of bytes to sign The number of bytes, including the first byte in the series, to be included in the signature.

Length of next series of bytes to sign The number of bytes, including the first byte in the series, to be included in the signature.

Offset to start of first series of bytes to sign. An offset to the first byte of a series of 1 or more bytes of data to be included in the signature.

Offset to start of next series of bytes to sign. An offset to the first byte of a series of 1 or more bytes of data to be included in the signature.

Resulting signature formats

For detailed descriptions of the fields in the tables, see Field Descriptions.

SGNB0100 format

SGNB0200 format

SGNB0300 format

SGNB0400 format

Field Descriptions

Certificate. The ASN.1 encoded certificate that is needed to verify the signature.

Certificate label. The label of the certificate that is needed to verify the signature. This is the label of the certificate in the *OBJECTSIGNING certificate store on the local system. This certificate will need to be exported to the system that will verify this signature.

Distinguished name. The distinguished name of the certificate that is needed to verify the signature.

Length of certificate. Number of bytes needed to contain the ASN.1 encoded certificate.

Length of certificate label. Number of bytes needed to contain the certificate label.

Length of distinguished name. Number of bytes needed to contain the distinguished name.

Length of signature. Number of bytes needed to contain the signature.

Offset to start of certificate. Offset from the beginning of this structure to the certificate.

Offset to start of certificate label. Offset from the beginning of this structure to the certificate label.

Offset to start of distinguished name. Offset from the beginning of this structure to the distinguished name.

Offset to start of signature. Offset from the beginning of this structure to the signature.

Signature. The encrypted hash of the bytestream that was passed in to this API. This can be used later to see if the bytestream has changed.

Error Messages