diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/ASN1_generate_nconf.pod | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod new file mode 100644 index 0000000000..bdee4067c7 --- /dev/null +++ b/doc/crypto/ASN1_generate_nconf.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions + +=head1 SYNOPSIS + + ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); + ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf); + +=head1 DESCRIPTION + +These functions generate the ASN1 encoding of a string +in an B<ASN1_TYPE> structure. + +B<str> contains the string to encode B<nconf> or B<cnf> contains +the optional configuration information where additional strings +will be read from. B<nconf> will typically come from a config +file wherease B<cnf> is obtained from an B<X509V3_CTX> structure +which will typically be used by X509 v3 certificate extension +functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional +configuration will be used. + +=head1 GENERATION STRING FORMAT + +The actual data encoded is determined by the string B<str> and +the configuration information. The general format of the string +is: + + B<[modifier,]type[:value]> + +That is zero or more comma separated modifiers followed by a type +followed by an optional colon and a value. The formats of B<type>, +B<value> and B<modifier> is explained below. + +=head2 SUPPORTED TYPES + +=over 2 + +=item B<BOOLEAN>, B<BOOL> + +This encodes a boolean type. The B<value> string is mandatory and +should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>, +B<y>, B<YES>, B<yes>, B<FALSE> B<false>, B<N>, B<n>, B<NO> and B<no> +are acceptable. + +=item B<NULL> + +Encode the B<NULL> type, the B<value> string must not be present. + +=item B<INTEGER>, B<INT> + +Encodes an ASN1 B<INTEGER> type. The B<value> string represents +the value of the integer, it can be preceeded by a minus sign and +is normally interpreted as a decimal value unless the prefix B<0x> +is included. + +=item B<ENUMERATED>, B<ENUM> + +Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to +B<INTEGER>. + +=item B<OBJECT>, B<OID> + +Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be +a short name, a long name or numerical format. + +=item B<UTCTIME>, B<UTC> + +Encodes an ASN1 B<UTCTime> structure, the value should be in +the format B<YYMMDDHHMMSSZ>. + +=item B<GENERALIZETIME>, B<GEN> + +Encodes an ASN1 B<GeneralizeTime> structure, the value should be in +the format B<YYYYMMDDHHMMSSZ>. + +=item B<OCTETSTRING>, B<OCT> + +Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents +of this structure, the format strings B<ASCII> and B<HEX> can be +used to specify the format of B<value>. + +=item B<BITSRING>, B<BITSTR> + +Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents +of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST> +can be used to specify the format of B<value>. + +If the format is anything other than B<BITLIST> the number of unused +bits is set to zero. + +=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>, +B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>, +B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>, +B<T61STRING>, B<TELETEXSTRING> + +These encode the corresponding string types. B<value> represents the +contents of this structure. The format can be B<ASCII> or B<UTF8>. + +=item B<SEQUENCE>, B<SEQ>, B<SET> + +Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value> +should be a section name which will contain the contents. The +field names are ignored and the values are in the generated +string format. If B<value> is absent the the content will be empty. + +=cut + +=head2 MODIFIERS + +... + +=head1 RETURN VALUES + +ASN1_generate_nconf() and ASN1_generate_v3() return the encoded +data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred. + +The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +X509_free() returns no value. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)> + +=head1 HISTORY + +ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8 + +=cut |