Commit 5d28ff38 authored by Rich Salz's avatar Rich Salz
Browse files

RT2964: Fix it via doc 



OBJ_nid2obj() and friends should be treated as const.

Reviewed-by: default avatarDr. Stephen Henson <steve@openssl.org>
parent c32bdbf1

doc/crypto/OBJ_nid2obj.pod

+11 −0
Original line number Diff line number Diff line
@@ -45,6 +45,12 @@ Deprecated: 


The ASN1 object utility functions process ASN1_OBJECT structures which are

a representation of the ASN1 OBJECT IDENTIFIER (OID) type.

For convenience, OIDs are usually represented in source code as numeric

identifiers, or B<NID>s.  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 -- OIDs, NIDs, or names -- as

constants.



OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to

an ASN1_OBJECT structure, its long name and its short name respectively,
@@ -123,6 +129,10 @@ exists for a particular algorithm). As a result they B<cannot> be encoded or 
decoded as part of ASN.1 structures. Applications can determine if there

is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.



These functions cannot return B<const> because an B<ASN1_OBJECT> can

represent both an internal, constant, OID and a dynamically-created one.

The latter cannot be constant because it needs to be freed after use.



=head1 EXAMPLES



Create an object for B<commonName>:
@@ -139,6 +149,7 @@ Create a new NID and initialize an object from it: 


 int new_nid;

 ASN1_OBJECT *obj;



 new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");



 obj = OBJ_nid2obj(new_nid);