i2t_ASN1_OBJECT,
OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln,
OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp,
-OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup
+OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup, OBJ_add_sigid
- ASN1 object utility functions
=head1 SYNOPSIS
size_t OBJ_length(const ASN1_OBJECT *obj);
const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);
+ int OBJ_add_sigid(int signid, int dig_id, int pkey_id);
+
Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:
code should treat all returned values -- OIDs, NIDs, or names -- as
constants.
-OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
+OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID I<n> to
an ASN1_OBJECT structure, its long name and its short name respectively,
or B<NULL> if an error occurred.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
-for the object B<o>, the long name <ln> or the short name <sn> respectively
+for the object I<o>, the long name I<ln> or the short name I<sn> respectively
or NID_undef if an error occurred.
-OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
+OBJ_txt2nid() returns NID corresponding to text string I<s>. I<s> can be
a long name, a short name or the numerical representation of an object.
-OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
-If B<no_name> is 0 then long names and short names will be interpreted
-as well as numerical forms. If B<no_name> is 1 only the numerical form
+OBJ_txt2obj() converts the text string I<s> into an ASN1_OBJECT structure.
+If I<no_name> is 0 then long names and short names will be interpreted
+as well as numerical forms. If I<no_name> is 1 only the numerical form
is acceptable.
-OBJ_obj2txt() converts the B<ASN1_OBJECT>
B<a> into a textual representation.
-The representation is written as a null terminated string to B<buf>
-at most B<buf_len> bytes are written, truncating the result if necessary.
-The total amount of space required is returned. If B<no_name> is 0 then
+OBJ_obj2txt() converts the B<ASN1_OBJECT>
I<a> into a textual representation.
+The representation is written as a null terminated string to I<buf>
+at most I<buf_len> bytes are written, truncating the result if necessary.
+The total amount of space required is returned. If I<no_name> is 0 then
if the object has a long or short name then that will be used, otherwise
-the numerical form will be used. If B<no_name> is 1 then the numerical
+the numerical form will be used. If I<no_name> is 1 then the numerical
form will always be used.
-i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero.
+i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the I<no_name> set to zero.
-OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
+OBJ_cmp() compares I<a> to I<b>. If the two are identical 0 is returned.
-OBJ_dup() returns a copy of B<o>.
+OBJ_dup() returns a copy of I<o>.
-OBJ_create() adds a new object to the internal table. B<oid> is the
-numerical form of the object, B<sn> the short name and B<ln> the
+OBJ_create() adds a new object to the internal table. I<oid> is the
+numerical form of the object, I<sn> the short name and I<ln> the
long name. A new NID is returned for the created object in case of
success and NID_undef in case of failure.
-OBJ_length() returns the size of the content octets of B<obj>.
+OBJ_length() returns the size of the content octets of I<obj>.
-OBJ_get0_data() returns a pointer to the content octets of B<obj>.
+OBJ_get0_data() returns a pointer to the content octets of I<obj>.
The returned pointer is an internal pointer which B<must not> be freed.
+OBJ_add_sigid() creates a new composite "Signature Algorithm" that associates a
+given NID with two other NIDs - one representing the underlying signature
+algorithm and the other representing a digest algorithm to be used in
+conjunction with it. I<signid> represents the NID for the composite "Signature
+Algorithm", I<dig_id> is the NID for the digest algorithm and I<pkey_id> is the
+NID for the underlying signature algorithm.
+
OBJ_cleanup() releases any resources allocated by creating new objects.
=head1 NOTES
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
a NID or B<NID_undef> on error.
+OBJ_add_sigid() returns 1 on success or 0 on error.
+
=head1 EXAMPLES
Create an object for B<commonName>:
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 B<NULL> to determine the amount of data that should be written.
-Instead B<buf> must point to a valid buffer and B<buf_len> should
+Instead I<buf> must point to a valid buffer and I<buf_len> should
be set to a positive value. A buffer length of 80 should be more
than enough to handle any OID encountered in practice.
void core_vset_error(const OSSL_CORE_HANDLE *handle,
uint32_t reason, const char *fmt, va_list args);
+ int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name,
+ const char *digest_name, const char *pkey_name);
+ int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid,
+ const char *sn, const char *ln);
+
/*
* Some OpenSSL functionality is directly offered to providers via
* dispatch
core_new_error OSSL_FUNC_CORE_NEW_ERROR
core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG
core_vset_error OSSL_FUNC_CORE_VSET_ERROR
+ core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID
+ core_obj_create OSSL_FUNC_CORE_OBJ_CREATE
CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC
CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC
CRYPTO_memdup OSSL_FUNC_CRYPTO_MEMDUP
=back
+The core_obj_create() function registers a new OID and associated short name
+I<sn> and long name I<ln> for the given I<handle>. It is similar to the OpenSSL
+function L<OBJ_create(3)> except that it returns 1 on success or 0 on failure.
+It will treat as success the case where the OID already exists (even if the
+short name I<sn> or long name I<ln> provided as arguments differ from those
+associated with the existing OID, in which case the new names are not
+associated).
+
+The core_obj_add_sigid() function registers a new composite signature algorithm
+(I<sign_name>) consisting of an underlying signature algorithm (I<pkey_name>)
+and digest algorithm (I<digest_name>) for the given I<handle>. It assumes that
+the OIDs for the composite signature algorithm as well as for the underlying
+signature and digest algorithms are either already known to OpenSSL or have been
+registered via a call to core_obj_create(). It corresponds to the OpenSSL
+function L<OBJ_add_sigid(3)>, except that the objects are identified by name
+rather than a numeric NID. Any name (OID, short name or long name) can be used
+to identify the object. It will treat as success the case where the composite
+signature algorithm already exists (even if registered against a different
+underlying signature or digest algorithm). It returns 1 on success or 0 on
+failure.
+
CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_write_ex(), BIO_up_ref(),
-BIO_free(), BIO_vprintf(), BIO_vsnprintf(), OPENSSL_cleanse()
-and OPENSSL_hexstr2buf() correspond exactly to the public functions with
+BIO_free(), BIO_vprintf(), BIO_vsnprintf(), OPENSSL_cleanse() and
+OPENSSL_hexstr2buf() correspond exactly to the public functions with
the same name. As a matter of fact, the pointers in the B<OSSL_DISPATCH>
-array are direct pointers to those public functions. Note that the BIO
+array are typically direct pointers to those public functions. Note that the BIO
functions take an B<OSSL_CORE_BIO> type rather than the standard B<BIO>
type. This is to ensure that a provider does not mix BIOs from the core
with BIOs used on the provider side (the two are not compatible).
projects / openssl.git / commitdiff