.\"	$OpenBSD: ASN1_STRING_length.3,v 1.6 2016/12/25 22:15:10 schwarze Exp $
.\"	OpenSSL 99d63d46 Tue Jun 21 07:03:34 2016 -0400
.\"
.\" This file was written by Dr. Stephen Henson.
.\" Copyright (c) 2002, 2006, 2013, 2015, 2016 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: December 25 2016 $
.Dt ASN1_STRING_LENGTH 3
.Os
.Sh NAME
.Nm ASN1_STRING_cmp ,
.Nm ASN1_STRING_data ,
.Nm ASN1_STRING_dup ,
.Nm ASN1_STRING_length ,
.Nm ASN1_STRING_length_set ,
.Nm ASN1_STRING_set ,
.Nm ASN1_STRING_to_UTF8 ,
.Nm ASN1_STRING_type
.Nd ASN1_STRING utility functions
.Sh SYNOPSIS
.In openssl/asn1.h
.Ft int
.Fo ASN1_STRING_cmp
.Fa "ASN1_STRING *a"
.Fa "ASN1_STRING *b"
.Fc
.Ft unsigned char *
.Fo ASN1_STRING_data
.Fa "ASN1_STRING *x"
.Fc
.Ft ASN1_STRING *
.Fo ASN1_STRING_dup
.Fa "ASN1_STRING *a"
.Fc
.Ft int
.Fo ASN1_STRING_length
.Fa "ASN1_STRING *x"
.Fc
.Ft void
.Fo ASN1_STRING_length_set
.Fa "ASN1_STRING *x"
.Fa "int len"
.Fc
.Ft int
.Fo ASN1_STRING_set
.Fa "ASN1_STRING *str"
.Fa "const void *data"
.Fa "int len"
.Fc
.Ft int
.Fo ASN1_STRING_to_UTF8
.Fa "unsigned char **out"
.Fa "ASN1_STRING *in"
.Fc
.Ft int
.Fo ASN1_STRING_type
.Fa "ASN1_STRING *x"
.Fc
.Sh DESCRIPTION
These functions manipulate
.Vt ASN1_STRING
structures.
.Pp
.Fn ASN1_STRING_cmp
compares
.Fa a
and
.Fa b
and returns 0 if the two are identical.
The string types and the content are compared.
.Pp
.Fn ASN1_STRING_data
returns an internal pointer to the data of
.Fa x .
Since this is an internal pointer, it should
.Em not
be freed or modified in any way.
.Pp
.Fn ASN1_STRING_dup
returns a copy of the structure
.Fa a .
.Pp
.Fn ASN1_STRING_length
returns the length of the content of
.Fa x .
.Pp
.Fn ASN1_STRING_length_set
sets the length attribute of
.Fa x
to
.Fa len .
It may put
.Fa x
into an inconsistent internal state.
.Pp
.Fn ASN1_STRING_set
sets the data of the string
.Fa str
to the buffer
.Fa data
of length
.Fa len .
The supplied data is copied.
If
.Fa len
is -1 then the length is determined by
.Fn strlen data .
.Pp
.Fn ASN1_STRING_to_UTF8
converts the string
.Fa in
to UTF8 format.
The converted data is copied into a newly allocated buffer
.Fa out .
The length of
.Fa out
is returned or a negative error code.
The buffer
.Fa out
should be freed using
.Xr free 3 .
.Pp
.Fn ASN1_STRING_type
returns the type of
.Fa x ,
using standard constants such as
.Dv V_ASN1_OCTET_STRING .
.Pp
Almost all ASN.1 types in OpenSSL are represented as
.Vt ASN1_STRING
structures.
Other types such as
.Vt ASN1_OCTET_STRING
are simply typedefed to
.Vt ASN1_STRING
and the functions call the
.Vt ASN1_STRING
equivalents.
.Vt ASN1_STRING
is also used for some CHOICE types which consist entirely of primitive
string types such as
.Vt DirectoryString
and
.Vt Time .
.Pp
These functions should
.Em not
be used to examine or modify
.Vt ASN1_INTEGER
or
.Vt ASN1_ENUMERATED
types: the relevant INTEGER or ENUMERATED utility functions should
be used instead.
.Pp
In general it cannot be assumed that the data returned by
.Fn ASN1_STRING_data
is NUL terminated, and it may contain embedded NUL characters.
The actual format of the data will depend on the actual string type itself:
for example for an
.Vt IA5String
the data will be ASCII, for a
.Vt BMPString
two bytes per character in big endian format, and a
.Vt UTF8String
will be in UTF8 format.
.Pp
Similar care should be take to ensure the data is in the correct format
when calling
.Fn ASN1_STRING_set .
.Sh SEE ALSO
.Xr ERR_get_error 3