Documentation and help portal

★ Home
regify Client SDK
Version 3.14
regify Client-SDK reference
Deutsch
Français
regify client SDK

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:

  1. the regify process (overview)

  2. regify client SDK functions

  3. 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

Regify Process

  1. The regify software encrypts and merges the text message and potential attachments of the sender’s email into a regify file.

  2. The message key and hash code of the regify file and the subject of the message will be sent to the regify provider.

  3. The regify provider relays the message key and the hash code to the regify clearing service.

  4. 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.

  5. 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.

  6. 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).

  7. 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.).

  8. 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.

In single byte mode you must encode all non 7bit ASCII chars and text using UTF-8!

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.

In single byte mode you must encode all non 7bit ASCII chars and text using UTF-8!

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.

In single byte mode you must encode all non 7bit ASCII chars and text using UTF-8!

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:

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:

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).

As an external SDK developer, please do not call this function. It is for regify only.

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:

/* define the types we need for the struct */
typedef void* (*open)();
typedef void (*updateNumber)(void*, int);
typedef void (*updateLabel)(void*, const char*);
typedef void (*close)(void*);

/* define the required structure */
typedef struct progressVectors_s {
 open progressOpen;
 updateNumber progressUpdate;
 updateLabel progressLabel;
 close progressClose;
} progressVectors;

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:

 
#include <stdio.h>

/* define the types we need for the struct */
typedef void* (*open)();
typedef void (*updateNumber)(void*, int);
typedef void (*updateLabel)(void*, const char*);
typedef void (*close)(void*);

/* define the required structure */
typedef struct progressVectors_s {
 open progressOpen;
 updateNumber progressUpdate;
 updateLabel progressLabel;
 close progressClose;
} progressVectors;

/* define some quick progress routines */
void* myOpen() {
 int num = 1;
 printf("Opening %d\n", num);
 return (void*) num;
}
void myUpdate(void* ctx, int num) {
 printf("Set percentage of %d to %d\n", (int) ctx, num);
}
void myLabel(void* ctx, const char* text) {
 printf("Set label of %d to %s\n", (int) ctx, text);
}
void myClose(void* ctx) {
 printf("Closing %d\n", (int) ctx);
}
int main(){
 /* set vectors to the routines */
 progressVectors vectors;
 vectors.progressOpen = myOpen;
 vectors.progressUpdate = myUpdate;
 vectors.progressLabel = myLabel
 vectors.progressClose = myClose;

 /* first get a session */
 void *sess = regifyNewSession("", "", "", "", "");


 /* some error checking here */


 /* pass vectors to the SDK */
 regifySetProgressCallbacks(sess, &vectors);

 /* other code to follow... */

}

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.

All provided PDF files will get converted and registered to regibill standard files automatically!

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.

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).

Set to 0 (zero) for provider default value.

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().

This function may return an empty string if the current user has been the sender of the message and he has not been one of the recipients for this message. So an empty result indicates not an error.

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.
Set intSaveEncrypted = 0 to save unencrypted.

If you leave strUnlockCode empty, decryption will fail.

This function returns "1", if all actions were performed without error.
If another identity file already exists at the given path, it will be overwritten.

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.
Attention! This action is not reversible. After deletion, the default regify identity file is used for further communication. Please use the regifyRequestIdentityFile() function to renew the identity file.

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:

 
jsonResult = regifyDisplayIdentityFile(sess);
jsonResult = regifyDisplayIdentityFile(0);
jsonResult = regifyDisplayIdentityFile(obj);
jsonResult = regifyDisplayIdentityFile("user_identity.rif");

details:

Depending on the submitted parameter *ptr, the function will display different identities:

  • Submit a session object sess and this function will return its associated user or deafault identity file

  • Set it to NULL or 0 to return the default identity file

  • Submit an operation object *obj of a decrypted regify container to return its sender identity.

  • Submit the adress to a String and this function will treat it as the file path to an identity file

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.

If you plan to use this function, please contact regify support at support@regify.com first.

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 regify provider offers SMS service (error205).

  • The first name, last name and email address of the certificate match the user data in the provider (error 201, 202).

  • The user entered a valid mobile phone number (error 203, 204)

  • The root CA of the signers certificate is known (Deutsche Post, Telekom, Luxtrust) (error 200)

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:

ID<TAB>Filename<TAB>Flags<TAB>Filesize|ID<TAB>Filename<TAB>Flags<TAB>Filesize|…​

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:

 
strSubject = regifyParseHeader(obj, "subject");

strRecipient = regifyParseHeader(obj, "recipient");

