Skip to content

Latest commit

 

History

History
591 lines (529 loc) · 36.8 KB

API.md

File metadata and controls

591 lines (529 loc) · 36.8 KB

Kerberos Python Library API References

Note that some methods of API have a large number of params, upto 6, clearly breaking the max-number-of-params-should-be-3 guideline of good programming.For slightly easier use of these, all params of all methods follow the following order :
random number ; request server ; UIDs for user : key ; encryption/decryption data ; tickets ; optional params. whichever are present.

Index

API

Constants

These are constant values used as defaults in various methods.

  • AUTH_INIT_VAL = 5 Initialization value for Auth ticket encryption
  • TGT_INIT_VAL = 5 Initialization value for Ticket Granting Ticket encryption
  • AUTH_TICKET_LIFETIME = 24 * 60 * 60 * 60 * 1000 (1 Day) lifetime of Authentication Ticket and Ticket Granting Ticket
  • TICKET_LIFETIME = 10 * 60 * 1000 (10 min) lifetime of a general server ticket
  • SERVER_INIT_RAND_MIN = 1 Minimum limit for choosing random initialization value for a server in TGS add_server()
  • SERVER_INIT_RAND_MAX = 2147483647 Maximum limit for choosing random initialization value for a server in TGS add_server() (Number chosen is limit of int in c++)

Class Server_Error

A class used to show errors specific to this library. This simply extends the default Error class in JS and does not specify any different methods of its own.

DB Classes

These are classes used to store and retrieve data that is needed in the operations.The main interface is defined by Class DB, and any custom db class must extend that and implement its methods.

Class DB

This is base class used as the interface for all DB classes in the module. This defines two methods save and get that must be implemented by any extending class.

save(name,data)

This method is used for saving the data in db.

Params :
  • name {string} : The key that the data should be associated with. Same will be used for retrieving the data
  • data {Any} : The data that is to be saved
Returns : {void}
get(name)

This method is used for retrieving the data from the DB

Params :
  • name {string} : the key that the data was saved with
Returns : {Any} The data that was saved corresponding to key.

Class Memory_DB

This is a db class that uses python Dict internally to save data. The access speed should be usually faster than Local_DB.

This is used where a lightweight db just for storing temporary data is needed, like verifying random numbers or in client for saving tickets.

This can be replaced by a class that connects with Redis DB if one wants an option which is sharable between multiple instances.

save(name,data)

This method is used for saving the data in db.

Params :
  • name {string} : The key that the data should be associated with. Same will be used for retrieving the data
  • data {Any} : The data that is to be saved
Returns : {void}
get(name)

This method is used for retrieving the data from the DB

Params :
  • name {string} : the key that the data was saved with
Returns : {Any} The data that was saved.

Class Local_DB

This class uses File System to save data in files on disk.

constructor(ticket_folder_path = None)

This by default creates a folder named 'Tickets' in the directory from which program was invoked if no parameter is given. Otherwise The given path is constructed if not present and is used for saving the data.

Params:
  • ticket_folder_path {string} : the path which should be used for saving the data files.
Returns : {Object} An instance of LocalDB.
save(name,data)

This method is used for saving the data in db. Given data is stored as stringified JSON object in a file named as the parameter name.

Params :
  • name {string} : The key that the data should be associated with. Same will be used for retrieving the data
  • data {Any} : The data that is to be saved
Returns : {void}
get(name)

This method is used for retrieving the data from the DB

Params :
  • name {string} : the key that the data was saved with
Returns : {Any} The data that was saved.

Cryptor Classes

These are classes used for encryption and decryption of data in the module. Main interface is defined by Class cryptor, and any custom Cryptographic class must extend it and implement its methods.

Class Cryptor

This is base class used as the interface for all Cryptographic classes in the module. This defines three methods encrypt, decrypt and get_random_key that must be implemented by any extending class.

get_random_key()

This method is used to get the keys required for encryption and decryption

Params : None
Returns : {String/Number} A key that can be given to encrypt and decrypt methods.
encrypt(key,value_str,**kwargs)

This method is used for encrypting the data.

