KRB-SAFE        ::= [APPLICATION 20] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (20),
           safe-body       [2] KRB-SAFE-BODY,
           cksum           [3] Checksum
   }

   KRB-SAFE-BODY   ::= SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress,
           r-address       [5] HostAddress OPTIONAL
   }

— Function: int shishi_safe (Shishi * handle, Shishi_safe ** safe)

handle: shishi handle as allocated by shishi_init().

safe: pointer to new structure that holds information about SAFE exchange

Create a new SAFE exchange.

Return value: Returns SHISHI_OK iff successful.

— Function: void shishi_safe_done (Shishi_safe * safe)

safe: structure that holds information about SAFE exchange

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

— Function: Shishi_key * shishi_safe_key (Shishi_safe * safe)

safe: structure that holds information about SAFE exchange

Get key structured from SAFE exchange.

Return value: Returns the key used in the SAFE exchange, or NULL if not yet set or an error occured.

— Function: void shishi_safe_key_set (Shishi_safe * safe, Shishi_key * key)

safe: structure that holds information about SAFE exchange

key: key to store in SAFE.

Set the Key in the SAFE exchange.

— Function: Shishi_asn1 shishi_safe_safe (Shishi_safe * safe)

safe: structure that holds information about SAFE exchange

Get ASN.1 SAFE structured from SAFE exchange.

Return value: Returns the ASN.1 safe in the SAFE exchange, or NULL if not yet set or an error occured.

— Function: void shishi_safe_safe_set (Shishi_safe * safe, Shishi_asn1 asn1safe)

safe: structure that holds information about SAFE exchange

asn1safe: KRB-SAFE to store in SAFE exchange.

Set the KRB-SAFE in the SAFE exchange.

— Function: int shishi_safe_safe_der (Shishi_safe * safe, char ** out, size_t * outlen)

safe: safe as allocated by shishi_safe().

out: output array with newly allocated DER encoding of SAFE.

outlen: length of output array with DER encoding of SAFE.

DER encode SAFE structure. Typically shishi_safe_build() is used to build the SAFE structure first. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_safe_der_set (Shishi_safe * safe, char * der, size_t derlen)

safe: safe as allocated by shishi_safe().

der: input array with DER encoded KRB-SAFE.

derlen: length of input array with DER encoded KRB-SAFE.

DER decode KRB-SAFE and set it SAFE exchange. If decoding fails, the KRB-SAFE in the SAFE exchange remains.

Return value: Returns SHISHI_OK.

— Function: int shishi_safe_print (Shishi * handle, FILE * fh, Shishi_asn1 safe)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

safe: SAFE to print.

Print ASCII armored DER encoding of SAFE to file.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_save (Shishi * handle, FILE * fh, Shishi_asn1 safe)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

safe: SAFE to save.

