Isode Messaging APIs

Summary Section: This page describes how to use the Isode X.400 API to retrieve and submit messages using P7 into or out of a Message Store, or P3 directly into or out of an MTA.

X.400 C API - Example Applications

Application Features

These examples do the following using the X.400 C API

You can use the same application to submit/retrieve using either P3 or P7, by passing the appropriate argument into X400msOpen().

Messaging Configuration

Before running the P3/P7 applications you need run Mconsole to configure and run a messaging configuration including, (if you are using P7) an Isode Message Store.

You also need to configure a P3 or P7 user using the X.400 Mailbox View in Mconsole.

Compiling the Applications

To build the applications an example Makefile is supplied. On Linux run the command

# make -f Makefile.sdk.unix

Configuring the Applications

A set of common utilities for the applications is in x400_common.c. The rest of this text describes how to configure the Session object using the set_defaults() functions.

x400_common.c:void set_defaults(IFP intfunc, IFP strfunc, void* sp);

The applications call this function as follows:

set_defaults(X400msSetIntDefault, X400msSetStrDefault, (void*)sp);

You must call this after the Session object has been initialised using X400msOpen(). (Note that you can use any way of configuring these value you wish - but you must set the values in the Session object after calling X400msOpen() using X400msSetIntDefault,X400msSetStrDefault).

Submission via the Message Store (P7)

To connect to the Message Store you need:

The Presentation Address of the Message Store, which includes the Internet address of the machine where it is running is held in the directory server. Use Mconsole to check the value used by your Message Store.

x400_ms_address:\"3001"/URI+0000+URL+itot://<hostname>:3001

The Credentials of the Message Store User,comprise an O/RName (DN and O/R address) and a password. Check in the X.400 Mailbox View the value used by your Message Store User.

The following entries are used to configure credentials

x400_ms_user_addr: /CN=P7User1/OU=Sales/O=<hostname>/PRMD=TestPRMD/ADMD=TestADMD/C=<country>/
x400_ms_user_dn:"cn=fred,c=gb"

The password of the user that is binding to the Message Store to send or receive messages must be entered on the command line. p>

The example P7 submission application is X400_mssend.c

The only value you must configure is the recipient to which the message will be sent. Make sure that the user referred to in the recip variable exists and the MTA knows how to route a message to recip. Use ckadr-x"<O/R address>" to check the O/R address.

Retrieval from the Message Store (P7)

This works in the same way as for Submission. The example P7 retrieval application is X400_msrcv.c

Generating and Verifying Cryptographic Signatures

The P3 and P7 API supports the generation of message signatures and their verification. There is support for three different forms of signatures which provide three X.400 services.

Types of signature:

STANAG 4406 and MOACs are per message signatures, whereas Message Tokens are per recipient.

To use this feature of the API, you need to do two things:

Generate a Security Environment

There are three parts to your Security Environment

Set the Security Environment in the application

To set the above values use the following attributes

It may be necessary for you to use more than one security environment in your application, for example if you need to use a certain certificate for a set of users, and another certificate (maybe signed by another CA) to another set of users. This is supported by the API.

You can set a different security environments per recipient or per message by using X400msRecipAddStrParam() or X400msMsgAddStrParam() respectively. This might be required when a message or recipient requires a different PKCS12 file for signing. This has no relevance when verifying signatures, as the default (per session) Security Environment is always used.

When signing, failures are identified by the return values from X400msMsgSend().

For verification, a richer set of values can be returned using X400msRecipGetIntParam() and X400msRecipGetStrParam(). A certificate object can also be returned using X400RecipGetCert() and X400msMsgGetCert() for certificates provided by the originator to verify the signature of the Message Token and MOAC respectively.

The following example applications are provided which illustrate how to generate and verify signed messages.

Running the Applications Interactively

To run the applications you simply run the executable from the command line. No arguments are required.

Submitting a message:

[root@dhcp-164 c]# ./x400_mssend
Connection type (0 = P7, 1 = P3 submit only, 2 = P3 both directions) [0]: 
Your ORAddress [/CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/] > 
Password [secret]: 
Presentation Address ["3001"/Internet=dhcp-164.isode.net+3001] > 
Message recipient [/CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/]: 
Subject [A Test Message from X.400 C API]: 
message priority is 0 ( 0 - normal, 1 - non-urgent, 2 - urgent)
military message priority is 0 ( 0 - low, 1 - high)
no binary file set - not sending X400_T_BINARY
no binary file set - not sending forwarded BP
Message submitted successfully

Retrieving a message:

[root@dhcp-164 c]# ./x400_msrcv 
Connection type (0 = P7, 1 = P3 submit only, 2 = P3 both directions) [0]: 
Your ORAddress [/CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/] >
Password [secret]: 
Presentation Address ["3001"/Internet=dhcp-164.isode.net+3001] >
Registered AutoAlert autoaction (id = 10) OK 
Deregistered AutoAlert autoaction (id = 10) OK 
1 messages waiting
Getting message
MsgGet successfully got message 
Message Identifier: [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.0426701-080216.193428] 
Originator: /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
There are 1 recipients
Envelope Recipient 1: /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Primary Recipient 1: /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
There is no Redirection History 
Subject: A Test Message from X.400 C API
Number of attachments is 2
Get attachment 1
got complex bodypart
Get Bodypart 1
got Bodypart 1, type = 407
got Bodypart 1, type = General Text
got 25 bytes of Bodypart data
Printable Data for BP is:
 First line