Params:
  • key {string/Number} : The key obtained from getRandomKey Method.
  • enc_str {String} : The data that is to be encrypted in string format
  • **kwargs {} : init_val is the third needed keyword arg.
Returns : {String} The encrypted form of the given string.
decrypt(key,enc_str,**kwargs)

This method is used for decrypting the data.

Params:
  • key {string/Number} : The key obtained from getRandomKey Method.
  • enc_str {String} : The encrypted string that is to be decrypted
  • **kwargs {} : init_val is the third needed keyword arg.
Returns : {String} The decrypted form of the given string.

Class AES_Cryptor

This is the class that used AES 256-bit CTR mode for encryption and decryption of data.This uses PyCrypto Module's AES 256 CTR Class to perform AES encryption/decryption.This class is default for all cryptographic requirements in the module.

get_random_key()

This method is used to get the keys required for encryption and decryption.This generates a 32 bytes (256 bit) long string that can be used for AES-CTR encryption/decryption.

Params : None
Returns : {String} A key that can be given to encrypt and decrypt methods.
encrypt(key,value_str,**kwargs)

This method is used for encrypting the data using AES-CTR mode.The Keyword argument init_val is used as initialization value for the counter required for CTR.

Params:
  • key {string} : The key obtained from getRandomKey Method.
  • encStr {String} : The data that is to be encrypted in string format
  • **kwargs {Number} : init_val is required keyword arg og type Number used as initialization value for AES CTR counter.
Returns : {String} The encrypted form of the given string.
decrypt(key,enc_str,**kwargs)

This method is used for decrypting the data using AES-CTR mode.The keyword arg init_val is used as initialization value for the counter required for CTR.

Params:
  • key {string} : The key obtained from getRandomKey Method.
  • encStr {String} : The encrypted string that is to be decrypted
  • **kwargs {Number} : init_val is required keyword arg og type Number used as initialization value for AES CTR counter.
Returns : {String} The decrypted form of the given string.

Kerberos KDC Classes

These are classes that contain methods useful on Key Distribution Center.

Class Kerberos_AS

This Class contains methods useful for Authentication Service of Kerberos.

constructor(cryptor, tgs, check_rand = False, verify_rand_db = None)

Constructor for the Kerberos_AS class

Params :
  • cryptor {Cryptor} : An instance of a cryptographic class used for encryption and decryption. Must extend the Cryptor class
  • tgs : {Kerberos_TGS} : An instance of Kerberos_TGS class. This is used for generating ticket granting ticket
  • check_rand {Boolean} : Enables the verify_random Method to prevent replay attacks.The verify_rand_db is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verify_rand_db {DB} : DB used to store mapping of user to used numbers.Defaults to Memory_DB if not provided.
Returns : {Object} An instance of Kerberos_AS class.
make_auth_tickets(rand,c_uid1,c_uid2,user_hash,lifetime_ms = AUTH_TICKET_LIFETIME)

Used to generate authentication tickets after verifying user.

Note : this does not performs any authentication of the user. This is supposed to be called after the user is verified for existence.

Params :
  • rand {Number} : the random number sent by the user in the request
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • user_hash {string} : A key generated by some field that is specific to a particular user such as password etc.Must be 32 bytes long (256 bit).Used for encryption of the response.Must be exactly same as that generated on client side.
  • lifetime_ms {Number} : Lifetime of Authentication and Ticket Granting Ticket in milliseconds. defaults to AUTH_TICKET_LIFETIME if not provided.
Returns : {Tuple}

A Tuple whose 0th position is response meant for user encrypted by user_hash and 1st position is encrypted Ticket Granting Ticket for TGS in auth and tgt fields respectively.The auth object contains both UIDs,timestamp, the random number,lifetime and a key that is supposed to be used by client for encrypting the request to TGS.

Class Kerberos_TGS

This class contains method useful for Ticket Granting Service of Kerberos.

