SecuritySNACCRuntime/c-examples/simple/README

   1 (RCS control information is at the end of this file.)
   2
   3
   4 C Simple Example README
   5 -----------------------
   6
   7 This directory should have 8 files in it:
   8
   9 README       - this file
  10 genber.c     - C source code for a program that creates and encodes
  11                a PersonnelRecord value to a file.
  12 expbuf_ex.c  - C source code for a program that calls the generated
  13                PersonnelRecord encoder and decoder routines
  14                using the ExpBuf buffer type
  15 minbuf_ex.c  - C source code for program that calls the generated
  16                PersonnelRecord encoder and decoder routines
  17                using the MinBuf buffer type
  18 sbuf_ex.c    - C source code for a program that calls the generated
  19                PersonnelRecord encoder and decoder routines
  20                using the MinBuf buffer type
  21 makefile     - compiles the example programs
  22 good_pr.ber  - BER encoding of a Personnel Record (all definite lengths)
  23
  24
  25
  26 Type "make" to generate the 7 example programs:
  27         genber
  28         expbuf_def
  29         expbuf_indef
  30         minbuf_def
  31         minbuf_indef
  32         sbuf_def
  33         sbuf_indef
  34
  35
  36 snacc is called from the makefile on snacc/asn1specs/p_rec.asn1 to
  37 generate the following files:
  38
  39 p_rec.h  - C data structs for PersonnelRecord and prototypes for
  40            the generated encode, decode, print and free routines.
  41 p_rec.c  - C source code for the PersonnelRecord encode, decode,
  42            print, and free routines.
  43
  44 These source files are then compiled with *_ex.c and genber.c files to
  45 make 7 programs.  Each program takes 1 argument (except genber), the
  46 name of a file containing an BER encoded PersonnelRecord value.
  47
  48
  49 Try the following: (or use the makefile's `check' phony target)
  50
  51 eg% ./genber                            # create a file called pr.ber
  52 eg% ./sbuf_indef good_pr.ber > indef_pr.ber
  53 eg% ./sbuf_def indef_pr.ber > def_pr.ber
  54 eg% diff good_pr.ber def_pr.ber         # should be no differences
  55
  56
  57 The above commands decode the BER value in "good_pr.ber" and
  58 indef_pr.ber respectively and then re-encode then to stdout.
  59 Both programs will decode any valid BER representation of a
  60 PersonnelRecord value but, the sbuf_def program will re-encode the
  61 given data using only the definite length BER format and the
  62 sbuf_indef program will re-encode the given data using only the
  63 indefinite length BER format.
  64
  65 Compare the lengths of the def_pr.ber and indef_pr.ber files,
  66 indefinite length encodings are usually larger.
  67
  68
  69
  70 Things to Note
  71 --------------
  72
  73
  74 Look at genber.c to see how to build a C value and then encode it.
  75 look at the *_ex.c files to see the different types of buffer
  76 manipulation.  Read the comments in the code.
  77
  78 It should be relatively simple to change the memory and buffer
  79 management to fit your target environment.
  80 (see snacc/c_include/asn_config.h.)
  81
  82
  83 Snacc ASN.1 comment commands
  84
  85 Notice the special "--snacc" ASN.1 comment in snacc/asn1specs/p_rec.asn1.
  86
  87 PersonnelRecord ::= --snacc isPdu:"TRUE" -- [APPLICATION 0] IMPLICIT SET
  88  { ... etc. ... }
  89
  90 The "isPdu" flag tells snacc that the PersonnelRecord is a PDU type
  91 that you will be calling the encoding and decoding routines directly
  92 from your code.  This causes snacc to generate the
  93 "BEncPersonnelRecord" and "BDecPersonnelRecord" routines in addition
  94 to the standard "BEncPersonnelRecordContent" and
  95 "BDecPersonnelRecordContent".
  96
  97 The Content encoding and decoding routines only deal with the content
  98 of the type, ignoring all of the tag and length pairs on the given
  99 type (in this case the APPLICATION (CONSTRUCTED) 0 tag and the length
 100 for the SET).  The "BEncPersonnelRecord" and "BDecPersonnelRecord"
 101 routines do encode the APPLICATION tag and the SET's length.  This
 102 design is motivated by IMPLICIT tagging.
 103
 104 The compiler generated routines generally only call the content
 105 oriented routines except in the case of ANY and ANY DEFINED BY types.
 106 For ANY and ANY DEFINED BY types the PDU form of the rouine is called
 107 since the tags are not known by the containing type.
 108
 109
 110 Length formats
 111
 112 Each pair of *_def and *_indef programs were generated from the same
 113 source file, *_ex.c.  Indefinite length encoders can be created by
 114 giving the -DUSE_INDEF_LEN flag to the C compiler when compiling.
 115 Currently the indefinite/definite length encoder choice is made a
 116 compile time.  To change this to a run-time decision, a simple
 117 solution would be to modify BerEncodeConsLen and BerEncodeEocIfNec
 118 macros in snacc/c_lib/asn_len.h to check a global flag.
 119
 120 #-------------------------------------------------------------------------------
 121 # $Header: /cvs/Darwin/src/live/Security/SecuritySNACCRuntime/c-examples/simple/README,v 1.1.1.1 2001/05/18 23:14:07 mb Exp $
 122 # $Log: README,v $
 123 # Revision 1.1.1.1  2001/05/18 23:14:07  mb
 124 # Move from private repository to open source repository
 125 #
 126 # Revision 1.1.1.1  1999/03/16 18:06:09  aram
 127 # Originals from SMIME Free Library.
 128 #
 129 # Revision 1.2  1995/02/17 16:17:24  rj
 130 # reflect the test script's integration into the makefile.
 131 #
 132 # Revision 1.1  1994/08/31  08:46:22  rj
 133 # first check-in. for a list of changes to the snacc-1.1 distribution please refer to the ChangeLog.
 134 #