Next: , Previous: Ticket Set Functions, Up: Programming Manual


5.4 AP-REQ and AP-REP Functions

The “AP-REQ” and “AP-REP” are ASN.1 structures used by application client and servers to prove to each other who they are. The structures contain auxilliary information, together with an authenticator (see Authenticator Functions) which is the real cryptographic proof. The following illustrates the AP-REQ and AP-REP ASN.1 structures.

AP-REQ		::= [APPLICATION 14] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (14),
	ap-options	[2] APOptions,
	ticket		[3] Ticket,
	authenticator	[4] EncryptedData {Authenticator,
				{ keyuse-pa-TGSReq-authenticator
				  | keyuse-APReq-authenticator }}
}

AP-REP		::= [APPLICATION 15] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (15),
	enc-part	[2] EncryptedData {EncAPRepPart,
				{ keyuse-EncAPRepPart }}
}

EncAPRepPart	::= [APPLICATION 27] SEQUENCE {
	ctime		[0] KerberosTime,
	cusec		[1] Microseconds,
	subkey		[2] EncryptionKey OPTIONAL,
	seq-number	[3] UInt32 OPTIONAL
}

shishi_ap

— Function: int shishi_ap (Shishi * handle, Shishi_ap ** ap)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

Create a new AP exchange with a random subkey of the default encryption type from configuration. Note that there is no guarantee that the receiver will understand that key type, you should probably use shishi_ap_etype() or shishi_ap_nosubkey() instead. In the future, this function will likely behave as shishi_ap_nosubkey() and shishi_ap_nosubkey() will be removed.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_etype

— Function: int shishi_ap_etype (Shishi * handle, Shishi_ap ** ap, int etype)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

etype: encryption type of newly generated random subkey.

Create a new AP exchange with a random subkey of indicated encryption type.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_nosubkey

— Function: int shishi_ap_nosubkey (Shishi * handle, Shishi_ap ** ap)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

Create a new AP exchange without subkey in authenticator.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_done