strDate = regifyParseHeader(obj, "creationdate");

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
(integer) 1 to 10=authentication level

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
EN = English
FR = French
CN = Simplified Chinese

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);

⇒ /tmp/ad_image.jpg|http://www.regify.com;10;10;400;40

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:

{
 "boxMax" : 2000,
 "boxCurrent": 164992.4,
 "rmMax": 200,
 "rmCurrent": 16
}

regifyGetUsername

function: regifyGetUsername

parameters:

*sess

return value:

(string) Username

description:

Returns the login username of the currently logged in user.
Works only after successfully calling regifyLogin() functions.
Otherwise this will return an empty string and regifyLastError() returns error 66.

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.
Works only after successfully calling regifyLogin() functions.
Otherwise this will return an empty string and regifyLastError() returns error 66.

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:

  • regifyNewSession()

  • regifySetProxy()

  • regifySetAppData()

  • regifyLogin()

  • regifyAutoLogin()

  • regifyFreeSession()

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 = regifyGetConfiguration("patrick@bikinibottom.com",
"supersecret", "", "", "", "");

result:

{
	"confChkSum": "DEADBEEF42...",
	"messageBodyHTML": "PGh0bWw+Cj...",
	"messageBodyPlain": "cmVnaWZ5ri...",
	"providerData": "0|AF04564FD...",
	"providerHomepage": "http:\/\/www.someprovider.com",
	"providerLogo": "iVBORw0...",
	"providerName": "someprovider",
	"providerUrl": "https:\/\/regify.someprovider.com\/",
	"proxyPassword": "",
	"proxyServer": "",
	"proxyUsername": "",
	"rulesServerID": "",
	"supportContact": "498912345678",
	"supportEmail": "support@someprovider.com",
	"user": {
		"abo": 0,
		"accountType": "regimail+regipay+regibill",
		"address1": "23 Any St.",
		"address2": "",
		"authentication": {
			"authLevel": 3,
			"identityName": "Mr Patrick Bikinibottom",
			"identityOrganisation": "",
			"keyDate": "2012-11-08 10:11:49",
			"ownerType": "person",
			"publicKey": "3082008B0282008096BA7574B0407A9C7...",
			"unlockReturnInformation": "491234567890",
			"vatNumber": ""
		},
		"city": "Anytown",
		"company": "",
		"country": "United Kingdom",
		"creationDate": "2011-04-19 14:21:32",
		"emails": ["patrik@bikinibottom.com", "patrik.b@gmx.com"],
		"firstName": "Patrik",
		"groupId": 0,
		"language": "EN",
		"lastActivity": "2013-02-27 15:54:21",
		"lastName": "Bikinibottom",
		"mainEmail": "patrik@bikinibottom.com",
		"phone": null,
		"phoneMobile": "491234567890",
		"realName": "Mr Patrick Bikinibottom",
		"salesId": "",
		"sendingAllowedUntil": "2013-05-19 00:00:00",
		"titleName": "Mr",
		"userId": 23,
		"userName": "patrik.b",
		"vatNumber": "",
		"zipcode": "12345"
	}
}

Returns public configuration

result = regifyGetConfiguration("", "",
"https://regify.someprovider.com/");

result:

{
 "confChkSum" : "DEADBEEF42...",
 "messageBodyHTML":"PGh0bWw+Cj...",
 "messageBodyPlain":"cmVnaWZ5ri...",
 "providerData":"0|AF04564FD...",
 "providerHomepage":"http:\/\/www.someprovider.com",
 "providerLogo":"iVBORw0...",
 "providerName":"someprovider",
 "providerUrl":"https:\/\/regify.someprovider.com\/",
 "proxyServer":"",
 "rulesServerID":"",
 "supportContact":"498912345678",
 "supportEmail":"support@someprovider.com",
 "timeZone":"Europe\/Berlin"
}

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.

Unless there is a server error (59) or the provider is non public (5), this function will return 0 when properly used. It will do so regardless of whether the user exists anywhere or not. This has to be done that way to prevent this function from being abused for email mining purposes.

example call:

Trigger a password reset

intResult = regifyResetPassword("patrick@bikinibottom.com", "", "", "", "");

result: one of the following

  • 0 the operation succeed. If the user is indeed enrolled somewhere they will receive an email with further instructions.

  • 5 the provider where the user is enrolled does not support the provider lookup protocol, usually because it is a corporate provider not permitting public access.

  • 59 something went wrong on the server. The only recourse is to try again later.

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:

Suggested Constant Integer Value Description

RF_LOG_NONE

0

turn logging off

RF_LOG_CRIT

1

fatal errors

