Sentinel SuperPro加密鎖編程開發指南
本文將簡要介紹Sentinel SuperPro軟件加密鎖的編程開發知識，可供需要進行軟件加密鎖開發的軟件開發商快速學習掌握這種類型的加密鎖的編程開發，快速保護自己的軟件不受侵害，防止加密狗被破解。本文資源來源於Sentinel SuperPro加密鎖開發套件中的開發手冊，僅供大家學習，文字版權屬於Sentinel SuperPro所有。
一、加密鎖簡介
Sentinel SuperPro加密鎖是一個硬件/軟件保護系統，功能主要是保護軟件，即防止未經允許非法使用開發商的軟件。如未把正確的加密鎖與計算機連接，則被保護的應用程序將無法實現全部功能。因此，只有合法用戶才能使用開發商的產品。
使用SuperPro軟件保護鎖完成軟件保護，就是將軟件開發商的未被保護的應用程序與SuperPro軟件保護鎖加密算法相綁定過程。最終實現綁定後的應用程序沒有軟件保護鎖不能單獨運行，只有插入軟件開發商自己定義算法的軟件保護鎖，應用程序才能正常運行。當軟件開發商的軟件銷售給最終用戶後，軟件即使被非法複製，而沒有軟件開發商提供的軟件保護鎖軟件不能被使用。這樣一來，從技術上防止盜版起到軟件保護的作用。
應用程序和Sentinel Superpro軟件保護鎖加密算法的綁定，是通過API函數調用來校驗軟件保護鎖是否存在來實現的。API函數驗證分由三部分組成：
1）詢問部分：開發商的應用程序通過API調用向軟件保護鎖的驅動程序發出的“查詢串”， 驅動程序自動將“查詢串”傳給並口或USB口上的SuperPro軟件保護鎖上的算法單元。
2）運算部分：加密鎖通過內部的算法芯片計算“查詢串”，並將運算結果“響應串”返回給驅動程序。
3）程序鑑定、行動部分：驅動程序將“響應串”返回給應用程序中的API函數調用。應用程序對返回值—“響應串”進行比較判斷，判斷與預知運算結果是否相等，根據判斷的結果進行相應的行動。
如果返回值—“響應串”與預知運算結果相等，則說明保護應用程序的軟件保護鎖存在，使用程序的用戶爲合法用戶。不相等則說明保護應用程序的軟件保護鎖不存在，用戶爲非法用戶，應用程序將終止被使用。
SentinelSuperPro 系統一個主要優點是可對一個加密鎖編程，以提供多種驅動程序類型，包括固定響應和可變響應。這樣，所創建的軟件鎖具有非常多的類型。
例如，可用單元存儲固定數據（如序列號、用戶名稱）或存儲控制功能詢問的代碼。然後，可簡單地讀取這些數據，以檢驗是否附加了加密鎖。也可使用存儲的數據控制程序流程或應用程序的函數。數據字組可以定義爲只讀的（鎖定）或可讀/寫的。
每個加密鎖的前 8 個單元爲系統信息保留。除了某些限制外，可以任意方式使用其它 56 個單元。
二、加密鎖編程接口
下面以VB語言爲例，說明使用SuperPro軟件保護鎖時，有關API調用的數據結構、函數以及必要的步驟。
1.基本信息
DEVELOPER ID：用戶ID爲加密編號，爲固定數字，沒有它就不能使用加密鎖。
地址：SuperPro 的地址從00H到3FH，以十六進制數表示。
訪問權限：SuperPro的每一個存儲單元可以單獨設置成不同的操作權限。
1- 可讀/寫數據；2- 只讀數據；3- 計數器；4- 算法
2.數據結構
APIPACKET
Type APIPACKET
data(4096) As Byte
End Type
除了sproInitialize, 所有的函數都使用APIPACKET數據結構，該結構在調用sproFindFirstUnit 時被初始化，在調用sproFindNextUnit的時候會根據下一個加密鎖的信息進行必要修改。當函數正常返回時，APIPACKET中存放必要的返回信息。
SuperPro驅動程序使用該結構中的信息與加密鎖進行通訊。開發者不要自行修改其中的數據。SuperPro驅動程序不負責分配APIPACKET數據單元，開發者在程序中必須分配APIPACKET結構變量，並且把指針傳遞給不同的函數。
3.API函數
● RNBOsproFindFirstUnit()
RNBOsproFindFirstUnit() 函數定位具有指定的開發者ID的SentinelSuperPro 加密鎖。在調用 RNBOsproInitialize() 之後，使用其他調用之前，必須首先調用該函數。如果找到了加密鎖，訊息包或UNITINFO 記錄中將包含有效的數據，如果未找到加密鎖，訊息包或 UNITINFO 記錄將被標記爲無效的。
RNBOsproFindFirstUnit() 將搜索所有連接在並行端口上的所有級聯單位。如果存在多個加密鎖具有相同的開發者 ID，RNBOsproFindFirstUnit() 存取找到的第一個加密鎖。在需要的時候，可以使用 RNBOsproFindNextUnit()查找具有相同開發者 ID 的其他加密鎖。
參數
RNBOsproFindFirstUnit() 調用需要以下參數：
■由 Rainbow Technologies 或者其他發佈者爲您指定的開發者 ID。
■指向訊息包記錄或者 UNITINFO 結構的指針。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproFindNextUnit()
RNBOsproFindNextUnit() 函數搜索具有給定開發者 ID 的下一個加密鎖。
開發者ID是由第一次調用的 RNBOsproFindFirstUnit() 指定的。（要找到具有不同的開發者ID的加密鎖，需要再 次調用RNBOsproFindFirstUnit()。）
如果 RNBOsproFindNextUnit() 成功了，訊息包或者 UNITINFO 記錄將包含下一個加密鎖的數據。如果未成功，訊息包或者 UNITINFO 記錄將被標記爲無效的。要重新對訊息包或 UNITINFO 記錄初始化，需要再次使用 RNBOsproFindFirstUnit() 以及 RNBOsproFindNextUnit()。
RNBOsproFindNextUnit() 將搜索連接到任何並行端口上的所有級聯單位。如果同時連接了幾個加密鎖，應用程序可 以多次調用RNBOsproFindNextUnit()。
參數
RNBOsproFindNextUnit()函數需要一個參數：指向訊息包記錄或者UNITINFO 結構的指針。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproFormatPacket()
RNBOsproFormatPacket() 函數檢驗訊息包記錄大小的有效性，並且初始化它的缺省值。該調用必須在調用其他 API 函數之前進行，否則將返回錯誤碼 2 (INVALID PACKET)。
參數
RNBOsproFormatPacket() 需要下 列參數：
■指向訊息包記錄 (RBP_RNBOspro_APIPACKET) 的指針。
■PacketLen 的值是一個整數， 包含了訊息包的長度 （1028 個字節） 。
返回值
所有的函數都返回一個無符號的 16 位的值。值爲 0 表示操作成功了，其他的值都表明發生了錯誤。如果發生了錯誤，函數將返回附錄中列出的狀態碼之一。如果返回的狀態碼爲非 0 的值，那麼函數返回的其他數據將是無意義的。
● RNBOsproGetVersion()
RNBOsproGetVersion() 函數返回與 SentinelSuperPro 驅動程序有關的信息，應用程序可以使用該信息。
參數
RNBOsproGetVersion() 函數需要下列參數：
■指向訊息包記錄或者 UNITINFO 結構的指針。
■指向用來返回主版本號的位置的指針。
■指向用來返回次版本號的位置的指針。
■指向用來返回修訂版本號的位置的指針。
■指向用來返回驅動程序類型標識符的位置的指針。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproInitialize()
RNBOsproInitialize() 函數使驅動程序執行所需的初始化操作。在調用任何其他的 API 之前，應用程序必須首先調用 RNBOsproInitialize() 一次。
參數
RNBOsproInitialize() 函數不需要任何參數。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproOverwrite()
RNBOsproOverwrite() 函數使應用程序能夠改變字組的值與存取碼，但是被限制的單元（0 到 7）除外。在使用該函數的時候，需要同時提供寫密碼和重寫密碼。
注意重寫密碼的能力是相當強大的。它的使用應該僅限於工作室中，而不應該在正式發佈的應用程序中出現。如果您的保護方案不需要在應用程序中使用重寫密碼，Rainbow 可以通過編程使您的每一個加密鎖具有一個“隨機重寫密碼”。每個加密鎖中將包含不同的重寫加密鎖密碼，並且不能在最終用戶實際使用中進行修改。
參數
RNBOsproOverwrite() 函數需要下列參數：
■指向訊息包記錄或者 UNITINFO 結構的指針。
■您的寫密碼。
■您的兩個字組長的重寫密碼。
■需要寫入的定址。
■賦予該字組的存取碼：0 （可讀/寫數據）、1 （只讀數據）、2 （計數器）、3 （算法/隱藏的）。
■希望寫到該定址上的值。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproQuery()
利用RNBOsproQuery() 函數，應用程序可以發送詢問字串到SentinelSuperPro 加密鎖。應用程序還可以指定用來對字串進行轉換的算法描述符。
加密鎖將使用自己的算法和指定的算法描述符中儲存的信息對輸入字串進行轉換。然後加密鎖將轉換之後的字串返回到應用程序。應用程序將返回的字串與希望得到的字串相比較，即可知道所需要的加密鎖是否仍連接在並行端口上。
在軟件開發階段，高級編程序的鑑定 API：詢問選項可以用來確認加密鎖的算法描述符對給定的輸入字串進行轉換的結果。
參數
RNBOsproQuery() 函數需要下列參數：
■指向訊息包記錄或者 UNITINFO 結構的指針。
■詢問字串中的字節個數（最大值 56）。
■指向包含詢問字串的緩衝區的指針（偏移量在前，段定址在後）。
■指向用來供驅動程序返回結果字串的緩衝區的指針。該緩衝區需要足夠大，以便容納整個的結果字串。另外一種可取的辦法是，將某個位置的指針傳遞給驅動程序，但驅動程序僅返回結果字串的最後 32 個位。
■詢問中使用的算法描述符的首（較低的）字組的定址。該定址必須是偶數。一般來說，較長的詢問字串能夠提供更好的保護。推薦的詢問字串長度至少爲 8 個十六進制字符（32 個位）。驅動程序允許的最長的詢問字串的長度爲 56 個字節。如果發送的字串長度小於 32 位，驅動程序將在添加一種已知的模式之後再將其發送出去。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproRead()
應用程序可以使用 RNBOsproRead() 函數讀取非隱藏的記憶體字組的值。非隱藏的字組的存取碼爲 0 （可讀/寫數據）、1 （只讀數據）或 2（計數器）。算法/隱藏的字組的存取碼爲 3，它是不能被讀取的。如果試圖讀取一個隱藏的字組，驅動程序將返回拒絕存取。通過檢查該狀態即可判斷字組是不是算法字組。RNBOsproRead() 返回字組的值，而不是其存取碼。要獲得字組的存取碼，可以使用 RNBOsproExtendedRead()。
參數
RNBOsproRead() 函數需要下列參數：
■指向訊息包記錄或者 UNITINFO 結構的指針。
■被讀取的定址。
■一個指針，在調用成功的時候，該指針指向驅動程序返回的指定字組的內容。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproDecrement()
RNBOsproDecrement() 函數將可讀/寫的數據字組（存取碼爲 0）或者計數器字組（存取碼爲 2）的值減量 1。在使用該函數時需要提供寫密碼。如果試圖對被鎖定或者隱藏的字組減量，驅動程序將返回拒絕存取。如果字組中的值已歸零，驅動程序將返回已歸零。對這兩種狀態碼應用程序都需要進行檢查。RNBOsproDecrement() 可以用來限制演示程序能夠被執行的次數。首先將一個計數器與一個算法描述符聯繫起來，然後在每次程序執行的時候將計數器減一。當計數器爲 0 時，算法將自動被去激活。以後的詢問將返回無效的響應。
參數
RNBOsproDecrement() 函數需要下列參數：
■指向訊息包記錄或者 UNITINFO 結構的指針。
■您的寫密碼。
■需要被減量的數據字組或計數器的定址。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
● RNBOsproExtendedRead()
RNBOsproExtendedRead() 函數讀取非隱藏的記憶體字組的值和存取碼。未隱藏的字組的存取碼爲 0 （可讀/寫數據）、（只讀數據）或 2 （計數器）。算法/隱藏字組的存取碼爲 3，它們是不可讀的。如果試圖讀取一個隱藏的字組，驅動程序返回拒絕存取。通過檢查該狀態，能夠確認一個字組是否是算法字組。
參數
RNBOsproExtendedRead() 函數需要下列參數：
■指向訊息包記錄或者 UNITINFO 結構的指針。
■要讀取的定址。
■指向指定字組的內容的指針，在調用成功時由驅動程序返回內容。
■指向指定字組的存取碼的指針，在調用成功時由驅動程序返回存取碼。存取碼可能是 0 （可讀/寫數據）、1 （只讀數據）或 2 （計數器）。調用不可能返回存取碼 3 （算法/隱藏的）。
返回值
如果執行成功，函數返回成功。如果發生了錯誤，函數將返回附錄中所列的狀態碼。
4.必要的初始化步驟
在調用API函數進行加密工作以前，必須在應用程序中完成以下有關加密的初始化工作。
分配APIPACKET數據結構
調用RNBOsproFormatPacket初始化結構（僅Win32程序使用）
調用RNBOsproInitialize函數
調用RNBOsproFindFirstUnit函數找到軟件保護鎖
以上工作完成以後，開發者可以根據各自的需要在程序的任何部分進行讀寫、查詢等工作。所有函數沒有必然的前後順序。
當利用查詢響應對，調用RNBOSproQuery進行查詢時，需要對查詢響應對進行適當轉換。
三、備註
如果想了解更多有關軟件保護鎖的信息，請參閱加密鎖手冊SentinelSuperPro Developer Guide。
附錄.API狀態碼返回數值
0 success - 調用順利地完成。
1 invalid function code - 指定了一個無效功能碼。對於有效的 API 功能碼，請查看您所使用的語言的包含檔案（例如：SUPERPRO.H ）。如果使用 Rainbow 提供的接口程序與驅動程序通訊，通常不應該產生該錯誤。
2 invalid packet - 在命令訊息包中檢測到覈對和錯誤，該錯誤表明內部不一致。因是訊息包記錄或 UNITINFO 結構還沒有被初始化，或者可能已被篡改了。如果使用Rainbow 提供的接口程序與驅動程序通訊，通常不應該產生該錯誤。
3 unit not found - 或者 RNBOsproFindFirstUnit()，或者 RNBOsproFindNextUnit() 無法找到指定的 SentinelSuperPro 加密鎖。請確信發送了正確的開發者 ID。如果該加密鎖消失（也就是說，已?被取消），該錯誤是其它函數返回的。
4 access denied - 企圖對字組執行非法操作。例如，您可能試圖從算法/隱藏字組中讀取、向鎖定的字組中寫入，或者將不是計數器字組或者數據字組的字組減量。
5 invalid memory address - 指定了無效的 SentinelSuperPro 記憶體定址。有效的定址是十進制的 0-63（十六進制的 0-3F）。對於許多操作，單元 0-7 是無效的。必須使用第一個（偶數）定址引用算法描述符。
6 invalid access code - 指定了一個無效的存取碼。存取碼必須是 0（讀/寫數據）、1（只讀數據）、2 （計數器）或者 3（算法/隱藏）。
7 port is busy - 因爲端口被佔用，所以請求的操作不能完成。導致的原因可能是有大量的打印任務，或者該端口上的某個單位正在執行寫操作並阻塞了該端口。請再試一次該函數。
8 write not ready - 由於暫時缺少足夠的能力，不能執行寫入或者減量操作。請再試一次該操作。
9 no port installed - 在工作站上沒有發現並行端口。
10 already zero - 試圖將已?包含 0 的計數器字組或者數據字組減量。如果使用該計數器控制演示程序執行，當對應的算法描述符被起動密碼重新激活之後，可能會出現這種情況。
12 driver not installed - 沒有安裝或者沒有檢測到系統設備驅動程序。不可能與該單位通訊。請驗證設備驅動程序的加載是否正確。
13 communications error - 系統設備驅動程序與該單位通訊時碰到問題。請驗證設備驅動程序的安裝是否正確。
18 version not supported - 當前的系統設備驅動程序過期。請更新驅動程序。
19 OS environment not supported - 客戶程序庫不支持該操作系統或者環境。請與技術支持聯繫。
20 query too long - 發送的詢問字串超過 56 個字符。請發送較短的字串。
30 driver is busy - 系統驅動程序繁忙。請再試一次該操作。
31 port allocation failure - 通過操作系統的並行端口爭用處理器來分配並行端口時失敗。
32 port release failure - 通過操作系統的並行端口爭用處理器來釋放先前分配的並行端口時失敗。
39 acquire port timeout - 在規定的超時時間內請求使用並行端口失敗。
42 signal not supported - 特定的機器不支持信號線。例如，企圖在一臺 NEC 9800 計算機上使用 ACK 線。
57 init not called - 沒有初始化加密鎖。在調用產生該錯誤的函數之前，請先調用RNBOsproInitialize() 函數。
58 driver type not supported - 對於定義的操作系統和客戶程序庫，不支持驅動程序的存取類型。該驅動程序的存取類型無論是直接 I/O，還是系統驅動程序。
59 fail on driver comm - 客戶程序庫與 Rainbow 的系統驅動程序通訊失敗。
60 API status unavailable - 擴充的 API 狀態函數不可用。
255 invalid status - 返回的狀態碼無效。
