Next: , Previous: Authenticator Functions, Up: Programming Manual

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().

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.

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.

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.

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.

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.

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.

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().

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.

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.

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().

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.

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

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.

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().

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.

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.

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.

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

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.

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.

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.

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.

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.

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().

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.

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.

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().

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.

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.

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.

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().

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.

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.

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.

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.