268 lines
6.3 KiB
Groff
268 lines
6.3 KiB
Groff
.\" $OpenBSD: X509_ATTRIBUTE_set1_object.3,v 1.3 2021/11/26 13:48:21 jsg Exp $
|
|
.\"
|
|
.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: November 26 2021 $
|
|
.Dt X509_ATTRIBUTE_SET1_OBJECT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm X509_ATTRIBUTE_set1_object ,
|
|
.Nm X509_ATTRIBUTE_set1_data ,
|
|
.Nm X509_ATTRIBUTE_create_by_OBJ ,
|
|
.Nm X509_ATTRIBUTE_create_by_NID ,
|
|
.Nm X509_ATTRIBUTE_create_by_txt
|
|
.\" In the following line, "X.501" and "Attribute" are not typos.
|
|
.\" The "Attribute" type is defined in X.501, not in X.509.
|
|
.\" The type is called "Attribute" with capital "A", not "attribute".
|
|
.Nd modify an X.501 Attribute
|
|
.Sh SYNOPSIS
|
|
.In openssl/x509.h
|
|
.Ft int
|
|
.Fo X509_ATTRIBUTE_set1_object
|
|
.Fa "X509_ATTRIBUTE *attr"
|
|
.Fa "const ASN1_OBJECT *obj"
|
|
.Fc
|
|
.Ft int
|
|
.Fo X509_ATTRIBUTE_set1_data
|
|
.Fa "X509_ATTRIBUTE *attr"
|
|
.Fa "int type"
|
|
.Fa "const void *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft X509_ATTRIBUTE *
|
|
.Fo X509_ATTRIBUTE_create_by_OBJ
|
|
.Fa "X509_ATTRIBUTE **pattr"
|
|
.Fa "const ASN1_OBJECT *obj"
|
|
.Fa "int type"
|
|
.Fa "const void *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft X509_ATTRIBUTE *
|
|
.Fo X509_ATTRIBUTE_create_by_NID
|
|
.Fa "X509_ATTRIBUTE **pattr"
|
|
.Fa "int nid"
|
|
.Fa "int type"
|
|
.Fa "const void *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft X509_ATTRIBUTE *
|
|
.Fo X509_ATTRIBUTE_create_by_txt
|
|
.Fa "X509_ATTRIBUTE **pattr"
|
|
.Fa "const char *name"
|
|
.Fa "int type"
|
|
.Fa "const unsigned char *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Fn X509_ATTRIBUTE_set1_object
|
|
sets the type of
|
|
.Fa attr
|
|
to
|
|
.Fa obj .
|
|
If
|
|
.Fa obj
|
|
is dynamically allocated, a deep copy is created.
|
|
If the type of
|
|
.Fa attr
|
|
was already set, the old type is freed
|
|
as far as it was dynamically allocated.
|
|
After calling this function,
|
|
.Fa attr
|
|
may be in an inconsistent state
|
|
because its values may not agree with the new attribute type.
|
|
.Pp
|
|
.Fn X509_ATTRIBUTE_set1_data
|
|
sets
|
|
.Fa attr
|
|
to be multi-valued and initializes its set of values
|
|
to contain a single new ASN.1 ANY object representing the
|
|
.Fa data .
|
|
.Pp
|
|
The interpretation of the
|
|
.Fa data
|
|
depends on the values of the
|
|
.Fa type
|
|
and
|
|
.Fa len
|
|
arguments; there are four different cases.
|
|
.Pp
|
|
If the
|
|
.Fa type
|
|
argument has the bit
|
|
.Dv MBSTRING_FLAG
|
|
set,
|
|
.Fa data
|
|
is expected to point to a multibyte character string that is
|
|
.Fa len
|
|
bytes long and uses the encoding specified by the
|
|
.Fa type
|
|
argument, and it is expected that an attribute type was already assigned to
|
|
.Fa attr ,
|
|
for example by calling
|
|
.Fn X509_ATTRIBUTE_set1_object
|
|
before calling
|
|
.Fn X509_ATTRIBUTE_set1_data .
|
|
In this case, an appropriate ASN.1 multibyte string type is chosen and
|
|
a new object of that type is allocated and populated to represent the
|
|
.Fa data
|
|
by calling
|
|
.Xr ASN1_STRING_set_by_NID 3 .
|
|
The type of that new ASN.1 string object is subsequently used instead of the
|
|
.Fa type
|
|
argument.
|
|
.Pp
|
|
If the
|
|
.Fa type
|
|
argument does not have the bit
|
|
.Dv MBSTRING_FLAG
|
|
set and the
|
|
.Fa len argument
|
|
is not \-1, the
|
|
.Fa type
|
|
argument is expected to be one of the types documented in
|
|
.Xr ASN1_STRING_new 3
|
|
and
|
|
.Fa data
|
|
is expected to point to a buffer of
|
|
.Fa len
|
|
bytes.
|
|
In this case, a new object is allocated with
|
|
.Xr ASN1_STRING_type_new 3
|
|
and populated with
|
|
.Xr ASN1_STRING_set 3 .
|
|
.Pp
|
|
If the
|
|
.Fa type
|
|
argument does not have the bit
|
|
.Dv MBSTRING_FLAG
|
|
set and the
|
|
.Fa len argument
|
|
is \-1,
|
|
.Fa data
|
|
is expected to point to an object of the given
|
|
.Fa type
|
|
rather than to a buffer.
|
|
In this case, a deep copy of the existing object
|
|
into the new ASN.1 ANY object is performed with
|
|
.Xr ASN1_TYPE_set1 3 .
|
|
.Pp
|
|
If the
|
|
.Fa type
|
|
argument is 0, the
|
|
.Fa data
|
|
and
|
|
.Fa len
|
|
arguments are ignored and the set of values is left empty
|
|
instead of adding a single ASN.1 ANY object to it.
|
|
This violates section 8.2 of the X.501 standard, which requires
|
|
every attribute to contain at least one value, but some attribute
|
|
types used by the library use empty sets of values anyway.
|
|
.Pp
|
|
.Fn X509_ATTRIBUTE_create_by_OBJ
|
|
sets the type of
|
|
.Pf ** Fa attr
|
|
to
|
|
.Fa obj
|
|
using
|
|
.Fn X509_ATTRIBUTE_set1_object
|
|
and copies the
|
|
.Fa data
|
|
into it using
|
|
.Fn X509_ATTRIBUTE_set1_data .
|
|
If
|
|
.Fa attr
|
|
or
|
|
.Pf * Fa attr
|
|
is
|
|
.Dv NULL ,
|
|
a new
|
|
.Vt X509_ATTRIBUTE
|
|
object is allocated, populated, and returned.
|
|
.Pp
|
|
.Fn X509_ATTRIBUTE_create_by_NID
|
|
is a wrapper around
|
|
.Fn X509_ATTRIBUTE_create_by_OBJ
|
|
that obtains the required
|
|
.Fa obj
|
|
argument by calling
|
|
.Xr OBJ_nid2obj 3
|
|
on the
|
|
.Fa nid
|
|
argument.
|
|
.Pp
|
|
.Fn X509_ATTRIBUTE_create_by_txt
|
|
is a similar wrapper that obtains
|
|
.Fa obj
|
|
by calling
|
|
.Xr OBJ_txt2obj 3
|
|
with the arguments
|
|
.Fa name
|
|
and 0, which means that long names, short names, and numerical OID
|
|
strings are all acceptable.
|
|
.Sh RETURN VALUES
|
|
.Fn X509_ATTRIBUTE_set1_object
|
|
returns 1 if successful or 0 if
|
|
.Fa attr
|
|
or
|
|
.Fa obj
|
|
is
|
|
.Dv NULL
|
|
or if memory allocation fails.
|
|
.Pp
|
|
.Fn X509_ATTRIBUTE_set1_data
|
|
returns 1 if successful or 0 if
|
|
.Fa attr
|
|
is
|
|
.Dv NULL
|
|
or if
|
|
.Xr ASN1_STRING_set_by_NID 3 ,
|
|
.Xr ASN1_STRING_set 3 ,
|
|
.Xr ASN1_TYPE_set1 3 ,
|
|
or memory allocation fails.
|
|
.Pp
|
|
.Fn X509_ATTRIBUTE_create_by_OBJ ,
|
|
.Fn X509_ATTRIBUTE_create_by_NID ,
|
|
and
|
|
.Fn X509_ATTRIBUTE_create_by_txt
|
|
return a pointer to the changed or new object or
|
|
.Dv NULL
|
|
if obtaining
|
|
.Fa obj ,
|
|
allocating memory, or copying fails.
|
|
.Sh SEE ALSO
|
|
.Xr ASN1_OBJECT_new 3 ,
|
|
.Xr ASN1_STRING_new 3 ,
|
|
.Xr ASN1_STRING_set 3 ,
|
|
.Xr ASN1_STRING_set_by_NID 3 ,
|
|
.Xr ASN1_TYPE_new 3 ,
|
|
.Xr OBJ_nid2obj 3 ,
|
|
.Xr X509_ATTRIBUTE_get0_object 3 ,
|
|
.Xr X509_ATTRIBUTE_new 3
|
|
.Sh HISTORY
|
|
These functions first appeared in OpenSSL 0.9.5
|
|
and have been available since
|
|
.Ox 2.7 .
|
|
.Sh BUGS
|
|
If
|
|
.Fa attr
|
|
already contains one or more values,
|
|
.Fn X509_ATTRIBUTE_set1_data ,
|
|
.Fn X509_ATTRIBUTE_create_by_OBJ ,
|
|
.Fn X509_ATTRIBUTE_create_by_NID ,
|
|
and
|
|
.Fn X509_ATTRIBUTE_create_by_txt
|
|
silently overwrite the pointers to the old values
|
|
and leak the memory used for them.
|