constructor(cryptor, db, check_rand = False, verify_rand_db = None

Constructor for class Kerberos_TGS

Params:
  • cryptor {Cryptor} : An instance of a cryptographic class used for encryption and decryption. Must extend the Cryptor class
  • db {DB} : Instance of a class extending DB class.This is used for saving the Server structures generated by add_server()
  • check_rand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verify_rand_db is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verify_rand_db {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of class Kerberos_TGS.
add_server(s_uid)

Method to generate a server structure fo specified sUid (name)

Params:
  • s_uid : An unique identifier for that server.This will be used as the key to save the generated structure in serverDB
Returns : {void}
get_tgt(c_uid1, c_uid2, key, lifetime_ms)

Method for generating a new Ticket Granting Ticket.

Params:
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • Key : {String} A key to encrypt the TGT with.This is usually generated by a field specific to a particular user such as password etc.Must be 32 bytes long (256 bit).Used for encryption of the response.Must be exactly same as that generated on client side.
  • lifetime_ms {Number} : Lifetime for the generated Ticket Granting Ticket in milliseconds.
decrypt_tgt(enc_tgt_str)

NOTE : This is an internal method that should not be used from outside

A method to decrypt TGT. This does not verify if the TGT is valid.

Params:
  • enc_tgt_str {string} : encrypted TGT string.
Returns : {dict} dict obtained from parsing JSON string of the TGT.
verify_tgt_and_get_key(c_uid1, c_uid2, tgt_enc_str)

NOTE : This is an internal method that should not be used from outside

Method to verify the TGT and get the secrete key used to decrypt the client's request.

Params:
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • tgt_enc_str {string} : Encrypted TGT user sent with request.
Returns : {String/Number} The secrete key inside TGT used to decrypt client's request.
Throws : {Server_Error} if the TGT is not valid.
decrypt_req(enc_req_str, tgt)

Method used to decrypt encrypted request sent to TGS.This method does not verify if the TGT is valid or not.

Params:
  • enc_req_str {String} : Encrypted request string.
  • tgt {String} : the encrypted TGT client sent with request.
Returns : {String} The decrypted request string.
verify_rand(rand,c_uid1, c_uid2)

This method is used to verify that the random number sent by user is used for the first time and prevent replay attacks.

Params:
  • rand {Number} : the random number sent by the user.
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
Returns : {void} nothing is the random number is used for the first time by the user.
Throws : {Server_Error} is the random number was already used by the user.
get_res_and_ticket(rand,req_server,c_uid1,c_uid2,tgt,lifetime_ms = TICKET_LIFETIME)

Method to generate response and Ticket for a particular server.

Params :
  • rand {Number} : the random number sent by the user.
  • req-server {string} : server for which the ticket is to be generated.This must be same as given in add_server.This fetches information of server from serverDB.
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • tgt {string} : the Ticket Granting ticket that is sent with the request.This will be verified before generating ticket and response.
  • lifetime_mS {Number} : Lifetime of generated ticket in milliseconds. defaults to TICKET_LIFETIME if not provided.
Returns : {Tuple} if successful

A Tuple that contains response meant for user encrypted by key in tgt at 0th position and encrypted Ticket for Server at 1st position.The res object contains timestamp, the random number,lifetime and a key that is supposed to be used by client for encrypting the request to TGS and initialization vale for encryption.

Throws : {Server_Error} if the tgt is not valid.

Class Kerberos_KDC

An interface class that provides an easier interface for both Authentication ans Ticket Granting Services.This provides exactly same methods provided by Kerberos_AS and Kerberos_TGS class, but can be used instead of maintaining instances of each of them, if the AS and TGS are in the same program.

constructor(cryptor = None,server_db = None,check_rand = False,verify_rand_db = None)

Constructor for Kerberos_KDC class

Params :
  • cryptor {Cryptor} : Instance of a class extending Cryptor.Defaults to AESCryptor if not provided.
  • serverDB {DB} : Instance of a class extending DB class.This is used for saving the Server structures generated by add_server()
  • check_rand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verify_rand_db is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verify_rand_db {DB} : DB used to store mapping of user to used numbers.Defaults to Memory_DB if not provided.
Returns : {Object} An instance of Kerberos_KDC class.
make_auth_tickets(rand,c_uid1,c_uid2,user_hash,lifetime_ms = AUTH_TICKET_LIFETIME)

Method to generate initial authentication response and Ticket Granting Ticket.

  • rand {Number} : the random number sent by the user in the request
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • user_hash {string} : A key generated by some field that is specific to a particular user such as password etc.Must be 32 bytes long (256 bit).Used for encryption of the response.Must be exactly same as that generated on client side.
  • lifetime_ms {Number} : Lifetime of Authentication and Ticket Granting Ticket in milliseconds. defaults to AUTH_TICKET_LIFETIME if not provided.
Returns : {Tuple}

A Tuple whose 0th position is response meant for user encrypted by user_hash and 1st position is encrypted Ticket Granting Ticket for TGS in auth and tgt fields respectively.The auth object contains both UIDs,timestamp, the random number,lifetime and a key that is supposed to be used by client for encrypting the request to TGS.

add_server(s_uid)

Method to generate a server structure fo specified sUid (name)

Params:
  • s_uid : An unique identifier for that server.This will be used as the key to save the generated structure in serverDB
Returns : {void}
get_res_and_ticket(rand,req_server,c_uid1,c_uid2,tgt,lifetime_ms = TICKET_LIFETIME)

Method to generate response and Ticket for a particular server.

Params :
  • rand {Number} : the random number sent by the user.
  • req_server {string} : server for which the ticket is to be generated.This must be same as given in add_server.This fetches information of server from serverDB.
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • tgt {string} : the Ticket Granting ticket that is sent with the request.This will be verified before generating ticket and response.
  • lifetime_ms {Number} : Lifetime of generated ticket in milliseconds. defaults to TICKET_LIFETIME if not provided.
Returns : {Tuple} if successful

A Tuple that contains response meant for user encrypted by key in tgt at 0th position and encrypted Ticket for Server at 1st position.The res object contains timestamp, the random number,lifetime and a key that is supposed to be used by client for encrypting the request to TGS and initialization vale for encryption.

Throws : {Server_Error} if the tgt is not valid.
decrypt_req(enc_req_str, tgt)

Method for decrypting the request sent to KDC

Params :
  • enc_req_str {string} : Encrypted request string sent by client
  • tgt {string} : the Ticket Granting ticket that is sent with the request.This will be verified before generating ticket and response.

Returns : {String} decrypted request string.

verify_rand(rand,c_uid1, c_uid2)

This method is used to verify that the random number sent by user is used for the first time and prevent replay attacks.

Params:
  • rand {Number} : the random number sent by the user.
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
Returns : {void} nothing is the random number is used for the first time by the user.
Throws : {Server_Error} is the random number was already used by the user.

Kerberos Server

Class Server

NOTE : This does not actually creates any kind of server, just contains methods that are useful on the server.

This defines a class that contain methods which are useful on a sever that is to be protected by Kerberos authentication methods.

Static make_server_from_db(name,cryptor = None,db = None,check_rand = False,verify_rand_db = None)

This is the static method that can be used to construct an instance of the Server class from the db, where the ticket generated by TGS is stored.

Params:
  • name {string} : name of the server that is to be made.This is used as the key to find the server structure in DB.
  • cryptor {Cryptor} : Instance of a class extending Cryptor.Defaults to AESCryptor if not provided.
  • db {DB} : Instance of a class extending DB class.This must be able to retrieve the server structure generated by TGS.Defaults to LocalDB is not provided.
  • check_rand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verify_rand_db is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verify_rand_db {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of Server Class.
constructor(server_dict,cryptor=None,check_rand=False,verify_rand_db=None)

Constructor of the Server class

Params:
  • Server_dict {Dict} : A dict containing key,init_val and uid(name) of the server.Should be the structure generated by TGS.Throws TypeError if any of three is missing.
  • cryptor {Cryptor} : Instance of a class extending Cryptor.Defaults to AESCryptor if not provided.
  • check_rand {Boolean} : Enables the verifyRand Method to prevent replay attacks.The verify_rand_db is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verify_rand_db {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of Server Class.
decrypt_ticket(ticket_enc_str)

NOTE : This is an internal method that should not be used from outside

A method to decrypt Ticket. This does not verify if the ticket is valid.

Params :
  • ticket_enc_str {String} : encrypted ticket string
Returns : {Dict} this returns the decrypted JSON object of ticket.
verify_ticket_and_get_key(c_uid1,c_uid2,ticket_enc_str)

Method used to verify the ticket received and get the secrete key in the ticket

Params:
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • ticket_enc_str {String} : The encrypted ticket that is sent with the request.
Returns : {String/Number} The secrete key inside the ticket that is used to decrypt the request of user.
decrypt_req(enc_req_str,ticket)

Method used to decrypt the request of user.

NOTE : this does not verify if the user is valid holder of ticket, or the ticket is valid or not. This just decrypts the request.

THe reason behind keeping this method is that it is not necessary to send just an encrypted object as a request. The request itself can be another encrypted string or so,which is then again encrypted with key in ticket.Server can use this to decrypt it and obtained the string inside, which can be further decrypted if required.

Params :
  • enc_req_str {String} : encrypted request string
  • ticket {String} : the encrypted ticket that was given by TGS.
Returns : {String} this returns the decrypted request.
encrypt_res(c_uid1,c_uid2,response,ticket)

This method can be used to encrypt the response that is to be sent back.This verifies the ticket first and then encrypts the stringified response.

Params:
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • response {Any} : This is stringified using the json module and then ecrypted with the secrete key in ticket.
  • ticket {String} : the encrypted ticket that was given by TGS.
Return : {String} Encrypted string form of the response.
verify_rand(rand,c_uid1,c_uid2)

This method is used to verify that the random number sent by user is used for the first time and prevent replay attacks.

Params:
  • rand {Number} : the random number sent by the user.
  • c_uid1 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
  • c_uid2 {string/Number} : An identifier unique to the user.This is verified with the uid inside the ticket to check if user is the valid holder. Eg: username,ip address etc.
Returns : {void} nothing is the random number is used for the first time by the user.
Throws : {Server_Error} is the random number was already used by the user.

Kerberos Client

Class Client

NOTE : This does not actually creates any kind of client, just contains methods that are useful on the client.

This defines a class that contain methods which are useful on a client that accesses the servers protected by kerberos methods.

constructor(cryptor = None, keymap_db = None)

Constructor for the class

Params:
  • cryptor {Cryptor} : Instance of a class extending Cryptor.Defaults to AESCryptor if not provided.
  • keymap_db {DB} : Instance of a class extending DB class.Used to save and retrieve tickets in save_ticket() and get_ticket() methods. Defaults to Memory_DB if not given
Returns : {Object} an instance of Client class.
encrypt_req(key,req,init_val = TGT_INIT_VAL)

Method for encrypting the request that is to be sent to server.

Params :
  • key {string} : key that is to be used for encryption.This can be the user key that is generated from password or so, or the key that is returned from the TGS in its response.
  • req {Any} : request that is to be encrypted.It it first stringified using JSON module and then that string is encrypted.
  • init_val {Number} : initialization value for the AES CTR mode Counter.This defaults to TGT_INIT_VAL from constants if not specified. This should the one received along with the key in TGS response.
Returns : {String} encrypted string of the req.
decrypt_res(key,res_enc_str,init_val = TGT_INIT_VAL)

Method used for decrypting the responses received from servers.

Params:
  • key {string} : key that is to be used for encryption.This can be the user key that is generated from password or so, or the key that is returned from the TGS in its response.
  • res_enc_str {string} : encrypted response string received from server in response.
  • init_val {Number} : initialization value for the AES CTR mode Counter.This defaults to TGT_INIT_VAL from constants if not specified. This should the one received along with the key in TGS response.
Returns : {string} decrypted JSON parsed format of the response. if the response is simple string, it wil return string and so on as per the json module loads method.
save_ticket(name, ticket)

Helper method to save the ticket in the keymapDB given in constructor.Can be used to keep all tickets in one place.

Params:
  • name {string} : key to save the ticket with.should be used when retrieving the ticket.
  • Ticket {Any} : ticket to be saved. This can be the encrypted string received from TGS, or the decrypted response object received from TGS.
Returns : {void}
get_ticket(name)

Helper method to retrieve tickets saved with save_ticket() method.

Params:
  • name {string} : the key with which the ticket was saved.
Returns : {Any} the data that was given to store corresponding to the key.