Second line
Get attachment 2
got text or binary attachment
Printable Data for BP is:
 First line
Second line
[root@dhcp-164 c]#

Windows

To aid in submitting and receiving messages the example programs have been pre-compiled by Isode. These example programs are located within $(BINDIR) typically C:\Program Files\Isode\bin These example programs work in the same way as their unix counterparts, and are compiled from the same code.

Submission directly to the MTA (P3)

Configuration of P3 Submission is similar to P7. You need to configure 

      x400_mta_address:\"593\"/Internet=<hostname>
      x400_mta_user_name:"cn=P3User1;c=gb $ /CN=P7User1/OU=Sales/O=<hostname>/PRMD=TestPRMD/ADMD=TestADMD/C=<country>/"

Note that, unlike P7, the O/R name is configured as a single value with an DN and O/R Address separated by a "$" (rather than separate DN and O/R address)

To make the X400_mssend.c application use P3, you need only change the argument to the X400msOpen()function. Configure the recipient in the same way as for P7.

Retrieval directly from the MTA (P3)

This works in the same way as for P3 Submission. The example P3 submission application is X400_msrcv.c

Running the Applications

To run the applications you simply run the executable from the command line. No arguments are required.

Submitting a message:

Unix

[root@dhcp-164 c]# ./x400_mssend
Connection type (0 = P7, 1 = P3 submit only, 2 = P3 both directions) [0]: 1
Your ORAddress [/CN=P3User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/] > 
Password [p3secret]: 
Presentation Address ["593"/Internet=dhcp-164.isode.net] > 
Message recipient [/CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/]: 
Subject [A Test Message from X.400 C API]: 
message priority is 0 ( 0 - normal, 1 - non-urgent, 2 - urgent)
military message priority is 0 ( 0 - low, 1 - high)
no binary file set - not sending X400_T_BINARY
no binary file set - not sending forwarded BP
Message submitted successfully

Retrieving a message:

[root@dhcp-164 c]# ./x400_msrcv 
Connection type (0 = P7, 1 = P3 submit only, 2 = P3 both directions) [0]: 2
Your ORAddress [/CN=P3User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/] > 
Password [p3secret]: 
Presentation Address ["593"/Internet=dhcp-164.isode.net] > 
1 messages waiting
Getting message
MsgGet successfully got message
Message Identifier: [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.0516701-080216.202106]
Originator: /CN=P3User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
There are 1 recipients
Envelope Recipient 1: /CN=P3User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Primary Recipient 1: /CN=P3User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
There is no Redirection History
Subject: A Test Message from X.400 C API
Number of attachments is 2
Get attachment 1
got complex bodypart
Get Bodypart 1
got Bodypart 1, type = 407
got Bodypart 1, type = General Text
got 25 bytes of Bodypart data
Printable Data for BP is:
 First line
Second line
Get attachment 2
got text or binary attachment
Printable Data for BP is:
 First line
Second line

Running the Applications Using Command Line Arguments

You can supply information about originator, recipient, priority etc using command line arguments if you wish. Possible values are:

x400_mssend_msg_tok_sign
usage: u37m:d:p:w:M:D:P:W:r:o:O:r:g:G:c:l:R:y:C:iaqsAve:x:b:f:Y:
	 where:
	 -u : Don't prompt to override defaults 
	 -3 : Use P3 connection 
	 -7 : Use P7 connection 
	 -m : OR Address in P7 bind arg 
	 -d : DN in P7 bind arg 
	 -p : Presentation Address of P7 Store 
	 -w : P7 password of P7 user 
	 -M : OR Address in P3 bind arg 
	 -D : DN in P3 bind arg 
	 -P : Presentation Address of P3 server
	 -W : P3 password of P3 user 
	 -o : Originator 
	 -O : Originator Return Address 
	 -r : Recipient
	 -l : Logline
	 -y : Priority (0 - normal, 1 - non-urgent, 2 - urgent 
	 -C : Content Type (2/22/772/OID) 
	 -i : Implicit conversion prohibited = TRUE 
	 -a : Alternate Recipient Prohibited = TRUE 
	 -q : Content Return Request = TRUE 
	 -s : Disclosure of Recipient = FALSE 
	 -A : Recipient Reassignment Prohibited = FALSE 
	 -v : Conversion with Loss Prohibited = FALSE 
	 -e : Security Environment (dir with x509 subdir): obsolete, use -Y <p12file>
	 -x : DN of X.509 Digital Identity
	 -b : Passphrase for private key in PKCS12 file
	 -f : Filename to transfer as binary bp
	 -Y : Filename of PKCS12 file containing Digital Identity

For example:

x400_mssend_sign -m "/G=p7/S=user1/O=bevan/PRMD=isode/ADMD= /C=gb/" -r "/G=p7/S=user1/O=bevan/PRMD=isode/ADMD= /C=gb/" 
 -p '"3001"/URI+0000+URL+itot://bevan.isode.net:3001' -u  -w secret 
 -Y /root/cn_p7user1_cn_WhitePages_o_Isode_o_R15.2messaging.p12 -b secret -Z

Windows

To aid in submitting and receiving messages the example programs have been pre-compiled by Isode. These example programs are located within $(BINDIR) typically C:\Program Files\Isode\bin These example programs work in the same way as their unix counterparts, and are compiled from the same code.

All rights reserved © 2002 - 2024 Isode Ltd.