In very simple words; to prevent ASP from transmitting AspSecretKey (AspPassword) openly on internet, there is need to establish a same encryption key at ASP & GSP end. ASP will then use the key (AspEK) to encrypt AspSecretKey and GSP will use the same key to decrypt AspSecretKey before authenticating ASP. Thus GetKey API will establish AspEK encryption key, identified by AspSessionID, periodically. Encryption used is AES/ECB/PKCS7.
Steps to be followed by ASP Application to establish and maintain ASP - GSP Session:
1. Call GetKey API to establish ASP - GSP Authentication
2. Call GST APIs
(Check validity of ASP - GSP session before every call or alternatively have timer to refresh ASP - GSP session before it expires.)
3. Use GetKey API to Refresh ASP - GSP session when it is Expired.
GetKey API for GSP / ASP Authentication assumes that ASP has registered with GSP and completed below steps:
1. Enrolled with GSP to obtain credentials AspID (ASPUserName or ASPUserID) and AspPassword (AspSecreatKey).
2. Self Generated DSC; PrivateKey and PublicKey pair for signing GetKey API request and registered PublicKey with GSP.
Steps for ASP Software Integrators:
Note: TaxProGST Desktop Application and TaxProGST.API library has inbuilt functionality for GetKey API and ASP - GSP Session is automatically checked for Expiery (and refreshed automatically) before call to any GST API. Details of implementation is given at the end of this page.
HTTP Method: POST
Headers
GetKey API Call should have below Headers
Property
Description
Data Type
aspid
AspUserId provided by GSP.
String
txn
Unique number which will be sent back in response as it is for ASP to map it back to original request.
String
Body
GetKey API request Body is of Type ReqGSPSession
Property
Description
Data Type
timestamp
.NET DateTime Format
"ddMMyyyyHHmmssFFFFFF"
String
signed_content
RSA SHA256 HASH of Concatenated string <“aspid” + ”timestamp”> should be signed using ASP PrivateKey (.pfx file as discussed at top of this page). Signing Algorithm: RSA SHA256
GspAPI.RefreshGSPSessionAsync method in lib TaxProGST.API does this transperatently.
String
Response
GetKey API response is of type RespGSPSession
Property
Description
Data Type
enc_key
The enc_key in GetKey response will be encrypted by GSP using ASPPassword (Password issued to ASP by GSP at the time of ASP registration). Decrypt enc_key and store in ApiSetting.AspKey.
Encrypt ASPPassword using ApiSetting.AspKey in subsequent GSTN API Calls. The Encrypted ASPPassword APISession header.
Algorithm: AES/ECB/PKCS7
APISession.StartApiTxn method in lib TaxProGST.API does this transperatently.
String
session_id
Session ID. This will be passed in the subsequent calls made by ASP. GSP System will decrypt aspid in subsequent calls to GST API, using enc_key for the session-id in header of subsequent calls.
String
validity_min
Validity of ASP- GSP Session in minutes. Session should be renewed after this period by call to GetKey API. This will provide new SessionID and AspEK in session_id and enc_key response variable respectively.
Integer
txn
Unique number which will be sent back in response as it is for ASP to map it back to original request.
String
message
Error Message if any.
String
status_cd
status_cd:"0" ( "0" is for failure)
status_cd:"1" ( "1" is for success )
String
GetKey API Call Method (applies only if you are using TaxProGST.API.GspAPI Class)
This method is used to Get & Refresh GSP session asynchronously.
This will also establish GSP Session Encryption Key: ApiSetting.AspEK used to encrypt GSP Security Key stored in: ApiSetting.AspPassword
This method is automatically called from APISession at the begining of StartAPITxn method, in case GSPSession is found to be expired and explicit call is not required.
Events
RefreshSessionCompleted
updates instance of APISession on which StartAPITxn method is invoked
Use this event to store updated AspSessionID, AspKey, AspSessionExp in database.
