Skip to content

Latest commit

 

History

History
590 lines (529 loc) · 36.5 KB

API.md

File metadata and controls

590 lines (529 loc) · 36.5 KB

Kerberos-JS 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 addServer()
  • SERVER_INIT_RAND_MAX = 2147483647 Maximum limit for choosing random initialization value for a server in TGS addServer() (Number chosen is limit of int in c++)

Class ServerError

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.

Class MemoryDB

This is a db class that uses JS Map internally to save data. The access speed should be usually faster than LocalDB.

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 corresponding to key.

Class LocalDB

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

constructor(ticketFolderPath = undefined)

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:
  • ticketFolderPath {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 {Object} : 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 : {Object} 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 getRandomKey that must be implemented by any extending class.

getRandomKey()

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,valueStr,...args)

This method is used for encrypting the data.

Params:
  • key {string/Number} : The key obtained from getRandomKey Method.
  • encStr {String} : The data that is to be encrypted in string format
  • ...args {} : This is used to pass a third value in AESCryptor as init-val
Returns : {String} The encrypted form of the given string.
decrypt(key,valueStr,...args)

This method is used for decrypting the data.

Params:
  • key {string/Number} : The key obtained from getRandomKey Method.
  • encStr {String} : The encrypted string that is to be decrypted
  • ...args {} : This is used to pass a third value in AESCryptor as init-val
Returns : {String} The decrypted form of the given string.

Class AESCryptor

This is the class that used AES 256-bit CTR mode for encryption and decryption of data.This uses the (external) library aes-js to perform AES encryption/decryption.This class is default for all cryptographic requirements in the module.

getRandomKey()

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,valueStr,...args)

This method is used for encrypting the data using AES-CTR mode.The Third argument (args[0]) 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
  • ...args {Number} : First argument in this must be a number that is used as initialization value for the counter.
Returns : {String} The encrypted form of the given string.
decrypt(key,valueStr,...args)

This method is used for decrypting the data using AES-CTR mode.The Third argument (args[0]) 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
  • ...args {Number} : First argument in this must be a number that is used as initialization value for the 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 KerberosAS

This Class contains methods useful for Authentication Service of Kerberos.

constructor(cryptor, tgs, checkRand = false, verifyRandDB = undefined)

Constructor for the KerberosAS class

