Externalizing Typed Message Buffers


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Using Security in ATMI Applications \| Local Topics \| Previous Topic \| Next Topic \| Contents

An externalized representation is a message buffer that does not include any ATMI header information that is normally added to a message buffer just before the buffer is transmitted. An externalized representation of a signed message buffer enables "pass through" transmission of signed data and long-term storage of the signed buffer for non-repudiation. It also enables an encrypted message buffer to be transported through intermediate processes without access to a decryption key.

How to Create an Externalized Representation

An ATMI process converts a typed message buffer into an externalized representation by calling the tpexport(3c) function. Pending signatures associated with a message buffer are generated at the time tpexport() is called, just as if the buffer were being transmitted to another process by an ATMI function. Similarly, pending seals associated with a message buffer are generated at the time tpexport() is called, just as if the buffer were being transmitted to another process by an ATMI communication function.

The externalized representation of a message buffer is stored in the PKCS-7 format, which is a binary format. If a string format is required, the calling process must call tpexport() with the TPEX_STRING flag specified.

Note: The ability to create an externalized representation of a typed message buffer is not unique to public key security. A process may call tpexport() to externalize a typed message buffer regardless of whether a message buffer is marked for digital signature or encryption.

How to Convert an Externalized Representation

A receiving process calls the tpimport(3c) function to convert the externalized representation of a message buffer into a typed message buffer. The tpimport() function also performs decryption, if necessary, and verifies any associated digital signatures.

Example Code for tpexport and tpimport

The following example code shows how to use tpexport() to convert a typed message buffer into an externalized representation, and how to use tpimport() to convert the externalized representation back into a typed message buffer.

Using tpexport and tpimport Example

static void hexdump _((unsigned char *, long));

#define MAX_BUFFER 80000

main(argc, argv)
int argc;
char *argv[];
#endif

{
      char    *databuf;
      char    exportbuf[MAX_BUFFER];
      long    exportbuf_size = 0;
      char    *importbuf = NULL;
      long    importbuf_size = 0;
      int go_on = 1;
    .
    .
    .
      exportbuf_size = 0;
      while (go_on == 1) {
            if (tpexport(databuf, 0, exportbuf, &exportbuf_size, 0) 
                  == -1) {
                  if (tperrno == TPELIMIT) {
                        printf("%d tperrno is TPELIMIT, exportbuf_size=%ld\n",
                              __LINE__, exportbuf_size);
                        if (exportbuf_size > MAX_BUFFER) {
                              return(1);
                        }
                  }
                  else {
                        printf("tpexport(%d) failed: tperrno=%d(%s)\n",
                              __LINE__, tperrno, tpstrerror(tperrno));
                        return(1);
                  }
            }
            else {
                  go_on = 0;
            }
      }
    .
    .
    .

      hexdump((unsigned char *) exportbuf, (long) exportbuf_size);

      if (tpimport(exportbuf, exportbuf_size, &importbuf,
            &importbuf_size, 0) == -1) {
            printf("tpimport(%d) failed: tperrno=%d(%s)\n",
                  __LINE__, tperrno, tpstrerror(tperrno));
            return(1);
      }
    .
    .
    .
}