Next: , Previous: , Up: Programming Manual   [Contents][Index]


5.10 AS/TGS Functions

The Authentication Service (AS) is used to get an initial ticket using e.g. your password. The Ticket Granting Service (TGS) is used to get subsequent tickets using other tickets. Protocol wise the procedures are very similar, which is the reason they are described together. The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP ASN.1 structures. Most of the functions use the mnemonic “KDC” instead of either AS or TGS, which means the function operates on both AS and TGS types. Only where the distinction between AS and TGS is important are the AS and TGS names used. Remember, these are low-level functions, and normal applications will likely be satisfied with the AS (see AS Functions) and TGS (see TGS Functions) interfaces, or the even more high-level Ticket Set (see Ticket Set Functions) interface.

-- Request --

AS-REQ		::= KDC-REQ {10}
TGS-REQ		::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP		::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
TGS-REP		::= KDC-REP {13, EncTGSRepPart,
			{ keyuse-EncTGSRepPart-sesskey
			  | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart	::= [APPLICATION 25] EncKDCRepPart
EncTGSRepPart	::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}

shishi_as_derive_salt

Function: int shishi_as_derive_salt (Shishi * handle, Shishi_asn1 asreq, Shishi_asn1 asrep, char ** salt, size_t * saltlen)

handle: Shishi handle as allocated by shishi_init().
asreq: Input AS-REQ variable.
asrep: Input AS-REP variable.
salt: Returned pointer to newly allocated output array.
saltlen: Pointer to integer, returning size of output array.

Description: Computes the salt that should be used when deriving a key via shishi_string_to_key() for an AS exchange. Currently this searches for PA-DATA of type SHISHI_PA_PW_SALT in the AS-REP provided by asrep, and if present returns it. Otherwise the salt is composed from the client name and the realm, both are extracted from the request asreq.

Return value: Returns SHISHI_OK if successful. Failure conditions include various ASN.1 issues.

shishi_kdcreq_sendrecv_hint

Function: int shishi_kdcreq_sendrecv_hint (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 * kdcrep, Shishi_tkts_hint * hint)

handle: Shishi library handle created by shishi_init().
kdcreq: Input variable with a prepared AS-REQ.
kdcrep: Output pointer variable for decoded AS-REP.
hint: Input Shishi_tkts_hint structure with flags.

Description: Sends a request to KDC, and receives the response. The provided request kdcreq and the hints structure hint, together determine transmitted data. On reception the reply is decoded as AS-REP into kdcrep.

Return value: Return code is SHISHI_OK on success, SHISHI_KDC_TIMEOUT on timeouts, SHISHI_ASN1_ERROR on translation errors, and SHISHI_GOT_KRBERROR for other corruptions.

shishi_kdcreq_sendrecv

Function: int shishi_kdcreq_sendrecv (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 * kdcrep)

handle: Shishi library handle created by shishi_init().
kdcreq: Input variable with a prepared AS-REQ.
kdcrep: Output pointer variable returning received AS-REP.

Description: Sends a request to KDC, and receives the response. The provided AS-REQ, in kdcreq, sets all data for the request. On reception the reply is decoded as AS-REP into kdcrep.

Return value: Return code is SHISHI_OK on success, SHISHI_KDC_TIMEOUT on timeouts, SHISHI_ASN1_ERROR on translation errors, and SHISHI_GOT_KRBERROR for other corruptions.

shishi_kdc_copy_crealm

Function: int shishi_kdc_copy_crealm (Shishi * handle, Shishi_asn1 kdcrep, Shishi_asn1 encticketpart)

handle: Shishi handle as allocated by shishi_init().
kdcrep: KDC-REP where the field "crealm" is updated.
encticketpart: EncTicketPart providing "crealm" field.

Description: Reads the field "crealm" from the ticket encticketpart and copies the value into the reply kdcrep.

Return value: Returns SHISHI_OK if successful, and ASN.1 failures otherwise.

shishi_as_check_crealm

Function: int shishi_as_check_crealm (Shishi * handle, Shishi_asn1 asreq, Shishi_asn1 asrep)

handle: Shishi handle as allocated by shishi_init().
asreq: Request of type AS-REQ.
asrep: Reply structure of type AS-REP.

Description: Verifies that the fields asreq.req-body.realm and asrep.crealm contain identical realm names. This is one of the steps that has to be performed when processing an exchange of AS-REQ and AS-REP; see shishi_kdc_process() for more details.

Return value: Returns SHISHI_OK if successful, SHISHI_REALM_MISMATCH whenever the realm names differ, and an error code otherwise.

shishi_kdc_copy_cname

Function: int shishi_kdc_copy_cname (Shishi * handle, Shishi_asn1 kdcrep, Shishi_asn1 encticketpart)

handle: Shishi handle as allocated by shishi_init().
kdcrep: KDC-REP where the field "cname" is updated.
encticketpart: EncTicketPart providing "cname" field.

Description: Reads the field "cname" from the ticket encticketpart and copies the value into the reply kdcrep.

Return value: Returns SHISHI_OK if successful, and ASN.1 failures otherwise.

shishi_as_check_cname

Function: int shishi_as_check_cname (Shishi * handle, Shishi_asn1 asreq, Shishi_asn1 asrep)

handle: Shishi handle as allocated by shishi_init().
asreq: Request of type AS-REQ.
asrep: Reply structure of type AS-REP.

Description: Verifies that the fields asreq.req-body.cname and asrep.cname contain identical names. This is one of the steps that has to be performed when processing an exchange of AS-REQ and AS-REP; see shishi_kdc_process() for more details.

Return value: Returns SHISHI_OK if successful, SHISHI_CNAME_MISMATCH if the names differ, and an error code otherwise.

shishi_kdc_copy_nonce

Function: int shishi_kdc_copy_nonce (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 enckdcreppart)

handle: Shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ providing "nonce" field.
enckdcreppart: EncKDCRepPart where "nonce" field is updated.

Description: Sets the field "nonce" in enckdcreppart to a value retreived from the corresponding field in kdcreq.

Return value: Returns SHISHI_OK if successful.

shishi_kdc_check_nonce

Function: int shishi_kdc_check_nonce (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 enckdcreppart)

handle: Shishi handle as allocated by shishi_init().
kdcreq: Request of type KDC-REQ.
enckdcreppart: Encrypted KDC-REP part.

Description: Verifies that kdcreq.req-body.nonce and enckdcreppart.nonce contain matching values. This is one of the steps that has to be performed when processing an exchange of KDC-REQ and KDC-REP.

Return value: Returns SHISHI_OK if successful, SHISHI_NONCE_MISMATCH whenever the nonces are of differing lengths (usually a sign that a buggy server truncates the nonce to 4 bytes) and the same code if the nonce values differ, or an error code otherwise.

shishi_tgs_process

Function: int shishi_tgs_process (Shishi * handle, Shishi_asn1 tgsreq, Shishi_asn1 tgsrep, Shishi_asn1 authenticator, Shishi_asn1 oldenckdcreppart, Shishi_asn1 * enckdcreppart)

handle: Shishi handle as allocated by shishi_init().
tgsreq: Input variable holding the transmitted KDC-REQ.
tgsrep: Input variable holding the received KDC-REP.
authenticator: Input variable with an authenticator extracted from the AP-REQ part of tgsreq.
oldenckdcreppart: Input variable with EncKDCRepPart used in the request.
enckdcreppart: Output variable holding the new EncKDCRepPart.

Description: Processes a TGS client exchange and outputs the decrypted EncKDCRepPart, holding details about the received ticket. This function simply derives the encryption key from the ticket used to construct the original TGS request, and then calls shishi_kdc_process().

Return value: Returns SHISHI_OK if the TGS client exchange was successful. Failures include ASN.1 and TGS conditions.

shishi_as_process

Function: int shishi_as_process (Shishi * handle, Shishi_asn1 asreq, Shishi_asn1 asrep, const char * string, Shishi_asn1 * enckdcreppart)

handle: Shishi handle as allocated by shishi_init().
asreq: Input variable holding the transmitted KDC-REQ.
asrep: Input variable holding the received KDC-REP.
string: Input variable with a null terminated password.
enckdcreppart: Output variable returning a new EncKDCRepPart.

Description: Processes an AS client exchange and returns the decrypted EncKDCRepPart, holding details about the received ticket. This function simply derives the encryption key from the password, and then calls shishi_kdc_process().

Return value: Returns SHISHI_OK if the AS client exchange was successful. Multiple failure conditions are possible.

shishi_kdc_process

Function: int shishi_kdc_process (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 kdcrep, Shishi_key * key, int keyusage, Shishi_asn1 * enckdcreppart)

handle: Shishi handle as allocated by shishi_init().
kdcreq: Input variable holding the transmitted KDC-REQ.
kdcrep: Input variable holding the received KDC-REP.
key: Input pointet to key for decrypting parts of kdcrep.
keyusage: Kerberos key usage code.
enckdcreppart: Output pointer for the extracted EncKDCRepPart.

Description: Processes a KDC client exchange and extracts a decrypted EncKDCRepPart, holding details about the received ticket. Use shishi_kdcrep_get_ticket() to extract the ticket itself. This function verifies the various conditions that must hold if the response is to be considered valid. In particular, it compares nonces (using shishi_kdc_check_nonce()), and if the exchange was an AS exchange, it also checks cname and crealm (using shishi_as_check_cname(), shishi_as_check_crealm()).

Usually shishi_as_process() and shishi_tgs_process() should be used instead of this call, since they simplify computation of the decryption key.

Return value: Returns SHISHI_OK if the KDC client exchange was successful. Multiple failure conditions are possible.

shishi_asreq

Function: Shishi_asn1 shishi_asreq (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Description: This function creates a new AS-REQ, populated with some default values.

Return value: Returns the AS-REQ or NULL on failure.

shishi_tgsreq

Function: Shishi_asn1 shishi_tgsreq (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Description: This function creates a new TGS-REQ, populated with some default values.

Return value: Returns the TGS-REQ or NULL on failure.

shishi_kdcreq_print

Function: int shishi_kdcreq_print (Shishi * handle, FILE * fh, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for writing.
kdcreq: KDC-REQ to print.

Description: Print ASCII armored DER encoding of KDC-REQ to file.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_save

Function: int shishi_kdcreq_save (Shishi * handle, FILE * fh, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for writing.
kdcreq: KDC-REQ to save.

Description: Print DER encoding of KDC-REQ to file.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_to_file

Function: int shishi_kdcreq_to_file (Shishi * handle, Shishi_asn1 kdcreq, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ 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 KDC-REQ to file in specified TYPE. The file will be truncated if it exists.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_parse

Function: int shishi_kdcreq_parse (Shishi * handle, FILE * fh, Shishi_asn1 * kdcreq)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for reading.
kdcreq: output variable with newly allocated KDC-REQ.

Description: Read ASCII armored DER encoded KDC-REQ from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_read

Function: int shishi_kdcreq_read (Shishi * handle, FILE * fh, Shishi_asn1 * kdcreq)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for reading.
kdcreq: output variable with newly allocated KDC-REQ.

Description: Read DER encoded KDC-REQ from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_from_file

Function: int shishi_kdcreq_from_file (Shishi * handle, Shishi_asn1 * kdcreq, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().
kdcreq: output variable with newly allocated KDC-REQ.
filetype: input variable specifying type of file to be read, see Shishi_filetype.
filename: input variable with filename to read from.

Description: Read KDC-REQ from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_nonce_set

Function: int shishi_kdcreq_nonce_set (Shishi * handle, Shishi_asn1 kdcreq, uint32_t nonce)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set client name field in.
nonce: integer nonce to store in KDC-REQ.

Description: Store nonce number field in KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_set_cname

Function: int shishi_kdcreq_set_cname (Shishi * handle, Shishi_asn1 kdcreq, Shishi_name_type name_type, const char * principal)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set client name field in.
name_type: type of principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.
principal: input array with principal name.

Description: Set the client name field in the KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_client

Function: int shishi_kdcreq_client (Shishi * handle, Shishi_asn1 kdcreq, char ** client, size_t * clientlen)

handle: Shishi library handle create by shishi_init().
kdcreq: KDC-REQ variable to get client name from.
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: Represent client principal name in KDC-REQ as zero-terminated string. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length clientlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_asreq_clientrealm

Function: int shishi_asreq_clientrealm (Shishi * handle, Shishi_asn1 asreq, char ** client, size_t * clientlen)

handle: Shishi library handle create by shishi_init().
asreq: AS-REQ variable to get client name and realm from.
client: pointer to newly allocated zero terminated string containing principal name and realm. 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: Convert cname and realm fields from AS-REQ to printable principal name format. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length clientlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_realm

Function: int shishi_kdcreq_realm (Shishi * handle, Shishi_asn1 kdcreq, char ** realm, size_t * realmlen)

handle: Shishi library handle create by shishi_init().
kdcreq: KDC-REQ variable to get client name from.
realm: pointer to newly allocated zero terminated string containing realm. May be NULL (to only populate realmlen).
realmlen: pointer to length of realm on output, excluding terminating zero. May be NULL (to only populate realmlen).

Description: Get realm field in KDC-REQ as zero-terminated string. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length realmlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_set_realm

Function: int shishi_kdcreq_set_realm (Shishi * handle, Shishi_asn1 kdcreq, const char * realm)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set realm field in.
realm: input array with name of realm.

Description: Set the realm field in the KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_server

Function: int shishi_kdcreq_server (Shishi * handle, Shishi_asn1 kdcreq, char ** server, size_t * serverlen)

handle: Shishi library handle create by shishi_init().
kdcreq: KDC-REQ variable to get server name from.
server: pointer to newly allocated zero terminated string containing principal 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: Represent server principal name in KDC-REQ as zero-terminated string. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length serverlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_set_sname

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

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set server name field in.
name_type: type of principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.
sname: input array with principal name.

Description: Set the server name field in the KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_till

Function: int shishi_kdcreq_till (Shishi * handle, Shishi_asn1 kdcreq, char ** till, size_t * tilllen)

handle: Shishi library handle created by shishi_init().
kdcreq: KDC-REQ variable to get endtime from.
till: pointer to newly allocated null terminated string containing "till" field with generalized time. May be passed as NULL to only populate tilllen.
tilllen: pointer to length of till for output, excluding the terminating null. Set to NULL, only till is populated.

Description: Get "till" field, i.e., "endtime", in KDC-REQ as a null-terminated string. The string is typically 15 characters long and is allocated by this function. It is the responsibility of the caller to deallocate it. Note that the output length tilllen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_tillc

Function: time_t shishi_kdcreq_tillc (Shishi * handle, Shishi_asn1 kdcreq)

handle: Shishi library handle created by shishi_init().
kdcreq: KDC-REQ variable to get "till" field from.

Description: Extract C time corresponding to the "till" field.

Return value: Returns the C time interpretation of the "till" field in KDC-REQ.

shishi_kdcreq_etype

Function: int shishi_kdcreq_etype (Shishi * handle, Shishi_asn1 kdcreq, int32_t * etype, int netype)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get etype field from.
etype: output encryption type.
netype: element number to return.

Return the netype: th encryption type from KDC-REQ. The first etype is number 1.

Return value: Returns SHISHI_OK iff etype successful set.

shishi_kdcreq_set_etype

Function: int shishi_kdcreq_set_etype (Shishi * handle, Shishi_asn1 kdcreq, int32_t * etype, int netype)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set etype field in.
etype: input array with encryption types.
netype: number of elements in input array with encryption types.

Description: Set the list of supported or wanted encryption types in the request. The list should be sorted in priority order.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_options

Function: int shishi_kdcreq_options (Shishi * handle, Shishi_asn1 kdcreq, uint32_t * flags)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.
flags: pointer to output integer with flags.

Description: Extract KDC-Options from KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_forwardable_p

Function: int shishi_kdcreq_forwardable_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option forwardable flag is set.

The FORWARDABLE option indicates that the ticket to be issued is to have its forwardable flag set. It may only be set on the initial request, or in a subsequent request if the ticket-granting ticket on which it is based is also forwardable.

Return value: Returns non-0 iff forwardable flag is set in KDC-REQ.

shishi_kdcreq_forwarded_p

Function: int shishi_kdcreq_forwarded_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option forwarded flag is set.

The FORWARDED option is only specified in a request to the ticket-granting server and will only be honored if the ticket-granting ticket in the request has its FORWARDABLE bit set. This option indicates that this is a request for forwarding. The address(es) of the host from which the resulting ticket is to be valid are included in the addresses field of the request.

Return value: Returns non-0 iff forwarded flag is set in KDC-REQ.

shishi_kdcreq_proxiable_p

Function: int shishi_kdcreq_proxiable_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option proxiable flag is set.

The PROXIABLE option indicates that the ticket to be issued is to have its proxiable flag set. It may only be set on the initial request, or in a subsequent request if the ticket-granting ticket on which it is based is also proxiable.

Return value: Returns non-0 iff proxiable flag is set in KDC-REQ.

shishi_kdcreq_proxy_p

Function: int shishi_kdcreq_proxy_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option proxy flag is set.

The PROXY option indicates that this is a request for a proxy. This option will only be honored if the ticket-granting ticket in the request has its PROXIABLE bit set. The address(es) of the host from which the resulting ticket is to be valid are included in the addresses field of the request.

Return value: Returns non-0 iff proxy flag is set in KDC-REQ.

shishi_kdcreq_allow_postdate_p

Function: int shishi_kdcreq_allow_postdate_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option allow-postdate flag is set.

The ALLOW-POSTDATE option indicates that the ticket to be issued is to have its MAY-POSTDATE flag set. It may only be set on the initial request, or in a subsequent request if the ticket-granting ticket on which it is based also has its MAY-POSTDATE flag set.

Return value: Returns non-0 iff allow-postdate flag is set in KDC-REQ.

shishi_kdcreq_postdated_p

Function: int shishi_kdcreq_postdated_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option postdated flag is set.

The POSTDATED option indicates that this is a request for a postdated ticket. This option will only be honored if the ticket-granting ticket on which it is based has its MAY-POSTDATE flag set. The resulting ticket will also have its INVALID flag set, and that flag may be reset by a subsequent request to the KDC after the starttime in the ticket has been reached.

Return value: Returns non-0 iff postdated flag is set in KDC-REQ.

shishi_kdcreq_renewable_p

Function: int shishi_kdcreq_renewable_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option renewable flag is set.

The RENEWABLE option indicates that the ticket to be issued is to have its RENEWABLE flag set. It may only be set on the initial request, or when the ticket-granting ticket on which the request is based is also renewable. If this option is requested, then the rtime field in the request contains the desired absolute expiration time for the ticket.

Return value: Returns non-0 iff renewable flag is set in KDC-REQ.

shishi_kdcreq_disable_transited_check_p

Function: int shishi_kdcreq_disable_transited_check_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option disable-transited-check flag is set.

By default the KDC will check the transited field of a ticket-granting-ticket against the policy of the local realm before it will issue derivative tickets based on the ticket-granting ticket. If this flag is set in the request, checking of the transited field is disabled. Tickets issued without the performance of this check will be noted by the reset (0) value of the TRANSITED-POLICY-CHECKED flag, indicating to the application server that the tranisted field must be checked locally. KDCs are encouraged but not required to honor the DISABLE-TRANSITED-CHECK option.

This flag is new since RFC 1510

Return value: Returns non-0 iff disable-transited-check flag is set in KDC-REQ.

shishi_kdcreq_renewable_ok_p

Function: int shishi_kdcreq_renewable_ok_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option renewable-ok flag is set.

The RENEWABLE-OK option indicates that a renewable ticket will be acceptable if a ticket with the requested life cannot otherwise be provided. If a ticket with the requested life cannot be provided, then a renewable ticket may be issued with a renew-till equal to the requested endtime. The value of the renew-till field may still be limited by local limits, or limits selected by the individual principal or server.

Return value: Returns non-0 iff renewable-ok flag is set in KDC-REQ.

shishi_kdcreq_enc_tkt_in_skey_p

Function: int shishi_kdcreq_enc_tkt_in_skey_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option enc-tkt-in-skey flag is set.

This option is used only by the ticket-granting service. The ENC-TKT-IN-SKEY option indicates that the ticket for the end server is to be encrypted in the session key from the additional ticket-granting ticket provided.

Return value: Returns non-0 iff enc-tkt-in-skey flag is set in KDC-REQ.

shishi_kdcreq_renew_p

Function: int shishi_kdcreq_renew_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option renew flag is set.

This option is used only by the ticket-granting service. The RENEW option indicates that the present request is for a renewal. The ticket provided is encrypted in the secret key for the server on which it is valid. This option will only be honored if the ticket to be renewed has its RENEWABLE flag set and if the time in its renew-till field has not passed. The ticket to be renewed is passed in the padata field as part of the authentication header.

Return value: Returns non-0 iff renew flag is set in KDC-REQ.

shishi_kdcreq_validate_p

Function: int shishi_kdcreq_validate_p (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to get kdc-options field from.

Description: Determine if KDC-Option validate flag is set.

This option is used only by the ticket-granting service. The VALIDATE option indicates that the request is to validate a postdated ticket. It will only be honored if the ticket presented is postdated, presently has its INVALID flag set, and would be otherwise usable at this time. A ticket cannot be validated before its starttime. The ticket presented for validation is encrypted in the key of the server for which it is valid and is passed in the padata field as part of the authentication header.

Return value: Returns non-0 iff validate flag is set in KDC-REQ.

shishi_kdcreq_options_set

Function: int shishi_kdcreq_options_set (Shishi * handle, Shishi_asn1 kdcreq, uint32_t options)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set etype field in.
options: integer with flags to store in KDC-REQ.

Description: Set options in KDC-REQ. Note that this reset any already existing flags.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_options_add

Function: int shishi_kdcreq_options_add (Shishi * handle, Shishi_asn1 kdcreq, uint32_t option)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ variable to set etype field in.
option: integer with options to add in KDC-REQ.

Description: Add KDC-Option to KDC-REQ. This preserves all existing options.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_clear_padata

Function: int shishi_kdcreq_clear_padata (Shishi * handle, Shishi_asn1 kdcreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ to remove PA-DATA from.

Description: Remove the padata field from KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_get_padata

Function: int shishi_kdcreq_get_padata (Shishi * handle, Shishi_asn1 kdcreq, Shishi_padata_type padatatype, char ** out, size_t * outlen)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ to get PA-DATA from.
padatatype: type of PA-DATA, see Shishi_padata_type.
out: output array with newly allocated PA-DATA value.
outlen: size of output array with PA-DATA value.

Description: Get pre authentication data (PA-DATA) from KDC-REQ. Pre authentication data is used to pass various information to KDC, such as in case of a SHISHI_PA_TGS_REQ padatatype the AP-REQ that authenticates the user to get the ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_get_padata_tgs

Function: int shishi_kdcreq_get_padata_tgs (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 * apreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ to get PA-TGS-REQ from.
apreq: Output variable with newly allocated AP-REQ.

Description: Extract TGS pre-authentication data from KDC-REQ. The data is an AP-REQ that authenticates the request. This function call shishi_kdcreq_get_padata() with a SHISHI_PA_TGS_REQ padatatype and DER decode the result (if any).

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_add_padata

Function: int shishi_kdcreq_add_padata (Shishi * handle, Shishi_asn1 kdcreq, int padatatype, const char * data, size_t datalen)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ to add PA-DATA to.
padatatype: type of PA-DATA, see Shishi_padata_type.
data: input array with PA-DATA value.
datalen: size of input array with PA-DATA value.

Description: Add new pre authentication data (PA-DATA) to KDC-REQ. This is used to pass various information to KDC, such as in case of a SHISHI_PA_TGS_REQ padatatype the AP-REQ that authenticates the user to get the ticket. (But also see shishi_kdcreq_add_padata_tgs() which takes an AP-REQ directly.)

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_add_padata_tgs

Function: int shishi_kdcreq_add_padata_tgs (Shishi * handle, Shishi_asn1 kdcreq, Shishi_asn1 apreq)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ to add PA-DATA to.
apreq: AP-REQ to add as PA-DATA.

Description: Add TGS pre-authentication data to KDC-REQ. The data is an AP-REQ that authenticates the request. This functions simply DER encodes the AP-REQ and calls shishi_kdcreq_add_padata() with a SHISHI_PA_TGS_REQ padatatype.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcreq_add_padata_preauth

Function: int shishi_kdcreq_add_padata_preauth (Shishi * handle, Shishi_asn1 kdcreq, Shishi_key * key)

handle: shishi handle as allocated by shishi_init().
kdcreq: KDC-REQ to add pre-authentication data to.
key: Key used to encrypt pre-auth data.

Description: Add pre-authentication data to KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_asrep

Function: Shishi_asn1 shishi_asrep (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Description: This function creates a new AS-REP, populated with some default values.

Return value: Returns the AS-REP or NULL on failure.

shishi_tgsrep

Function: Shishi_asn1 shishi_tgsrep (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Description: This function creates a new TGS-REP, populated with some default values.

Return value: Returns the TGS-REP or NULL on failure.

shishi_kdcrep_print

Function: int shishi_kdcrep_print (Shishi * handle, FILE * fh, Shishi_asn1 kdcrep)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for writing.
kdcrep: KDC-REP to print.

Description: Print ASCII armored DER encoding of KDC-REP to file.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_save

Function: int shishi_kdcrep_save (Shishi * handle, FILE * fh, Shishi_asn1 kdcrep)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for writing.
kdcrep: KDC-REP to save.

Description: Print DER encoding of KDC-REP to file.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_to_file

Function: int shishi_kdcrep_to_file (Shishi * handle, Shishi_asn1 kdcrep, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP 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 KDC-REP to file in specified TYPE. The file will be truncated if it exists.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_parse

Function: int shishi_kdcrep_parse (Shishi * handle, FILE * fh, Shishi_asn1 * kdcrep)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for reading.
kdcrep: output variable with newly allocated KDC-REP.

Description: Read ASCII armored DER encoded KDC-REP from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_read

Function: int shishi_kdcrep_read (Shishi * handle, FILE * fh, Shishi_asn1 * kdcrep)

handle: shishi handle as allocated by shishi_init().
fh: file handle open for reading.
kdcrep: output variable with newly allocated KDC-REP.

Description: Read DER encoded KDC-REP from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_from_file

Function: int shishi_kdcrep_from_file (Shishi * handle, Shishi_asn1 * kdcrep, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().
kdcrep: output variable with newly allocated KDC-REP.
filetype: input variable specifying type of file to be read, see Shishi_filetype.
filename: input variable with filename to read from.

Description: Read KDC-REP from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_crealm_set

Function: int shishi_kdcrep_crealm_set (Shishi * handle, Shishi_asn1 kdcrep, const char * crealm)

handle: shishi handle as allocated by shishi_init().
kdcrep: Kdcrep variable to set realm field in.
crealm: input array with name of realm.

Description: Set the client realm field in the KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_cname_set

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

handle: shishi handle as allocated by shishi_init().
kdcrep: Kdcrep variable to set server name field in.
name_type: type of principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.
cname: input array with principal name.

Description: Set the client name field in the KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_client_set

Function: int shishi_kdcrep_client_set (Shishi * handle, Shishi_asn1 kdcrep, const char * client)

handle: shishi handle as allocated by shishi_init().
kdcrep: Kdcrep variable to set server name field in.
client: zero-terminated string with principal name on RFC 1964 form.

Description: Set the client name field in the KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_get_enc_part_etype

Function: int shishi_kdcrep_get_enc_part_etype (Shishi * handle, Shishi_asn1 kdcrep, int32_t * etype)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP variable to get value from.
etype: output variable that holds the value.

Description: Extract KDC-REP.enc-part.etype.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_get_ticket

Function: int shishi_kdcrep_get_ticket (Shishi * handle, Shishi_asn1 kdcrep, Shishi_asn1 * ticket)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP variable to get ticket from.
ticket: output variable to hold extracted ticket.

Description: Extract ticket from KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_set_ticket

Function: int shishi_kdcrep_set_ticket (Shishi * handle, Shishi_asn1 kdcrep, Shishi_asn1 ticket)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP to add ticket field to.
ticket: input ticket to copy into KDC-REP ticket field.

Description: Copy ticket into KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_set_enc_part

Function: int shishi_kdcrep_set_enc_part (Shishi * handle, Shishi_asn1 kdcrep, int32_t etype, uint32_t kvno, const char * buf, size_t buflen)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP to add enc-part field to.
etype: encryption type used to encrypt enc-part.
kvno: key version number.
buf: input array with encrypted enc-part.
buflen: size of input array with encrypted enc-part.

Description: Set the encrypted enc-part field in the KDC-REP. The encrypted data is usually created by calling shishi_encrypt() on the DER encoded enc-part. To save time, you may want to use shishi_kdcrep_add_enc_part() instead, which calculates the encrypted data and calls this function in one step.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_add_enc_part

Function: int shishi_kdcrep_add_enc_part (Shishi * handle, Shishi_asn1 kdcrep, Shishi_key * key, int keyusage, Shishi_asn1 enckdcreppart)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP to add enc-part field to.
key: key used to encrypt enc-part.
keyusage: key usage to use, normally SHISHI_KEYUSAGE_ENCASREPPART, SHISHI_KEYUSAGE_ENCTGSREPPART_SESSION_KEY or SHISHI_KEYUSAGE_ENCTGSREPPART_AUTHENTICATOR_KEY.
enckdcreppart: EncKDCRepPart to add.

Description: Encrypts DER encoded EncKDCRepPart using key and stores it in the KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_kdcrep_clear_padata

Function: int shishi_kdcrep_clear_padata (Shishi * handle, Shishi_asn1 kdcrep)

handle: shishi handle as allocated by shishi_init().
kdcrep: KDC-REP to remove PA-DATA from.

Description: Remove the padata field from KDC-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_get_key

Function: int shishi_enckdcreppart_get_key (Shishi * handle, Shishi_asn1 enckdcreppart, Shishi_key ** key)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
key: newly allocated encryption key handle.

Description: Extract the key to use with the ticket sent in the KDC-REP associated with the EncKDCRepPart input variable.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_key_set

Function: int shishi_enckdcreppart_key_set (Shishi * handle, Shishi_asn1 enckdcreppart, Shishi_key * key)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
key: key handle with information to store in enckdcreppart.

Description: Set the EncKDCRepPart.key field to key type and value of supplied key.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_nonce_set

Function: int shishi_enckdcreppart_nonce_set (Shishi * handle, Shishi_asn1 enckdcreppart, uint32_t nonce)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
nonce: nonce to set in EncKDCRepPart.

Description: Set the EncKDCRepPart.nonce field.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_flags_set

Function: int shishi_enckdcreppart_flags_set (Shishi * handle, Shishi_asn1 enckdcreppart, int flags)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
flags: flags to set in EncKDCRepPart.

Description: Set the EncKDCRepPart.flags field.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_authtime_set

Function: int shishi_enckdcreppart_authtime_set (Shishi * handle, Shishi_asn1 enckdcreppart, const char * authtime)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
authtime: character buffer containing a generalized time string.

Description: Set the EncTicketPart.authtime to supplied value.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_starttime_set

Function: int shishi_enckdcreppart_starttime_set (Shishi * handle, Shishi_asn1 enckdcreppart, const char * starttime)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
starttime: character buffer containing a generalized time string.

Description: Set the EncTicketPart.starttime to supplied value. Use a NULL value for starttime to remove the field.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_endtime_set

Function: int shishi_enckdcreppart_endtime_set (Shishi * handle, Shishi_asn1 enckdcreppart, const char * endtime)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
endtime: character buffer containing a generalized time string.

Description: Set the EncTicketPart.endtime to supplied value.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_renew_till_set

Function: int shishi_enckdcreppart_renew_till_set (Shishi * handle, Shishi_asn1 enckdcreppart, const char * renew_till)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
renew_till: character buffer containing a generalized time string.

Description: Set the EncTicketPart.renew-till to supplied value. Use a NULL value for renew_till to remove the field.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_srealm_set

Function: int shishi_enckdcreppart_srealm_set (Shishi * handle, Shishi_asn1 enckdcreppart, const char * srealm)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: EncKDCRepPart variable to set realm field in.
srealm: input array with name of realm.

Description: Set the server realm field in the EncKDCRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_sname_set

Function: int shishi_enckdcreppart_sname_set (Shishi * handle, Shishi_asn1 enckdcreppart, Shishi_name_type name_type, char * sname[])

handle: shishi handle as allocated by shishi_init().
enckdcreppart: EncKDCRepPart variable to set server name field in.
name_type: type of principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.
sname: input array with principal name.

Description: Set the server name field in the EncKDCRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_enckdcreppart_populate_encticketpart

Function: int shishi_enckdcreppart_populate_encticketpart (Shishi * handle, Shishi_asn1 enckdcreppart, Shishi_asn1 encticketpart)

handle: shishi handle as allocated by shishi_init().
enckdcreppart: input EncKDCRepPart variable.
encticketpart: input EncTicketPart variable.

Description: Set the flags, authtime, starttime, endtime, renew-till and caddr fields of the EncKDCRepPart to the corresponding values in the EncTicketPart.

Return value: Returns SHISHI_OK iff successful.


Next: , Previous: , Up: Programming Manual   [Contents][Index]