|
ITK Programmer's Guide |
||||||||||
Table of contents |
Intro | General
| TCP Low Level |
TCP High Level |
UDP | DNS
| PPP
|
Since version 2.5, ITK support SSL (Secured Socket Layer) version 2 and 3 as well as TLS (Transport Layer Secured) version 1. SSL support is only available in the "Pro" version of ITK and not available for 68K Macs .This support is mostly transparent, all existing ITK v2 based code should work in SSL with almost no modification.
Here are the changes you need to do in order to use SSL instead of TCP:
Acting as a server :
- call ITK_SSLSetCert after calling ITK_TCPListen .
This will let you speficy the certificate/private key that will be used for this SSL stream.Acting as a client :
- pass a new option (value 1024) in ITK_TCPOpen tcpOpt parameter (the 4th parameter).
This will switch this stream to SSL "client".All other ITK_TCP routines can be used on an SSL stream.
SSL Server Certificates and private keys
In order to act as a server, you must have a certificate that will allow the client to identify your server.A certificate is a text file looking like this:
-----BEGIN CERTIFICATE----- MIICqzCCAhSgAwIBAgIDKyXqMA0GCSqGSIb3DQEBBAUAMIGHMQswCQYDVQQGEwJa QTEiMCAGA1UECBMZRk9SIFRFU1RJTkcgUFVSUE9TRVMgT05MWTEdMBsGA1UEChMU ... jhsh9nP5wIYjia5GxuN4HWAJpnSFwC98LZcMqLU09+6XMymX8R2Voj0vBI8NlfQk HgHQlPQulXcgaNONSP5A -----END CERTIFICATE-----A certificate is linked to a private key which is needed in order to use the certificate. The certificate is useless without the private key. The private key generated by ITK_MakeCSR (see below) is also a text file looking like this :
-----BEGIN RSA PRIVATE KEY----- MIICXAIBAAKBgQDBO/ieW0VhcH/SniA6r9EPls6KBGWZDQVhzWLURXLe00VKgDOk RrZ+L8umdlBZM1y1RPWaCM3U56WiOUfq/2wflnbtjgb14m7lbtr0e0UuKDZa7SJJ ... Yvv+effpcMccy+amOxkCQGKGsjoMKhjgoifv1AElDWsFCK3OWiUFEWqWDYJcDVXK RBQBN/B6lJof5D4GN1L3B4gHgcsxkSSqYj1ud34zppk= -----END RSA PRIVATE KEY-----A private key can be password protected, in that case, you'll need to provide the password in order to use the private key. A password protected private generate by ITK_MakeCSR key looks like this:
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,D4A75236509E8F8C Ii6hR/SwPlUgDUfy7bIk//Sc52zhL76ecvSKO4PBJ1rYpOYnHUrQF0YEvDuVuD8j JdUGaC9i1bCKFU2Z3ryTXFUmU4rvWyXFs0Xq/sYb+o3kfwRo96VnpR7b1OsGom3K ... y5WwsxBhUpKZOtgPjgGNCcIAf4dkBmzM50HrkSPW0klCRisZiuDyWYmMXL/dYDAh 7ez5I1K/GJSaAJyJxW7rzNpLa+V1gEEwDSXjoNNxXWJbmcuHRkf04A== -----END RSA PRIVATE KEY-----
Generation of certificate signed requests (CSR) and private keys
Here is the process to generate a private key and obtain a certificate:Use the small tool called "ITK_MakeCSR".
ITK_MakeCSR will first generate a private key, will ask you if you want to protect it using a password, then will ask for some informations that will be stored in your certificate:
- Country Name* : enter a 2 letter country code (ex: US, FR, BE, CH, etc).
- State or Province Name*: Enter state or country name (ex: NY)
- Locality Name*: enter your city name (ex: New-York)
- Organization Name*: enter you company name
- Org. Unit Name*: enter some more info about your company (department, etc)
- Domain name for SSL server**: enter the name of the machine that will use the certificate (ex: secure.mydomain.com).
- Email address*: enter your email address
ITK_MakeCSR creates two text files: a private key file (which can be password protected) named "keyout.pem", and a Certificate Signed Request (CSR) named "certreq.pem".
Once you have create your CSR, you can go thru one of the certification authorities (like Thawte , Verisign , Equifax, etc) to obtain your certificate. These certification authorities (CA) will ask you for your CSR and some ID papers to be sure that the certificate you are requesting match who you really are.
Then the CA will send you your certificate (also a text file).
If you just want to do some tests, you can obtain a test certificate instantly from Thawte (https://www.thawte.com/cgi/server/test.exe).
It is highly recommended to always do some tests with test certificates before buying a certificate from a certification authority. This will ensure that the certificate format is compatible with ITK.
Note about certificate and private key file format:
ITK uses certificates in PEM format. These files are text files. Windows and MacOS are using differents kind of "end of lines" in text files. Windows standard is ending lines with CR+LF, while MacOS uses only a CR.
ITK v2.5 recognize CRLF end of lines under both MacOS and Windows, and also recognize CR under MacOs (but not under Windows).
Be sure to use the right kind of "end of line" in your certificate and private key files otherwise, these files will be unusable.
ITK_SSLSetCert |
|||||||||||||||||||||||||||||||
|
Not available in ITK Light or on 68K Macs |
||||||||||||||||||||||||||||||
Syntax: |
error := ITK_SSLSetCert (streamRef; pKeyPath; certPath; password)
|
||||||||||||||||||||||||||||||
Description: |
ITK_SSLSetCert allows to specify a private key and a certificate for a given stream.
|
||||||||||||||||||||||||||||||
Note: |
ITK_SSLSetCert must be used BEFORE the stream gets connected . It is recommended to call ITK_SSLSetCert just after calling ITK_TCPListen and before calling ITK_TCPStatus or ITK_TCPWaitConn. Be sure to use FULL pathname for the private key and the cerficate files.
Starting with ITK v2.6, if streamRef is equal to 0, ITK_SSLSetCert will allow to set a default private key file, a default certificate file and a default password. This allows to be sure that a certificate is set BEFORE the stream gets connected. See the example...
|
||||||||||||||||||||||||||||||
Params: |
|
||||||||||||||||||||||||||||||
Example: |
$streamRef := ITK_TCPListen(0;0;443) ` listen on HTTPS port If ($streamRef # 0) ` set our server certificate immediately $err := ITK_SSLSetCert($streamRef;"myHD:myFolder:keyout.pem"; "myHD:myFolder:cert.pem";"") ... Using default values machanism: $err := ITK_SSLSetCert($streamRef;"myHD:myFolder:keyout.pem"; "myHD:myFolder:cert.pem";"") ... $streamRef := ITK_TCPListen(0;0;443) ` listen on HTTPS port If ($streamRef # 0) ` no need to set the certificate infos, we can use the streamRef immediately $s := ITK_TCPWaitConn($s) |
ITK_SSLStrmInfo |
||||||||||||||||||||||||||||||||||||
|
Not available in ITK Light or on 68K Macs |
|||||||||||||||||||||||||||||||||||
Syntax: |
error := ITK_SSLStrmInfo (streamRef;sslVers;cipher;keyBits;certData)
|
|||||||||||||||||||||||||||||||||||
Description: |
This routine allows to get some informations about the SSL stream like the version of SSL or TLS used, the cipher (encryption algorithm) used, and the length (in bits) of the key used to crypt the transmission as well as some data about the remote certificate (if you're acting as a client). Since ITK v2.6.2, it can also be used to get the OpenSSL library version that is currently used by ITK (see example below).
|
|||||||||||||||||||||||||||||||||||
Note: |
This routine can only return valid informations when the stream is connected and SSL negociation has occured).
|
|||||||||||||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||||||||||||
Example: |
$streamRef := ITK_TCPListen(0;0;443) ` listen on HTTPS port If ($streamRef # 0) ` set our server certificate $err := ITK_SSLSetCert($streamRef;"myHD:myFolder:keyout.pem"; "myHD:myFolder:cert.pem";"") ` wait for connection $err := ITK_TCPWaitConn($streamRef) ` get some info about the connection $err := ITK_SSLStrmInfo($streamRef; $sslVers; $cipher; $keyLen) If ($keyLen >= 128) ` we are in "strong" 128bits (or above) mode .... ` Get the curent OpenSSL version with ITK v2.6.2 and above $err := ITK_SSLStrmInfo(0;sslVers) |
ITK_SSLGetError |
|||||||||||||||||||||
|
Not available in ITK Light or on 68K Macs |
||||||||||||||||||||
Syntax: |
errNum := ITK_SSLGetError (streamRef;errString)
|
||||||||||||||||||||
Description: |
This routine allows to get details on the last error that occured on the given stream. An error code is returned, as well as a error string which gives more details on the error.
|
||||||||||||||||||||
Note: |
The string returned as the following format:
Example: error:0906A068:PEM routines:PEM_do_header:bad password read
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$streamRef := ITK_TCPListen(0;0;443) ` listen on HTTPS port If ($streamRef # 0) ` set our server certificate $err := ITK_SSLSetCert($streamRef;"myHD:myFolder:keyout.pem"; "myHD:myFolder:cert.pem";"") If ($err # 0) $err := ITK_SSLGetError($streamRef; $error) Alert("SSL "+$error) ... |
ITK_SSLSetCiphers |
|||||||||||||||||||||
|
v2.6 and above, Not available in ITK Light or on 68K Macs |
||||||||||||||||||||
Syntax: |
errNum := ITK_SSLSetCiphers (streamRef;cipherList)
|
||||||||||||||||||||
Description: |
This routine allows to select which ciphers will be accepted on the given SSL stream. The cipher list follows OpenSSL cipher list syntax.
|
||||||||||||||||||||
Note: |
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$streamRef := ITK_TCPListen(0;0;443) ` listen on HTTPS port If ($streamRef # 0) ` set our server certificate $err := ITK_SSLSetCiphers($streamRef;"") ... |
A digest is like some "super-checksum" calculated on some data. They can be used as digital signatures or to transfer encrypted information.The original information cannot be recovered from the digest.For example, MD5 digests can be used to had a digital signature to emails to ensure that the message content has not been changed (see RFC#1544).
MD5 digests are also used in the POP3 APOP command which allows user authentication with transferring the user's password (see RFC#1939).
MD5 and SHA digests are also used in the SSL protocol.
RIPEMD-160 digests (added in ITK v2.0.4) are used by QuickDNS Pro load balancing system.
ITK 2.5 also supports SHA-1 (modified SHA) digests, as well as CRC32 and ADLER32 checksums.
Using ITK digest calculation routines
The first step is to initialise a digest calculation using ITK_DigestInit .
Then data are added to the calculation using the ITK_DigestAdd and ITK_DigestBlob routines
Finally, ITK_DigestCalc is called to get the final digest value (returned as a string).
ITK_DigestInit |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
digestRef := ITK_DigestInit (digestType)
|
|||||||||||||||
Description: |
ITK_DigestInit initialises a new digest calculation and returns a digest reference which will be needed in the next step of a digest calculation (ITK_DigestAdd or ITK_DigestBlob, then ITK_DigestCalc).
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$digestRef := ITK_DigestInit(2) ` start MD2 digest calculation ITK_DigestAdd($digestRef;"Here is some text") ITK_DigestAdd($digestRef;"and some more") ITK_DigestBlob($digestRef;myBlob) $myDigest := ITK_DigestCalc($digestRef) ` get the result |
ITK_DigestAdd |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
ITK_DigestAdd (digestRef;text)
|
|||||||||||||||
Description: |
Adds some text to a current digest calculation referenced by digestRef. This routine may be called several times during a digest calculation.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$digestRef := ITK_DigestInit(2) ` start MD2 digest calculation ITK_DigestAdd($digestRef;"Here is some text") ITK_DigestAdd($digestRef;"and some more") ITK_DigestBlob($digestRef;myBlob) $myDigest := ITK_DigestCalc($digestRef) ` get the result |
ITK_DigestBlob |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
ITK_DigestBlob (digestRef;blob)
|
|||||||||||||||
Description: |
Adds some data contained in a blob to a current digest calculation referenced by digestRef. This routine may be called several times during a digest calculation.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$digestRef := ITK_DigestInit(2) ` start MD2 digest calculation ITK_DigestAdd($digestRef;"Here is some text") ITK_DigestAdd($digestRef;"and some more") ITK_DigestBlob($digestRef;myBlob) $myDigest := ITK_DigestCalc($digestRef) ` get the result |
ITK_DigestCalc |
|||||||||||||||||||||
|
|
||||||||||||||||||||
Syntax: |
digest := ITK_DigestCalc (digestRef;digestFormat)
|
||||||||||||||||||||
Description: |
Terminates the digest calculation and returns the calculated digest according to the format option. After calling this routine, the digestRef previously returned by ITK_DigestInit is not valid anymore.
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$digestRef := ITK_DigestInit(2) ` start MD2 digest calculation ITK_DigestAdd($digestRef;"Here is some text") ITK_DigestAdd($digestRef;"and some more") ITK_DigestBlob($digestRef;myBlob) $myDigest := ITK_DigestCalc($digestRef) ` get the result |
ITK_Rot13Text |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
encodedText := ITK_Rot13Text (originalText)
|
|||||||||||||||
Description: |
Applies ROT13 "light encryption" to some text. ROT13 is an email standard to hide some text. It is not a real encryption, only a shift in characters to make some text unreadable. ROT13 is auto-reversible, apply it a second time to get
the original text back. If the original text was 7bit only, the resulting text will still be a 7bit only text.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$rot13 := ITK_Rot13Text("Hello") |
ITK_Rot13Blob |
|||||||||||
|
|
||||||||||
Syntax: |
ITK_Rot13Blob (theBlob)
|
||||||||||
Description: |
Applies ROT13 "light encryption" to a blob. ROT13 is an email standard to hide some data. It is not a real encryption, only a shift in characters to make some data unreadable. ROT13 is auto-reversible, apply it a second time to get the original data back. If the original data was 7bit only, the resulting data will still be a 7bit only text. The original blob is directly "encrypted" to avoid a copy in memory.
|
||||||||||
Params: |
|
||||||||||
Example: |
ITK_Rot13Blob(myBlob) |
ITK_Rot13Blob |
|||||||||||
|
|
||||||||||
Syntax: |
ITK_Rot13Blob (theBlob)
|
||||||||||
Description: |
Applies ROT13 "light encryption" to a blob. ROT13 is an email standard to hide some data. It is not a real encryption, only a shift in characters to make some data unreadable. ROT13 is auto-reversible, apply it a second time to get the original data back. If the original data was 7bit only, the resulting data will still be a 7bit only text. The original blob is directly "encrypted" to avoid a copy in memory.
|
||||||||||
Params: |
|
||||||||||
Example: |
ITK_Rot13Blob(myBlob) |
ITK v2.5 supports several ciphers (encryption/decryption algorithms):
Algorithm name
Algorithm ID
Key length (bits)
DES
kCipherAlgDES (1)
56 (in fact 8 x 7bits chars)
TripleDES
kCipherAlgTripleDES (2)
168 (in fact 24 x 7bits chars)
3Way
kCipherAlgThreeWay (3)
96
CAST-128 (defined in RFC#2144)
kCipherAlgCAST_128 (8)
128
TwoFish-128
kCipherAlgTWOFISH_128 (10)
128
Unix Crypt
kCipherAlgUnixCrypt (28)
64, stream algorithm
These algorithms are working on block of data. There are several block mode supported by ITKv2.5 :
Block mode name
Block mode ID
CBC
kCiphermodeCBC (0)
ECB
kCiphermodeECB (1)
CFB
kCiphermodeCFB (2)
OFB
kCiphermodeOFB (3)
nOFB
kCiphermodenOFB (4)
stream
kCiphermodeStream (5)
It is mandatory to use the same algorithm and the same block mode while encrypting and decrypting.
ITK_EncryptText |
||||||||||||||||||||||||||||||||||||
|
Not available in ITK Light |
|||||||||||||||||||||||||||||||||||
Syntax: |
error := ITK_EncryptText (text; secretKey; algoID; blockMode; IV)
|
|||||||||||||||||||||||||||||||||||
Description: |
ITK_EncryptText can be used to encrypt some text using your choice of cipher algorithm and block mode. You will be able to decrypt it using ITK_DecryptText.
|
|||||||||||||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||||||||||||
Example: |
err := ITK_EncryptText(text;"12345678";kCipherAlgDES;kCiphermodeECB) |
ITK_DecryptText |
||||||||||||||||||||||||||||||||||||
|
Not available in ITK Light |
|||||||||||||||||||||||||||||||||||
Syntax: |
error := ITK_DecryptText (text; secretKey; algoID; blockMode; IV)
|
|||||||||||||||||||||||||||||||||||
Description: |
ITK_DecryptText can be used to decrypt some text using your choice of cipher algorithm and block mode.
|
|||||||||||||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||||||||||||
Example: |
err := ITK_DecryptText(text;"12345678";kCipherAlgDES;kCiphermodeECB) |
ITK_EncryptBlob |
||||||||||||||||||||||||||||||||||||
|
Not available in ITK Light |
|||||||||||||||||||||||||||||||||||
Syntax: |
error := ITK_EncryptText (blob; secretKey; algoID; blockMode; IV)
|
|||||||||||||||||||||||||||||||||||
Description: |
ITK_EncryptBlob can be used to encrypt a blob content using your choice of cipher algorithm and block mode. You will be able to decrypt it using ITK_DecryptBlob.
|
|||||||||||||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||||||||||||
Example: |
err := ITK_EncryptBlob(myBlob;"12345678";kCipherAlgDES;kCiphermodeECB) |
ITK_DecryptBlob |
||||||||||||||||||||||||||||||||||||
|
Not available in ITK Light |
|||||||||||||||||||||||||||||||||||
Syntax: |
clearText := ITK_DecryptBlob (blob; secretKey; algoID; blockMode; IV)
|
|||||||||||||||||||||||||||||||||||
Description: |
ITK_DecryptBlob can be used to decrypt some text using you choice of cipher algorithm and block mode.
|
|||||||||||||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||||||||||||
Example: |
err := ITK_DecryptBlob (myBlob;"12345678";kCipherAlgDES;kCiphermodeECB) |