Next: , Previous: Ticket (ASN.1) Functions, Up: Programming Manual


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: newly allocated output array with salt.

saltlen: holds actual size of output array with salt.

Derive 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 and returns it if found, otherwise the salt is derived from the client name and realm in AS-REQ.

Return value: Returns SHISHI_OK iff successful.

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 to read crealm from.

encticketpart: EncTicketPart to set crealm in.

Set crealm in KDC-REP to value in EncTicketPart.

Return value: Returns SHISHI_OK if successful.

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: AS-REQ to compare realm field in.

asrep: AS-REP to compare realm field in.

Verify that AS-REQ.req-body.realm and AS-REP.crealm fields matches. This is one of the steps that has to be performed when processing a AS-REQ and AS-REP exchange, see shishi_kdc_process().

Return value: Returns SHISHI_OK if successful, SHISHI_REALM_MISMATCH if the values differ, or an error code.

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-REQ to read cname from.

encticketpart: EncTicketPart to set cname in.

Set cname in KDC-REP to value in EncTicketPart.

Return value: Returns SHISHI_OK if successful.

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: AS-REQ to compare client name field in.

asrep: AS-REP to compare client name field in.

Verify that AS-REQ.req-body.realm and AS-REP.crealm fields matches. This is one of the steps that has to be performed when processing a AS-REQ and AS-REP exchange, see shishi_kdc_process().

Return value: Returns SHISHI_OK if successful, SHISHI_CNAME_MISMATCH if the values differ, or an error code.

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 to read nonce from.

enckdcreppart: EncKDCRepPart to set nonce in.

Set nonce in EncKDCRepPart to value in KDC-REQ.

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: KDC-REQ to compare nonce field in.

enckdcreppart: Encrypted KDC-REP part to compare nonce field in.

Verify that KDC-REQ.req-body.nonce and EncKDCRepPart.nonce fields matches. This is one of the steps that has to be performed when processing a KDC-REQ and KDC-REP exchange.

Return value: Returns SHISHI_OK if successful, SHISHI_NONCE_LENGTH_MISMATCH if the nonces have different lengths (usually indicates that buggy server truncated nonce to 4 bytes), SHISHI_NONCE_MISMATCH if the values differ, or an error code.

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 that holds the sent KDC-REQ.

tgsrep: input variable that holds the received KDC-REP.

authenticator: input variable with Authenticator from AP-REQ in KDC-REQ.

oldenckdcreppart: input variable with EncKDCRepPart used in request.

enckdcreppart: output variable that holds new EncKDCRepPart.

Process a TGS client exchange and output decrypted EncKDCRepPart which holds details for the new ticket received. This function simply derives the encryption key from the ticket used to construct the TGS request and calls shishi_kdc_process(), which see.

Return value: Returns SHISHI_OK iff the TGS client exchange was successful.

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 that holds the sent KDC-REQ.

asrep: input variable that holds the received KDC-REP.

string: input variable with zero terminated password.

enckdcreppart: output variable that holds new EncKDCRepPart.

Process an AS client exchange and output decrypted EncKDCRepPart which holds details for the new ticket received. This function simply derives the encryption key from the password and calls shishi_kdc_process(), which see.

Return value: Returns SHISHI_OK iff the AS client exchange was successful.

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 that holds the sent KDC-REQ.

kdcrep: input variable that holds the received KDC-REP.

key: input array with key to decrypt encrypted part of KDC-REP with.

keyusage: kereros key usage value.

enckdcreppart: output variable that holds new EncKDCRepPart.

Process a KDC client exchange and output decrypted EncKDCRepPart which holds details for the new ticket received. Use shishi_kdcrep_get_ticket() to extract the ticket. This function verifies the various conditions that must hold if the response is to be considered valid, specifically it compares nonces (shishi_kdc_check_nonce()) and if the exchange was a AS exchange, it also compares cname and crealm (shishi_as_check_cname() and shishi_as_check_crealm()).

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

Return value: Returns SHISHI_OK iff the KDC client exchange was successful.

shishi_asreq

— Function: Shishi_asn1 shishi_asreq (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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.

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

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.

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 create by shishi_init().

kdcreq: KDC-REQ variable to get client name from.

till: pointer to newly allocated zero terminated string containing "till" field with generalized time. May be NULL (to only populate realmlen).

tilllen: pointer to length of till on output, excluding terminating zero. May be NULL (to only populate tilllen).

Get "till" field (i.e. "endtime") in KDC-REQ, as zero-terminated string. The string is typically 15 characters long. The string is allocated 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_tillc

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

handle: Shishi library handle create by shishi_init().

kdcreq: KDC-REQ variable to get till field from.

Extract C time corresponding to the "till" field.

Return value: Returns 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.