Save DER encoding of SAFE to file.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_to_file (Shishi * handle, Shishi_asn1 safe, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

safe: SAFE to save.

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

filename: input variable with filename to write to.

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

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_parse (Shishi * handle, FILE * fh, Shishi_asn1 * safe)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

safe: output variable with newly allocated SAFE.

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

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_read (Shishi * handle, FILE * fh, Shishi_asn1 * safe)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

safe: output variable with newly allocated SAFE.

Read DER encoded SAFE from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_from_file (Shishi * handle, Shishi_asn1 * safe, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

safe: output variable with newly allocated SAFE.

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

filename: input variable with filename to read from.

Read SAFE from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_cksum (Shishi * handle, Shishi_asn1 safe, int32_t * cksumtype, char ** cksum, size_t * cksumlen)

handle: shishi handle as allocated by shishi_init().

safe: safe as allocated by shishi_safe().

cksumtype: output checksum type.

cksum: output array with newly allocated checksum data from SAFE.

cksumlen: output size of output checksum data buffer.

Read checksum value from KRB-SAFE. cksum is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_set_cksum (Shishi * handle, Shishi_asn1 safe, int32_t cksumtype, const char * cksum, size_t cksumlen)

handle: shishi handle as allocated by shishi_init().

safe: safe as allocated by shishi_safe().

cksumtype: input checksum type to store in SAFE.

cksum: input checksum data to store in SAFE.

cksumlen: size of input checksum data to store in SAFE.

Store checksum value in SAFE. A checksum is usually created by calling shishi_checksum() on some application specific data using the key from the ticket that is being used. To save time, you may want to use shishi_safe_build() instead, which calculates the checksum and calls this function in one step.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_user_data (Shishi * handle, Shishi_asn1 safe, char ** userdata, size_t * userdatalen)

handle: shishi handle as allocated by shishi_init().

safe: safe as allocated by shishi_safe().

userdata: output array with newly allocated user data from KRB-SAFE.

userdatalen: output size of output user data buffer.

Read user data value from KRB-SAFE. userdata is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_set_user_data (Shishi * handle, Shishi_asn1 safe, const char * userdata, size_t userdatalen)

handle: shishi handle as allocated by shishi_init().

safe: safe as allocated by shishi_safe().

userdata: input user application to store in SAFE.

userdatalen: size of input user application to store in SAFE.

Set the application data in SAFE.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_build (Shishi_safe * safe, Shishi_key * key)

safe: safe as allocated by shishi_safe().

key: key for session, used to compute checksum.

Build checksum and set it in KRB-SAFE. Note that this follows RFC 1510bis and is incompatible with RFC 1510, although presumably few implementations use the RFC1510 algorithm.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_safe_verify (Shishi_safe * safe, Shishi_key * key)

safe: safe as allocated by shishi_safe().

key: key for session, used to verify checksum.

Verify checksum in KRB-SAFE. Note that this follows RFC 1510bis and is incompatible with RFC 1510, although presumably few implementations use the RFC1510 algorithm.

Return value: Returns SHISHI_OK iff successful, SHISHI_SAFE_BAD_KEYTYPE if an incompatible key type is used, or SHISHI_SAFE_VERIFY_FAILED if the actual verification failed.

   KRB-PRIV        ::= [APPLICATION 21] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (21),
                           -- NOTE: there is no [2] tag
           enc-part        [3] EncryptedData -- EncKrbPrivPart
   }

   EncKrbPrivPart  ::= [APPLICATION 28] SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress -- sender's addr --,
           r-address       [5] HostAddress OPTIONAL -- recip's addr
   }

— Function: int shishi_priv (Shishi * handle, Shishi_priv ** priv)

handle: shishi handle as allocated by shishi_init().

priv: pointer to new structure that holds information about PRIV exchange

Create a new PRIV exchange.

Return value: Returns SHISHI_OK iff successful.

