Method GSSAPI.Context()->unwrap()

Method unwrap

string unwrap(string message, void|int accept_encrypted_only)

Description

Verifies the origin and integrity of the given message using the MIC included in it, and also decrypts the message if it was encrypted. The message has been calculated by the sender using wrap or some other GSS_Wrap wrapper.

This wraps GSS_Unwrap according to RFC 2743 section 2.3.4.

This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

Parameter message

The message to be unwrapped.

Parameter accept_encrypted_only

If this is nonzero then it is an error if message isn't encrypted, and zero is returned in that case (the status returned by last_major_status will still indicate success, though).

Returns

Zero is returned if the verification fails with GSSAPI.DEFECTIVE_TOKEN or GSSAPI.BAD_MIC.

Zero is also returned if message isn't encrypted and accept_encrypted_only is set.

Otherwise the message is successfully decrypted (provided it was encrypted to begin with), and its origin and integrity checks out, but it might still be considered wrong depending on whether the replay detection or sequencing services are required (see required_services):

If replay detection (c.f. GSSAPI.REPLAY_FLAG) is required then zero is returned if the message is duplicated (GSSAPI.DUPLICATE_TOKEN) or old (GSSAPI.OLD_TOKEN).

If sequencing (c.f. GSSAPI.SEQUENCE_FLAG) is required then in addition to the replay detection conditions, zero is also returned if the message is out of sequence (GSSAPI.UNSEQ_TOKEN or GSSAPI.GAP_TOKEN).

Otherwise the unwrapped message is returned, which is valid according to the currently required services (note however that requiring the confidentiality service does not imply that an error is signalled whenever an unencrypted message is received - see instead accept_encrypted_only above).

Throws

Any GSS-API errors except GSSAPI.DEFECTIVE_TOKEN and GSSAPI.BAD_MIC are thrown.

Note

This function sets the value returned by last_confidential and last_qop.

Note

Even if the message is considered valid by the return value, last_major_status may be called to check for the informatory codes mentioned above.