doc/crypto/ASN1_generate_nconf.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
   6
   7 =head1 SYNOPSIS
   8
   9  ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
  10  ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
  11
  12 =head1 DESCRIPTION
  13
  14 These functions generate the ASN1 encoding of a string
  15 in an B<ASN1_TYPE> structure.
  16
  17 B<str> contains the string to encode B<nconf> or B<cnf> contains
  18 the optional configuration information where additional strings
  19 will be read from. B<nconf> will typically come from a config
  20 file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
  21 which will typically be used by X509 v3 certificate extension
  22 functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
  23 configuration will be used.
  24
  25 =head1 GENERATION STRING FORMAT
  26
  27 The actual data encoded is determined by the string B<str> and
  28 the configuration information. The general format of the string
  29 is:
  30
  31  B<[modifier,]type[:value]>
  32
  33 That is zero or more comma separated modifiers followed by a type
  34 followed by an optional colon and a value. The formats of B<type>,
  35 B<value> and B<modifier> is explained below.
  36
  37 =head2 SUPPORTED TYPES
  38
  39 =over 2
  40
  41 =item B<BOOLEAN>, B<BOOL>
  42
  43 This encodes a boolean type. The B<value> string is mandatory and
  44 should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
  45 B<y>, B<YES>, B<yes>, B<FALSE> B<false>, B<N>, B<n>, B<NO> and B<no>
  46 are acceptable.
  47
  48 =item B<NULL>
  49
  50 Encode the B<NULL> type, the B<value> string must not be present.
  51
  52 =item B<INTEGER>, B<INT>
  53
  54 Encodes an ASN1 B<INTEGER> type. The B<value> string represents
  55 the value of the integer, it can be preceeded by a minus sign and
  56 is normally interpreted as a decimal value unless the prefix B<0x>
  57 is included.
  58
  59 =item B<ENUMERATED>, B<ENUM>
  60
  61 Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
  62 B<INTEGER>.
  63
  64 =item B<OBJECT>, B<OID>
  65
  66 Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
  67 a short name, a long name or numerical format.
  68
  69 =item B<UTCTIME>, B<UTC>
  70
  71 Encodes an ASN1 B<UTCTime> structure, the value should be in
  72 the format B<YYMMDDHHMMSSZ>.
  73
  74 =item B<GENERALIZETIME>, B<GEN>
  75
  76 Encodes an ASN1 B<GeneralizeTime> structure, the value should be in
  77 the format B<YYYYMMDDHHMMSSZ>.
  78
  79 =item B<OCTETSTRING>, B<OCT>
  80
  81 Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
  82 of this structure, the format strings B<ASCII> and B<HEX> can be
  83 used to specify the format of B<value>.
  84
  85 =item B<BITSRING>, B<BITSTR>
  86
  87 Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
  88 of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
  89 can be used to specify the format of B<value>.
  90
  91 If the format is anything other than B<BITLIST> the number of unused
  92 bits is set to zero.
  93
  94 =item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
  95 B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
  96 B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
  97 B<T61STRING>, B<TELETEXSTRING>
  98
  99 These encode the corresponding string types. B<value> represents the
 100 contents of this structure. The format can be B<ASCII> or B<UTF8>.
 101
 102 =item B<SEQUENCE>, B<SEQ>, B<SET>
 103
 104 Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
 105 should be a section name which will contain the contents. The
 106 field names are ignored and the values are in the generated
 107 string format. If B<value> is absent the the content will be empty.
 108
 109 =cut
 110
 111 =head2 MODIFIERS
 112
 113 ...
 114
 115 =head1 RETURN VALUES
 116
 117 ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
 118 data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
 119
 120 The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
 121
 122 X509_free() returns no value.
 123
 124 =head1 SEE ALSO
 125
 126 L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)>
 127
 128 =head1 HISTORY
 129
 130 ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
 131
 132 =cut