| Extracted from Pike v7.8 release 866 at 2016-04-05.

[Top]
GSSAPI
GSSAPI.Context

# 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.