RF_LOG_WARN

2

things that do not look good

RF_LOG_INFO

3

usefull things such as start/stop etc.

RF_LOG_FLOW

4

good for reporting flow

RF_LOG_VERB

5

really verbose used in inner loops etc.

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:

{
	"abo": 0,
	"accountType": "regimail+regipay+regibill",
	"address1": "23 Any St.",
	"address2": "",
	"authentication": {
		"authLevel": 3,
		"identityName": "Mr Patrick Bikinibottom",
		"identityOrganisation": "",
		"keyDate": "2012-11-08 10:11:49",
		"ownerType": "person",
		"publicKey": "3082008B0282008096BA7574B0407A9C7...",
		"unlockReturnInformation": "491234567890",
		"vatNumber": ""
	},
	"city": "Anytown",
	"company": "",
	"country": "United Kingdom",
	"creationDate": "2011-04-19 14:21:32",
	"emails": ["patrik@bikinibottom.com", "patrik.b@gmx.com"],
	"firstName": "Patrik",
	"groupId": 0,
	"language": "EN",
	"lastActivity": "2013-02-27 15:54:21",
	"lastName": "Bikinibottom",
	"mainEmail": "patrik@bikinibottom.com",
	"phone": null,
	"phoneMobile": "491234567890",
	"realName": "Mr Patrick Bikinibottom",
	"salesId": "",
	"sendingAllowedUntil": "2013-05-19 00:00:00",
	"titleName": "Mr",
	"userId": 23,
	"userName": "patrik.b",
	"vatNumber": "",
	"zipcode": "12345"
}

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:

 
sess = regifyNewSession(....)

/* use the session */
sessData = regifyGetSession(sess);
/* then save it */

regifyFreeSession(sess);

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:

 
/* First call */
sess = regifyNewSession(....)
/* use the session */
/* then save it */
sessData = regifyGetSession(sess);
regifyFreeSession(sess);
/* end first call */

/* start subsequent calls */
sess = regifySetSession(sessData);
/* use the session */
regifyFreeSession(sess);
/* end subsequent 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:

 
/* Setup MIME content */
mime = "From: Alice Doe <alice.doe@abc.com>\n"
"Date: Thu, 31 Jul 2014 11:25:59 +0200\n"
"To: bob@def.com[bob@def.com], info@def.com\n"
"Subject: Hi Bob\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8; format=flowed\n"
"Content-Transfer-Encoding: 8bit\n"
"\n"
"Hi Bob,\n"
"\n"
"nice to meet you.\n"
"\n"
"Alice"

/* Send the email */
ret = regifySendEmail("alice@abc.com", "bob@def.com info@def.com", mime);

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

  1. Set all the login parameters using regifyNewSession()

  2. Optionally set the proxy using regifySetProxy()

  3. Set regify application information using regifySetAppData()

  4. Log into the provider using regifyLogin()

  5. Optional get user name and email address using regifyGetUserMailaddress() and regifyGetRealUsername() and use this values to generate sender information (if needed)

  6. 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.

  7. Generate all message components

  8. Compose the container using regifyComposeRegimail()

  9. Rename the container using the transaction id (see regifyGetTransactionIds())

  10. 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)

  11. Cleanup operation resources using regifyCleanup() function

  12. Optionally perform another message operation (go to step #6)

  13. Log the user out of the regify provider using regifyLogout()

  14. Optionally log in as another user using regifySetUser() (go to step #3)

  15. Cleanup session resources by calling regifyFreeSession()

Receiving a regify message

  1. Receive the regify file (xxx.rgf)

  2. Set all the login parameters using regifyNewSession()

  3. Optionally set the proxy using regifySetProxy()

  4. Set regify application information using regifySetAppData()

  5. Log into the provider using regifyLogin()

  6. Decrypt the regify file using regifyDecryptContainer() function

  7. Parse the regify file using the regifyParse…​() functions

  8. Substitute placeholders

  9. Display content

  10. Cleanup session resources by calling regifyFreeSession()

Request a New Identity File

  1. Set all the login parameters using regifyNewSession(). Please use the default identity file by assigning an empty string to strIdentityFile.

  2. Optionally set the proxy using regifySetProxy()

  3. Set regify application information using regifySetAppData()

  4. Log into the provider using regifyLogin()

  5. Call regifyRequestIdentityFile() function and submit a filename (remember, that you need write permissions to this destination).

  6. 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.

  7. 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.

Email

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.

email

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

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 „&reg;“ and to encode „>“ you have to enter „&gt;“ 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.
DE = German
EN = English
FR = French
CN = Simplified Chinese

(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.