|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/asn1.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
|
|
Packit |
c4476c |
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
These functions generate the ASN1 encoding of a string
|
|
Packit |
c4476c |
in an B<ASN1_TYPE> structure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
B<str> contains the string to encode B<nconf> or B<cnf> contains
|
|
Packit |
c4476c |
the optional configuration information where additional strings
|
|
Packit |
c4476c |
will be read from. B<nconf> will typically come from a config
|
|
Packit |
c4476c |
file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
|
|
Packit |
c4476c |
which will typically be used by X509 v3 certificate extension
|
|
Packit |
c4476c |
functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
|
|
Packit |
c4476c |
configuration will be used.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 GENERATION STRING FORMAT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The actual data encoded is determined by the string B<str> and
|
|
Packit |
c4476c |
the configuration information. The general format of the string
|
|
Packit |
c4476c |
is:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<[modifier,]type[:value]>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
That is zero or more comma separated modifiers followed by a type
|
|
Packit |
c4476c |
followed by an optional colon and a value. The formats of B<type>,
|
|
Packit |
c4476c |
B<value> and B<modifier> are explained below.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Supported Types
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The supported types are listed below. Unless otherwise specified
|
|
Packit |
c4476c |
only the B<ASCII> format is permissible.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<BOOLEAN>, B<BOOL>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This encodes a boolean type. The B<value> string is mandatory and
|
|
Packit |
c4476c |
should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
|
|
Packit |
c4476c |
B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
|
|
Packit |
c4476c |
are acceptable.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<NULL>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encode the B<NULL> type, the B<value> string must not be present.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<INTEGER>, B<INT>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes an ASN1 B<INTEGER> type. The B<value> string represents
|
|
Packit |
c4476c |
the value of the integer, it can be prefaced by a minus sign and
|
|
Packit |
c4476c |
is normally interpreted as a decimal value unless the prefix B<0x>
|
|
Packit |
c4476c |
is included.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<ENUMERATED>, B<ENUM>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
|
|
Packit |
c4476c |
B<INTEGER>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<OBJECT>, B<OID>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
|
|
Packit |
c4476c |
a short name, a long name or numerical format.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<UTCTIME>, B<UTC>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes an ASN1 B<UTCTime> structure, the value should be in
|
|
Packit |
c4476c |
the format B<YYMMDDHHMMSSZ>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<GENERALIZEDTIME>, B<GENTIME>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
|
|
Packit |
c4476c |
the format B<YYYYMMDDHHMMSSZ>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<OCTETSTRING>, B<OCT>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
|
|
Packit |
c4476c |
of this structure, the format strings B<ASCII> and B<HEX> can be
|
|
Packit |
c4476c |
used to specify the format of B<value>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<BITSTRING>, B<BITSTR>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
|
|
Packit |
c4476c |
of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
|
|
Packit |
c4476c |
can be used to specify the format of B<value>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
If the format is anything other than B<BITLIST> the number of unused
|
|
Packit |
c4476c |
bits is set to zero.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
|
|
Packit |
c4476c |
B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
|
|
Packit |
c4476c |
B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
|
|
Packit |
c4476c |
B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
|
|
Packit |
c4476c |
B<NUMERIC>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
These encode the corresponding string types. B<value> represents the
|
|
Packit |
c4476c |
contents of this structure. The format can be B<ASCII> or B<UTF8>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<SEQUENCE>, B<SEQ>, B<SET>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
|
|
Packit |
c4476c |
should be a section name which will contain the contents. The
|
|
Packit |
c4476c |
field names in the section are ignored and the values are in the
|
|
Packit |
c4476c |
generated string format. If B<value> is absent then an empty SEQUENCE
|
|
Packit |
c4476c |
will be encoded.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Modifiers
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Modifiers affect the following structure, they can be used to
|
|
Packit |
c4476c |
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
|
|
Packit |
c4476c |
the string format of the final type and value. The supported
|
|
Packit |
c4476c |
formats are documented below.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<EXPLICIT>, B<EXP>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Add an explicit tag to the following structure. This string
|
|
Packit |
c4476c |
should be followed by a colon and the tag value to use as a
|
|
Packit |
c4476c |
decimal value.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
By following the number with B<U>, B, B or B<C> UNIVERSAL,
|
|
Packit |
c4476c |
APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
|
|
Packit |
c4476c |
the default is CONTEXT SPECIFIC.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<IMPLICIT>, B<IMP>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This is the same as B<EXPLICIT> except IMPLICIT tagging is used
|
|
Packit |
c4476c |
instead.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The following structure is surrounded by an OCTET STRING, a SEQUENCE,
|
|
Packit |
c4476c |
a SET or a BIT STRING respectively. For a BIT STRING the number of unused
|
|
Packit |
c4476c |
bits is set to zero.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item B<FORMAT>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This specifies the format of the ultimate value. It should be followed
|
|
Packit |
c4476c |
by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
If no format specifier is included then B<ASCII> is used. If B<UTF8> is
|
|
Packit |
c4476c |
specified then the value string must be a valid B<UTF8> string. For B<HEX> the
|
|
Packit |
c4476c |
output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
|
|
Packit |
c4476c |
STRING) is a comma separated list of the indices of the set bits, all other
|
|
Packit |
c4476c |
bits are zero.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
|
|
Packit |
c4476c |
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The error codes that can be obtained by L<ERR_get_error(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 EXAMPLES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A simple IA5String:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
IA5STRING:Hello World
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
An IA5String explicitly tagged:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EXPLICIT:0,IA5STRING:Hello World
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
An IA5String explicitly tagged using APPLICATION tagging:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
EXPLICIT:0A,IA5STRING:Hello World
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A BITSTRING with bits 1 and 5 set and all others zero:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
FORMAT:BITLIST,BITSTRING:1,5
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A more complex example using a config file to produce a
|
|
Packit |
c4476c |
SEQUENCE consisting of a BOOL an OID and a UTF8String:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
asn1 = SEQUENCE:seq_section
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
[seq_section]
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
field1 = BOOLEAN:TRUE
|
|
Packit |
c4476c |
field2 = OID:commonName
|
|
Packit |
c4476c |
field3 = UTF8:Third field
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This example produces an RSAPrivateKey structure, this is the
|
|
Packit |
c4476c |
key contained in the file client.pem in all OpenSSL distributions
|
|
Packit |
c4476c |
(note: the field names such as 'coeff' are ignored and are present just
|
|
Packit |
c4476c |
for clarity):
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
asn1=SEQUENCE:private_key
|
|
Packit |
c4476c |
[private_key]
|
|
Packit |
c4476c |
version=INTEGER:0
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
|
|
Packit |
c4476c |
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
e=INTEGER:0x010001
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
|
|
Packit |
c4476c |
F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
|
|
Packit |
c4476c |
D4BD57
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
|
|
Packit |
c4476c |
46EC4F
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
|
|
Packit |
c4476c |
9C0A39B9
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
|
|
Packit |
c4476c |
E7B2458F
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
|
|
Packit |
c4476c |
628657053A
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This example is the corresponding public key in a SubjectPublicKeyInfo
|
|
Packit |
c4476c |
structure:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
# Start with a SEQUENCE
|
|
Packit |
c4476c |
asn1=SEQUENCE:pubkeyinfo
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
# pubkeyinfo contains an algorithm identifier and the public key wrapped
|
|
Packit |
c4476c |
# in a BIT STRING
|
|
Packit |
c4476c |
[pubkeyinfo]
|
|
Packit |
c4476c |
algorithm=SEQUENCE:rsa_alg
|
|
Packit |
c4476c |
pubkey=BITWRAP,SEQUENCE:rsapubkey
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
# algorithm ID for RSA is just an OID and a NULL
|
|
Packit |
c4476c |
[rsa_alg]
|
|
Packit |
c4476c |
algorithm=OID:rsaEncryption
|
|
Packit |
c4476c |
parameter=NULL
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
# Actual public key: modulus and exponent
|
|
Packit |
c4476c |
[rsapubkey]
|
|
Packit |
c4476c |
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
|
|
Packit |
c4476c |
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
e=INTEGER:0x010001
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<ERR_get_error(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|