SAFE and PRIV Functions (GNU Shishi 1.0.3)

5.5 SAFE and PRIV Functions

The “KRB-SAFE” is an ASN.1 structure used by application client and servers to exchange integrity protected data. The integrity protection is keyed, usually with a key agreed on via the AP exchange (see AP-REQ and AP-REP Functions). The following illustrates the KRB-SAFE ASN.1 structure.

   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
   }

shishi_safe

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

Description: Create a new SAFE exchange.

Return value: Returns SHISHI_OK iff successful.

shishi_safe_done

Function: void shishi_safe_done (Shishi_safe * safe)

safe: structure that holds information about SAFE exchange

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

shishi_safe_key

Function: Shishi_key * shishi_safe_key (Shishi_safe * safe)

safe: structure that holds information about SAFE exchange

Description: 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.

shishi_safe_key_set

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.

Description: Set the Key in the SAFE exchange.

shishi_safe_safe

Function: Shishi_asn1 shishi_safe_safe (Shishi_safe * safe)

safe: structure that holds information about SAFE exchange

Description: 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.

shishi_safe_safe_set

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.

Description: Set the KRB-SAFE in the SAFE exchange.

shishi_safe_safe_der

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.

Description: 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.

shishi_safe_safe_der_set

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.

Description: 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.

shishi_safe_print

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.

Description: Print ASCII armored DER encoding of SAFE to file.

Return value: Returns SHISHI_OK iff successful.

shishi_safe_save

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.

Description: Save DER encoding of SAFE to file.

Return value: Returns SHISHI_OK iff successful.

shishi_safe_to_file

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.

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

Return value: Returns SHISHI_OK iff successful.

shishi_safe_parse

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.

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

Return value: Returns SHISHI_OK iff successful.

shishi_safe_read

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.

Description: Read DER encoded SAFE from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_safe_from_file

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.

Description: Read SAFE from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_safe_cksum

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.

Description: 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.

shishi_safe_set_cksum

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.

Description: 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.

shishi_safe_user_data

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.

Description: 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.

shishi_safe_set_user_data

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.

Description: Set the application data in SAFE.

Return value: Returns SHISHI_OK iff successful.

shishi_safe_build

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.

Description: 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.

shishi_safe_verify

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.

Description: 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.

The “KRB-PRIV” is an ASN.1 structure used by application client and servers to exchange confidential data. The confidentiality is keyed, usually with a key agreed on via the AP exchange (see AP-REQ and AP-REP Functions). The following illustrates the KRB-PRIV ASN.1 structure.

   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
   }

shishi_priv

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

Description: Create a new PRIV exchange.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_done

Function: void shishi_priv_done (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

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

shishi_priv_key

Function: Shishi_key * shishi_priv_key (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

Description: 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.

shishi_priv_key_set

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.

Description: Set the Key in the PRIV exchange.

shishi_priv_priv

Function: Shishi_asn1 shishi_priv_priv (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

Description: 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.

shishi_priv_priv_set

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.

Description: Set the KRB-PRIV in the PRIV exchange.

shishi_priv_priv_der

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.

Description: 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.

shishi_priv_priv_der_set

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.

Description: 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.

shishi_priv_encprivpart

Function: Shishi_asn1 shishi_priv_encprivpart (Shishi_priv * priv)

priv: structure that holds information about PRIV exchange

Description: 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.

shishi_priv_encprivpart_set

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.

Description: Set the ENCPRIVPART in the PRIV exchange.

shishi_priv_encprivpart_der

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.

Description: DER encode ENCPRIVPART structure. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_encprivpart_der_set

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.

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

Return value: Returns SHISHI_OK.

shishi_priv_print

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.

Description: Print ASCII armored DER encoding of PRIV to file.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_save

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.

Description: Save DER encoding of PRIV to file.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_to_file

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.

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

Return value: Returns SHISHI_OK iff successful.

shishi_priv_parse

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.

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

Return value: Returns SHISHI_OK iff successful.

shishi_priv_read

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.

Description: Read DER encoded PRIV from file and populate given variable.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_from_file

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.

Description: Read PRIV from file in specified TYPE.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_enc_part_etype

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.

Description: Extract PRIV.enc-part.etype.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_set_enc_part

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.

Description: 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.

shishi_encprivpart_user_data

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.

Description: 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.

shishi_encprivpart_set_user_data

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.

Description: Set the application data in PRIV.

Return value: Returns SHISHI_OK iff successful.

shishi_priv_build

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.

Description: 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.

shishi_priv_process

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.

Description: 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.