regify client SDK
- Introduction
- The regify Process
- regify Client SDK Functions
- General Information
- Installation and Setup Prerequisites
- Connection Functions
- RGF File Specific Functions
- regibill Standard Specific Functions
- Identity File Specific Functions
- Parsing the regify File
- Cryptographic Functions
- Advertising Functions
- Other Functions
- regifyLastError
- regifyGetMetrics
- regifyGetUsername
- regifyGetRealUsername
- regifyGetUserMailaddress
- regifyGetConfigCheckSum()
- regifyAutoLogin
- regifyGetConfiguration
- regifyResetPassword
- regifyCleanup
- regifyVersion
- regifyGetURL
- regifyGetURLFile
- regifySetSingleByteEncoded
- regifySetLogLevel
- regifySetLogFilePath
- regifySetCaCertFile
- regifySetReplyAddress
- regifyGetUserdata
- regifyGetSession
- regifySetSession
- regifySendEmail
- Best Practices
- Code Samples
- Error Codes
- regifycmd Utility
- Command Line Parameters
- General Parameters
- Creation of regify Files
- Open and Extract regify Files
- Creating regibill Standard Documents
- Verifying regibill Standard Documents
- Receive Users Identity File
- Showing Users Identity File
- Getting the User Data
- Getting the User Metrics
- Getting the Configuration
- Resetting the Password
- Appendix
Introduction
The regify software provides a large variety of capabilities for trusted and binding email communication. regify solutions such as the ones offered and operated by regify providers have been developed by regify using the "regify client SDK", regify’s software development kit. In this first phase of the market, regify designed its own client SDK in order to make the internal development process more effective and more efficient.
Now, we are entering the second stage, that of a regify community of partners and customers who are developing new and innovative ideas about how they want to use the regify service. Many of these ideas are covered with the "standard regify service" but others are not. We at regify believe in market innovation and we will empower all members of the regify community to write their own applications. Consequently, we make our client SDK available to our partners and customers. As of now, software programmers will be entitled to develop regify based applications that use core capabilities of the regify service.
This document shall enable developers to
-
develop individual regify applications
-
apply regify technology to existing products and solutions
The only prerequisite for developers is that they have a good command of their programming language and the external libraries inside their development environment. Of course, they should also have a thorough understanding of the regify service.
This document is structured into three main chapters:
-
the regify process (overview)
-
regify client SDK functions
-
regifycmd command line utility
The appendix provides additional graphics and information about the regify service.
If you are in search for file format description, this information has been separated in February 2011 into a new document (regify_file_formats_Vx.x.x.pdf). If you need the file format specifications, please contact regify support directly.
Document Conventions
This document uses the following textual conventions
Text Style | Description |
---|---|
/* retrieve the last error code */ |
Code comment found in a code snippet |
intError = regifyLastError(); |
Sample code snippet |
regifyLogin() |
Reference to a function |
ProviderUrl |
Quotation of a value or other things such as strings or numbers. |
*sess or strText |
A parameter or variable being described |
The regify Process
In order to use the regify SDK, the regify process and the regify communication including encryption must be understand. The following two pages give an overview. More detailed documentation can be made available upon request.
The Process
-
The regify software encrypts and merges the text message and potential attachments of the sender’s email into a regify file.
-
The message key and hash code of the regify file and the subject of the message will be sent to the regify provider.
-
The regify provider relays the message key and the hash code to the regify clearing service.
-
An email with the encrypted regify file (regify email) will be sent to the addressee. This email service is independent of regify. Customers can simply use their existing email services.
-
The recipient receives the regify file as an attachment to an email and opens the file with the regify software. This software has been designed to work seamlessly with the email client software.
-
The regify software will authenticate the recipient (6a). Upon successful authentication (6b), i.e. match between recipient address and hash code, the regify clearing service will send the message key to the recipient (6a).
-
The received message key key will be used to decrypt the regify file, thereby giving the addressee access to the contents of the message (message text, files, etc.).
-
The regify provider of the addressee will notify the regify clearing service which in return will notify the regify provider of the sender. Finally, that provider will send an email confirmation of receipt to the sender.
regify Client SDK Functions
General Information
A variety of functions is dedicated to the the handling of regify files and other functions providing cryptographic capabilities.
Windows DLL (Dynamic Link Library) Information
component: | regify2.dll | ||
---|---|---|---|
charset: |
All strings are Unicode unless regifySetSingleByteEncoded() has been called to set single byte mode.
|
||
company: |
regify GmbH |
||
copyright: |
© regify GmbH |
||
system: |
Microsoft Windows beginning with Windows Vista / 2003 Server |
Linux SO (Shared Object) Information
component: | libregify2.so | ||
---|---|---|---|
charset: |
All strings are Unicode unless regifySetSingleByteEncoded() has been called to set single byte mode.
|
||
company: |
regify GmbH |
||
copyright: |
© regify GmbH |
||
system: |
Linux systems running libc6 |
Mac OSX DYLIB (Dynamic Library) Information
component: | libregify2.dylib | ||
---|---|---|---|
charset: |
All strings are Unicode unless regifySetSingleByteEncoded() has been called to set single byte mode.
|
||
company: |
regify GmbH |
||
copyright: |
© regify GmbH |
||
system: |
Mac OSX 10.9 or greater |
Installation and Setup Prerequisites
regify2.dll for MS Windows
The regify2.dll and its sub components do not need any runtime environments (.net or visual basic etc.) or other prerequisites to run on a standard Microsoft Windows machine.
Currently, regify supports the following operating systems:
-
Windows Vista / 2008 Server 32/64 Bit
-
Windows 7 32/64 Bit
-
Windows 8 and Windows 8.1 32/64 Bit
-
Windows 10 32/64 Bit
To install and use the regify2.dll, the following files must be
available inside the windows system directory or at least in the same
directory as the regify2.dll:
-
cryptoc.dll(regify cryptographic functions library)
-
libcurl.dll(curl library for networking)
-
zlib1.dll(compression library)
To install and use the regifycmd.exe utility, the following files must be available inside the windows system directory or at least in the same directory as the regifycmd.exe:
-
regify2.dll and its dependencies listed above
You can find all files in the ZIP file you’ve downloaded or received. If you need a newer version of the files, please contact regify support using support@regify.com.
libregify2.so for Linux
The libregify2.so and its sub components do not need any runtime environments (java etc.) or other prerequisites to run on a standard 32 bit or 64 bit Linux system.
To install the regify SDK on a linux machine, please copy the following files from the ZIP archive to your system folders:
-
Copy all from the archive /lib folder to your system library path such as /usr/lib or /usr/lib32 or /usr/lib64.
-
Copy all from the archive /bin folder to your system binary path such as /usr/bin.
Additionally, OpenSSL and CURL need to be available on your system. Your distribution should have packages available, if not, you can find the most recent versions and more information here:
-
OpenSSL: http://www.openssl.org/
libregify2.dylib for Mac OSX
The libregify2.dylib and its sub components do not need any runtime environments (java etc.) or other prerequisites to run on a standard Mac OSX system.
To install and use the libregify2.dylib, the following files must be
available in the library path such as /usr/lib or under
/System/Library:
-
libcryptoc.dylib (regify cryptographic functions library)
-
cacert.pem (optional: collection of trusted root certification authorities)
Additionally, the 32bit versions of the OpenSSL and CURL systems need to be available on your system. You can find the most recent versions here:
-
OpenSSL: http://www.openssl.org/
To install and use the func:*regifycmd* utility, the following files must be available in the library path such as /usr/lib or under /System/Library:
-
libregify2.dylib and its dependencies listed above
Connection Functions
regifyNewSession
function: | regifyNewSession |
---|---|
parameters: |
strProviderUrl, strProviderData, strRegifyUserName, strRegifyPassword, strRegifyIdentityFile |
return value: |
(integer) !0=ok, 0=error |
description: |
Initializes a new session and implicitly calls regifySetProvider() followed by regifySetUser(). To use a proxy server, call regifySetProxy() before calling regifyLogin() or any other function that makes a network connection. You may call this function with all parameters set, or all of them Blank or just the user data blank depending on your needs. You can call regifySetProvider(), regifySetUser() or regifySetProxy() at any time to make changes to this session. When done regifyFreeSession() should be called to release the resources. Use the return value of this function as the *sess parameter in all the SDK functions that require it. |
example call: |
*sess = regifyNewSession("https://portal.regify.com", "AACDF3400EF...", "HansMeiser", "MyPassword", "");` |
regifySetProvider
function: | regifySetProvider |
---|---|
parameters: |
*sess, strProviderUrl, strProviderData |
return value: |
(integer) 1=ok, 0=error |
description: |
Initializes the provider parameters needed for connecting to the regify provider. Please enter strProviderUrl including "https://" or "http://" and including the port divided using colon (see example). This function implicitly calls regifyLogout() and resets all provider and user data. So regifySetUser() must be called after this, but before calling regifyLogin(). strProviderData is the value of the providerData field returned by the getConfiguration() call. This function also frees any *obj that was created and not yet freed using this login. |
example call: |
regifySetProvider(sess,"https://portal.regify.com", "AACDF3400EF..."); |
regifySetUser
function: | regifySetUser |
---|---|
parameters: |
*sess, strRegifyUserName, strRegifyPassword, strRegifyIdentityFile |
return value: |
(integer) 1=ok, 0=error |
description: |
Initializes the user parameters needed to log into the regify provider. Please insure regifySetProvider() has been called before this function as it will delete the settings set here. Please use strRegifyIdentityFile to point onto an existing identity file. Leave it blank to use the built in default identity file. This function allows the usage of the SHA1 hash code of the password (160bit, HEX, 40 chars), too. In this case, simply set the hash code as password and it will be automatically detected. This function also frees any *obj that was created and not yet freed using this login. |
example call: |
regifySetUser(sess, "HansMeiser", "MyPassword", ""); |
regifySetProxy
function: | regifySetProxy |
---|---|
parameters: |
*sess, strProxyServer, strProxyUsername, strProxyPassword |
return value: |
(integer) 1=ok, 0=error |
description: |
Initializes the proxy parameters needed for network connections. Please enter replace: strProxyServer including "https://" or "http://" and including the port divided using colon (see example). To use the proxy server, this function must be called before calling regifyLogin(). You can skip this, if you do not plan to support proxy servers. Calling this function with a blank strProxyServer will unset the proxy settings for sess. |
example call: |
regifySetProxy(sess, "192.168.100.244:1080", "", ""); |
regifySetAppData
function: | regifySetAppData | ||
---|---|---|---|
parameters: |
*sess, strAppName, strAppVersion |
||
return value: |
(integer) 1=ok, 0=error |
||
description: |
Set the used application identifiers. This must be done before calling regifyLogin(). These values are used to identify allowed app versions on provider side and also for statistic purposes. If not set, it uses defaults (“sdk” and version equals the SDK version).
|
||
example call: |
regifySetAppData(sess, "regify client", "4.1.0-1234"); |
regifyLogin
function: | regifyLogin |
---|---|
parameters: |
*sess |
return value: |
(integer) 1=ok, 0=error |
description: |
Performs the login of a user to the regify provider. After success, the connection is established. |
example call: |
regifyLogin(sess); |
regifyLogout
function: | regifyLogout |
---|---|
parameters: |
*sess |
return value: |
- |
description: |
Disconnects an existing regify provider connection established with regifyLogin(). This function closes the progress dialogue that was opened using regifyLogin(). It does not reset user or provider parameters. It only resets session related data. This means a simple call to regifyLogin(sess) will log the same user into the provider again. |
example call: |
regifyLogout(sess); |
regifyFreeSession
function: | regifyFreeSession |
---|---|
parameters: |
*sess |
return value: |
- |
description: |
Logs out any existing user, closes any operations that are in use and frees the session context resources. Should be called when everything that was created with the session and the session itself is no longer needed. This function also frees any *obj that was created and not yet freed using this login. |
example call: |
regifyFreeSession(sess); |
regifySetProgressCallbacks
function: | regifySetProgressCallbacks |
---|---|
parameters: |
*sess, *progressVectors |
return value: |
none |
description: |
Passes in the desired methods to use for a progress bar. Every method that is set is called. The vectors data type consist of 4 function pointers with the following signature in C notation:
Then the return value of progressOpen is used as a context void pointer for the other 3 routines. This way open can return window handles or whatever else is required by the other routines to properly function. The updateLabel function currently issues English single byte ASCII text, while the updateNumber function issues integers ranging from 0 to 100. Passing a NULL pointer to regifySetProgressCallbacks turns all progress updates off. |
example call: |
|
RGF File Specific Functions
regifyComposeRegimail
function: | regifyComposeRegimail |
---|---|
parameters: |
*sess, strContainerFile, strFileList, strMessageBody, strRecipients, strSubject, strSenderName, strCommAddress, intReminderDuration |
return value: |
(integer) !0=ok, 0=error |
description: |
Creates a new regify file for a regimail. You need to call regifyLogin() first! The result is an operation object. Use regifyGetTransactionIds() to get the transaction ids for this object. Call regifyCleanup() or regifyFreeSession() to free the object resources after the transaction ids have been retrieved. |
example call: |
regifyComposeRegimail(sess, "/tmp/regify-file.rgf", "\{\"/data/File1.jpg\":{},\"/data/File2.doc\":{}}" , "Hi John, this is a simple example.", "john@testcompany.com;bob@mycompany.com", "Testmessage for regify", "Melissa Hart", "", 5); |
details: |
*sess is the current session context. The user needs to be logged in. strContainerFile is the complete destination path for the regify file to create. If the file in strContainerFile already exists, it will be overwritten. strFileList is a JSON list of all PDF files that need to be added into the regify file and possibly be uploaded. The format is described in the RGF File Specific Functions chapter. strMessageBody contains the complete message to include into the container. strRecipients lists all recipient mail addresses, divided using semicolon (;). strSubject contains the subject of the message. strSenderName contains the name of the sender of the message. If you set strSenderName to an empty string, the real name of the user in his regify portal will get used (including title). strCommAddress is an optional address. The regify provider may use this address for messages related to this special transaction. Leave empty if the standard account should be used. Please do only set addresses that are registered to your regify account (otherwise triggers error-code 17 during registration). intReminderDuration is the number of days the reminder will be set (1-60). |
regifyComposeRegibill
function: | regifyComposeRegibill | ||||
---|---|---|---|---|---|
parameters: |
*sess, strContainerFile, strFileList, strMessageBody, strRecipient, strSubject, strSenderName, strCommAddress, intReminderDuration |
||||
return value: |
(integer) !0=ok, 0=error |
||||
description: |
Creates a new regify file for a regibill premium message. You need to call regifyLogin() first! The result is an operation object. Use regifyGetTransactionIds() to get the transaction ids for this object. Call regifyCleanup() or regifyFreeSession() to free the object resources after the transaction ids have been retrieved.
|
||||
example call: |
regifyComposeRegibill(sess, "/tmp/regibill-file.rgf", "{\"/data/bill.pdf\":{\"regibill\":true},\"/data/bill2.pdf\":{\"regibill\":true}}", "Hi John, here is your invoice.", "john@testcompany.com", "Testmessage for regibill", "Melissa Hart", "", 5); |
||||
details: |
*sess is the current session context. The user needs to be logged in. strContainerFile is the complete destination path for the regify file to create. If the file in strContainerFile already exists, it will be overwritten. strFileList is a JSON list of all PDF files that need to be added into the regify file and possibly be uploaded. The format is described in the strFileList Explained chapter. strMessageBody contains the complete message to include into the container. strRecipient the recipient mail addresses.
strSubject contains the subject of the message strSenderName contains the name of the sender of the message If you set strSenderName to an empty string, the real name of the user in his regify portal will get used (including title). strCommAddress is an optional address. The regify provider may use this address for messages related to this special transaction. Leave empty if the standard account should be used. Please do only set addresses that are registered to your regify account (otherwise triggers error-code 17 during registration). intReminderDuration is the number of days the reminder will be set (1-60).
|
regifyComposeRegipay
function: | regifyComposeRegipay |
---|---|
parameters: |
*sess, strContainerFile, strPDFFileList, strMessageBody, strRecipient, strSubject, strSenderName, strCommAddress, intReminderDuration |
return value: |
(integer) !0=ok, 0=error |
description: |
Creates a new regipay file. You need to call regifyLogin() first! The result is an operation object. Use regifyGetTransactionIds() to get the transaction ids for this object. Call regifyCleanup() or regifyFreeSession() to free the object resources after the transaction ids have been retrieved. |
example call: |
regifyComposeRegipay(sess, "/tmp/regipay-file.rgf", "{\"/data/paystub.pdf\":{}}" , "Hi John, this is your sample paystub.", "john@testcompany.com", "Testmessage for regipay", "Melissa Hart", "", 5); |
details: |
*sess is the current session context. The user needs to be logged in. strContainerFile is the complete destination path for the regipay file to create. If the file in strContainerFile already exists, it will be overwritten. strFileList is a JSON list of one PDF files that has to be added into the regify file and possibly be uploaded. The format is described in the STR File List Chaper. strMessageBody contains the complete message to include into the container. strRecipient the recipient mail addresses. Only one allowed! strSubject contains the subject of the message strSenderName contains the name of the sender of the message If you set strSenderName to an empty string, the real name of the user in his regify portal will get used (including title). strCommAddress is an optional address. The regify provider may use this address for messages related to this special transaction. Leave empty if the standard account should be used. Please do only set addresses that are registered to your regify account (otherwise triggers error-code 17 during registration). intReminderDuration is the number of days the reminder will be set (1-60). |
regifyDecryptContainer
function: | regifyDecryptContainer |
---|---|
parameters: |
*sess, strContainerFile |
return value: |
(integer) !0=ok, 0=error |
description: |
This function decrypts a regify file and keeps the results in memory. You need to call regifyLogin() first. The result is an operation object. Use the regifyParse…() functions for content and regifyGetTransactionIds() to get the transaction ids for this object. Call regifyCleanup() or regifyFreeSession() to free the object resources after use. |
example call: |
regifyDecryptContainer(sess, "/tmp/regify-file.rgf");` |
details: |
*sess is the current session context. The user needs to be logged in. strContainerFile the file to decrypt into temporary memory. Use parsing functions to gather the content. |
regifyGetTransactionIds
function: | regifyGetTransactionIds | ||
---|---|---|---|
parameters: |
*obj |
||
return value: |
(string) strTransactionIds |
||
description: |
Returns the strTransactionIds (same as shown in portal or emails) of the current object. If the current transaction had more than one recipient, the different transaction ids are divided using pipe (|) character (ASCII 124). You can use these ids to rename the current regify file. This may help future users of your application to identify different regify files because this ID is used for user communication, too (eg for reminders or certificates of delivery). *obj is the result of regifyComposeRegimail(), regifyComposeRegibill(), regifyComposeRegipay() or regifyDecryptContainer().
|
||
example call: |
strTransactionID = regifyGetTransactionIds(*obj); |
strFileList Explained
The strFileList parameter used in the regifyCompose..() functions is a JSON structure and has the following format.
filePath | Map describing how to handle this file. | |
---|---|---|
upload |
Optional parameter indicating that the file is to be uploaded to the provider. Can be true or false and defaults false. |
|
regibill |
Optional parameter indicating that the file is a PDF document to be turned into a regibill file. |
|
meta |
Optional list of strings to associate with the given document. Ignored when upload is not set to true. |
In the following example, invoice_678432.pdf and invoice_126742.pdf are uploaded with their respective meta information while marketing_flyer.pdf and special_offer.pdf are not.
{
"/path/to/invoice_678432.pdf" : {
"upload" : true,
"meta": [ "bzu54r2bzu", "€99.95" ]
},
"/path/to/some/marketing_flyer.pdf" : { },
"/path/to/invoice_126742.pdf" : {
"upload" : true,
"meta": [ "Invoice#=asd21r2f00", "Total=$23" ]
},
"/path/to/some/special_offer.pdf" : { "upload" : false }
}
Simplified example with 4 files (no upload, no meta, no regibill):
{
"/path/to/invoice_678432.pdf" : { },
"/path/to/some/marketing_flyer.pdf" : { },
"/path/to/invoice_126742.pdf" : { },
"/path/to/some/special_offer.pdf" : { }
}
regibill Standard Specific Functions
A regibill standard is not to be compared against a regimail or regipay. It is quite different in technology and handling. In contrast, a regibill premium is nearly the same as a regimail.
A regibill standard is a PDF document containing a regibill digest. This regibill digest allows a regify provider to validate the integrity and sender information of the PDF document.
If you are interested in details about how regibill standard works, please contact support@regify.com to request further information.
Use regifyCreateRegibillPDF() to create and register such a PDF document.
Use regifyValidateRegibillPDF() to validate such a PDF document.
regifyCreateRegibillPDF
function: | regifyCreateRegibillPDF |
---|---|
parameters: |
*sess, strPDFFileIn, strPDFFileOut, strRecipient, strSubject |
return value: |
(integer) !0=ok, 0=error |
description: |
Creates a new regibill document. You need to call regifyLogin() first! The result is an operation object. Use regifyGetTransactionIds() to get the transaction ids for this object. Call regifyCleanup() or regifyFreeSession() to free the object resources after the transaction ids have been retrieved. |
example call: |
regifyCreateRegibillPDF(sess, "/tmp/original.pdf", "/tmp/regibill.pdf" , "john@testcompany.com", ""); |
details: |
*sess is the current session context. The user needs to be logged in. strPDFFileIn is a JSON list of the file that needs to be converted to a regibill standard file and possibly be uploaded. The format is described in the STR File List Explained Chapter. Only one file is allowed. strPDFFileOut will be the document, but with regbill digest added. If the file in strPDFFileOut already exists, it will be overwritten. strRecipient is the recipient mail address (only one!) strSubject is an alternative subject for the transaction history. If blank, some default subject is used. If you send the regibill using email, please set and use the same subject! |
important: |
This function will create a regibill document and directly register this with the regify service. |
regifyValidateRegibillPDF
function: | regifyValidateRegibillPDF |
---|---|
parameters: |
*sess, strPDFFileIn, strRegifyServer |
return value: |
(string) strValidationResult |
description: |
Validates a regibill standard PDF document. Returns "ERROR" or JSON encoded result. The result is described in the appendix chapter. You do not need to be logged in. If you like to use a proxy, please call regifySetProxy() first. If you do not set a value for strRegifyServer, the system tries to use the URL that is contained in the regibill digest (in most times, this is the regify provider of the sending user). |
example call: |
sess = regifyNewSession("", "", "", "", "") validationResult = regifyValidateRegibillPDF(sess, "/tmp/regibill.pdf"); regifyFreeSession(sess); |
details: |
*sess is the current session context. The user does NOT need to be logged in. strPDFFileIn must be a regibill standard PDF document. |
Identity File Specific Functions
regifyRequestIdentityFile
function: | regifyRequestIdentityFile |
---|---|
parameters: |
*sess, strIdentityFile,intSaveEncrypted, strUnlockCode |
return value: |
(integer) 1=ok, 0=error |
description: |
Requests the current identity file for the current user. The unlock code must be asked for before calling this function. You need to call regifyLogin() first. |
example call: |
regifyRequestIdentityFile(sess, "/home/me/myidentity.rif", 1, "password"); |
details: |
If the identity file has been downloaded, this function will decrypt it using the given unlock code. After successful decryption of the identity file, the identity file will be stored in the path given using strIdentityFile. If you set intSaveEncrypted to 1 (recommended), the file will be
encrypted using current machine code:
cryptoGetMachineCode(), which is described in the Cryptographic Functions chapter. If you leave strUnlockCode empty, decryption will fail. This function returns "1", if all actions were performed without
error. The extensions of identity files must be .rif (regify identity file)! |
important: |
To use this function, it is strongly recommended to use no individual identity file while connecting. If the user already uses this new identity on another computer and your current installation uses an old identity file, this connection may be refused (error 11) because the local identity file will be out of date. Always call regifyNewSession() or regifySetUser() using an empty identity file parameter before using this function. |
The identity file normally will be saved in encrypted format. The used encryption key is generated using hardware dependent information (see cryptoGetMachineCode()). This means that this identity file will only work on this machine and can not get copied to another computer. This works also on Citrix- and TerminalServer clusters. |
regifyRemoveIdentityFile
function: | regifyRemoveIdentityFile |
---|---|
parameters: |
strIdentityFile |
return value: |
(integer) 1=ok, 0=error |
description: |
Removes the given identity file and secures this deletion
by multiple overwriting the used data section on your hard disk. It is
not the same like simply deleting the file. Please use this function to
avoid problems in future versions and enhance the security. |
example call: |
regifyRemoveIdentityFile("/home/me/myidentity.rif"); |
regifyGetIdentity
function: | regifyGetIdentity |
---|---|
parameters: |
*ptr |
return value: |
(string) jsonResult |
description: |
Returns a JSON string with the information of the given identity file. Look into the regifyGetIdenity JSON Result Chapter for details of the result. |
example call: |
|
details: |
Depending on the submitted parameter *ptr, the function will display different identities:
|
regifySignedAuthRequest
function: | regifySignedAuthRequest | ||
---|---|---|---|
parameters: |
*sess, strSignedDigestFile, strSignedDigestDataFile |
||
return value: |
(integer) 1=ok, 0=error |
||
description: |
Asks the regify provider to authenticate the current logged in user using the signed authentication digest. If you are using .p7m, you only need to set strSignedDigestFile with the p7m file and set strSignedDigestDataFile empty (""). If you like to use .p7s, the strSignedDigestFile is the p7s file and strSignedDigestDataFile is the file that has been signed. The function returns 1 on success. If returned 0, you can get the error number using regifyLastError() function.
|
||
example call: |
regifySignedAuthRequest(sess, "/home/me/auth_20120712155002.txt.p7m", ""); regifySignedAuthRequest(sess, "/home/me/auth_20120712155002.txt.p7s", "/home/me/regify_auth_20120712155002.txt"); |
||
details: |
This functions only succeeds if
The content of the signed file should the user data of the user (you can use regifyGetUserdata() function to get this information) in a readable form (like JSON or XML). But the regify provider does not really care about the file content. It is only about the signature. |
Parsing the regify File
Use these functions after calling the regifyDecryptContainer() function to obtain data from the resulting operation object. The decrypted regify file will be held in this object until you call regifyCleanup() function. Calling regifySetUser(), regifySetProvider() or regifyFreeSession() with the parent session obj will also release these resources.
regifyParseBody
function: | regifyParseBody |
---|---|
parameters: |
*obj |
return value: |
(string) strBody (please check regifyLastError() if result was empty) |
description: |
Returns the parsed body of the parsed regify file. If you are using this to display, please respect the placeholders! |
example call: |
strBody = regifyParseBody(obj); |
regifyParseFileList
function: | regifyParseFileList |
---|---|
parameters: |
*obj |
return value: |
(string) strFileList (please check regifyLastError() if result was empty) |
description: |
Returns a list of all files inside the parsed regify file. |
example call: |
strFileList = regifyParseFileList(obj); |
details: |
The list is defined in the following manner:
Each entry is divided using pipe (ASCII 124). Each value is divided using tab character (ASCII 9). ID is a number for each file. It is possible, that it not starts using Filename contains the filename (without path information) of the attached file. Flags contain file specific flags (A=encoded using TF256, Z=zipped, E=enforced document). Filesize contains the size of the uncompressed original file in bytes. |
regifyParseExtractFile
function: | regifyParseExtractFile |
---|---|
parameters: |
*obj, intFileID, strDestination |
return value: |
(integer) 0=error, 1=ok |
description: |
Extracts a file from the parsed regify file. The number must be the same that is gathered using regifyParseFileList() function. |
example call: |
regifyParseExtractFile(obj, 2, "/tmp/MyFile.doc"); |
details: |
The file will be stored using the filename in strDestination. Please use a full path here. If the destination file already exists, the file will be overwritten. |
regifyParseHeader
function: | regifyParseHeader |
---|---|
parameters: |
*obj, strHeaderField |
return value: |
(string) strResult (please check regifyLastError() if result was empty) |
description: |
Extracts a header information of the parsed regify file. |
example calls: |
|
details: |
The following header fields are supported: subject = the subject of the message recipient = the recipient given by the sender sender = the full name of the sender (as specified in his application) creationdate = the date and time this message was created (sender computer time) creationuser = user name (login name) of the sender user certificate = contains certificate information (see regify container description) flags = some flags (see regify container description) filecount = number of contained files inside this container Please refer to the regify file format description (separate document). |
regifyParseSenderAuthenticated
function: | regifyParseSenderAuthenticated |
---|---|
parameters: |
*obj |
return value: |
(integer) 0=not authenticated |
description: |
Looks inside the decrypted regify file and checks the certificate header. If the certificate is default, the function will return 0. If the sender used a valid identity file during the sending process, this function returns a value ranging from 1 to 10 to show the authentication level of the sender. |
example call: |
intAuthLevel = regifyParseSenderAuthenticated(obj); |
Individual Placeholder Substitution
As the sender assumes that all available placeholders in the body are getting replaced with some values, you should implement the replacement of the following placeholders just before displaying the message:
placeholder | description |
---|---|
[LANGUAGEID] |
Please replace this with an ID that indicates the language your user speaks. DE = German |
Cryptographic Functions
This library contains cryptographic functions that may help you to secure your application.
cryptoHashOfString
function: | cryptoHashOfString |
---|---|
parameters: |
strAlgorithm, strOriginal |
return value: |
(string) strHashcodeHEX (result is hex encoded) |
description: |
calculates the hash of the given string. strAlgorithm can be one of the following sha-1, sha-256, sha-384, ha-512 |
example call: |
strHash = cryptoHashOfString("sha-256", "something to hash"); |
cryptoHashOfFile
function: | cryptoHashOfFile |
---|---|
parameters: |
strAlgorithm, strFilename |
return value: |
(string) strHashcodeHEX (result is hex encoded) |
description: |
calculates the hash code of the given file. strAlgorithm can be one of the following sha-1, sha-256, sha-384, ha-512 |
example call: |
strHash = cryptoHashOfFile("sha-256", "/home/me/test.doc"); |
cryptoEncrypt
function: | cryptoEncrypt |
---|---|
parameters: |
strAlgorithm, strOriginal, strKeyHEX, strInitVector |
return value: |
(string) strResultHEX (result is HEX encoded) |
description: |
encrypts the plain string using the key. The key must be exactly 256 bit hex encoded (64 chars). strInitVector is the initialization vector when cbc is used. Leave blank for ecb. strAlgorithm can be one of the following ecb-aes-128, cbc-aes-128, ecb-aes-256, cbc-aes-256, ecb-tf-128, cbc-tf-128, ecb-tf-256, cbc-tf-256. |
example call: |
strEncrypted = cryptoEncrypt("ecb-tf-256", "something to hash","3082008B02820080A8FE1A91547476DD33F9809197FE56F3F61521EC7EECA593", ""); |
cryptoDecrypt
function: | cryptoDecrypt |
---|---|
parameters: |
strAlgorithm, strEncryptedHEX, strKeyHEX, strInitVector |
return value: |
(string) strResult (result is plain encoded) |
description: |
decrypts the encoded string using the key. The encrypted string must be hex encoded. The key must be exactly 256 bit hex encoded (64 chars). strInitVector is the initialization vector when cbc is used. Leave blank for ecb. strAlgorithm can be one of the following ecb-aes-128, cbc-aes-128, ecb-aes-256, cbc-aes-256, ecb-tf-128, cbc-tf-128, ecb-tf-256, cbc-tf-256. |
example call: |
strDecrypted = cryptoDecrypt("ecb-tf-256", "70B8BB6ED0ED64354A284157D8FCF12FA9918B1823CBAD8C5D6","3082008B02820080A8FE1A91547476DD33F9809197FE56F3F61521EC7EECA593", ""); |
cryptoRandom
function: | cryptoRandom |
---|---|
parameters: |
intBitlength |
return value: |
(string) strRandomHEX (result is hex encoded) |
description: |
generates a random, hex encoded key using a FIPS-140/X9.31/X9.17 compliant random number generator. Please choose the length. Possible values are : 8-16384 and must be a power of 8. |
example call: |
strRandom = cryptoRandom(256); |
cryptoGetMachineCode
function: | cryptoGetMachineCode |
---|---|
parameters: |
- |
return value: |
(string) strMachineCodeHEX (result is hex encoded) |
description: |
Returns a machine and hardware dependent 256 bit code (hex encoded). This is the same on the same hardware but changes if the hardware has changed (hard drive, network card etc.) |
example call: |
strMachineCodeHEX = cryptoGetMachineCode(); |
Advertising Functions
regifyDisplayAds
function: | regifyDisplayAds |
---|---|
parameters: |
*sess |
return value: |
(integer) intAdState |
description: |
Returns the state of advertising. If this function returns 1, you must use regifyGetAds() to get advertising information. This information has to be displayed to the user for a minimum of 10 seconds. The only exception is server side usage. If this function returns 0, you do not need to display ads at all. |
example call: |
intDisplayAds = regifyDisplayAds(sess); |
details: |
*sess is the current session context. The user needs to be logged in. |
regifyGetAds
function: | regifyGetAds |
---|---|
parameters: |
*sess |
return value: |
(string) strAds |
description: |
Returns the Ads to display. The result is a filename for the image to display and additional information about links and coordinates for the advertising image. |
details: |
*sess is the current session context. The user needs to be logged in. The result is a string with different dividers: Filename|Link;X;Y;Width;Height|Link;X;Y;Width;Height|… Filename is the local path to the file to get displayed. The following entries are the links and link area coordinates in the image that must open up upon clicking. Link = Link to open in case of a click X = X-coordinate of the link area Y = Y-coordinate of the link area Width = the width of the link area Height = the height of the link area There may be multiple link areas in one document! |
example call: |
strGetAds = regifyGetAds(sess); ⇒ |
Other Functions
regifyLastError
function: | regifyLastError |
---|---|
parameters: |
- |
return value: |
(integer) intErrorNumber |
description: |
Returns the error number of the last error occurred. Please use this function, if one of the other functions returned 0 or an empty string upon some error occurred. Refers to the error codes table in the error code chapter. |
example call: |
intError = regifyLastError(); |
regifyGetMetrics
function: | regifyGetMetrics |
---|---|
parameters: |
*sess |
return value: |
(string) Metrics in JSON format |
description: |
Returns metrics information about the current user (use only after calling regifyLogin() functions). Works only with regify provider V4.0.7 or newer. boxMax and boxCurrent are the allowed box size and the current usage in MegaBytes. rmMax and rmCurrent are the number of allowed regimails/month and the current value. |
example call: |
strMetricsJson = regifyGetMetrics(sess); |
details: |
*sess is the current session context. The user needs to be logged in. result:
|
regifyGetUsername
function: | regifyGetUsername |
---|---|
parameters: |
*sess |
return value: |
(string) Username |
description: |
Returns the login username of the currently logged in
user. |
example call: |
strUsername = regifyGetUsername(sess); |
details: |
*sess is the current session context. The user needs to be logged in. |
regifyGetRealUsername
function: | regifyGetRealUsername |
---|---|
parameters: |
*sess |
return value: |
(string) Username |
description: |
Returns the real and full name of the logged in user
including title. |
example call: |
strRealUsername = regifyGetRealUsername(sess); |
details: |
*sess is the current session context. The user needs to be logged in. |
regifyGetUserMailaddress
function: | regifyGetUserMailaddress |
---|---|
parameters: |
*sess |
return value: |
(string) email of the current user |
description: |
Returns the main email address of the logged in user. Works only after successfully calling regifyLogin() functions. Otherwise this will return an empty string and regifyLastError() returns error 66. |
example call: |
strUserMailaddress = regifyGetUserMailadress(sess); |
details: |
*sess is the current session context. The user needs to be logged in. |
regifyGetConfigCheckSum()
function: | regifyGetConfigCheckSum() |
---|---|
parameters: |
*sess |
return value: |
(string) Checksum |
description: |
Returns the configuration checksum returned by the provider during the last log in. Works only after successfully calling regifyLogin() functions. Otherwise this will return an empty string and regifyLastError() returns error 66. This check sum should be compared to the one returned in the confChkSum field in the regifyGetConfiguration() call. If the values differ, the configuration is stale and should be reloaded from the provider. |
example call: |
strConfChkSum = regifyGetConfigCheckSum(sess); |
details: |
*sess is the current session context. The user needs to be logged in. |
regifyAutoLogin
function: | regifyAutoLogin |
---|---|
parameters: |
*sess, strPage, strLanguage |
return value: |
(string) URL |
description: |
Returns a valid URL for opening in a webbrowser. Calling this link will create a new temporary session with a valid logged in web-browser session for the current user. Use only after calling regifyLogin() and regifySetAppData() function. strPage is the destination page on your regify provider. Common pages are "phpInvite.php", "phpMenu.php" or "phpAccountSummary.php". strLanguage defines the language to use for the link. Best to set this to your current application language (DE, EN, FR, CN). The returned URL can get passed through to the default webbrowser or a web-gadget etc. |
example call: |
strURL = regifyAutoLogin(sess, "phpInvite.php", "DE"); |
details: |
*sess is the current session context. The user needs to be logged in. Optimal order for calling this stuff:
|
regifyGetConfiguration
function: | regifyGetConfiguration |
---|---|
parameters: |
strEmail, strPassword, strRegifyServer, strProxyServer, strProxyUsername, strProxyPassword |
return value: |
(string) Configuration JSON Result or an Error message detailed in the regifyGetConfiguration JSON Result chapter. |
description: |
Returns the public configuration of the given provider when used with just the strRegifyServer parameter. When strEmail and strPassword are provided, user information such as the regify username are also included in the JSON. If the strRegifyServer is left blank, the provider lookup service is used to determine the provider where the given email address is registered. At least the strEmail and strPassword or the strRegifyServer parameter must be set, or the function returns an error. To initialize the proxy parameters needed for network connections, enter strProxyServer and strProxyUsername, strProxyPassword as needed. For more details see regifySetProxy() in the Connection Functions Chapter. |
example call: |
Returns full configuration
result:
Returns public configuration
result:
|
regifyResetPassword
function: | regifyResetPassword | ||
---|---|---|---|
parameters: |
strEmail, strProxyServer, strProxyUsername, strProxyPassword |
||
return value: |
(integer) a status code as detailed in the Error COdes chapter. |
||
description: |
Tries to initiate a password reset for given strEmail on the right provider using the PLS passwordReset. At least the strEmail parameter must be set, or the function returns an error. To initialize the proxy parameters needed for network connections, enter strProxyServer and strProxyUsername, strProxyPassword as needed. For more details see regifySetProxy() in the Connection Functions chapter. The maximum number of resets that can be done from any given IP number is limited to 10 per hour. After that error 54 is returned. If more resets than that need to be made, the provider must be used instead.
|
||
example call: |
Trigger a password reset intResult = regifyResetPassword("patrick@bikinibottom.com", "", "", "", ""); result: one of the following
|
regifyCleanup
function: | regifyCleanup |
---|---|
parameters: |
*obj |
return value: |
(integer) 1=ok, 0=error |
description: |
Use this function to release the resources used by an operation object like those created by regifyDecryptContainer() or the regifyCompose functions. |
example call: |
regifyCleanup(obj); |
regifyVersion
function: | regifyVersion |
---|---|
parameters: |
- |
return value: |
(string) strVersion |
description: |
Returns the current version of the SDK as string. The format is "Major.Minor.Patch-Build" |
example call: |
strVersion = regifyVersion(); result: 3.0.0-1234 |
regifyGetURL
function: | regifyGetURL |
---|---|
parameters: |
*sess, strURL |
return value: |
(string) strResult |
description: |
https://) |
example call: |
sess = regifyNewSession("", "", "", "", "") strPageContent = regifyGetURL(sess, "https://mypage/test.php"); result: some content returned by the page |
details: |
*sess is the current session context. The user does NOT need to be logged in. If you like to use this function together with a proxy server, please call regifySetProxy() prior to the call of this function. |
regifyGetURLFile
function: | regifyGetURLFile |
---|---|
parameters: |
*sess, strURL, strFilename |
return value: |
(integer) intResult |
description: |
Downloads the given URL to a local file defined in strFilename. Returns the file size or 0 in case of error. In case of error call regifyLastError() for details. |
example call: |
sess = regifyNewSession("", "", "", "", "") intResult = regifyGetURLFile(sess, "https://mypage/test.png", "/tmp/test.png"); result: 55238 |
details: |
*sess is the current session context. The user does NOT need to be logged in. If you like to use this function together with a proxy server, please call regifySetProxy() prior to the call of this function. |
regifySetSingleByteEncoded
function: | regifySetSingleByteEncoded |
---|---|
parameters: |
intIsSb |
return value: |
- |
description: |
Set the default string format. If intIsSb is 0, all string parameters and return strings are 2 byte Unicode. If intIsSb is not 0 all strings are assumed to be UTF-8. By default intIsSb is 0 and all strings are assumed to be Unicode. |
regifySetLogLevel
function: | regifySetLogLevel | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
parameters: |
intLogLevel |
|||||||||||||||||||||
return value: |
- |
|||||||||||||||||||||
description: |
Set the log level you need. Possible values are:
|
regifySetLogFilePath
function: | regifySetLogFilePath |
---|---|
parameters: |
strLogFile |
return value: |
- |
description: |
Set the filename for the log file you need. |
regifySetCaCertFile
function: | regifySetCaCertFile |
---|---|
parameters: |
strFilePath |
return value: |
- |
description: |
Complete file path to the PEM encoded file or directory of files containing the trusted public certificate authority keys. |
details: |
If not used, this will default to cacerts.pem in the program directory. |
regifySetReplyAddress
function: | regifySetReplyAddress |
---|---|
parameters: |
*sess, strReplyAddress |
return value: |
intResult (1 for success, 0 for failure) |
description: |
Set the reply address used in the regify file. If you do not set this value, the main email address defined in your regify provider will get used. You need to call this function after regifyLogin() and before regifyComposeRegiBill(), regifyComposeRegiMail() or regifyComposeRegiPay(). |
example call: |
regifySetReplyAddress(sess, "patrick@bikinibottom.com"); |
regifyGetUserdata
function: | regifyGetUserdata |
---|---|
parameters: |
*sess |
return value: |
(string) User data JSON |
description: |
Returns some user data of the currently logged in user. If some error occurred, this will return an empty string and regifyLastError() returns error number. |
example call: |
result = regifyGetUserdata(sess); result:
|
regifyGetSession
function: | regifyGetSession |
---|---|
parameters: |
*sess |
return value: |
(string) Current session data in encrypted format. |
description: |
Returns the current session data. Use this together with regifySetSession. |
example call: |
|
regifySetSession
function: | regifySetSession |
---|---|
parameters: |
strSessionData |
return value: |
intResult (1 for success, 0 for failure) |
description: |
Restores the current session using given encrypted data. This is the data provided by regifyGetSession(). A successful call returns a session obj. If the given session is valid, you can directly call all SDK functions without having to login first. Important: You can not use session data generated on other hardware than the originating system. It is encrypted with hardware based keys, like the cryptoGetMachineCode(). |
example call: |
|
regifySendEmail
function: | regifySendEmail |
---|---|
parameters: |
*sess, strFrom, strTo, strMime |
return value: |
intResult (1 for success, 0 for failure) |
description: |
Send the given strMime to the space separated list of recipient email addresses in strTo on behalf of strFrom. The address in strFrom must be a registered email address of the logged in user. You need to call this function after regifyLogin(). |
example call: |
|
details |
*sess is the current session context. The user needs to be logged in. strFrom the address on which behalf the email is sent. strTo a space separated list of recipient email addresses. strMime The mime of the email to send to the recipients. |
Best Practices
Best Practices for performing regify transactions using this SDK include:
Sending a regimail message
-
Set all the login parameters using regifyNewSession()
-
Optionally set the proxy using regifySetProxy()
-
Set regify application information using regifySetAppData()
-
Log into the provider using regifyLogin()
-
Optional get user name and email address using regifyGetUserMailaddress() and regifyGetRealUsername() and use this values to generate sender information (if needed)
-
Optionally set the reply address (if you do not like to use the main email address configured as main address in your regify provider). Use regifySetReplyAddress() function.
-
Generate all message components
-
Compose the container using regifyComposeRegimail()
-
Rename the container using the transaction id (see regifyGetTransactionIds())
-
Send the container using SMTP or any other transport mechanism (it is strongly recommended to validate the sending to avoid transactions that can never get delivered because the message never left the system)
-
Cleanup operation resources using regifyCleanup() function
-
Optionally perform another message operation (go to step #6)
-
Log the user out of the regify provider using regifyLogout()
-
Optionally log in as another user using regifySetUser() (go to step #3)
-
Cleanup session resources by calling regifyFreeSession()
Receiving a regify message
-
Receive the regify file (xxx.rgf)
-
Set all the login parameters using regifyNewSession()
-
Optionally set the proxy using regifySetProxy()
-
Set regify application information using regifySetAppData()
-
Log into the provider using regifyLogin()
-
Decrypt the regify file using regifyDecryptContainer() function
-
Parse the regify file using the regifyParse…() functions
-
Substitute placeholders
-
Display content
-
Cleanup session resources by calling regifyFreeSession()
Request a New Identity File
-
Set all the login parameters using regifyNewSession(). Please use the default identity file by assigning an empty string to strIdentityFile.
-
Optionally set the proxy using regifySetProxy()
-
Set regify application information using regifySetAppData()
-
Log into the provider using regifyLogin()
-
Call regifyRequestIdentityFile() function and submit a filename (remember, that you need write permissions to this destination).
-
If the function returns "1", the new identity file has been successfully created. Otherwise, please call regifyLastError() to check the error to determine whether a user aborted the transaction or whether a real error occurred.
-
Cleanup session resources by calling regifyFreeSession()
Code Samples
Creating a regimail
The following pseudo code snippet demonstrates how to create a regify rgf file.
/* environmental variables */
const char* myHome = "/home/foo/";
const char* proxyHost = "";
const char* proxyUsername = "";
const char* proxyPassword = "";
/* user related variables */
const char* regifyUrl = "https://regify.myprovider.com/";
const char* email = "foo.bar@company.com";
const char* password = "secret123";
const char* userName = "foo.bar";
const char* myName = "Foo Bar";
const char* identityFile = myHome + "user_identity.rif";
const char* providerData = NULL;
/* file related variables */
const char* file1 = myHome + "regify.png";
const char* files = "\{\"" + file1 + "\": \{}}";
const char* regifyFile = myHome + "regifytest.rgf";
const char* message = "regify make encryption easy.";
const char* recipient = email;
const char* subject = "Testing regify";
int reminderPeriod = 3;
int ret = 0;
if (providerData == "") {
/* we need get the configuration first to get the providerData for
the corresponding regifyUrl. We only need to do this once and can
store the configuration for subsequent use */
configJson.s = regifyGetConfiguration(email, password, regifyUrl,
proxyHost, proxyUsername,
proxyPassword);
void* jData = JSON_decode(configJson);
providerData = JSON_getString(jData, "providerData");
}
/* create a session */
void* sess = regifyNewSession(regifyUrl, providerData, userName,
password, identityFile);
if (sess == 0) {
ret = regifyLastError();
PrintN("ERROR: Session creation failed error: " + ret);
exit(ret);
}
/* set proxy if I have one */
if (proxyHost != "") {
regifySetProxy(sess, proxyHost, proxyUsername, proxyPassword);
}
/* set application information for provider (only regify staff!) */
regifySetAppData(sess, "regify client", "4.1.1-1039");
/* login */
If (regifyLogin(sess) == 0) {
ret = regifyLastError();
PrintN("ERROR: Login failed error: " + ret);
exit(ret);
}
/* create mail... */
void *obj = regifyComposeRegimail(sess, regifyFile, files, message,
recipient ,subject, myName, "",
reminderPeriod);
if (obj == 0) {
ret = regifyLastError();
PrintN("ERROR: Composing failed error: " + ret);
exit(ret);
}
/* retrieve the trans action id */
const char *transId = regifyGetTransactionIds(*obj);
if (transId == "") {
ret = regifyLastError();
PrintN("ERROR: No transaction ids found: " + ret);
exit(ret);
}
PrintN("OK: regify file successfully created. Transaction id: "
transId);
/* clean up the session, cleans up obj too. */
regifyFreeSession(sess);
exit(0);
Using the DLL in VB.NET
Please declare the functions like in this example:
<DllImport("regify2.dll", Entrypoint:="regifyVersion",
SetLastError:=True)> _
Private Function regifyVersion() As Integer
End Function
To receive string results, please use one of these functions:
' ANSI VERSION (older dll/so)
Private Function P2S(ByVal intPtr As Integer) As String
' Get ansi string from pointer
Return Marshal.PtrToStringAnsi(intPtr)
End Function
Debugger.WriteLine("Version:" + P2S(regifyVersion()));
' UNICODE VERSION (newer dll/so)
Private Function P2S(ByVal intPtr As Integer) As String
' Get unicode string from pointer
Return Marshal.PtrToStringUni(intPtr)
End Function
Debugger.WriteLine("Version:" + P2S(regifyVersion()));
Using the DLL in C#
Please declare the functions like in this example:
using System.Runtime.InteropServices;
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern int regifyLogin(int intSession);
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern IntPtr regifyVersion();
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern IntPtr regifyGetURL(string strURL);
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern int regifyLastError();
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern int regifySetLogLevel(int intLogLevel);
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern int regifySetLogFilePath(string strLogFile);
[DllImport("regify2.dll", CharSet = CharSet.Unicode,
CallingConvention = CallingConvention.StdCall)]
private static extern int regifySetSingleByteEncoded(int intIsSb);
// Help getting unicode string from pointer
private static string P2S(IntPtr lngPtr)
{
return Marshal.PtrToStringUni(lngPtr);
}
// Example usage
regifySetLogLevel(5); // verbose
regifySetLogFilePath("C:\temp\regify_log.txt"); // Windows
Console.WriteLine("DLL Version: " + P2S(regifyVersion()));
int sess = regifyNewSession("https://portal.regify.com/", "ProviderDataHEX", "Patrick", "password", "");
int Result = regifyLogin(sess);
Console.WriteLine("Result of Login: " + Result.ToString());
if (Result == 0)
{
Console.WriteLine("Failed Login with error code: " + P2S(regifyLastError()));
}
else
{
Console.WriteLine("Successfull Login!");
}
Error Codes
This table comprises all function related error codes returned by the regifyLastError() function. Please display the errors in the current user language. Some errors are more developer specific and may trigger an entry in the debug log file located in the same directory as your application. If you need more information about an error, please turn on logging and consult the specified debug log file.
Error | Description |
---|---|
1 |
Invalid session. Please check your internet connection. |
2 |
Missing parameters. |
3 |
Wrong protocol. Use a https:// connection for regify (SSL) in your configuration. |
4 |
Outdated regify client! |
5 |
Your regify provider does not support the regify provider lookup service. |
10 |
Invalid username or password. |
11 |
Invalid identity-file. |
12 |
Maximum 500 recipients allowed per operation |
13 |
The monthly transaction limit was reached. |
14 |
The monthly transaction limit for free transactions was reached. |
15 |
You reached the maximum number of transactions per second. Please try again later. |
16 |
Invalid session file. |
17 |
Invalid e-mail address for communication and notifications. |
18 |
Invalid login with old password. |
20 |
Sorry, but this transaction can not be opened. |
21 |
Sorry, but this transaction can not be opened. The sender of this transaction stated, that the recipient needs to be authenticated. |
22 |
The message gets not opened, because you decided that the senders authentication level is not sufficient. |
23 |
The clearing service will not deliver this message key because of invalid sender information. |
24 |
The clearing service can not deliver the key, since the sender (or his regify provider) prohibited delivery through clearing-roaming. |
25 |
Sorry, but this transaction can not be opened, because you are not the desired recipient. |
30 |
The identity file cannot be delivered. Please note that you need to be authenticated. |
40 |
Your regimail professional membership has expired. |
42 |
Your unlock code is not valid for this identity file! |
43 |
You are not allowed to post regibill transactions. |
44 |
You are not allowed to post regipay transactions. |
45 |
One of the recipients e-mail addresses is blocked by your regipay exclusion filter list.\nAffected address: <VAL2> |
46 |
You are not allowed to create your own regiboxes. |
47 |
This regibox exceeds its size limit. |
48 |
The regibox could not be found. |
52 |
A problem occurred while securely accessing the internet (SSL/TLS handshake failed). |
53 |
Your regify provider currently has regibox in maintenance mode. Please try again later. |
54 |
It is not possible to reset your password more than 10 times per hour. Please wait at least 1 hour before trying again. |
55 |
The regify Provider Lookup Service (PLS) was not able to determine your assignment to a regify provider. |
56 |
Your regify provider is currently in maintenance mode. Please try it later. |
57 |
The regify Clearing Service is currently in maintenance mode. Please try it later. |
58 |
Can not connect to the regify provider. |
59 |
Internet connection problem (check if proxy is needed). |
60 |
File not found: NAME |
61 |
No decrypted regify file available |
62 |
Header-information not found |
63 |
FileID not allowed |
64 |
Missing parameter. Please ensure, that you use the newest program-version. |
65 |
Can not open the identity-file. |
66 |
You need to be connected to a regify provider for this function. |
67 |
Please compose a regify file at first. |
68 |
The program runs out of memory. Please consider sending smaller attachments. |
69 |
A file can not be opened. Please check your paths and user-rights. |
70 |
Sorry, but the program can not access the user-home directory. Please check your rights. |
71 |
Wrong parameter length. Please ensure, that you use the newest program-version. |
72 |
One or more e-mail addresses are not valid. |
73 |
Error while copying to the destination path. Please check your rights. |
74 |
There is no valid regibill information in this document. |
75 |
Missing regify system dependencies (check needed .dll / .so). Please re-install the software. |
76 |
You need to be connected using a sufficiently authenticated account (using your individual identity file). |
77 |
Invalid parameter. |
78 |
The given file is already a regibill file. |
79 |
Only one recipient allowed for each message. |
80 |
This message uses a compression or encryption algorithm that is not supported by your regify client. |
81 |
The regify provider signature is missing or invalid. |
82 |
The regify provider response signature is invalid. |
83 |
The file "NAME" can not get opened or displayed. Access to external storage has been denied. |
84 |
The PDF document "NAME" could not be processed. |
85 |
Sorry, but the program can not write the path "<FILE>". Please check your permissions. |
97 |
Your regify provider does not support this function. Please contact your regify provider support to find out if this feature will get supported in the future. |
98 |
User aborted |
99 |
Sorry, but an internal server error occurred Please contact your corresponding program support. |
200 |
Invalid or not readable certificate. |
201 |
The e-mail address of your certificate is not congruent with your regify user data. |
202 |
The name information of your certificate is not congruent with the data in your regify account. |
203 |
In order to authenticate you, your mobile phone number needs to be entered at your regify account data. |
204 |
We were not able to send you your unlock code via SMS. |
205 |
Your regify provider does not support this authentication method. |
206 |
You do not have enough permissions to complete this operation. |
regifycmd Utility
The regifycmd utility allows creation and extraction of regify files by command line. While the regify client software manages the identity file and login information by itself, the regifycmd utility manages nothing of this aspects and works like a raw implementation. It was initially developed as a backend for web portal integration of regify enabled platforms.
It is available as windows, Mac OS X and Linux executable. The examples are using the Linux as well as the windows executable. The only difference, on Linux and Mac you have:
regifycmd <parameters>
while on Windows you substitute it with:
regifycmd.exe <parameters>
Pathes on Linux and Mac are separated with / and on Windows with \.
Command Line Parameters
The regifycmd utility knows several modes of operation:
-
creation of regify files, regipay and regibill documents
-
extraction of regify files
-
validation of regibill documents
-
receive and decrypt users identity file
General Parameters
Running regifycmd -h will produce the following help output
regifycmd.exe - regify commandline utility version 3.4.0-1397.win32 (c) 2008-2016 regify S.A. Usage: regifycmd <OPERATIONS> <COMMON PARAMETERS> <SPECIFIC PARAMETERS> MISCELLANEAOUS OPTIONS: -c Path to the SSL certificate authority file or directory. -h This output. -l Specifies log file to log to. No logging will be done without this. -q Quiet mode. Do not output anything to STDOUT. Returns the error code or 0 upon success. If -w is set, the error code alone is written to the output file. -v Verbose mode. Increases log level to verbose. Requires -l. -w Write output to given filename incl. path. With -q only the error code or 0 upon success. -x Proxy protocol, host and port (like 'http://host:8080/') -y Proxy username:password (password is optional) Requires -x. -t Optional transactional session file for persistent connections. -T Transactional session file for persistent connections. If file exists it must be valid, else an error will be generated. OPERATIONS: -A Get metrics / accumulators. -D Decrypt. -M Create regimail. -P Create regipay. -B Create regibill. -S Create regibill standard. -I Get identity file. -G Show identity file. -V Verify regibill standard. -C Get configuration. -E Extract (Get) user data. -R Password reset COMMON PARAMETERS: -u regify Username. -p regify Password or SHA1 of password. -f The complete filename of the identity file to use. -U The URL to reach the regify service (https://portal.regify.com). -k The provider data associated with the regify service (0|94F47D0...). DECRYPTING: -i The complete filename incl. path to the regify file to open. -o The folder in which To extract the content message body is always named body.asc or body.html. CREATING REGIMAIL, REGIBILL OR REGIPAY: -e Optional regify communications email address of the sender. Must be registered/assigned to the used regify account (overrides -a). -i The folder, in which all the main body and optional upload.json can be found. Please use body.asc or body.html for the message (ASCII Or html). -o The complete filename incl. path to the regify file to create (overwrite!). Use #id (lower case) as placeholder to insert the transaction id into the filename. -s The subject for the message (use quotation marks). -r One (regibill/regipay) or more (regimail) recipient mailaddresses divided using semicolon (;). -n The full name of the sender. -a Similar to -e, but does not affect regify specific communication. -d How many days this transaction will be active. CREATING A REGIBILL STANDARD PDF: -i The complete filename incl. path to the input PDF. To also upload the document for archiving specify a .json file containing { "/path/to/file.pdf": { "upload": true, "meta": ["tag1", "tag2", ...] } } The 'meta' parameter is optional. -o The complete filename incl. path to the regibill PDF to create (overwrite!). -s The subject for the message (use quotation marks, optional value). -r The recipient mailaddresse. -n The full name of the sender. VALIDATING A REGIBILL STANDARD PDF: -i The complete filename incl. path to the regibill PDF to validate. -o The complete filename incl. path to the result file to create (overwrite). GETTING IDENTITY FILE: -o The complete filename of the new identity file to collect. -Q The question for unlock code in the current language. -d Save identity file unencrypted (default is encrypted). -L The code to unlock the identity file. SHOWING IDENTITY FILE: -i The complete filename of the new identity file to show. -o The complete filename incl. path to the result file to create (overwrite). GETTING THE CONFIGURATION: -e Email address registered with regify. Optional if URL is specified. -p regify Password or SHA1 of password. Optional if URL is specified. -U The URL to reach the regify service (https://portal.regify.com). Optional if email and password are specified. -o The complete filename incl. path to the result file to create (overwrite). GETTING THE USER DATA: -o The complete filename incl. path to the result file to create (overwrite). RESETTING THE PASSWORD: -e Email address registered with regify for which the password is to be reset. Examples: Creating a regimail document: regifycmd -M -o 'regimail.rgf' -i 'InputDir' -u 'Username' \ -p 'Password' [-f 'IdentityFile'] -s 'Subject' -d 3 -e 'sender@domain.com' \ -r 'recip1;recip2' -n 'sendername' -U 'regifyURL' -k '0|94F47D...' Creating a regibill or regipay document: regifycmd -M -o 'regimail.rgf' -i 'InputDir' -u 'Username' \ -p 'Password' -f 'IdentityFile' -s 'Subject' -d 3 -e 'sender@domain.com'\ -r 'recip1;recip2' -n 'sendername' -U 'regifyURL' -k '0|94F47D...' Decrypting a regify document: regifycmd -D -i 'regimail.rgf' -o 'OutputDir' -u 'Username' \ -p 'Password' [-f 'IdentityFile'] -U 'regifyURL' -k '0|94F47D...' Getting an identity file: regifycmd -I -o 'DestFile' -u 'Username' -p 'Password' \ -Q 'Question' [-d] -L 'UnlockCode' -U 'regifyURL' -k '0|94F47D...' Showing an identity file: regifycmd -G [-i 'IdentityFile'] -o 'DestFile' Creating a regibill standard document: regifycmd -S -o 'regibill.pdf' -i 'bill.pdf' -u 'Username' \ -p 'Password' -f 'IdentityFile' -r 'recipient' -n 'sendername' \ -U 'regifyURL' -k '0|94F47D...' Validating a regibill standard document: regifycmd -V -i 'regibill.pdf' -o 'result.txt' [-U 'regifyURL'] Getting the configuration: regifycmd -C [-e 'email@domain.com' -p 'Password'] [-U 'regifyURL'] -o 'config.json' Getting user data: regifycmd -E -o 'DestFile' -u 'Username' -p 'Password' \ [-f 'IdentityFile'] -U 'regifyURL' -k '0|94F47D...' Getting user metrics: regifycmd -A -o 'DestFile' -u 'Username' -p 'Password' \ [-f 'IdentityFile'] -U 'regifyURL' -k '0|94F47D...' Initiate a password reset: regifycmd -R -e 'email@domain.com' It is recommended to cover each parameter using quotation marks. It is absolutely needed in case of spaces or other special chars.
Creation of regify Files
Command Line Syntax
The same syntax as regimail applies to regipay or regibill, depending on which switch you use -M, -P or -B. The identity file is optional for regimail.
regifycmd -M -o <RegifyFile> -u <Username> -p <Password> [-f <IdentityFile>] -s <Subject> -e <SenderAddress> -r <Recipients> -n <SenderName> -i <InputDir> -d <Days> -U <RegifyURL> -k <ProviderData>
Parameter | Description |
---|---|
-M |
Tells regifycmd to create a regimail file. |
RegifyFile |
the complete filename incl. path to the regify file to create (existing file will be overwritten!). You can insert #id (lowercase) to let the regifycmd utility replace this #id with the transaction id of the initiated transaction. |
Username |
regify username |
Password |
regify password or SHA1 of password |
IdentityFile |
the complete filename of the identity file to use |
Subject |
the subject for the message |
SenderAddress |
the address of the sender |
Recipients |
one or more recipient email addresses divides using semicolon |
SenderName |
the full name of the sender |
InputDir |
the folder, in which all content can be found. Please use body.asc or body.html for the message (ASCII- or html- format). Optionally use upload.json for defining the input files. All other files inside this folder will be included as additional attachments to the generated regify file. |
Days |
how many days this transaction will be active |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
ProviderData |
the providerData field of the regifyGetConfiguration JSON Result response |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes. The given order of the command line options does not matter.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
Input Description
The regify file will be created with the given parameters. The body of the new regify file will be created using a file that is named body.asc or body.html (use .asc for ascii body and .html for html encoded body). The attachments of the new regify file will be specified by an optional JSON file called upload.json found inside the InputDir. If this is not given, all files are getting included.
Sample upload.json
{
"/tmp/regifydir/invoice_678432.pdf" : {
"upload" : true,
"meta": [ "bzu54r2bzu", "€99.95" ]
},
"/home/me/marketing/marketing_flyer.pdf" : { },
"/home/me/invoices/invoice_126742.pdf" : {
"upload" : true,
"meta": [ "Invoice#=asd21r2f00", "Total=$23" ]
},
"/home/me/sales/special_offer.pdf" : { "upload" : false }
}
Example Call
regifycmd -M -o "/home/me/testfile_#id.rgf" -u "regifyUser" -p "regifyPass" -f "/home/me/my_identity.rif" -s "hi peter" -r "peter@inter.net;alice@inter.net" -n "Lois Lane" -i "/tmp/regifydir/" -d "5" -U "https://portal.regify.com" -k "2|11E6B3F59E..."
This will create a regimail file /home/me/testfile_XX.rgf. The sender is authenticated using regifyUser + regifyPass and the identity file /home/me/my_identity.rif. The message subject is hi peter. The message body is created by reading body.asc or body.html in this folder. Due to the -d "5" switch, this message will trigger a reminder email after 5 days. As specified in the above upload.json, it will have the following attachments:
-
invoice_678432.pdf to be uploaded and tagged with bzu54r2bzu and €99.95
-
marketing_flyer.pdf
-
invoice_126742.pdf to be uploaded and tagged with Invoice#=asd21r2f00 and Total=$23.
-
special_offer.pdf
Open and Extract regify Files
Command Line Syntax
regifycmd -D -i <RegifyFile> -u <Username> -p <Password> [-f <IdentityFile>] -o <OutputDir> -U <RegifyURL> -k <ProviderData>
Parameter | Description |
---|---|
-D |
tells regifycmd to decrypt a regify file. |
RegifyFile |
the complete filename incl. path to the regify file which should be opened. |
Username |
regify username |
Password |
regify password or SHA1 of password |
IdentityFile |
the complete filename of the identity file to use |
OutputDir |
the folder, in which all content should be extracted. The message body will be named Body.asc or Body.html corresponding to the type of message. The other attachment will be extracted directly to this folder. |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
ProviderData |
the providerData field of the regifyGetConfiguration() JSON response |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message>
ERROR: <Message>
The <Message> contains a short additional information about the state.
Output Description
The regifycmd utility stores all extracted attachments into the OutputDir folder. Some additional information is stored using special filenames:
Filename | Description |
---|---|
_r_Body.asc |
The body of the message in ASCII format. This file is only created, if the message content has been created in ASCII format. |
_r_Body.html |
The body of the message in HTML format. This file is only created, if the message content has been created in HTML format. |
_r_Subject.asc |
The subject of the message in ASCII format. |
_r_Sender.asc |
The sender addresses in ASCII format. |
_r_Recipient.asc |
The recipient addresses in ASCII format. |
_r_CreationDate.asc |
The message creation date in the following format: YYYY/MM/DD HH/MM/SS Info: This is the time of the sending computer while creation process of the regify file. It is not a certified date. |
_r_SenderAuth.asc |
The senders authentication information. It is exactly the string of the regify file header. The content is described in the regify file format documentation. This output is available since regifycmd V1.3.0.1. |
Example Call
regifycmd -D -i "/home/me/testfile_234.rgf" -u "regifyUser" -p "regifyPass" -f "/home/me/my_identity.rif" -o "/home/me/extractedData/" -U "https://portal.regify.com" -k "0|11E6B3F59E..."
This will open and extract regify file /home/me/testfile_234.rgf. The recipient is authentificated using regifyUser + regifyPass and the identity file /home/me/my_identity.rif. The content of the regify file will be extracted to the folder /home/me/extractedData/. The message body will be in the file named Body.asc or Body.html.
Creating regibill Standard Documents
Command Line Syntax
regifycmd -S -i <PdfFile> -u <Username> -p <Password> -f <IdentityFile> -o <RegibillDocument> -U <RegifyURL> -r <Recipient> -n <SenderName> -k <ProviderData>
Parameter | Description |
---|---|
-S |
tells regifycmd to create a regibill standard document. |
PdfFile |
the complete filename incl. path to the PDF file to be converted. To also upload the document for archiving specify a .json file containing a single filePath entry as specified in the strFileList Explained chapter. The regibill parameter may be omitted here. |
Username |
regify username |
Password |
regify password or SHA1 of password |
IdentityFile |
the complete filename of the identity file to use. This cannot be the default identity file. |
RegibillDocument |
the complete filename incl. Path under which the generated regibill document will be stored. Any existing file at that location will be overwritten. |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
Recipient |
the recipients email address. |
SenderName |
the full name of the sender (optional) |
ProviderData |
the providerData field of the regifyGetConfiguration() JSON response |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Call
regifycmd -S -i "/home/me/testbill.pdf" -u "regifyUser" -p "regifyPass" -f "/home/me/my_identity.rif" -o "/home/me/testbill_regibill.pdf" -U "https://portal.regify.com" -r "alice@inter.net" -n "Lois Lane" -k "0|11E6B3F59E..."
This will open and convert the PDF document /home/me/testbill.pdf into a regibill standard document located at /home/me/testbill_regibill.pdf. The sender is authentificated using regifyUser + regifyPass and the identity file /home/me/my_identity.rif. The recipient is alice@inter.net.
Verifying regibill Standard Documents
Command Line Syntax
regifycmd -V -i <RegibillDocument> -o <JsonResult> [-U <RegifyURL>]
Parameter | Description |
---|---|
-V |
tells regifycmd to verify a regibill standard document. |
RegibillDocument |
the complete filename incl. Path of the regibill document to verify. |
JsonResult |
the complete filename incl. Path under which the return Json result will be stored. Any existing file at that location will be overwritten. |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) (optional) |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Call
regifycmd -V -i "/home/me/testbill_regibill .pdf" -o "/home/me/json_result.txt" -U "https://portal.regify.com"
This will verify the regibill standard document located at /home/me/testbill_regibill.pdf. The results will be store using JSON notation in /home/me/json_result.txt and might look like this:
{
"Filename" : "testbill_regibill.pdf",
"Result" : "valid",
"Recipient" : "alice@inter.net",
"ValidationDate" : "2011/07/18 17:11:13",
"ValidationProvidername" : "regify demo portal",
"ValidationProviderURL" : "http://portal.regify.com",
"SenderAuthType" : "person",
"SenderAuthName" : "Lois Lane",
"SenderAuthOrganisation" : "",
"SenderAuthVATID" : "DE9673421",
"SenderAuthLevel" : "5",
"SenderAuthIssuer" : "regify demo portal",
"SenderAuthDate" : "2011-05-04 10:42:07 UTC",
"DocumentCreationDate" : "2011/07/18 17:11:13",
"DocumentHashcode" : "7C71BAF9D67523B5B6A1DBA188AB46A72C4D83F3BE8A2770CAC05671018C38CE",
"DigestHashcode" : "A70FB75477D5C3AF3BE436747B26AAE4BD1B6194E698DE0D26567FCCB7BA7F7C"
}
Receive Users Identity File
Command Line Syntax
regifycmd -I -u <Username> -p <Password> -o <DestinationFile> -U <RegifyURL> -k <ProviderData> [-Q \{<Title>}] [-d]
Parameter | Description |
---|---|
-I |
tells regifycmd to retrieve an identity file. |
Username |
regify username |
Password |
regify password or SHA1 of password |
DestinationFile |
the complete filename of the new identity file to create |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
ProviderData |
the providerData field of the regifyGetConfiguration() JSON response |
Title (optional) |
the text that will be shown as the question for the unlock code of a new identity file. If you don’t enter something, the following text will be used (English): "Please enter the unlock code in order to unlock your identity file:" |
-d (optional) |
When -d is specified the received identity file will be stored unencrypted. The default is to store the file encrypted. |
UnlockCode(optional) |
enter the unlock code for the identity file to receive. Leave empty to open a predefined dialog to get the unlock code from the user. This parameter allows you to use regifycmd in unattended mode. This parameter is only available in versions since February 2011. |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
The identity file normally will be saved in encrypted format. This encryption key is generated using hardware dependend information. This means that this identity file will only work on this machine and can not get copied to another computer. This works also on citrix clusters. |
Example Call
regifycmd -I -u "regifyUser" -p "regifyPass" -o "/home/me/personal_identity.rif" -U "https://portal.regify.com" -Q "Please enter unlock code:" -d -k "0|11E6B3F59E..."
This will connect to the provider to receive the file personal_identity.rif. The regifycmd utility will always display its own dialog for getting the unlock code from the user. The identity file will be stored decrypted.
Showing Users Identity File
Command Line Syntax
regifycmd -G -i <IdentityFile> -o <DestinationFile>
Parameter | Description |
---|---|
-G |
tells regifycmd to show an identity file. |
IdentityFile |
the complete filename of the identity file to show |
DestinationFile |
the complete filename where the resulting JSON will be written to |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Call
regifycmd -G -i "/home/me/personal_identity.rif" -o "/home/me/identity.jsn"
This will try to open the identity file personal_identity.rif and display its contents as a JSON array.
Getting the User Data
Command Line Syntax
regifycmd -E -u <Username> -p <Password> [-f <IdentityFile>] -o <DestinationFile> -U <RegifyURL> -k <ProviderData>
Parameter | Description |
---|---|
-E |
tells regifycmd to request the user data. |
Username |
regify username |
Password |
regify password or SHA1 of password |
IdentityFile |
the complete filename of the identity file to use. |
DestinationFile |
the complete filename incl. Path under which the generated regibill document will be stored. Any existing file at that location will be overwritten. |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
ProviderData |
the providerData field of the regifyGetConfiguration() JSON response |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Call
regifycmd -E -u "regifyUser" -p "regifyPass" -f"/home/me/my_identity.rif" -o "/home/me/userdata.jsn" -U "https://portal.regify.com" -k "0| 11E6B3F59E..."
This will connect to the provider and download the user data after verifying the given password. The result will be stored in /home/me/userdata.jsn.
Getting the User Metrics
Command Line Syntax
regifycmd -A -u <Username> -p <Password> [-f <IdentityFile>] -o <DestinationFile> -U <RegifyURL> -k <ProviderData>
Parameter | Description |
---|---|
-A |
tells regifycmd to request the user metrics. |
Username |
regify username |
Password |
regify password or SHA1 of password |
IdentityFile |
the complete filename of the identity file to use. |
DestinationFile |
the complete filename incl. Path under which the generated regibill document will be stored. Any existing file at that location will be overwritten. |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
ProviderData |
the providerData field of the regifyGetConfiguration() JSON response |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message> ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Call
regifycmd -A -u "regifyUser" -p "regifyPass" -o "/home/me/usermetrics.jsn" -U "https://portal.regify.com" -k "0|11E6B3F59E..."
This will connect to the provider and download the user data after verifying the given password. The result will be stored in /home/me/usermetrics.jsn.
Getting the Configuration
Command Line Syntax
regifycmd -C -e <Email> -p <Password> -U <RegifyURL> -o <DestinationFile>
Parameter | Description |
---|---|
-C |
tells regifycmd to retrieve the configuration. |
An email address registered at regify |
|
Password |
regify password or SHA1 of password of the account where the email address is registered under. |
DestinationFile |
the complete filename where the resulting JSON will be written to |
RegifyURL |
the URL to reach the regify service (https://www.regify.com) |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message>
ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Calls
regifycmd -C -e "user@domain.com" -p "regifyPass" -o "/home/me/configuration.jsn" -U "https://portal.regify.com"
This will connect to the provider and download the configuration data after verifying the given password. The result will be stored in /home/me/configuration.jsn.
regifycmd -C -e "user@domain.com" -p "regifyPass" -o "/home/me/configuration.jsn"
This will determine the provider via provider lookup service, connect to the provider and download the configuration data after verifying the given password. The result will be stored in /home/me/configuration.jsn.
regifycmd -C -U "https://portal.regify.com" -o "/home/me/configuration.jsn"
This will connect to the provider and download the public configuration data. The result will be stored in /home/me/configuration.jsn.
Resetting the Password
Command Line Syntax
regifycmd -R -e <Email>
Parameter |
Description |
-R |
tells regifycmd to initiate a password rest. |
An email address registered at regify |
It is recommended to cover all parameters that may contain spaces or special chars using double quotes.
The regifycmd utility returns two kind of message to the command line prompt:
OK: <Message>
ERROR: <Message>
The <Message> contains a short additional information about the state.
Example Calls
regifycmd -R -e "user@domain.com"
This will look up the provider using PLS and initiate a password reset at the given provider.
Appendix
regifyValidateRegibillPDF JSON Result
The JSON encoded result of regifyValidateRegibillPDF() function contains the following fields:
Field Name | Field Description | Type |
---|---|---|
Filename |
The filename of the validated document. |
S |
Result |
The result of the validation. Possible results: "valid", "invalid" |
S |
Recipient |
The desired recipient of this document. |
S |
ValidationProvidername |
The name of the provider who generated this report. |
S |
ValidationProviderURL |
The URL used to generate this report. |
S |
ValidationDate |
The date of this report (now). |
D |
SenderAuthType |
The type of authentication the sender provides. Possible results: "person", "organisation" |
S |
SenderAuthName |
The name of the sender. |
S |
SenderAuthOrganisation |
The name of the senders organisation. |
S |
SenderAuthVATID |
The VAT ID number of the sender. |
S |
SenderAuthLevel |
The authentication level of the senders authentication. |
N |
SenderAuthIssuer |
The organisation who provided the senders authentication. |
S |
SenderAuthDate |
The date the sender has been authenticated. |
D |
DocumentCreationDate |
The date the message digest has been generated. |
D |
DocumentHashcode |
The validated hash code of the regibill document (HEX encoded). |
S |
DigestHashcode |
The validated hash code of the regibill digest (HEX encoded). |
S |
regifyGetConfiguration JSON Result
The JSON encoded result of regifyGetconfiguration() function contains the following fields:
Field Name | Description | Type |
---|---|---|
confChkSum |
The check sum of the current configuration. Should be compared against the one returned by regifyGetConfigCheckSum() after logging in. When they differ the configuration is stale and should be reloaded. |
S |
providerUrl |
The URL of this provider. |
S |
maxUploadSize |
The maximum number of bytes that can be uploaded for archiving if given. |
N |
messageBodyHtml |
The content to use as default message in HTML format. |
SB |
messageBodyPlain |
The content to use as default message in plain text format. |
SB |
providerData |
The provider signature data. This data must be supplied when specifying a provider using regifyNewSession() or regifySetProvider() |
S |
providerHomepage |
The homepage url of this provider. |
S |
providerLogo |
The logo image of this provider. This is a base64 encoded PNG image binary for saving into Logo.png. The customization dialog allows to upload the Logo.png. It should be a PNG file with transparent background (alpha channel). |
SB |
providerName |
The name of this provider. |
S |
providerUrl |
The URL of the provider |
S |
proxyPassword |
The password used for proxy access (if given). |
S |
proxyServer |
These fields contain the proxy settings in case the client SDK used a proxy. |
S |
proxyUsername |
The username used for proxy access (if given). |
S |
rulesServerId |
The id to be used for the regify Rules Server. |
S |
supportContact |
Additional contact information for technical support (most time this is a phone number). |
S |
supportEmail |
The email address to display for support. |
S |
timeZone |
The time zone this provider is running on. |
S |
user |
The regifyGetUserdata JSON Result (if credentials were specified) |
SJ |
It is important to respect, that some values may not be given (missing or empty). Try to use good default values in that case.
*1) Type format values:
S = String
D = Date in "YYYY/MM/DD HH:MM:SS" format
N = Numeric Value
SB=String (base64 encoded)
SJ=JSON String
regifyGetUserdata JSON Result
The JSON encoded result of regifyGetUserdata() function contains the following fields:
Field Name | Field Description | Type1 |
---|---|---|
accountType |
Whether this user can send regibill, regipay or is regimail private. |
S |
address1 |
The address line 1. |
S |
address2 |
The address line 2. |
S |
authentication |
Authentication JSON Result] (if user is authenticated) |
SJ |
city |
The city name. |
S |
company |
The organisation name of the user. |
S |
country |
The country name. |
S |
creationDate |
The date the user signed up. |
D |
emails |
All registered email addresses divided by comma. |
CS |
firstName |
The first name of the user. |
S |
groupId |
The id of the group. Is 0 if user is not grouped. |
N |
language |
The language code (DE, EN or FR). |
S |
lastActivity |
The date the user last used regify. |
D |
lastname |
The last name of the user. |
S |
mainEmail |
The main email address of the user. |
S |
newsletter |
Whether this user subscribes to the newsletter. |
N |
phone |
The land line phone number of the user. |
S |
phoneMobile |
The mobile phone number of the user. |
S |
realName |
The complete real name of the user. |
S |
salesId |
The sales id of the user. Used for accounting. |
S |
sendingAllowedUntil |
The date until the user is regimail premium. If this date is in the past, user is regimail private or regimail standard. |
D |
titleName |
The title of the user. |
S |
userId |
The id of the user |
N |
userName |
The account name the user logs in with. |
S |
vatNumber |
The VAT number of the user or his organisation. |
S |
zipcode |
The ZIP code. |
S |
*1) Type format values:
S = String
D = Date in "YYYY/MM/DD HH:MM:SS" format
SJ=JSON String
N = Numeric Value
CS=Comma Separated Strings
Authentication JSON Result
The JSON encoded result of the authentication field of regifyGetUserdata() function contains the following fields:
Field Name | Field Description | Type |
---|---|---|
authLevel |
The current authentication level of the user (0=not authenticated). |
N |
identityName |
The complete real name of the user used for authentication. |
S |
IdentityOrganization |
The organisation name of the user used for authentication. |
S |
keyDate |
The date the key was generated. |
D |
ownerType |
Type (person, organisation etc.) |
S |
publicKey |
Public key in Hex |
SH |
unlockReturnInformation |
The registered phone number to use to retrieve unlock code. |
S |
vatNumber |
Tax number (if part of authentication) |
S |
*1) Type format values:
S = String
SH=String (hex encoded)
D = Date in "YYYY/MM/DD HH:MM:SS" format
regifyGetIdenity JSON Result
The JSON encoded result of regifyGetIdentity() function contains the following fields:
Field Name | Description | Type |
---|---|---|
IdentityHash |
Hash of parts to the identity |
SH |
PublicCertificate |
Parts of the identity | Concatenated together |
S |
OwnerName |
Name of the owner of the key |
S |
KeyDate |
Issue date of identity file |
S |
ProviderName |
Name of the provider |
S |
PublicKey |
Public key in Hex |
SH |
OwnerOrganisation |
Organization of the owner |
S |
VATNumber |
Tax number (if part of authentication) |
S |
OwnerType |
Type (person, organisation etc.) |
S |
AuthLevel |
Authentication Level (0-10) |
S |
ProviderID |
Id of the provider |
S |
UserID |
Identity file id (user id) |
S |
KeyLength |
Bit length of Key (1024, 2048 etc.) |
S |
KeyType |
Key algorithm (RSA etc.) |
S |
It is important to respect, that some values may not be given (missing or empty). Try to use good default values in that case.
Type format values:
S = String
SH=String (hex encoded)
regify Service Overview
Common Problems and Solutions (Developer FAQ)
This will help you to solve some common problems that may occur for developers.
Q: The recipients have problems displaying my text using umlaute.
A: You need to convert all given strings using umlaute to UTF-8 encoded strings before using them with the SDK. This especially affects the subject, real names and the message body.
Q: I use ASCII encoded body but linebreaks are getting ignored while displaying in regify client.
A: Try to encode your body content using UTF-8.
Q: I use HTML encoded body but umlaute are not correctly displayed.
A: Try to encode your body content using UTF-8. Alternatively, please remember that special chars er getting represented using HTML codes. To encode „®“ you have to enter „®“ and to encode „>“ you have to enter „>“ in your HTML text.
Q: Login using usernames with umlaute or special chars fails.
A: Try to change username encoding between UTF-8 and ASCII. This mostly helps.
Individual Placeholder Substitution
As the sender assumes that all available placeholders are getting replaced with the substituted values, you should implement the replacement of the following placeholders just before displaying the message:
placeholder | description |
---|---|
[LANGUAGEID] |
Please replace this with an ID that indicates the language your user
speaks. (if you need another language, please contact regify support at support@regify.com). |
Document History
31. Oct 2007DLL V1.3
regifyParseExtractFile() function has a new parameter to switch between
checking the signature of each file or not.
Internal change for new CKeyAndHash value of protocol.
13. Nov 2007DLL V1.3.1
regifyRequestIdentityFile() function has a new parameter to change between encrypted and unencrypted storage of the requested identity file.
regifycmd utility features a new parameter for storing requested identity files in encrypted or not encrypted format.
regifycmd utility outputs the console output (OK… ERROR…) to a file called 'regifycmd.out', too. Please refer the three function references for more information about the location of this file.
01. Jun 2008 DLL V1.4
Only some small bugfixes and a final new release with much better documentation.
05. Dec 2008DLL V1.5.2
New function regifyParseTransactionID() to receive the transaction id after calling regifyDecryptContainer().
The placeholder substitution is included.
09. Jan 2009DLL V1.5.3
New function regifyConnectHash() to allow provider connection by giving the SHA1 hash code of the password as parameter (instead of the plain password).
Added the new function CryptoSHA1().
03. Aug 2009DLL V1.5.11
Internal change to new protocol using POST instead of URL Encoding for "Data". Currently, this is used only for the regifyInitiateTransaction() function.
01. Oct 2009DLL V1.5.12
New "AuthLevel" parameter in identity files. Affects "certificate" entry in regify files.
The function regifyDecryptContainer() now may return an additional result to show unsuccessfull sender identity validation (returns 2 instead of 1).
The function regifyParseSenderAuthenticated() now returns the authentication level instead a simple status (0 to 10).
17. Nov 2009DLL V1.5.18
Actualized some information about placeholders and authentication levels.
Document structure cleaned up (some headlines have been corrupt).
22. Dec 2009DLL V1.6.1
Function regifyInitProvider() is deprecated. The new function to connect a regify provider is regifyInitConnection() and allows usage of proxy username and password. You still can call the old function for compatibility (without proxy settings).
REGIFYCMD.EXE does no longer support a <port> parameter.
You may need to adapt your software! |
18. Jan 2010DLL V1.6.2
Fixed internal bug while displaying identity information of sender using regifyDisplayIdentityFile() function (missing AuthLevel).
22. July 2010DLL V1.6.6
Fixed handling of identity information to correctly use UTF-8 encoding in certificate header entry.
New function regifyGetURL() to retrieve URL contents from the web.
25. October 2010DLL V1.6.8
New functions regifyGetUserMailaddress() and regifyGetRealUsername() to retrieve the main email address and the real username of the currently logged in user.
The REGIFYCMD.EXE utility is extended in it’s open feature. It now returns information about sender authentication, too.
Fixed some errors in regifycmd.exe documentation (port parameter, etc.).
19. February 2011DLL V1.7.0
Extracted all file format descriptions into a seperate document (regify_file_formats_V1.0.0.pdf).
Some changes and additions due to the inclusion of the Java SDK.
New parameter strUnlockCode for regifyRequestIdentityFile() function.
The regifyParseExtractFile() function does no longer do a signature check.
regifyComposeContainer() does no longer insert a Sign_n value to regify file.
regify connection transmits sdk version and version number to provider.
The certificate and identity file contains new field VATNumber.
The regifycmd utility is now available in a JAVA version, too (jar file).
Additional documentation about the used padding.
Added some additional developer FAQ.
11. Mai 2011 DLL V2.0.0
The functions regifySetProxy() and regifyLogin() are replacing the deprecated functions regifyInitConnection() and regifyConnect().
SDK compiles on Linux, too.
SDK uses curl library for internet access.
Added stronger log levels using regifySetLogLevel() and regifySetLogFilename().
New functions regifyCreateRegibillPDF() and regifyValidateRegibillPDF().
New functions regifyComposeRegimail(), regifyComposeRegibill() and regifyComposeRegipay().
The regifyComposeContainer() function is deprecated now. Use regifyComposeRegimail() instead.
New function cryptoGetMachineCode() to retrieve a valid, hardware dependent hardware code (256 bit).
New function regifySetReplyAddress() to set the used reply address in
the regify file to compose.
24. October 2011DLL V2.1.0
New advertising functions regifyDisplayAds() and regifyGetAds().
Internal prepared for new cipher and error messages (not really finished, but gives correct error codes).
28. October 2011DLL V2.2.0
Remove UI dependencies from SDK.
Add regifySetProgressCallbacks() to facilitate user implementation of progress dialogues.
Remove the question parameter from regifyRequestIdentityFile. The unlock code mus now be set when calling this function.
Change the regifyDisplayIdentityFile API to facilitate a display callback.
02. February 2012DLL V2.2.x
Fixed documentation that showed wrong intHideProgressDialog parameter for regifyLogin() function.
This parameter no longer exists! |
x. June 2012DLL V2.3
Now the SDK works completely in unicode mode. If you are using a single byte environment, please convert all data to utf8 before submitting. Results are now unicode. If you need single byte return values, please use regifySetSingleByteEncoded() function.
Added regifyGetURLFile() function.
19. June 2012
Added -c certificate switch to regifycmd.
24. July 2012
Added regifyGetUserdata(), regifyGetSession() and regifySetSession() functions.
Added regifySignedAuthRequest() function (experimental).
14. August 2012
Added new error codes to documentation.
01. October 2012
regifycmd now also extracts SenderAddress.asc and SenderInfo.asc.
12. October 2012
Added strSubject parameter to regifyCreateRegibillPDF() function.
Added -s parameter for regifycmd while creation of regibill standard.
regifycmd.exe now returns the identity file in JSON format
regifycmd.exe now returns the userdata in JSON format
12. May 2014 DLL V3.1.0
Enhanced upload-json description for regifycmd.
Updated commandline interface help for regifycmd.
Clarified some regipay related parameters in documentation (eg one PDF only).
Added regifyComposeRegichat() function (internal only).
01. August 2014 DLL V3.1.3
Updated OS dependency information.
Updated document formats.
Automatic generation of PDF documentation (internal information).
March 2015 DLL V3.2.0
Mark regifyGetCredits() function as deprecated
May 2017 DLL V3.6.1
Updated OS dependencies and OS specific information.
Updated error codes.
July 2017 DLL V3.7.x
Added function regifySetAppData() to set protocol specific data. Only for regify owned products. Do not set as an external developer.
August 2017 DLL V3.7.x
Added function regifyAutoLogin() to convert the session into a valid web session.
June 2021 DLL Vx.x
Deleted regifyComposeRegichat() function and removed any regichat related options.