Params :
  • cryptor {Cryptor} : An instance of a cryptographic class used for encryption and decryption. Must extend the Cryptor class
  • tgs : {KerberosTGS} : An instance of KerberosTGS class. This is used for generating ticket granting ticket
  • checkRand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verifyRandDB is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verifyRandDB {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of KerberosAS class.
makeAuthTickets(rand,cUid1,cUid2,userHash,lifetimeMs = 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
  • cUid1 {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.
  • cUid2 {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.
  • userHash {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.
  • lifetimeMS {Number} : Lifetime of Authentication and Ticket Granting Ticket in milliseconds. defaults to AUTH_TICKET_LIFETIME if not provided.
Returns : {Object}

An object that contains response meant for user encrypted by userHash and 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 KerberosTGS

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

constructor(cryptor, db, checkRand = false, verifyRandDB = undefined)

Constructor for class KerberosTGS

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 addServer()
  • checkRand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verifyRandDB is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verifyRandDB {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of class KerberosTGS.
addServer(sUid)

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

Params:
  • sUid : An unique identifier for that server.This will be used as the key to save the generated structure in serverDB
Returns : {void}
getTGT(cUid1, cUid2, key, lifetimeMs)

Method for generating a new Ticket Granting Ticket.

Params:
  • cUid1 {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.
  • cUid2 {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.
  • lifetimeMs {Number} : Lifetime for the generated Ticket Granting Ticket in milliseconds.
decryptTGT(encTGT)

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:
  • encTGT {string} : encrypted TGT string.
Returns : {Object} a JSON object of the TGT.
verifyTGTAndGetKey(cUid1, cUid2, tgtEncStr)

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:
  • cUid1 {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.
  • cUid2 {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.
  • tgtEncStr {string} : Encrypted TGT user sent with request.
Returns : {String/Number} The secrete key inside TGT used to decrypt client's request.
Throws : {ServerError} if the TGT is not valid.
decryptReq(encReqStr, tgt)

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

Params:
  • encReqStr {String} : Encrypted request string.
  • tgt {String} : the encrypted TGT client sent with request.
Returns : {String} The decrypted request string.
verifyRand(rand,cUid1, cUid2)

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.
  • cUid1 {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.
  • cUid2 {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 : {ServerError} is the random number was already used by the user.
getResAndTicket(rand,reqServer,cUid1,cUid2,tgt,lifetimeMs = TICKET_LIFETIME)

Method to generate response and Ticket for a particular server.

Params :
  • rand {Number} : the random number sent by the user.
  • reqServer {string} : server for which the ticket is to be generated.This must be same as given in addServer.This fetches information of server from serverDB.
  • cUid1 {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.
  • cUid2 {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.
  • lifetimeMS {Number} : Lifetime of generated ticket in milliseconds. defaults to TICKET_LIFETIME if not provided.
Returns : {Object} if successful

An object that contains response meant for user encrypted by key in tgt and encrypted Ticket for Server in res and ticket fields respectively.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 : {ServerError} if the tgt is not valid.

Class KerberosKDC

An interface class that provides an easier interface for both Authentication ans Ticket Granting Services.This provides exactly same methods provided by KerberosAS and KerberosTGS 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 = undefined,serverDB = undefined,checkRand = false,verifyRandDB = undefined)

Constructor for KerberosKDC 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 addServer()
  • checkRand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verifyRandDB is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verifyRandDB {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of Kerberos_KDC class.
makeAuthTickets(rand,cUid1,cUid2,userHash,lifetimeMs = 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
  • cUid1 {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.
  • cUid2 {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.
  • userHash {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.
  • lifetimeMS {Number} : Lifetime of Authentication and Ticket Granting Ticket in milliseconds. defaults to AUTH_TICKET_LIFETIME if not provided.
Returns : {Object}

An object that contains response meant for user encrypted by userHash and 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.

addServer(sUid)

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

Params:
  • sUid : An unique identifier for that server.This will be used as the key to save the generated structure in serverDB
Returns : {void}
getResAndTicket(rand,reqServer,cUid1,cUid2,tgt,lifetimeMs = TICKET_LIFETIME)

Method to generate response and Ticket for a particular server.

Params :
  • rand {Number} : the random number sent by the user.
  • reqServer {string} : server for which the ticket is to be generated.This must be same as given in addServer.This fetches information of server from serverDB.
  • cUid1 {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.
  • cUid2 {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.
  • lifetimeMS {Number} : Lifetime of generated ticket in milliseconds. defaults to TICKET_LIFETIME if not provided.
Returns : {Object} if successful

An object that contains response meant for user encrypted by key in tgt and encrypted Ticket for Server in res and ticket fields respectively.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 : {ServerError} if the tgt is not valid.
decryptReq(encReqStr, tgt)

Method for decrypting the request sent to KDC

Params :
  • encReqStr {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.

verifyRand(rand,cUid1, cUid2)

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.
  • cUid1 {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.
  • cUid2 {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 : {ServerError} 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 MakeServerFromDB(name,cryptor = null,db = null,checkRand = false,verifyRandDB = undefined)

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.
  • checkRand {Boolean} : Enables the verifyRandom Method to prevent replay attacks.The verifyRandDB is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verifyRandDB {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(serverObj,cryptor=undefined,checkRand=false,verifyRandDB=undefined)

Constructor of the Server class

Params:
  • ServerObj {Object} : An object 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.
  • checkRand {Boolean} : Enables the verifyRand Method to prevent replay attacks.The verifyRandDB is used to store user-to-used-numbers connections.Defaults to false if not provided.
  • verifyRandDB {DB} : DB used to store mapping of user to used numbers.Defaults to MemoryDB if not provided.
Returns : {Object} An instance of Server Class.
decryptTicket(encTicket)

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 :
  • encTicket {String} : encrypted ticket string
Returns : {Object} this returns the decrypted JSON object of ticket.
verifyTicketAndGetKey(cUid1,cUid2,ticketEncStr)

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

Params:
  • cUid1 {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.
  • cUid2 {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.
  • ticketEncStr {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.
decryptReq(reqEncStr,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 :
  • reqEncStr {String} : encrypted request string
  • ticket {String} : the encrypted ticket that was given by TGS.
Returns : {String} this returns the decrypted request.
encryptRes(cUid1,cUid2,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:
  • cUid1 {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.
  • cUid2 {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.
verifyRand(rand,cUid1,cUid2)

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.
  • cUid1 {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.
  • cUid2 {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 : {ServerError} 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 = undefined, keymapDB = undefined)

Constructor for the class

Params:
  • cryptor {Cryptor} : Instance of a class extending Cryptor.Defaults to AESCryptor if not provided.
  • keymapDB {DB} : Instance of a class extending DB class.Used to save and retrieve tickets in saveTicket() and getTicket() methods. Defaults to MemoryDB if not given
Returns : {Object} an instance of Client class.
encryptReq(key,req, initVal = 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.
  • initVal {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.
decryptRes(key,resEncStr, initVal = 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.
  • resEncStr {string} : encrypted response string received from server in response.
  • initVal {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 parse method.
saveTicket(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}
getTicket(name)

Helper method to retrieve tickets saved with saveTicket() 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.