— Function: void shishi_priv_done (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

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

— Function: Shishi_key * shishi_priv_key (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

Get key from PRIV exchange.

Return value: Returns the key used in the PRIV exchange, or NULL if not yet set or an error occured.

— Function: void shishi_priv_key_set (Shishi_priv * priv, Shishi_key * key)

priv: structure that holds information about PRIV exchange

key: key to store in PRIV.

Set the Key in the PRIV exchange.

— Function: Shishi_asn1 shishi_priv_priv (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

Get ASN.1 PRIV structure in PRIV exchange.

Return value: Returns the ASN.1 priv in the PRIV exchange, or NULL if not yet set or an error occured.

— Function: void shishi_priv_priv_set (Shishi_priv * priv, Shishi_asn1 asn1priv)

priv: structure that holds information about PRIV exchange

asn1priv: KRB-PRIV to store in PRIV exchange.

Set the KRB-PRIV in the PRIV exchange.

— Function: int shishi_priv_priv_der (Shishi_priv * priv, char ** out, size_t * outlen)

priv: priv as allocated by shishi_priv().

out: output array with newly allocated DER encoding of PRIV.

outlen: length of output array with DER encoding of PRIV.

DER encode PRIV structure. Typically shishi_priv_build() is used to build the PRIV structure first. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_priv_der_set (Shishi_priv * priv, char * der, size_t derlen)

priv: priv as allocated by shishi_priv().

der: input array with DER encoded KRB-PRIV.

derlen: length of input array with DER encoded KRB-PRIV.

DER decode KRB-PRIV and set it PRIV exchange. If decoding fails, the KRB-PRIV in the PRIV exchange remains.

Return value: Returns SHISHI_OK.

— Function: Shishi_asn1 shishi_priv_encprivpart (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

Get ASN.1 EncPrivPart structure from PRIV exchange.

Return value: Returns the ASN.1 encprivpart in the PRIV exchange, or NULL if not yet set or an error occured.

— Function: void shishi_priv_encprivpart_set (Shishi_priv * priv, Shishi_asn1 asn1encprivpart)

priv: structure that holds information about PRIV exchange

asn1encprivpart: ENCPRIVPART to store in PRIV exchange.

Set the ENCPRIVPART in the PRIV exchange.

— Function: int shishi_priv_encprivpart_der (Shishi_priv * priv, char ** out, size_t * outlen)

priv: priv as allocated by shishi_priv().

out: output array with newly allocated DER encoding of ENCPRIVPART.

outlen: length of output array with DER encoding of ENCPRIVPART.

DER encode ENCPRIVPART structure. Typically shishi_encprivpart_build() is used to build the ENCPRIVPART structure first. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_encprivpart_der_set (Shishi_priv * priv, char * der, size_t derlen)

priv: priv as allocated by shishi_priv().

der: input array with DER encoded ENCPRIVPART.

derlen: length of input array with DER encoded ENCPRIVPART.

DER decode ENCPRIVPART and set it PRIV exchange. If decoding fails, the ENCPRIVPART in the PRIV exchange remains.

Return value: Returns SHISHI_OK.

— Function: int shishi_priv_print (Shishi * handle, FILE * fh, Shishi_asn1 priv)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

priv: PRIV to print.

Print ASCII armored DER encoding of PRIV to file.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_save (Shishi * handle, FILE * fh, Shishi_asn1 priv)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for writing.

priv: PRIV to save.

Save DER encoding of PRIV to file.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_to_file (Shishi * handle, Shishi_asn1 priv, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

priv: PRIV to save.

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

filename: input variable with filename to write to.

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

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_parse (Shishi * handle, FILE * fh, Shishi_asn1 * priv)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

priv: output variable with newly allocated PRIV.

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

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_read (Shishi * handle, FILE * fh, Shishi_asn1 * priv)

handle: shishi handle as allocated by shishi_init().

fh: file handle open for reading.

priv: output variable with newly allocated PRIV.

Read DER encoded PRIV from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_from_file (Shishi * handle, Shishi_asn1 * priv, int filetype, const char * filename)

handle: shishi handle as allocated by shishi_init().

priv: output variable with newly allocated PRIV.

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

filename: input variable with filename to read from.

Read PRIV from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_enc_part_etype (Shishi * handle, Shishi_asn1 priv, int32_t * etype)

handle: shishi handle as allocated by shishi_init().

priv: PRIV variable to get value from.

etype: output variable that holds the value.

Extract PRIV.enc-part.etype.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_set_enc_part (Shishi * handle, Shishi_asn1 priv, int32_t etype, const char * encpart, size_t encpartlen)

handle: shishi handle as allocated by shishi_init().

priv: priv as allocated by shishi_priv().

etype: input encryption type to store in PRIV.

encpart: input encrypted data to store in PRIV.

encpartlen: size of input encrypted data to store in PRIV.

Store encrypted data in PRIV. The encrypted data is usually created by calling shishi_encrypt() on some application specific data using the key from the ticket that is being used. To save time, you may want to use shishi_priv_build() instead, which encryptes the data and calls this function in one step.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_encprivpart_user_data (Shishi * handle, Shishi_asn1 encprivpart, char ** userdata, size_t * userdatalen)

handle: shishi handle as allocated by shishi_init().

encprivpart: encprivpart as allocated by shishi_priv().

userdata: output array with newly allocated user data from KRB-PRIV.

userdatalen: output size of output user data buffer.

Read user data value from KRB-PRIV. userdata is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_encprivpart_set_user_data (Shishi * handle, Shishi_asn1 encprivpart, const char * userdata, size_t userdatalen)

handle: shishi handle as allocated by shishi_init().

encprivpart: encprivpart as allocated by shishi_priv().

userdata: input user application to store in PRIV.

userdatalen: size of input user application to store in PRIV.

Set the application data in PRIV.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_build (Shishi_priv * priv, Shishi_key * key)

priv: priv as allocated by shishi_priv().

key: key for session, used to encrypt data.

Build checksum and set it in KRB-PRIV. Note that this follows RFC 1510bis and is incompatible with RFC 1510, although presumably few implementations use the RFC1510 algorithm.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_priv_process (Shishi_priv * priv, Shishi_key * key)

priv: priv as allocated by shishi_priv().

key: key to use to decrypt EncPrivPart.

Decrypt encrypted data in KRB-PRIV and set the EncPrivPart in the PRIV exchange.

Return value: Returns SHISHI_OK iff successful, SHISHI_PRIV_BAD_KEYTYPE if an incompatible key type is used, or SHISHI_CRYPTO_ERROR if the actual decryption failed.