315 lines
12 KiB
HTML
Executable File
315 lines
12 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>ASN1_generate_nconf</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#generation_string_format">GENERATION STRING FORMAT</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#supported_types">Supported Types</a></li>
|
|
<li><a href="#modifiers">Modifiers</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/asn1.h></pre>
|
|
<pre>
|
|
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
|
|
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>These functions generate the ASN1 encoding of a string
|
|
in an <strong>ASN1_TYPE</strong> structure.</p>
|
|
<p><em>str</em> contains the string to encode <em>nconf</em> or <em>cnf</em> contains
|
|
the optional configuration information where additional strings
|
|
will be read from. <em>nconf</em> will typically come from a config
|
|
file whereas <em>cnf</em> is obtained from an <strong>X509V3_CTX</strong> structure
|
|
which will typically be used by X509 v3 certificate extension
|
|
functions. <em>cnf</em> or <em>nconf</em> can be set to NULL if no additional
|
|
configuration will be used.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="generation_string_format">GENERATION STRING FORMAT</a></h1>
|
|
<p>The actual data encoded is determined by the string <em>str</em> and
|
|
the configuration information. The general format of the string
|
|
is:</p>
|
|
<dl>
|
|
<dt><strong><a name="modifier_type_value" class="item">[<em>modifier</em>,]<em>type</em>[:<em>value</em>]</a></strong></dt>
|
|
|
|
</dl>
|
|
<p>That is zero or more comma separated modifiers followed by a type
|
|
followed by an optional colon and a value. The formats of <em>type</em>,
|
|
<em>value</em> and <em>modifier</em> are explained below.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="supported_types">Supported Types</a></h2>
|
|
<p>The supported types are listed below. Unless otherwise specified
|
|
only the <strong>ASCII</strong> format is permissible.</p>
|
|
<dl>
|
|
<dt><strong><a name="boolean_bool" class="item"><strong>BOOLEAN</strong>, <strong>BOOL</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This encodes a boolean type. The <em>value</em> string is mandatory and
|
|
should be <strong>TRUE</strong> or <strong>FALSE</strong>. Additionally <strong>TRUE</strong>, <strong>true</strong>, <strong>Y</strong>,
|
|
<strong>y</strong>, <strong>YES</strong>, <strong>yes</strong>, <strong>FALSE</strong>, <strong>false</strong>, <strong>N</strong>, <strong>n</strong>, <strong>NO</strong> and <strong>no</strong>
|
|
are acceptable.</p>
|
|
</dd>
|
|
<dt><strong><a name="null" class="item"><strong>NULL</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encode the <strong>NULL</strong> type, the <em>value</em> string must not be present.</p>
|
|
</dd>
|
|
<dt><strong><a name="integer_int" class="item"><strong>INTEGER</strong>, <strong>INT</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes an ASN1 <strong>INTEGER</strong> type. The <em>value</em> string represents
|
|
the value of the integer, it can be prefaced by a minus sign and
|
|
is normally interpreted as a decimal value unless the prefix <strong>0x</strong>
|
|
is included.</p>
|
|
</dd>
|
|
<dt><strong><a name="enumerated_enum" class="item"><strong>ENUMERATED</strong>, <strong>ENUM</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes the ASN1 <strong>ENUMERATED</strong> type, it is otherwise identical to
|
|
<strong>INTEGER</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="object_oid" class="item"><strong>OBJECT</strong>, <strong>OID</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes an ASN1 <strong>OBJECT IDENTIFIER</strong>, the <em>value</em> string can be
|
|
a short name, a long name or numerical format.</p>
|
|
</dd>
|
|
<dt><strong><a name="utctime_utc" class="item"><strong>UTCTIME</strong>, <strong>UTC</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes an ASN1 <strong>UTCTime</strong> structure, the value should be in
|
|
the format <strong>YYMMDDHHMMSSZ</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="generalizedtime_gentime" class="item"><strong>GENERALIZEDTIME</strong>, <strong>GENTIME</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes an ASN1 <strong>GeneralizedTime</strong> structure, the value should be in
|
|
the format <strong>YYYYMMDDHHMMSSZ</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="octetstring_oct" class="item"><strong>OCTETSTRING</strong>, <strong>OCT</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes an ASN1 <strong>OCTET STRING</strong>. <em>value</em> represents the contents
|
|
of this structure, the format strings <strong>ASCII</strong> and <strong>HEX</strong> can be
|
|
used to specify the format of <em>value</em>.</p>
|
|
</dd>
|
|
<dt><strong><a name="bitstring_bitstr" class="item"><strong>BITSTRING</strong>, <strong>BITSTR</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encodes an ASN1 <strong>BIT STRING</strong>. <em>value</em> represents the contents
|
|
of this structure, the format strings <strong>ASCII</strong>, <strong>HEX</strong> and <strong>BITLIST</strong>
|
|
can be used to specify the format of <em>value</em>.</p>
|
|
<p>If the format is anything other than <strong>BITLIST</strong> the number of unused
|
|
bits is set to zero.</p>
|
|
</dd>
|
|
<dt><strong><a name="universalstring_univ_ia5_ia5string_utf8_utf8string_bmp_bmpstring_visiblestring_visible_printablestring_printable_t61_t61string_teletexstring_generalstring_numericstring_numeric" class="item"><strong>UNIVERSALSTRING</strong>, <strong>UNIV</strong>, <strong>IA5</strong>, <strong>IA5STRING</strong>, <strong>UTF8</strong>,
|
|
<strong>UTF8String</strong>, <strong>BMP</strong>, <strong>BMPSTRING</strong>, <strong>VISIBLESTRING</strong>,
|
|
<strong>VISIBLE</strong>, <strong>PRINTABLESTRING</strong>, <strong>PRINTABLE</strong>, <strong>T61</strong>,
|
|
<strong>T61STRING</strong>, <strong>TELETEXSTRING</strong>, <strong>GeneralString</strong>, <strong>NUMERICSTRING</strong>,
|
|
<strong>NUMERIC</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>These encode the corresponding string types. <em>value</em> represents the
|
|
contents of this structure. The format can be <strong>ASCII</strong> or <strong>UTF8</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="sequence_seq_set" class="item"><strong>SEQUENCE</strong>, <strong>SEQ</strong>, <strong>SET</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Formats the result as an ASN1 <strong>SEQUENCE</strong> or <strong>SET</strong> type. <em>value</em>
|
|
should be a section name which will contain the contents. The
|
|
field names in the section are ignored and the values are in the
|
|
generated string format. If <em>value</em> is absent then an empty SEQUENCE
|
|
will be encoded.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="modifiers">Modifiers</a></h2>
|
|
<p>Modifiers affect the following structure, they can be used to
|
|
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
|
|
the string format of the final type and value. The supported
|
|
formats are documented below.</p>
|
|
<dl>
|
|
<dt><strong><a name="explicit_exp" class="item"><strong>EXPLICIT</strong>, <strong>EXP</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Add an explicit tag to the following structure. This string
|
|
should be followed by a colon and the tag value to use as a
|
|
decimal value.</p>
|
|
<p>By following the number with <strong>U</strong>, <strong>A</strong>, <strong>P</strong> or <strong>C</strong> UNIVERSAL,
|
|
APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
|
|
the default is CONTEXT SPECIFIC.</p>
|
|
</dd>
|
|
<dt><strong><a name="implicit_imp" class="item"><strong>IMPLICIT</strong>, <strong>IMP</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This is the same as <strong>EXPLICIT</strong> except IMPLICIT tagging is used
|
|
instead.</p>
|
|
</dd>
|
|
<dt><strong><a name="octwrap_seqwrap_setwrap_bitwrap" class="item"><strong>OCTWRAP</strong>, <strong>SEQWRAP</strong>, <strong>SETWRAP</strong>, <strong>BITWRAP</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The following structure is surrounded by an OCTET STRING, a SEQUENCE,
|
|
a SET or a BIT STRING respectively. For a BIT STRING the number of unused
|
|
bits is set to zero.</p>
|
|
</dd>
|
|
<dt><strong><a name="format" class="item"><strong>FORMAT</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This specifies the format of the ultimate value. It should be followed
|
|
by a colon and one of the strings <strong>ASCII</strong>, <strong>UTF8</strong>, <strong>HEX</strong> or <strong>BITLIST</strong>.</p>
|
|
<p>If no format specifier is included then <strong>ASCII</strong> is used. If <strong>UTF8</strong> is
|
|
specified then the value string must be a valid <strong>UTF8</strong> string. For <strong>HEX</strong> the
|
|
output must be a set of hex digits. <strong>BITLIST</strong> (which is only valid for a BIT
|
|
STRING) is a comma separated list of the indices of the set bits, all other
|
|
bits are zero.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
|
|
data as an <strong>ASN1_TYPE</strong> structure or NULL if an error occurred.</p>
|
|
<p>The error codes that can be obtained by <em>ERR_get_error(3)</em>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>A simple IA5String:</p>
|
|
<pre>
|
|
IA5STRING:Hello World</pre>
|
|
<p>An IA5String explicitly tagged:</p>
|
|
<pre>
|
|
EXPLICIT:0,IA5STRING:Hello World</pre>
|
|
<p>An IA5String explicitly tagged using APPLICATION tagging:</p>
|
|
<pre>
|
|
EXPLICIT:0A,IA5STRING:Hello World</pre>
|
|
<p>A BITSTRING with bits 1 and 5 set and all others zero:</p>
|
|
<pre>
|
|
FORMAT:BITLIST,BITSTRING:1,5</pre>
|
|
<p>A more complex example using a config file to produce a
|
|
SEQUENCE consisting of a BOOL an OID and a UTF8String:</p>
|
|
<pre>
|
|
asn1 = SEQUENCE:seq_section</pre>
|
|
<pre>
|
|
[seq_section]</pre>
|
|
<pre>
|
|
field1 = BOOLEAN:TRUE
|
|
field2 = OID:commonName
|
|
field3 = UTF8:Third field</pre>
|
|
<p>This example produces an RSAPrivateKey structure, this is the
|
|
key contained in the file client.pem in all OpenSSL distributions
|
|
(note: the field names such as 'coeff' are ignored and are present just
|
|
for clarity):</p>
|
|
<pre>
|
|
asn1=SEQUENCE:private_key
|
|
[private_key]
|
|
version=INTEGER:0</pre>
|
|
<pre>
|
|
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
|
|
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9</pre>
|
|
<pre>
|
|
e=INTEGER:0x010001</pre>
|
|
<pre>
|
|
d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
|
|
F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D</pre>
|
|
<pre>
|
|
p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
|
|
D4BD57</pre>
|
|
<pre>
|
|
q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
|
|
46EC4F</pre>
|
|
<pre>
|
|
exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
|
|
9C0A39B9</pre>
|
|
<pre>
|
|
exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
|
|
E7B2458F</pre>
|
|
<pre>
|
|
coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
|
|
628657053A</pre>
|
|
<p>This example is the corresponding public key in a SubjectPublicKeyInfo
|
|
structure:</p>
|
|
<pre>
|
|
# Start with a SEQUENCE
|
|
asn1=SEQUENCE:pubkeyinfo</pre>
|
|
<pre>
|
|
# pubkeyinfo contains an algorithm identifier and the public key wrapped
|
|
# in a BIT STRING
|
|
[pubkeyinfo]
|
|
algorithm=SEQUENCE:rsa_alg
|
|
pubkey=BITWRAP,SEQUENCE:rsapubkey</pre>
|
|
<pre>
|
|
# algorithm ID for RSA is just an OID and a NULL
|
|
[rsa_alg]
|
|
algorithm=OID:rsaEncryption
|
|
parameter=NULL</pre>
|
|
<pre>
|
|
# Actual public key: modulus and exponent
|
|
[rsapubkey]
|
|
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
|
|
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9</pre>
|
|
<pre>
|
|
e=INTEGER:0x010001</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ERR_get_error(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|