— Function: void shishi_ap_done (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Deallocate resources associated with AP exchange. This should be called by the application when it no longer need to utilize the AP exchange handle.

shishi_ap_set_tktoptions

— Function: int shishi_ap_set_tktoptions (Shishi_ap * ap, Shishi_tkt * tkt, int options)

ap: structure that holds information about AP exchange

tkt: ticket to set in AP.

options: AP-REQ options to set in AP.

Set the ticket (see shishi_ap_tkt_set()) and set the AP-REQ apoptions (see shishi_apreq_options_set()).

Return value: Returns SHISHI_OK iff successful.

shishi_ap_set_tktoptionsdata

— Function: int shishi_ap_set_tktoptionsdata (Shishi_ap * ap, Shishi_tkt * tkt, int options, const char * data, size_t len)

ap: structure that holds information about AP exchange

tkt: ticket to set in AP.

options: AP-REQ options to set in AP.

data: input array with data to checksum in Authenticator.

len: length of input array with data to checksum in Authenticator.

Set the ticket (see shishi_ap_tkt_set()) and set the AP-REQ apoptions (see shishi_apreq_options_set()) and set the Authenticator checksum data.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_set_tktoptionsraw

— Function: int shishi_ap_set_tktoptionsraw (Shishi_ap * ap, Shishi_tkt * tkt, int options, int32_t cksumtype, const char * data, size_t len)

ap: structure that holds information about AP exchange

tkt: ticket to set in AP.

options: AP-REQ options to set in AP.

cksumtype: authenticator checksum type to set in AP.

data: input array with data to store in checksum field in Authenticator.

len: length of input array with data to store in checksum field in Authenticator.

Set the ticket (see shishi_ap_tkt_set()) and set the AP-REQ apoptions (see shishi_apreq_options_set()) and set the raw Authenticator checksum data.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_set_tktoptionsasn1usage

— Function: int shishi_ap_set_tktoptionsasn1usage (Shishi_ap * ap, Shishi_tkt * tkt, int options, Shishi_asn1 node, const char * field, int authenticatorcksumkeyusage, int authenticatorkeyusage)

ap: structure that holds information about AP exchange

tkt: ticket to set in AP.

options: AP-REQ options to set in AP.

node: input ASN.1 structure to store as authenticator checksum data.

field: field in ASN.1 structure to use.

authenticatorcksumkeyusage: key usage for checksum in authenticator.

authenticatorkeyusage: key usage for authenticator.

Set ticket, options and authenticator checksum data using shishi_ap_set_tktoptionsdata(). The authenticator checksum data is the DER encoding of the ASN.1 field provided.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_tktoptions

— Function: int shishi_ap_tktoptions (Shishi * handle, Shishi_ap ** ap, Shishi_tkt * tkt, int options)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

tkt: ticket to set in newly created AP.

options: AP-REQ options to set in newly created AP.

Create a new AP exchange using shishi_ap(), and set the ticket and AP-REQ apoptions using shishi_ap_set_tktoptions(). A random session key is added to the authenticator, using the same keytype as the ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_tktoptionsdata

— Function: int shishi_ap_tktoptionsdata (Shishi * handle, Shishi_ap ** ap, Shishi_tkt * tkt, int options, const char * data, size_t len)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

tkt: ticket to set in newly created AP.

options: AP-REQ options to set in newly created AP.

data: input array with data to checksum in Authenticator.

len: length of input array with data to checksum in Authenticator.

Create a new AP exchange using shishi_ap(), and set the ticket, AP-REQ apoptions and the Authenticator checksum data using shishi_ap_set_tktoptionsdata(). A random session key is added to the authenticator, using the same keytype as the ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_tktoptionsraw

— Function: int shishi_ap_tktoptionsraw (Shishi * handle, Shishi_ap ** ap, Shishi_tkt * tkt, int options, int32_t cksumtype, const char * data, size_t len)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

tkt: ticket to set in newly created AP.

options: AP-REQ options to set in newly created AP.

cksumtype: authenticator checksum type to set in AP.

data: input array with data to store in checksum field in Authenticator.

len: length of input array with data to store in checksum field in Authenticator.

Create a new AP exchange using shishi_ap(), and set the ticket, AP-REQ apoptions and the raw Authenticator checksum data field using shishi_ap_set_tktoptionsraw(). A random session key is added to the authenticator, using the same keytype as the ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_etype_tktoptionsdata

— Function: int shishi_ap_etype_tktoptionsdata (Shishi * handle, Shishi_ap ** ap, int32_t etype, Shishi_tkt * tkt, int options, const char * data, size_t len)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

etype: encryption type of newly generated random subkey.

tkt: ticket to set in newly created AP.

options: AP-REQ options to set in newly created AP.

data: input array with data to checksum in Authenticator.

len: length of input array with data to checksum in Authenticator.

Create a new AP exchange using shishi_ap(), and set the ticket, AP-REQ apoptions and the Authenticator checksum data using shishi_ap_set_tktoptionsdata(). A random session key is added to the authenticator, using the same keytype as the ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_tktoptionsasn1usage

— Function: int shishi_ap_tktoptionsasn1usage (Shishi * handle, Shishi_ap ** ap, Shishi_tkt * tkt, int options, Shishi_asn1 node, const char * field, int authenticatorcksumkeyusage, int authenticatorkeyusage)

handle: shishi handle as allocated by shishi_init().

ap: pointer to new structure that holds information about AP exchange

tkt: ticket to set in newly created AP.

options: AP-REQ options to set in newly created AP.

node: input ASN.1 structure to store as authenticator checksum data.

field: field in ASN.1 structure to use.

authenticatorcksumkeyusage: key usage for checksum in authenticator.

authenticatorkeyusage: key usage for authenticator.

Create a new AP exchange using shishi_ap(), and set ticket, options and authenticator checksum data from the DER encoding of the ASN.1 field using shishi_ap_set_tktoptionsasn1usage(). A random session key is added to the authenticator, using the same keytype as the ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_tkt

— Function: Shishi_tkt * shishi_ap_tkt (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Get Ticket from AP exchange.

Return value: Returns the ticket from the AP exchange, or NULL if not yet set or an error occured.

shishi_ap_tkt_set

— Function: void shishi_ap_tkt_set (Shishi_ap * ap, Shishi_tkt * tkt)

ap: structure that holds information about AP exchange

tkt: ticket to store in AP.

Set the Ticket in the AP exchange.

shishi_ap_authenticator_cksumdata

— Function: int shishi_ap_authenticator_cksumdata (Shishi_ap * ap, char * out, size_t * len)

ap: structure that holds information about AP exchange

out: output array that holds authenticator checksum data.

len: on input, maximum length of output array that holds authenticator checksum data, on output actual length of output array that holds authenticator checksum data.

Get checksum data from Authenticator.

Return value: Returns SHISHI_OK if successful, or SHISHI_TOO_SMALL_BUFFER if buffer provided was too small (then len will hold necessary buffer size).

shishi_ap_authenticator_cksumdata_set

— Function: void shishi_ap_authenticator_cksumdata_set (Shishi_ap * ap, const char * authenticatorcksumdata, size_t authenticatorcksumdatalen)

ap: structure that holds information about AP exchange

authenticatorcksumdata: input array with data to compute checksum on and store in Authenticator in AP-REQ.

authenticatorcksumdatalen: length of input array with data to compute checksum on and store in Authenticator in AP-REQ.

Set the Authenticator Checksum Data in the AP exchange. This is the data that will be checksumed, and the checksum placed in the checksum field. It is not the actual checksum field. See also shishi_ap_authenticator_cksumraw_set.

shishi_ap_authenticator_cksumraw_set

— Function: void shishi_ap_authenticator_cksumraw_set (Shishi_ap * ap, int32_t authenticatorcksumtype, const char * authenticatorcksumraw, size_t authenticatorcksumrawlen)

ap: structure that holds information about AP exchange

authenticatorcksumtype: authenticator checksum type to set in AP.

authenticatorcksumraw: input array with authenticator checksum field value to set in Authenticator in AP-REQ.

authenticatorcksumrawlen: length of input array with authenticator checksum field value to set in Authenticator in AP-REQ.

Set the Authenticator Checksum Data in the AP exchange. This is the actual checksum field, not data to compute checksum on and then store in the checksum field. See also shishi_ap_authenticator_cksumdata_set.

shishi_ap_authenticator_cksumtype

— Function: int32_t shishi_ap_authenticator_cksumtype (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Get the Authenticator Checksum Type in the AP exchange.

Return value: Return the authenticator checksum type.

shishi_ap_authenticator_cksumtype_set

— Function: void shishi_ap_authenticator_cksumtype_set (Shishi_ap * ap, int32_t cksumtype)

ap: structure that holds information about AP exchange

cksumtype: authenticator checksum type to set in AP.

Set the Authenticator Checksum Type in the AP exchange.

shishi_ap_authenticator

— Function: Shishi_asn1 shishi_ap_authenticator (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Get ASN.1 Authenticator structure from AP exchange.

Return value: Returns the Authenticator from the AP exchange, or NULL if not yet set or an error occured.

shishi_ap_authenticator_set

— Function: void shishi_ap_authenticator_set (Shishi_ap * ap, Shishi_asn1 authenticator)

ap: structure that holds information about AP exchange

authenticator: authenticator to store in AP.

Set the Authenticator in the AP exchange.

shishi_ap_req

— Function: Shishi_asn1 shishi_ap_req (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Get ASN.1 AP-REQ structure from AP exchange.

Return value: Returns the AP-REQ from the AP exchange, or NULL if not yet set or an error occured.

shishi_ap_req_set

— Function: void shishi_ap_req_set (Shishi_ap * ap, Shishi_asn1 apreq)

ap: structure that holds information about AP exchange

apreq: apreq to store in AP.

Set the AP-REQ in the AP exchange.

shishi_ap_req_der

— Function: int shishi_ap_req_der (Shishi_ap * ap, char ** out, size_t * outlen)

ap: structure that holds information about AP exchange

out: pointer to output array with der encoding of AP-REQ.

outlen: pointer to length of output array with der encoding of AP-REQ.

Build AP-REQ using shishi_ap_req_build() and DER encode it. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_req_der_set

— Function: int shishi_ap_req_der_set (Shishi_ap * ap, char * der, size_t derlen)

ap: structure that holds information about AP exchange

der: input array with DER encoded AP-REQ.

derlen: length of input array with DER encoded AP-REQ.

DER decode AP-REQ and set it AP exchange. If decoding fails, the AP-REQ in the AP exchange is lost.

Return value: Returns SHISHI_OK.

shishi_ap_req_build

— Function: int shishi_ap_req_build (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Checksum data in authenticator and add ticket and authenticator to AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_req_decode

— Function: int shishi_ap_req_decode (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Decode ticket in AP-REQ and set the Ticket fields in the AP exchange.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_req_process_keyusage

— Function: int shishi_ap_req_process_keyusage (Shishi_ap * ap, Shishi_key * key, int32_t keyusage)

ap: structure that holds information about AP exchange

key: cryptographic key used to decrypt ticket in AP-REQ.

keyusage: key usage to use during decryption, for normal AP-REQ's this is normally SHISHI_KEYUSAGE_APREQ_AUTHENTICATOR, for AP-REQ's part of TGS-REQ's, this is normally SHISHI_KEYUSAGE_TGSREQ_APREQ_AUTHENTICATOR.

Decrypt ticket in AP-REQ using supplied key and decrypt Authenticator in AP-REQ using key in decrypted ticket, and on success set the Ticket and Authenticator fields in the AP exchange.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_req_process

— Function: int shishi_ap_req_process (Shishi_ap * ap, Shishi_key * key)

ap: structure that holds information about AP exchange

key: cryptographic key used to decrypt ticket in AP-REQ.

Decrypt ticket in AP-REQ using supplied key and decrypt Authenticator in AP-REQ using key in decrypted ticket, and on success set the Ticket and Authenticator fields in the AP exchange.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_req_asn1

— Function: int shishi_ap_req_asn1 (Shishi_ap * ap, Shishi_asn1 * apreq)

ap: structure that holds information about AP exchange

apreq: output AP-REQ variable.

Build AP-REQ using shishi_ap_req_build() and return it.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_key

— Function: Shishi_key * shishi_ap_key (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Extract the application key from AP. If subkeys are used, it is taken from the Authenticator, otherwise the session key is used.

Return value: Return application key from AP.

shishi_ap_rep

— Function: Shishi_asn1 shishi_ap_rep (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Get ASN.1 AP-REP structure from AP exchange.

Return value: Returns the AP-REP from the AP exchange, or NULL if not yet set or an error occured.

shishi_ap_rep_set

— Function: void shishi_ap_rep_set (Shishi_ap * ap, Shishi_asn1 aprep)

ap: structure that holds information about AP exchange

aprep: aprep to store in AP.

Set the AP-REP in the AP exchange.

shishi_ap_rep_der

— Function: int shishi_ap_rep_der (Shishi_ap * ap, char ** out, size_t * outlen)

ap: structure that holds information about AP exchange

out: output array with newly allocated DER encoding of AP-REP.

outlen: length of output array with DER encoding of AP-REP.

Build AP-REP using shishi_ap_rep_build() and DER encode it. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_rep_der_set

— Function: int shishi_ap_rep_der_set (Shishi_ap * ap, char * der, size_t derlen)

ap: structure that holds information about AP exchange

der: input array with DER encoded AP-REP.

derlen: length of input array with DER encoded AP-REP.

DER decode AP-REP and set it AP exchange. If decoding fails, the AP-REP in the AP exchange remains.

Return value: Returns SHISHI_OK.

shishi_ap_rep_build

— Function: int shishi_ap_rep_build (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Checksum data in authenticator and add ticket and authenticator to AP-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_rep_asn1

— Function: int shishi_ap_rep_asn1 (Shishi_ap * ap, Shishi_asn1 * aprep)

ap: structure that holds information about AP exchange

aprep: output AP-REP variable.

Build AP-REP using shishi_ap_rep_build() and return it.

Return value: Returns SHISHI_OK iff successful.

shishi_ap_rep_verify

— Function: int shishi_ap_rep_verify (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Verify AP-REP compared to Authenticator.

Return value: Returns SHISHI_OK, SHISHI_APREP_VERIFY_FAILED or an error.

shishi_ap_rep_verify_der

— Function: int shishi_ap_rep_verify_der (Shishi_ap * ap, char * der, size_t derlen)

ap: structure that holds information about AP exchange

der: input array with DER encoded AP-REP.

derlen: length of input array with DER encoded AP-REP.

DER decode AP-REP and set it in AP exchange using shishi_ap_rep_der_set() and verify it using shishi_ap_rep_verify().

Return value: Returns SHISHI_OK, SHISHI_APREP_VERIFY_FAILED or an error.

shishi_ap_rep_verify_asn1

— Function: int shishi_ap_rep_verify_asn1 (Shishi_ap * ap, Shishi_asn1 aprep)

ap: structure that holds information about AP exchange

aprep: input AP-REP.

Set the AP-REP in the AP exchange using shishi_ap_rep_set() and verify it using shishi_ap_rep_verify().

Return value: Returns SHISHI_OK, SHISHI_APREP_VERIFY_FAILED or an error.

shishi_ap_encapreppart

— Function: Shishi_asn1 shishi_ap_encapreppart (Shishi_ap * ap)

ap: structure that holds information about AP exchange

Get ASN.1 EncAPRepPart structure from AP exchange.

Return value: Returns the EncAPREPPart from the AP exchange, or NULL if not yet set or an error occured.

shishi_ap_encapreppart_set

— Function: void shishi_ap_encapreppart_set (Shishi_ap * ap, Shishi_asn1 encapreppart)

ap: structure that holds information about AP exchange

encapreppart: EncAPRepPart to store in AP.

Set the EncAPRepPart in the AP exchange.

shishi_ap_option2string

— Function: const char * shishi_ap_option2string (Shishi_apoptions option)

option: enumerated AP-Option type, see Shishi_apoptions.

Convert AP-Option type to AP-Option name string. Note that option must be just one of the AP-Option types, it cannot be an binary ORed indicating several AP-Options.

Return value: Returns static string with name of AP-Option that must not be deallocated, or "unknown" if AP-Option was not understood.

shishi_ap_string2option

— Function: Shishi_apoptions shishi_ap_string2option (const char * str)

str: zero terminated character array with name of AP-Option, e.g. "use-session-key".

Convert AP-Option name to AP-Option type.

Return value: Returns enumerated type member corresponding to AP-Option, or 0 if string was not understood.

shishi_apreq

— Function: Shishi_asn1 shishi_apreq (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

This function creates a new AP-REQ, populated with some default values.

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

shishi_apreq_print

— Function: int shishi_apreq_print (Shishi * handle, FILE * fh, Shishi_asn1 apreq)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

apreq: AP-REQ to print.

Print ASCII armored DER encoding of AP-REQ to file.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_save

— Function: int shishi_apreq_save (Shishi * handle, FILE * fh, Shishi_asn1 apreq)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

apreq: AP-REQ to save.

Save DER encoding of AP-REQ to file.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_to_file

— Function: int shishi_apreq_to_file (Shishi * handle, Shishi_asn1 apreq, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

apreq: AP-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 AP-REQ to file in specified TYPE. The file will be truncated if it exists.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_parse

— Function: int shishi_apreq_parse (Shishi * handle, FILE * fh, Shishi_asn1 * apreq)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

apreq: output variable with newly allocated AP-REQ.

Read ASCII armored DER encoded AP-REQ from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_read

— Function: int shishi_apreq_read (Shishi * handle, FILE * fh, Shishi_asn1 * apreq)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

apreq: output variable with newly allocated AP-REQ.

Read DER encoded AP-REQ from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_from_file

— Function: int shishi_apreq_from_file (Shishi * handle, Shishi_asn1 * apreq, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

apreq: output variable with newly allocated AP-REQ.

filetype: input variable specifying type of file to be read, see Shishi_filetype.

filename: input variable with filename to read from.

Read AP-REQ from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_set_authenticator

— Function: int shishi_apreq_set_authenticator (Shishi * handle, Shishi_asn1 apreq, int32_t etype, uint32_t kvno, const char * buf, size_t buflen)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ to add authenticator field to.

etype: encryption type used to encrypt authenticator.

kvno: version of the key used to encrypt authenticator.

buf: input array with encrypted authenticator.

buflen: size of input array with encrypted authenticator.

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

Return value: Returns SHISHI_OK on success.

shishi_apreq_add_authenticator

— Function: int shishi_apreq_add_authenticator (Shishi * handle, Shishi_asn1 apreq, Shishi_key * key, int keyusage, Shishi_asn1 authenticator)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ to add authenticator field to.

key: key to to use for encryption.

keyusage: cryptographic key usage value to use in encryption.

authenticator: authenticator as allocated by shishi_authenticator().

Encrypts DER encoded authenticator using key and store it in the AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_set_ticket

— Function: int shishi_apreq_set_ticket (Shishi * handle, Shishi_asn1 apreq, Shishi_asn1 ticket)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ to add ticket field to.

ticket: input ticket to copy into AP-REQ ticket field.

Copy ticket into AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_options

— Function: int shishi_apreq_options (Shishi * handle, Shishi_asn1 apreq, uint32_t * flags)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ to get options from.

flags: Output integer containing options from AP-REQ.

Extract the AP-Options from AP-REQ into output integer.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_use_session_key_p

— Function: int shishi_apreq_use_session_key_p (Shishi * handle, Shishi_asn1 apreq)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ as allocated by shishi_apreq().

Return non-0 iff the "Use session key" option is set in the AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_mutual_required_p

— Function: int shishi_apreq_mutual_required_p (Shishi * handle, Shishi_asn1 apreq)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ as allocated by shishi_apreq().

Return non-0 iff the "Mutual required" option is set in the AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_options_set

— Function: int shishi_apreq_options_set (Shishi * handle, Shishi_asn1 apreq, uint32_t options)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ as allocated by shishi_apreq().

options: Options to set in AP-REQ.

Set the AP-Options in AP-REQ to indicate integer.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_options_add

— Function: int shishi_apreq_options_add (Shishi * handle, Shishi_asn1 apreq, uint32_t option)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ as allocated by shishi_apreq().

option: Options to add in AP-REQ.

Add the AP-Options in AP-REQ. Options not set in input parameter option are preserved in the AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_options_remove

— Function: int shishi_apreq_options_remove (Shishi * handle, Shishi_asn1 apreq, uint32_t option)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ as allocated by shishi_apreq().

option: Options to remove from AP-REQ.

Remove the AP-Options from AP-REQ. Options not set in input parameter option are preserved in the AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_get_authenticator_etype

— Function: int shishi_apreq_get_authenticator_etype (Shishi * handle, Shishi_asn1 apreq, int32_t * etype)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ variable to get value from.

etype: output variable that holds the value.

Extract AP-REQ.authenticator.etype.

Return value: Returns SHISHI_OK iff successful.

shishi_apreq_get_ticket

— Function: int shishi_apreq_get_ticket (Shishi * handle, Shishi_asn1 apreq, Shishi_asn1 * ticket)

handle: shishi handle as allocated by shishi_init().

apreq: AP-REQ variable to get ticket from.

ticket: output variable to hold extracted ticket.

Extract ticket from AP-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep

— Function: Shishi_asn1 shishi_aprep (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

This function creates a new AP-REP, populated with some default values.

Return value: Returns the authenticator or NULL on failure.

shishi_aprep_print

— Function: int shishi_aprep_print (Shishi * handle, FILE * fh, Shishi_asn1 aprep)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

aprep: AP-REP to print.

Print ASCII armored DER encoding of AP-REP to file.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep_save

— Function: int shishi_aprep_save (Shishi * handle, FILE * fh, Shishi_asn1 aprep)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

aprep: AP-REP to save.

Save DER encoding of AP-REP to file.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep_to_file

— Function: int shishi_aprep_to_file (Shishi * handle, Shishi_asn1 aprep, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

aprep: AP-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 AP-REP to file in specified TYPE. The file will be truncated if it exists.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep_parse

— Function: int shishi_aprep_parse (Shishi * handle, FILE * fh, Shishi_asn1 * aprep)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

aprep: output variable with newly allocated AP-REP.

Read ASCII armored DER encoded AP-REP from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep_read

— Function: int shishi_aprep_read (Shishi * handle, FILE * fh, Shishi_asn1 * aprep)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

aprep: output variable with newly allocated AP-REP.

Read DER encoded AP-REP from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep_from_file

— Function: int shishi_aprep_from_file (Shishi * handle, Shishi_asn1 * aprep, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

aprep: output variable with newly allocated AP-REP.

filetype: input variable specifying type of file to be read, see Shishi_filetype.

filename: input variable with filename to read from.

Read AP-REP from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_aprep_get_enc_part_etype

— Function: int shishi_aprep_get_enc_part_etype (Shishi * handle, Shishi_asn1 aprep, int32_t * etype)

handle: shishi handle as allocated by shishi_init().

aprep: AP-REP variable to get value from.

etype: output variable that holds the value.

Extract AP-REP.enc-part.etype.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart

— Function: Shishi_asn1 shishi_encapreppart (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

This function creates a new EncAPRepPart, populated with some default values. It uses the current time as returned by the system for the ctime and cusec fields.

Return value: Returns the encapreppart or NULL on failure.

shishi_encapreppart_print

— Function: int shishi_encapreppart_print (Shishi * handle, FILE * fh, Shishi_asn1 encapreppart)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

encapreppart: EncAPRepPart to print.

Print ASCII armored DER encoding of EncAPRepPart to file.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_save

— Function: int shishi_encapreppart_save (Shishi * handle, FILE * fh, Shishi_asn1 encapreppart)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

encapreppart: EncAPRepPart to save.

Save DER encoding of EncAPRepPart to file.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_to_file

— Function: int shishi_encapreppart_to_file (Shishi * handle, Shishi_asn1 encapreppart, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart to save.

filetype: input variable specifying type of file to be written, see Shishi_filetype.

filename: input variable with filename to write to.

Write EncAPRepPart to file in specified TYPE. The file will be truncated if it exists.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_parse

— Function: int shishi_encapreppart_parse (Shishi * handle, FILE * fh, Shishi_asn1 * encapreppart)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

encapreppart: output variable with newly allocated EncAPRepPart.

Read ASCII armored DER encoded EncAPRepPart from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_read

— Function: int shishi_encapreppart_read (Shishi * handle, FILE * fh, Shishi_asn1 * encapreppart)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

encapreppart: output variable with newly allocated EncAPRepPart.

Read DER encoded EncAPRepPart from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_from_file

— Function: int shishi_encapreppart_from_file (Shishi * handle, Shishi_asn1 * encapreppart, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

encapreppart: output variable with newly allocated EncAPRepPart.

filetype: input variable specifying type of file to be read, see Shishi_filetype.

filename: input variable with filename to read from.

Read EncAPRepPart from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_get_key

— Function: int shishi_encapreppart_get_key (Shishi * handle, Shishi_asn1 encapreppart, Shishi_key ** key)

handle: shishi handle as allocated by shishi_init().

encapreppart: input EncAPRepPart variable.

key: newly allocated key.

Extract the subkey from the encrypted AP-REP part.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_ctime

— Function: int shishi_encapreppart_ctime (Shishi * handle, Shishi_asn1 encapreppart, char ** t)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart as allocated by shishi_encapreppart().

t: newly allocated zero-terminated character array with client time.

Extract client time from EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_ctime_set

— Function: int shishi_encapreppart_ctime_set (Shishi * handle, Shishi_asn1 encapreppart, const char * t)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart as allocated by shishi_encapreppart().

t: string with generalized time value to store in EncAPRepPart.

Store client time in EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_cusec_get

— Function: int shishi_encapreppart_cusec_get (Shishi * handle, Shishi_asn1 encapreppart, uint32_t * cusec)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart as allocated by shishi_encapreppart().

cusec: output integer with client microseconds field.

Extract client microseconds field from EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_cusec_set

— Function: int shishi_encapreppart_cusec_set (Shishi * handle, Shishi_asn1 encapreppart, uint32_t cusec)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart as allocated by shishi_encapreppart().

cusec: client microseconds to set in authenticator, 0-999999.

Set the cusec field in the Authenticator.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_seqnumber_get

— Function: int shishi_encapreppart_seqnumber_get (Shishi * handle, Shishi_asn1 encapreppart, uint32_t * seqnumber)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart as allocated by shishi_encapreppart().

seqnumber: output integer with sequence number field.

Extract sequence number field from EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_seqnumber_remove

— Function: int shishi_encapreppart_seqnumber_remove (Shishi * handle, Shishi_asn1 encapreppart)

handle: shishi handle as allocated by shishi_init().

encapreppart: encapreppart as allocated by shishi_encapreppart().

Remove sequence number field in EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_seqnumber_set

— Function: int shishi_encapreppart_seqnumber_set (Shishi * handle, Shishi_asn1 encapreppart, uint32_t seqnumber)

handle: shishi handle as allocated by shishi_init().

encapreppart: encapreppart as allocated by shishi_encapreppart().

seqnumber: integer with sequence number field to store in encapreppart.

Store sequence number field in EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encapreppart_time_copy

— Function: int shishi_encapreppart_time_copy (Shishi * handle, Shishi_asn1 encapreppart, Shishi_asn1 authenticator)

handle: shishi handle as allocated by shishi_init().

encapreppart: EncAPRepPart as allocated by shishi_encapreppart().

authenticator: Authenticator to copy time fields from.

Copy time fields from Authenticator into EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.