5.12 KRB-ERROR Functions

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
}

shishi_krberror

Function: Shishi_asn1 shishi_krberror (Shishi * handle)

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.

shishi_krberror_print

Function: int shishi_krberror_print (Shishi * handle, FILE * fh, Shishi_asn1 krberror)

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.

shishi_krberror_save

Function: int shishi_krberror_save (Shishi * handle, FILE * fh, Shishi_asn1 krberror)

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.

shishi_krberror_to_file

Function: int shishi_krberror_to_file (Shishi * handle, Shishi_asn1 krberror, int filetype, const char * filename)

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.

shishi_krberror_parse

Function: int shishi_krberror_parse (Shishi * handle, FILE * fh, Shishi_asn1 * krberror)

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.

shishi_krberror_read

Function: int shishi_krberror_read (Shishi * handle, FILE * fh, Shishi_asn1 * krberror)

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.

shishi_krberror_from_file

Function: int shishi_krberror_from_file (Shishi * handle, Shishi_asn1 * krberror, int filetype, const char * filename)

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.

shishi_krberror_build

Function: int shishi_krberror_build (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_der

Function: int shishi_krberror_der (Shishi * handle, Shishi_asn1 krberror, char ** out, size_t * outlen)

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.

shishi_krberror_crealm

Function: int shishi_krberror_crealm (Shishi * handle, Shishi_asn1 krberror, char ** realm, size_t * realmlen)

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.

shishi_krberror_remove_crealm

Function: int shishi_krberror_remove_crealm (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_set_crealm

Function: int shishi_krberror_set_crealm (Shishi * handle, Shishi_asn1 krberror, const char * crealm)

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.

shishi_krberror_client

Function: int shishi_krberror_client (Shishi * handle, Shishi_asn1 krberror, char ** client, size_t * clientlen)

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.

shishi_krberror_set_cname

Function: int shishi_krberror_set_cname (Shishi * handle, Shishi_asn1 krberror, Shishi_name_type name_type, const char * cname[])

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.

shishi_krberror_remove_cname

Function: int shishi_krberror_remove_cname (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_client_set

Function: int shishi_krberror_client_set (Shishi * handle, Shishi_asn1 krberror, const char * client)

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.

shishi_krberror_realm

Function: int shishi_krberror_realm (Shishi * handle, Shishi_asn1 krberror, char ** realm, size_t * realmlen)

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.

shishi_krberror_set_realm

Function: int shishi_krberror_set_realm (Shishi * handle, Shishi_asn1 krberror, const char * realm)

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.

shishi_krberror_server

Function: int shishi_krberror_server (Shishi * handle, Shishi_asn1 krberror, char ** server, size_t * serverlen)

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.

shishi_krberror_remove_sname

Function: int shishi_krberror_remove_sname (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_set_sname

Function: int shishi_krberror_set_sname (Shishi * handle, Shishi_asn1 krberror, Shishi_name_type name_type, const char * sname[])

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.

shishi_krberror_server_set

Function: int shishi_krberror_server_set (Shishi * handle, Shishi_asn1 krberror, const char * server)

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.

shishi_krberror_ctime

Function: int shishi_krberror_ctime (Shishi * handle, Shishi_asn1 krberror, char ** t)

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.

shishi_krberror_ctime_set

Function: int shishi_krberror_ctime_set (Shishi * handle, Shishi_asn1 krberror, const char * t)

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.

shishi_krberror_remove_ctime

Function: int shishi_krberror_remove_ctime (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_cusec

Function: int shishi_krberror_cusec (Shishi * handle, Shishi_asn1 krberror, uint32_t * cusec)

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.

shishi_krberror_cusec_set

Function: int shishi_krberror_cusec_set (Shishi * handle, Shishi_asn1 krberror, uint32_t cusec)

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.

shishi_krberror_remove_cusec

Function: int shishi_krberror_remove_cusec (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_stime

Function: int shishi_krberror_stime (Shishi * handle, Shishi_asn1 krberror, char ** t)

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.

shishi_krberror_stime_set

Function: int shishi_krberror_stime_set (Shishi * handle, Shishi_asn1 krberror, const char * t)

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.

shishi_krberror_susec

Function: int shishi_krberror_susec (Shishi * handle, Shishi_asn1 krberror, uint32_t * susec)

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.

shishi_krberror_susec_set

Function: int shishi_krberror_susec_set (Shishi * handle, Shishi_asn1 krberror, uint32_t susec)

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.

shishi_krberror_errorcode

Function: int shishi_krberror_errorcode (Shishi * handle, Shishi_asn1 krberror, int32_t * errorcode)

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.

shishi_krberror_errorcode_fast

Function: int shishi_krberror_errorcode_fast (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_errorcode_set

Function: int shishi_krberror_errorcode_set (Shishi * handle, Shishi_asn1 krberror, int errorcode)

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.

shishi_krberror_etext

Function: int shishi_krberror_etext (Shishi * handle, Shishi_asn1 krberror, char ** etext, size_t * etextlen)

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.

shishi_krberror_set_etext

Function: int shishi_krberror_set_etext (Shishi * handle, Shishi_asn1 krberror, const char * etext)

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.

shishi_krberror_remove_etext

Function: int shishi_krberror_remove_etext (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_edata

Function: int shishi_krberror_edata (Shishi * handle, Shishi_asn1 krberror, char ** edata, size_t * edatalen)

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.

shishi_krberror_methoddata

Function: int shishi_krberror_methoddata (Shishi * handle, Shishi_asn1 krberror, Shishi_asn1 * methoddata)

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.

shishi_krberror_set_edata

Function: int shishi_krberror_set_edata (Shishi * handle, Shishi_asn1 krberror, const char * edata)

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.

shishi_krberror_remove_edata

Function: int shishi_krberror_remove_edata (Shishi * handle, Shishi_asn1 krberror)

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.

shishi_krberror_pretty_print

Function: int shishi_krberror_pretty_print (Shishi * handle, FILE * fh, Shishi_asn1 krberror)

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.

shishi_krberror_errorcode_message

Function: const char * shishi_krberror_errorcode_message (Shishi * handle, int errorcode)

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.

shishi_krberror_message

Function: const char * shishi_krberror_message (Shishi * handle, Shishi_asn1 krberror)

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.