Next: Cryptographic Functions, Previous: Authenticator Functions, Up: Programming Manual [Contents][Index]
The “KRB-ERROR” is an ASN.1 structure that can be returned, instead of, e.g., KDC-REP or AP-REP, to indicate various error conditions. Unfortunately, the semantics of several of the fields are ill specified, so the typically procedure is to extract “e-text” and/or “e-data” and show it to the user. The following illustrates the KRB-ERROR ASN.1 structure.
KRB-ERROR ::= [APPLICATION 30] SEQUENCE {
pvno [0] INTEGER (5),
msg-type [1] INTEGER (30),
ctime [2] KerberosTime OPTIONAL,
cusec [3] Microseconds OPTIONAL,
stime [4] KerberosTime,
susec [5] Microseconds,
error-code [6] Int32,
crealm [7] Realm OPTIONAL,
cname [8] PrincipalName OPTIONAL,
realm [9] Realm -- service realm --,
sname [10] PrincipalName -- service name --,
e-text [11] KerberosString OPTIONAL,
e-data [12] OCTET STRING OPTIONAL
}
handle: shishi handle as allocated by shishi_init().
Description: This function creates a new KRB-ERROR, populated with some default values.
Return value: Returns the KRB-ERROR or NULL on failure.
handle: shishi handle as allocated by shishi_init().
fh: file handle open for writing.
krberror: KRB-ERROR to print.
Description: Print ASCII armored DER encoding of KRB-ERROR to file.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
fh: file handle open for writing.
krberror: KRB-ERROR to save.
Description: Save DER encoding of KRB-ERROR to file.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR to save.
filetype: input variable specifying type of file to be written,
see Shishi_filetype.
filename: input variable with filename to write to.
Description: Write KRB-ERROR to file in specified TYPE. The file will be truncated if it exists.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
fh: file handle open for reading.
krberror: output variable with newly allocated KRB-ERROR.
Description: Read ASCII armored DER encoded KRB-ERROR from file and populate given variable.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
fh: file handle open for reading.
krberror: output variable with newly allocated KRB-ERROR.
Description: Read DER encoded KRB-ERROR from file and populate given variable.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: output variable with newly allocated KRB-ERROR.
filetype: input variable specifying type of file to be read,
see Shishi_filetype.
filename: input variable with filename to read from.
Description: Read KRB-ERROR from file in specified TYPE.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
Description: Finish KRB-ERROR, called before e.g. shishi_krberror_der. This function removes empty but OPTIONAL fields (such as cname), and
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
out: output array with newly allocated DER encoding of KRB-ERROR.
outlen: length of output array with DER encoding of KRB-ERROR.
Description: DER encode KRB-ERROR. The caller must deallocate the OUT buffer.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
realm: output array with newly allocated name of realm in KRB-ERROR.
realmlen: size of output array.
Description: Extract client realm from KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
Description: Remove client realm field in KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
crealm: input array with realm.
Description: Set realm field in krberror to specified value.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
client: pointer to newly allocated zero terminated string containing
principal name. May be NULL (to only populate clientlen).
clientlen: pointer to length of client on output, excluding terminating
zero. May be NULL (to only populate client).
Description: Return client principal name in KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
name_type: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
cname: input array with principal name.
Description: Set principal field in krberror to specified value.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
Description: Remove client realm field in KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror to set client name field in.
client: zero-terminated string with principal name on RFC 1964 form.
Description: Set the client name field in the Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
realm: output array with newly allocated name of realm in KRB-ERROR.
realmlen: size of output array.
Description: Extract (server) realm from KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
realm: input array with (server) realm.
Description: Set (server) realm field in krberror to specified value.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
server: pointer to newly allocated zero terminated string containing
server name. May be NULL (to only populate serverlen).
serverlen: pointer to length of server on output, excluding terminating
zero. May be NULL (to only populate server).
Description: Return server principal name in KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror to set server name field in.
Description: Remove server name field in KRB-ERROR. (Since it is not marked OPTIONAL in the ASN.1 profile, what is done is to set the name-type to UNKNOWN and make sure the name-string sequence is empty.)
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
name_type: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
sname: input array with principal name.
Description: Set principal field in krberror to specified value.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror to set server name field in.
server: zero-terminated string with principal name on RFC 1964 form.
Description: Set the server name field in the Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror to set client name field in.
t: newly allocated zero-terminated output array with client time.
Description: Extract client time from KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror as allocated by shishi_krberror().
t: string with generalized time value to store in Krberror.
Description: Store client time in Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror as allocated by shishi_krberror().
Description: Remove client time field in Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror as allocated by shishi_krberror().
cusec: output integer with client microseconds field.
Description: Extract client microseconds field from Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
cusec: client microseconds to set in krberror, 0-999999.
Description: Set the cusec field in the Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror as allocated by shishi_krberror().
Description: Remove client usec field in Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror to set client name field in.
t: newly allocated zero-terminated output array with server time.
Description: Extract server time from KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror as allocated by shishi_krberror().
t: string with generalized time value to store in Krberror.
Description: Store server time in Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: Krberror as allocated by shishi_krberror().
susec: output integer with server microseconds field.
Description: Extract server microseconds field from Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
susec: server microseconds to set in krberror, 0-999999.
Description: Set the susec field in the Krberror.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code.
errorcode: output integer KRB-ERROR error code.
Description: Extract error code from KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code.
Description: Get error code from KRB-ERROR, without error checking.
Return value: Return error code (see shishi_krberror_errorcode())
directly, or -1 on error.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code to set.
errorcode: new error code to set in krberror.
Description: Set the error-code field to a new error code.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code.
etext: output array with newly allocated error text.
etextlen: output length of error text.
Description: Extract additional error text from server (possibly empty).
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
etext: input array with error text to set.
Description: Set error text (e-text) field in KRB-ERROR to specified value.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
Description: Remove error text (e-text) field in KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code.
edata: output array with newly allocated error data.
edatalen: output length of error data.
Description: Extract additional error data from server (possibly empty).
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code.
methoddata: output ASN.1 METHOD-DATA.
Description: Extract METHOD-DATA ASN.1 object from the e-data field. The e-data
field will only contain a METHOD-DATA if the krberror error code is
SHISHI_KDC_ERR_PREAUTH_REQUIRED.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
edata: input array with error text to set.
Description: Set error text (e-data) field in KRB-ERROR to specified value.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
krberror: krberror as allocated by shishi_krberror().
Description: Remove error text (e-data) field in KRB-ERROR.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
fh: file handle opened for writing.
krberror: KRB-ERROR structure with error code.
Description: Print KRB-ERROR error condition and some explanatory text to file descriptor.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
errorcode: integer KRB-ERROR error code.
Description: Get human readable string describing KRB-ERROR code.
Return value: Return a string describing error code. This function will always return a string even if the error code isn’t known.
handle: shishi handle as allocated by shishi_init().
krberror: KRB-ERROR structure with error code.
Description: Extract error code (see shishi_krberror_errorcode_fast()) and
return error message (see shishi_krberror_errorcode_message()).
Return value: Return a string describing error code. This function will always return a string even if the error code isn’t known.
Next: Cryptographic Functions, Previous: Authenticator Functions, Up: Programming Manual [Contents][Index]