sync code with last improvements from OpenBSD
This commit is contained in:
parent
30d14db1d3
commit
0c904fa153
GPG key ID:
F42C07F07E2E35B7
235 changed files with 12410 additions and 6193 deletions
|
|
@ -1,10 +1,10 @@
|
|||
.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.15 2021/12/15 20:07:51 schwarze Exp $
|
||||
.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.16 2023/09/05 15:01:39 schwarze Exp $
|
||||
.\" full merge up to: OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
|
||||
.\"
|
||||
.\" This file is a derived work.
|
||||
.\" The changes are covered by the following Copyright and license:
|
||||
.\"
|
||||
.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@openbsd.org>
|
||||
.\" Copyright (c) 2017, 2021, 2023 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
|
||||
|
|
@ -65,7 +65,7 @@
|
|||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd $Mdocdate: December 15 2021 $
|
||||
.Dd $Mdocdate: September 5 2023 $
|
||||
.Dt ASN1_OBJECT_NEW 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -207,3 +207,22 @@ first appeared in SSLeay 0.5.1 and
|
|||
in SSLeay 0.8.0.
|
||||
These functions have been available since
|
||||
.Ox 2.4 .
|
||||
.Sh BUGS
|
||||
The function
|
||||
.Fn ASN1_OBJECT_new
|
||||
is not useful for any practical purpose because the library does not
|
||||
provide any function capable of adding data to an existing object.
|
||||
Consequently, if the application program creates an object with
|
||||
.Fn ASN1_OBJECT_new ,
|
||||
that object will always remain empty.
|
||||
.Pp
|
||||
Similarly, if an
|
||||
.Fa nid
|
||||
of
|
||||
.Dv NID_undef
|
||||
is passed to
|
||||
.Fn ASN1_OBJECT_create ,
|
||||
or if
|
||||
.Dv NULL
|
||||
is passed for any of its pointer arguments, the returned object
|
||||
will permanently remain incomplete.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,23 @@
|
|||
.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.2 2023/08/26 15:14:28 schwarze Exp $
|
||||
.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.4 2023/09/05 14:37:00 schwarze Exp $
|
||||
.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000
|
||||
.\"
|
||||
.\" This file is a derived work.
|
||||
.\" The changes are covered by the following Copyright and license:
|
||||
.\"
|
||||
.\" Copyright (c) 2023 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.
|
||||
.\"
|
||||
.\" The original file was written by Richard Levitte <levitte@openssl.org>
|
||||
.\" Copyright (c) 2015 The OpenSSL Project.
|
||||
.\" All rights reserved.
|
||||
|
|
@ -49,7 +66,7 @@
|
|||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd $Mdocdate: August 26 2023 $
|
||||
.Dd $Mdocdate: September 5 2023 $
|
||||
.Dt EVP_CIPHER_METH_NEW 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -184,75 +201,116 @@ Zero or more of the following flags can be OR'ed into the
|
|||
.Fa flags
|
||||
argument:
|
||||
.Bl -tag -width Ds
|
||||
.It EVP_CIPH_VARIABLE_LENGTH
|
||||
This cipher is of variable length.
|
||||
.It EVP_CIPH_CUSTOM_IV
|
||||
Storing and initialising the IV is left entirely to the implementation.
|
||||
.It EVP_CIPH_ALWAYS_CALL_INIT
|
||||
Set this if the implementation's
|
||||
.Fn init
|
||||
function should be called even if
|
||||
.Fa key
|
||||
is
|
||||
.Dv NULL .
|
||||
.It EVP_CIPH_CTRL_INIT
|
||||
Set this to have the implementation's
|
||||
.Fn ctrl
|
||||
function called with command code
|
||||
.Dv EVP_CTRL_INIT
|
||||
early in its setup.
|
||||
.It EVP_CIPH_CUSTOM_KEY_LENGTH
|
||||
Checking and setting the key length after creating the
|
||||
.Vt EVP_CIPHER
|
||||
is left to the implementation.
|
||||
Whenever someone uses
|
||||
.It Dv EVP_CIPH_VARIABLE_LENGTH
|
||||
This cipher has a variable key length, and the function
|
||||
.Xr EVP_CIPHER_CTX_set_key_length 3
|
||||
on a
|
||||
.Vt EVP_CIPHER
|
||||
with this flag set, the implementation's
|
||||
.Fn ctrl
|
||||
function will be called with the control code
|
||||
can be used with it.
|
||||
.It Dv EVP_CIPH_CUSTOM_IV
|
||||
Instruct
|
||||
.Xr EVP_CipherInit_ex 3
|
||||
and similar initialization functions to leave storing and initialising
|
||||
the IV entirely to the implementation.
|
||||
If this flag is set,
|
||||
the implementation is typically expected to do that in its
|
||||
.Fa init
|
||||
function.
|
||||
.It Dv EVP_CIPH_ALWAYS_CALL_INIT
|
||||
Instruct
|
||||
.Xr EVP_CipherInit_ex 3
|
||||
and similar initialization functions to call the implementation's
|
||||
.Fa init
|
||||
function even if the
|
||||
.Fa key
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.It Dv EVP_CIPH_CTRL_INIT
|
||||
Instruct
|
||||
.Xr EVP_CipherInit_ex 3
|
||||
and similar initialization functions to call the implementation's
|
||||
.Fa ctrl
|
||||
function with a command
|
||||
.Fa type
|
||||
of
|
||||
.Dv EVP_CTRL_INIT
|
||||
early during the setup.
|
||||
.It Dv EVP_CIPH_CUSTOM_KEY_LENGTH
|
||||
Instruct
|
||||
.Xr EVP_CIPHER_CTX_set_key_length 3
|
||||
to not check and set the key length itself,
|
||||
but to leave that to the implementation by instead calling its
|
||||
.Fa ctrl
|
||||
function with a command
|
||||
.Fa type
|
||||
of
|
||||
.Dv EVP_CTRL_SET_KEY_LENGTH
|
||||
and the key length in
|
||||
.Fa arg .
|
||||
.It EVP_CIPH_NO_PADDING
|
||||
Don't use standard block padding.
|
||||
.It EVP_CIPH_RAND_KEY
|
||||
Making a key with random content is left to the implementation.
|
||||
This is done by calling the implementation's
|
||||
.Fn ctrl
|
||||
function with the control code
|
||||
.It Dv EVP_CIPH_NO_PADDING
|
||||
Instruct
|
||||
.Xr EVP_CipherFinal_ex 3
|
||||
and similar finalization functions to not use standard block padding
|
||||
but instead report an error if the total amount of data
|
||||
to be encrypted or decrypted is not a multiple of the block size.
|
||||
.It Dv EVP_CIPH_RAND_KEY
|
||||
Instruct
|
||||
.Xr EVP_CIPHER_CTX_rand_key 3
|
||||
to not generate a random key using
|
||||
.Xr arc4random_buf 3
|
||||
but instead leave that to the implementation by calling the
|
||||
.Fa ctrl
|
||||
function with a command
|
||||
.Fa type
|
||||
of
|
||||
.Dv EVP_CTRL_RAND_KEY
|
||||
and the pointer to the key memory storage in
|
||||
.Fa ptr .
|
||||
.It EVP_CIPH_CUSTOM_COPY
|
||||
Set this to have the implementation's
|
||||
.Fn ctrl
|
||||
function called with command code
|
||||
.It Dv EVP_CIPH_CUSTOM_COPY
|
||||
Instruct
|
||||
.Xr EVP_CIPHER_CTX_copy 3
|
||||
to call the implementation's
|
||||
.Fa ctrl
|
||||
function with a command
|
||||
.Fa type
|
||||
of
|
||||
.Dv EVP_CTRL_COPY
|
||||
at the end of
|
||||
.Xr EVP_CIPHER_CTX_copy 3 .
|
||||
and the destination
|
||||
.Fa "EVP_CIPHER_CTX *out"
|
||||
in the
|
||||
.Fa ptr
|
||||
argument immediately before returning successfully.
|
||||
The intended use is for further things to deal with after the
|
||||
implementation specific data block has been copied.
|
||||
The destination
|
||||
.Vt EVP_CIPHER_CTX
|
||||
object is passed to the control with the
|
||||
.Fa ptr
|
||||
parameter.
|
||||
The implementation-specific data block is reached with
|
||||
.Xr EVP_CIPHER_CTX_get_cipher_data 3 .
|
||||
.It EVP_CIPH_FLAG_DEFAULT_ASN1
|
||||
Use the default EVP routines to pass IV to and from ASN.1.
|
||||
.It EVP_CIPH_FLAG_LENGTH_BITS
|
||||
.It Dv EVP_CIPH_FLAG_DEFAULT_ASN1
|
||||
Instruct
|
||||
.Xr EVP_CIPHER_param_to_asn1 3
|
||||
to use
|
||||
.Xr ASN1_TYPE_set_octetstring 3
|
||||
if no
|
||||
.Fa set_asn1_parameters
|
||||
function is installed, and instruct
|
||||
.Xr EVP_CIPHER_asn1_to_param 3
|
||||
to use
|
||||
.Xr ASN1_TYPE_get_octetstring 3
|
||||
if no
|
||||
.Fa get_asn1_parameters
|
||||
function is installed.
|
||||
.It Dv EVP_CIPH_FLAG_LENGTH_BITS
|
||||
Signals that the length of the input buffer for encryption / decryption
|
||||
is to be understood as the number of bits instead of bytes for this
|
||||
implementation.
|
||||
This is only useful for CFB1 ciphers.
|
||||
.It EVP_CIPH_FLAG_CUSTOM_CIPHER
|
||||
This indicates that the implementation takes care of everything,
|
||||
.It Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
|
||||
Instruct
|
||||
.Xr EVP_CipherUpdate 3 ,
|
||||
.Xr EVP_CipherFinal_ex 3 ,
|
||||
and similar encryption, decryption, and finalization functions
|
||||
that the implementation's
|
||||
.Fa do_cipher
|
||||
function takes care of everything,
|
||||
including padding, buffering and finalization.
|
||||
The EVP routines will simply give them control and do nothing more.
|
||||
.It EVP_CIPH_FLAG_AEAD_CIPHER
|
||||
.It Dv EVP_CIPH_FLAG_AEAD_CIPHER
|
||||
This indicates that this is an AEAD cipher implementation.
|
||||
.El
|
||||
.Pp
|
||||
|
|
@ -261,7 +319,9 @@ sets the size of the EVP_CIPHER's implementation context so that it can
|
|||
be automatically allocated.
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_meth_set_init
|
||||
sets the cipher init function for
|
||||
sets the
|
||||
.Fa init
|
||||
function for
|
||||
.Fa cipher .
|
||||
The cipher init function is called by
|
||||
.Xr EVP_CipherInit 3 ,
|
||||
|
|
@ -269,6 +329,7 @@ The cipher init function is called by
|
|||
.Xr EVP_EncryptInit 3 ,
|
||||
.Xr EVP_EncryptInit_ex 3 ,
|
||||
.Xr EVP_DecryptInit 3 ,
|
||||
and
|
||||
.Xr EVP_DecryptInit_ex 3 .
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_meth_set_do_cipher
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.2 2023/09/01 17:28:21 schwarze Exp $
|
||||
.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.3 2023/09/05 14:54:21 schwarze Exp $
|
||||
.\" full merge up to: OpenSSL man3/EVP_EncryptInit.pod
|
||||
.\" 0874d7f2 Oct 11 13:13:47 2022 +0100
|
||||
.\"
|
||||
|
|
@ -66,12 +66,13 @@
|
|||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd $Mdocdate: September 1 2023 $
|
||||
.Dd $Mdocdate: September 5 2023 $
|
||||
.Dt EVP_CIPHER_NID 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm EVP_CIPHER_nid ,
|
||||
.Nm EVP_CIPHER_CTX_nid ,
|
||||
.Nm EVP_CIPHER_name ,
|
||||
.Nm EVP_CIPHER_type ,
|
||||
.Nm EVP_CIPHER_CTX_type ,
|
||||
.Nm EVP_CIPHER_block_size ,
|
||||
|
|
@ -91,6 +92,10 @@
|
|||
.Fo EVP_CIPHER_CTX_nid
|
||||
.Fa "const EVP_CIPHER_CTX *ctx"
|
||||
.Fc
|
||||
.Ft const char *
|
||||
.Fo EVP_CIPHER_name
|
||||
.Fa "const EVP_CIPHER *cipher"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo EVP_CIPHER_type
|
||||
.Fa "const EVP_CIPHER *ctx"
|
||||
|
|
@ -137,6 +142,12 @@ returns the NID of the cipher that
|
|||
.Fa ctx
|
||||
is configured to use.
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_name
|
||||
converts the NID of the
|
||||
.Fa cipher
|
||||
to its short name with
|
||||
.Xr OBJ_nid2sn 3 .
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_type
|
||||
returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the
|
||||
.Fa cipher ,
|
||||
|
|
@ -196,12 +207,27 @@ and the return value of
|
|||
returns the cipher mode of the cipher that
|
||||
.Fa ctx
|
||||
is configured to use.
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_name ,
|
||||
.Fn EVP_CIPHER_CTX_type ,
|
||||
.Fn EVP_CIPHER_mode ,
|
||||
and
|
||||
.Fn EVP_CIPHER_CTX_mode
|
||||
are implemented as macros.
|
||||
.Sh RETURN VALUES
|
||||
.Fn EVP_CIPHER_nid
|
||||
and
|
||||
.Fn EVP_CIPHER_CTX_nid
|
||||
return an NID.
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_name
|
||||
returns a pointer to a string that is owned by an internal library object or
|
||||
.Dv NULL
|
||||
if the NID is neither built into the library nor added to the global
|
||||
object table by one of the functions documented in the manual page
|
||||
.Xr OBJ_create 3 ,
|
||||
of if the object does not contain a short name.
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_type
|
||||
and
|
||||
.Fn EVP_CIPHER_CTX_type
|
||||
|
|
@ -264,6 +290,10 @@ and
|
|||
.Fn EVP_CIPHER_CTX_mode
|
||||
first appeared in OpenSSL 0.9.6 and have been available since
|
||||
.Ox 2.9 .
|
||||
.Pp
|
||||
.Fn EVP_CIPHER_name
|
||||
first appeared in OpenSSL 0.9.7 and has been available since
|
||||
.Ox 3.2 .
|
||||
.Sh CAVEATS
|
||||
The behaviour of the functions taking an
|
||||
.Vt EVP_CIPHER_CTX
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
.\" $OpenBSD: OBJ_nid2obj.3,v 1.20 2023/07/21 05:02:53 tb Exp $
|
||||
.\" $OpenBSD: OBJ_nid2obj.3,v 1.21 2023/09/05 13:50:22 schwarze Exp $
|
||||
.\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000
|
||||
.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
|
||||
.\"
|
||||
.\" This file is a derived work.
|
||||
.\" The changes are covered by the following Copyright and license:
|
||||
.\"
|
||||
.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@openbsd.org>
|
||||
.\" Copyright (c) 2017, 2021, 2023 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
|
||||
|
|
@ -67,7 +67,7 @@
|
|||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd $Mdocdate: July 21 2023 $
|
||||
.Dd $Mdocdate: September 5 2023 $
|
||||
.Dt OBJ_NID2OBJ 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -89,19 +89,19 @@
|
|||
.In openssl/objects.h
|
||||
.Ft ASN1_OBJECT *
|
||||
.Fo OBJ_nid2obj
|
||||
.Fa "int n"
|
||||
.Fa "int nid"
|
||||
.Fc
|
||||
.Ft const char *
|
||||
.Fo OBJ_nid2ln
|
||||
.Fa "int n"
|
||||
.Fa "int nid"
|
||||
.Fc
|
||||
.Ft const char *
|
||||
.Fo OBJ_nid2sn
|
||||
.Fa "int n"
|
||||
.Fa "int nid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo OBJ_obj2nid
|
||||
.Fa "const ASN1_OBJECT *o"
|
||||
.Fa "const ASN1_OBJECT *object"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo OBJ_ln2nid
|
||||
|
|
@ -124,7 +124,7 @@
|
|||
.Fo OBJ_obj2txt
|
||||
.Fa "char *buf"
|
||||
.Fa "int buf_len"
|
||||
.Fa "const ASN1_OBJECT *a"
|
||||
.Fa "const ASN1_OBJECT *object"
|
||||
.Fa "int no_name"
|
||||
.Fc
|
||||
.Ft int
|
||||
|
|
@ -134,86 +134,102 @@
|
|||
.Fc
|
||||
.Ft ASN1_OBJECT *
|
||||
.Fo OBJ_dup
|
||||
.Fa "const ASN1_OBJECT *o"
|
||||
.Fa "const ASN1_OBJECT *object"
|
||||
.Fc
|
||||
.In openssl/asn1.h
|
||||
.Ft int
|
||||
.Fo i2t_ASN1_OBJECT
|
||||
.Fa "char *buf"
|
||||
.Fa "int buf_len"
|
||||
.Fa "const ASN1_OBJECT *a"
|
||||
.Fa "const ASN1_OBJECT *object"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo i2a_ASN1_OBJECT
|
||||
.Fa "BIO *out_bio"
|
||||
.Fa "const ASN1_OBJECT *a"
|
||||
.Fa "const ASN1_OBJECT *object"
|
||||
.Fc
|
||||
.Sh DESCRIPTION
|
||||
The ASN.1 object utility functions process
|
||||
.Vt ASN1_OBJECT
|
||||
structures which are a representation of the ASN.1 OBJECT IDENTIFIER
|
||||
(OID) type.
|
||||
For convenience, OIDs are usually represented in source code as
|
||||
numeric identifiers, or NIDs.
|
||||
OpenSSL has an internal table of OIDs that are generated when the
|
||||
library is built, and their corresponding NIDs are available as
|
||||
defined constants.
|
||||
For the functions below, application code should treat all returned
|
||||
values \(em OIDs, NIDs, or names \(em as constants.
|
||||
structures, in the following called
|
||||
.Dq objects .
|
||||
An object represents an ASN.1
|
||||
.Vt OBJECT IDENTIFIER
|
||||
.Pq OID .
|
||||
The library maintains an internal global table of objects.
|
||||
Many of these objects are built into the library
|
||||
and contained in the global table by default.
|
||||
The application program can add additional objects to the global table
|
||||
by using functions documented in the
|
||||
.Xr OBJ_create 3
|
||||
manual page.
|
||||
Consequently, there are three classes of objects:
|
||||
built-in table objects, user-defined table objects, and non-table objects.
|
||||
.Pp
|
||||
.Fn OBJ_nid2obj ,
|
||||
.Fn OBJ_nid2ln ,
|
||||
In addition to the OID, each object can hold
|
||||
a long name, a short name, and a numerical identifier (NID).
|
||||
Even though the concept of NIDs is specific to the library
|
||||
and not standardized, using the NID is often the most convenient way
|
||||
for source code to refer to a specific OID.
|
||||
The NIDs of the built-in objects are available as defined constants.
|
||||
.Pp
|
||||
Built-in table objects have certain advantages
|
||||
over objects that are not in the global table:
|
||||
for example, their NIDs can be used in C language switch statements.
|
||||
They are also shared:
|
||||
there is only a single static constant structure for each built-on OID.
|
||||
.Pp
|
||||
Some functions operate on table objects only:
|
||||
.Pp
|
||||
.Fn OBJ_nid2obj
|
||||
retrieves the table object associated with the
|
||||
.Fa nid .
|
||||
.Fn OBJ_nid2ln
|
||||
and
|
||||
.Fn OBJ_nid2sn
|
||||
convert the NID
|
||||
.Fa n
|
||||
to an
|
||||
.Vt ASN1_OBJECT
|
||||
structure, its long name, and its short name, respectively, or return
|
||||
.Dv NULL
|
||||
if an error occurred.
|
||||
retrieve its long and short name, respectively.
|
||||
.Pp
|
||||
.Fn OBJ_obj2nid ,
|
||||
.Fn OBJ_ln2nid ,
|
||||
.Fn OBJ_obj2nid
|
||||
retrieves the NID associated with the given
|
||||
.Fa object ,
|
||||
which is either the NID stored in the
|
||||
.Fa object
|
||||
itself, if any, or otherwise the NID stored in a table object
|
||||
containing the same OID.
|
||||
.Pp
|
||||
.Fn OBJ_ln2nid
|
||||
and
|
||||
.Fn OBJ_sn2nid
|
||||
return the corresponding NID for the object
|
||||
.Fa o ,
|
||||
the long name
|
||||
.Fa ln ,
|
||||
retrieve the NID from the table object with the long name
|
||||
.Fa ln
|
||||
or the short name
|
||||
.Fa sn ,
|
||||
respectively, or
|
||||
.Dv NID_undef
|
||||
if an error occurred.
|
||||
respectively.
|
||||
.Pp
|
||||
.Fn OBJ_txt2nid
|
||||
returns the NID corresponding to text string
|
||||
.Fa s .
|
||||
.Fa s
|
||||
can be a long name, a short name, or the numerical representation
|
||||
of an object.
|
||||
retrieves the NID from the table object described by the text string
|
||||
.Fa s ,
|
||||
which can be a long name, a short name,
|
||||
or the numerical representation of an OID.
|
||||
.Pp
|
||||
The remaining functions can be used both on table objects
|
||||
and on objects that are not in the global table:
|
||||
.Pp
|
||||
.Fn OBJ_txt2obj
|
||||
converts the text string
|
||||
.Fa s
|
||||
into an
|
||||
.Vt ASN1_OBJECT
|
||||
structure.
|
||||
retrieves or creates an object matching the text string
|
||||
.Fa s .
|
||||
If
|
||||
.Fa no_name
|
||||
is 0 then long names and short names will be interpreted as well as
|
||||
numerical forms.
|
||||
is 1, only the numerical representation of an OID is accepted.
|
||||
If
|
||||
.Fa no_name
|
||||
is 1, only the numerical form is acceptable.
|
||||
is 0, long names and short names are accepted as well.
|
||||
.Pp
|
||||
.Fn OBJ_obj2txt
|
||||
converts the
|
||||
.Vt ASN1_OBJECT
|
||||
.Fa a
|
||||
into a textual representation.
|
||||
The representation is written as a NUL terminated string to
|
||||
writes a NUL terminated textual representation
|
||||
of the OID contained in the given
|
||||
.Fa object
|
||||
into
|
||||
.Fa buf .
|
||||
At most
|
||||
.Fa buf_len
|
||||
|
|
@ -221,8 +237,13 @@ bytes are written, truncating the result if necessary.
|
|||
The total amount of space required is returned.
|
||||
If
|
||||
.Fa no_name
|
||||
is 0 and the object has a long or short name, then that will be used,
|
||||
otherwise the numerical form will be used.
|
||||
is 0 and the table object containing the same OID
|
||||
contains a long name, the long name is written.
|
||||
Otherwise, if
|
||||
.Fa no_name
|
||||
is 0 and the table object containing the same OID
|
||||
contains a short name, the short name is written.
|
||||
Otherwise, the numerical representation of the OID is written.
|
||||
.Pp
|
||||
.Fn i2t_ASN1_OBJECT
|
||||
is the same as
|
||||
|
|
@ -232,18 +253,18 @@ with
|
|||
set to 0.
|
||||
.Pp
|
||||
.Fn i2a_ASN1_OBJECT
|
||||
writes a textual representation of
|
||||
.Fa a
|
||||
writes a textual representation of the OID contained in the given
|
||||
.Fa object
|
||||
to
|
||||
.Fa out_bio
|
||||
using
|
||||
.Xr BIO_write 3 .
|
||||
It does not write a terminating NUL byte.
|
||||
If
|
||||
.Fa a
|
||||
is
|
||||
If the
|
||||
.Fa object
|
||||
argument is
|
||||
.Dv NULL
|
||||
or contains no data, it writes the 4-byte string
|
||||
or contains no OID, it writes the 4-byte string
|
||||
.Qq NULL .
|
||||
If
|
||||
.Fn i2t_ASN1_OBJECT
|
||||
|
|
@ -255,103 +276,128 @@ Otherwise, it writes the string constructed with
|
|||
.Fn i2t_ASN1_OBJECT .
|
||||
.Pp
|
||||
.Fn OBJ_cmp
|
||||
compares
|
||||
tests whether
|
||||
.Fa a
|
||||
to
|
||||
.Fa b .
|
||||
If the two are identical, 0 is returned.
|
||||
and
|
||||
.Fa b
|
||||
represent the same ASN.1
|
||||
.Vt OBJECT IDENTIFIER .
|
||||
Any names and NIDs contained in the two objects are ignored,
|
||||
even if they differ between both objects.
|
||||
.Pp
|
||||
.Fn OBJ_dup
|
||||
returns a deep copy of
|
||||
.Fa o
|
||||
if
|
||||
.Fa o
|
||||
is marked as dynamically allocated.
|
||||
The new object and all data contained in it is marked as dynamically
|
||||
returns a deep copy of the given
|
||||
.Fa object
|
||||
if it is marked as dynamically allocated.
|
||||
The new object and all data contained in it are marked as dynamically
|
||||
allocated.
|
||||
If
|
||||
.Fa o
|
||||
If the given
|
||||
.Fa object
|
||||
is not marked as dynamically allocated,
|
||||
.Fn OBJ_dup
|
||||
just returns
|
||||
.Fa o
|
||||
just returns a pointer to the
|
||||
.Fa object
|
||||
itself.
|
||||
.Pp
|
||||
Objects can have a short name, a long name, and a numerical
|
||||
identifier (NID) associated with them.
|
||||
A standard set of objects is represented in an internal table.
|
||||
The appropriate values are defined in the header file
|
||||
.In openssl/objects.h .
|
||||
.Pp
|
||||
For example, the OID for commonName has the following definitions:
|
||||
.Bd -literal
|
||||
#define SN_commonName "CN"
|
||||
#define LN_commonName "commonName"
|
||||
#define NID_commonName 13
|
||||
.Ed
|
||||
.Pp
|
||||
New objects can be added by calling
|
||||
.Xr OBJ_create 3 .
|
||||
.Pp
|
||||
Table objects have certain advantages over other objects: for example
|
||||
their NIDs can be used in a C language switch statement.
|
||||
They are also static constant structures which are shared: that is there
|
||||
is only a single constant structure for each table object.
|
||||
.Pp
|
||||
Objects which are not in the table have the NID value
|
||||
.Dv NID_undef .
|
||||
.Pp
|
||||
Objects do not need to be in the internal tables to be processed:
|
||||
the functions
|
||||
.Fn OBJ_txt2obj
|
||||
and
|
||||
.Fn OBJ_obj2txt
|
||||
can process the numerical form of an OID.
|
||||
.Sh RETURN VALUES
|
||||
.Fn OBJ_nid2obj ,
|
||||
.Fn OBJ_txt2obj ,
|
||||
and
|
||||
.Fn OBJ_dup
|
||||
return an
|
||||
.Vt ASN1_OBJECT
|
||||
object or
|
||||
Application code should treat all returned values \(em
|
||||
objects, names, and NIDs \(em as constants.
|
||||
.Pp
|
||||
.Fn OBJ_nid2obj
|
||||
returns a pointer to a table object owned by the library or
|
||||
.Dv NULL
|
||||
if an error occurs.
|
||||
if no matching table object is found.
|
||||
.Pp
|
||||
.Fn OBJ_nid2ln
|
||||
and
|
||||
.Fn OBJ_nid2sn
|
||||
return a valid string or
|
||||
return a pointer to a string owned by a table object or
|
||||
.Dv NULL
|
||||
on error.
|
||||
.Pp
|
||||
.Fn OBJ_obj2nid ,
|
||||
.Fn OBJ_ln2nid ,
|
||||
.Fn OBJ_sn2nid ,
|
||||
if no matching table object is found.
|
||||
For
|
||||
.Dv NID_undef ,
|
||||
they return the constant static strings
|
||||
.Qq undefined
|
||||
and
|
||||
.Fn OBJ_txt2nid
|
||||
return a NID or
|
||||
.Qq UNDEF ,
|
||||
respectively.
|
||||
.Pp
|
||||
.Fn OBJ_obj2nid
|
||||
returns an NID on success, or
|
||||
.Dv NID_undef
|
||||
on error.
|
||||
if
|
||||
.Fa object
|
||||
is
|
||||
.Dv NULL ,
|
||||
does not contain an OID,
|
||||
if no table object matching the OID is found,
|
||||
or if the matching object does not contain an NID.
|
||||
.Pp
|
||||
.Fn OBJ_ln2nid
|
||||
and
|
||||
.Fn OBJ_sn2nid
|
||||
return an NID on success or
|
||||
.Dv NID_undef
|
||||
if no matching table object is found
|
||||
or if the matching object does not contain an NID.
|
||||
.Pp
|
||||
.Fn OBJ_txt2nid
|
||||
returns an NID on success or
|
||||
.Dv NID_undef
|
||||
if parsing of
|
||||
.Fa s
|
||||
or memory allocation fails, if no matching table object is found,
|
||||
or if the matching object does not contain an NID.
|
||||
.Pp
|
||||
.Fn OBJ_txt2obj
|
||||
returns a pointer to a table object owned by the library if lookup of
|
||||
.Fa s
|
||||
as a long or short name succeeds.
|
||||
Otherwise, it returns a newly created object,
|
||||
transferring ownership to the caller, or
|
||||
.Dv NULL
|
||||
if parsing of
|
||||
.Fa s
|
||||
or memory allocation fails.
|
||||
.Pp
|
||||
.Fn OBJ_obj2txt
|
||||
and
|
||||
.Fn i2t_ASN1_OBJECT
|
||||
return the amount of space required in bytes,
|
||||
including the terminating NUL byte.
|
||||
.Pp
|
||||
.Fn i2a_ASN1_OBJECT
|
||||
returns the number of bytes written, even if
|
||||
.Fa a
|
||||
is invalid or contains invalid data,
|
||||
but a negative value if memory allocation or a write operation fails.
|
||||
including the terminating NUL byte,
|
||||
or zero if an error occurs before the required space can be calculated,
|
||||
in particular if
|
||||
.Fa buf_len
|
||||
is negative,
|
||||
.Fa object
|
||||
is
|
||||
.Dv NULL
|
||||
or does not contain an OID,
|
||||
or if memory allocation fails.
|
||||
.Pp
|
||||
.Fn OBJ_cmp
|
||||
returns 0 if the contents of
|
||||
.Fa a
|
||||
and
|
||||
.Fa b
|
||||
are identical, or non-zero otherwise.
|
||||
returns 0 if both objects refer to the same OID
|
||||
or neither of them are associated with any OID,
|
||||
or a non-zero value if at least one of them refers to an OID
|
||||
but the other one does not refer to the same OID.
|
||||
.Pp
|
||||
.Fn OBJ_dup
|
||||
returns the pointer to the original
|
||||
.Fa object
|
||||
if it is not marked as dynamically allocated.
|
||||
Otherwise, it returns a newly created object,
|
||||
transferring ownership to the caller, or
|
||||
.Dv NULL
|
||||
if
|
||||
.Fa object
|
||||
is
|
||||
.Dv NULL
|
||||
or memory allocation fails.
|
||||
.Pp
|
||||
.Fn i2a_ASN1_OBJECT
|
||||
returns the number of bytes written, even if the given
|
||||
.Fa object
|
||||
is invalid or contains invalid data,
|
||||
but a negative value if memory allocation or a write operation fails.
|
||||
.Pp
|
||||
In some cases of failure of
|
||||
.Fn OBJ_nid2obj ,
|
||||
|
|
@ -367,23 +413,23 @@ and
|
|||
the reason can be determined with
|
||||
.Xr ERR_get_error 3 .
|
||||
.Sh EXAMPLES
|
||||
Create an object for
|
||||
Retrieve the object for
|
||||
.Sy commonName :
|
||||
.Bd -literal -offset indent
|
||||
ASN1_OBJECT *o;
|
||||
o = OBJ_nid2obj(NID_commonName);
|
||||
ASN1_OBJECT *object;
|
||||
object = OBJ_nid2obj(NID_commonName);
|
||||
.Ed
|
||||
.Pp
|
||||
Check if an object is
|
||||
Check whether an object contains the OID for
|
||||
.Sy commonName :
|
||||
.Bd -literal -offset indent
|
||||
if (OBJ_obj2nid(obj) == NID_commonName)
|
||||
if (OBJ_obj2nid(object) == NID_commonName)
|
||||
/* Do something */
|
||||
.Ed
|
||||
.Pp
|
||||
Create a new object directly:
|
||||
.Bd -literal -offset indent
|
||||
obj = OBJ_txt2obj("1.2.3.4", 1);
|
||||
object = OBJ_txt2obj("1.2.3.4", 1);
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr ASN1_OBJECT_new 3 ,
|
||||
|
|
@ -416,7 +462,52 @@ first appeared in OpenSSL 0.9.2b.
|
|||
first appeared in OpenSSL 0.9.4.
|
||||
Both functions have been available since
|
||||
.Ox 2.6 .
|
||||
.Sh CAVEATS
|
||||
The API contract of
|
||||
.Fn OBJ_txt2obj
|
||||
when called with a
|
||||
.Fa no_name
|
||||
argument of 0 and of
|
||||
.Fn OBJ_dup
|
||||
is scary in so far as the caller cannot find out from the returned
|
||||
object whether it is owned by the library or whether ownership was
|
||||
transferred to the caller.
|
||||
Consequently, it is best practice to assume that ownership of the object
|
||||
may have been transferred and call
|
||||
.Xr ASN1_OBJECT_free 3
|
||||
on the returned object when the caller no longer needs it.
|
||||
In case the library retained ownership of the returned object,
|
||||
.Xr ASN1_OBJECT_free 3
|
||||
has no effect and is harmless.
|
||||
.Pp
|
||||
Objects returned from
|
||||
.Fn OBJ_txt2obj
|
||||
with a
|
||||
.Fa no_name
|
||||
argument of 1 always require
|
||||
.Xr ASN1_OBJECT_free 3
|
||||
to prevent memory leaks.
|
||||
.Pp
|
||||
Objects returned from
|
||||
.Fn OBJ_nid2obj
|
||||
never require
|
||||
.Xr ASN1_OBJECT_free 3 ,
|
||||
but calling it anyway has no effect and is harmless.
|
||||
.Sh BUGS
|
||||
Usually, an object is expected to contain an NID other than
|
||||
.Dv NID_undef
|
||||
if and only if it is a table object.
|
||||
However, this is not an invariant guaranteed by the API.
|
||||
In particular,
|
||||
.Xr ASN1_OBJECT_create 3
|
||||
allows the creation of non-table objects containing bogus NIDs.
|
||||
.Fn OBJ_obj2nid
|
||||
returns such bogus NIDs even though
|
||||
.Fn OBJ_nid2obj
|
||||
cannot use them for retrieval.
|
||||
On top of that, the global table contains one built-in object with an NID of
|
||||
.Dv NID_undef .
|
||||
.Pp
|
||||
.Fn OBJ_obj2txt
|
||||
is awkward and messy to use: it doesn't follow the convention of other
|
||||
OpenSSL functions where the buffer can be set to
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue